{"_id":"@aefree/pi-subagents","_rev":"4-d463b8d240a38e4defbee6499df1a2e2","name":"@aefree/pi-subagents","dist-tags":{"latest":"0.8.3"},"versions":{"0.8.0":{"name":"@aefree/pi-subagents","version":"0.8.0","keywords":["pi-package"],"license":"MIT","_id":"@aefree/pi-subagents@0.8.0","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"homepage":"https://github.com/aefreedman/pi-subagents#readme","bugs":{"url":"https://github.com/aefreedman/pi-subagents/issues"},"pi":{"skills":["./skills"],"extensions":["./extensions/index.ts"]},"dist":{"shasum":"67e7541e4625f2d16a1c8686d0360e67bd088029","tarball":"https://registry.npmjs.org/@aefree/pi-subagents/-/pi-subagents-0.8.0.tgz","fileCount":17,"integrity":"sha512-J3nd+cqtXkyTOjgjHFtAYH6NYGy6YI/b7fmaAea1pmeK1XJ/otd0v5+bnmPv4UnLmxvwq52GYSNw9svTwbMkkg==","signatures":[{"sig":"MEUCIQCigORY7CpFfmdAPiKdUfi+wHyzhrgD9iosf1JUSVlSRwIgAxIvYtvkMJJjR+XLwy4083G0s5ZpPaGT3uXgDE27cQM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":155581},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"5bbe1527fc0e5a8c40bd543fad43b7ce10b29800","scripts":{"test":"npx --yes tsx tests/using-subagents-skill.test.ts && npx --yes tsx tests/agent-discovery.test.ts && npx --yes tsx tests/package-agent-registry.test.ts && npx --yes tsx tests/execution-profile.test.ts && npx --yes tsx tests/project-agent-trust.test.ts && npx --yes tsx tests/child-extensions.test.ts && npx --yes tsx tests/child-process.test.ts && npx --yes tsx tests/pi-launcher.test.ts && npx --yes tsx tests/packed-package.test.ts","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"aefree","email":"aaron@secretcrush.net"},"repository":{"url":"git+https://github.com/aefreedman/pi-subagents.git","type":"git"},"_npmVersion":"11.6.2","description":"Pi tools and package support for subagent orchestration.","directories":{},"_nodeVersion":"24.13.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-agent-core":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.8.0_1785972137274_0.7700801358788436","host":"s3://npm-registry-packages-npm-production"}},"0.8.1":{"name":"@aefree/pi-subagents","version":"0.8.1","keywords":["pi-package"],"license":"MIT","_id":"@aefree/pi-subagents@0.8.1","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"homepage":"https://github.com/aefreedman/pi-subagents#readme","bugs":{"url":"https://github.com/aefreedman/pi-subagents/issues"},"pi":{"skills":["./skills"],"extensions":["./extensions/index.ts"]},"dist":{"shasum":"1942a6139ab16ae96c865b27813837b861f9ce9c","tarball":"https://registry.npmjs.org/@aefree/pi-subagents/-/pi-subagents-0.8.1.tgz","fileCount":18,"integrity":"sha512-UvsA+7v+eJ/kjbp2A9BCe45xC6aR+sl835HUKQHKGuISA9p/czh/4kOyjAKMv4IRhoVEd0RSYMn9r2E05Fjk/Q==","signatures":[{"sig":"MEUCIQDj7TOROl/n+Q9dMExktzHD8xMH0hOxNAJ2D4gYDWGviAIgEGQAhAK6qbNEzNn55hMmVCsccVF1JQc8azyvFSofKdY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aefree%2fpi-subagents@0.8.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":152429},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"dab12e3f13c47d054dd41b6a91c6f315c1215fe2","scripts":{"test":"npx --yes tsx tests/using-subagents-skill.test.ts && npx --yes tsx tests/agent-discovery.test.ts && npx --yes tsx tests/package-agent-registry.test.ts && npx --yes tsx tests/execution-profile.test.ts && npx --yes tsx tests/project-agent-trust.test.ts && npx --yes tsx tests/child-extensions.test.ts && npx --yes tsx tests/child-resources.test.ts && npx --yes tsx tests/child-process.test.ts && npx --yes tsx tests/pi-launcher.test.ts && npx --yes tsx tests/packed-package.test.ts","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4371f437-da8a-485b-936c-a2fd02f8d11a"}},"repository":{"url":"git+https://github.com/aefreedman/pi-subagents.git","type":"git"},"_npmVersion":"11.19.0","description":"Pi tools and package support for subagent orchestration.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-agent-core":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.8.1_1786217102489_0.047964481749066534","host":"s3://npm-registry-packages-npm-production"}},"0.8.2":{"name":"@aefree/pi-subagents","version":"0.8.2","keywords":["pi-package"],"license":"MIT","_id":"@aefree/pi-subagents@0.8.2","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"homepage":"https://github.com/aefreedman/pi-subagents#readme","bugs":{"url":"https://github.com/aefreedman/pi-subagents/issues"},"pi":{"skills":["./skills"],"extensions":["./extensions/index.ts"]},"dist":{"shasum":"da118c448264c331a6b06bf5831f16adf0c8f368","tarball":"https://registry.npmjs.org/@aefree/pi-subagents/-/pi-subagents-0.8.2.tgz","fileCount":18,"integrity":"sha512-1G2+VLQyXIMM/zPYIMi2O5V6B7F/Tcivzcf0Fp8PBdH5xPBLO2dYqi32r8ZfWVtTi3B1v96gnSfE7j+brVirdQ==","signatures":[{"sig":"MEUCIAWq32ihF4utf4hnY2EnfxYeMi2W4mfly0+ve2BnAz5YAiEA6WfdNw66RLm+PKmo/SCGuvbfHKmimVq53zh+uxat0v4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIF5l+w+lTDQyoYcAfSmMl1Q7xqKcojCI00SyEvCYseSGAiEA0sKDBD3JomnWGrmi0tfKpWT6UzhqenPxHkr2NacJkdc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aefree%2fpi-subagents@0.8.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":152938},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"1a7373fad399dd7c99bb66b2c9ce4c909a78f5a4","scripts":{"test":"npx --yes tsx tests/using-subagents-skill.test.ts && npx --yes tsx tests/agent-discovery.test.ts && npx --yes tsx tests/package-agent-registry.test.ts && npx --yes tsx tests/execution-profile.test.ts && npx --yes tsx tests/project-agent-trust.test.ts && npx --yes tsx tests/child-extensions.test.ts && npx --yes tsx tests/child-resources.test.ts && npx --yes tsx tests/child-process.test.ts && npx --yes tsx tests/pi-launcher.test.ts && npx --yes tsx tests/packed-package.test.ts","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4371f437-da8a-485b-936c-a2fd02f8d11a"}},"repository":{"url":"git+https://github.com/aefreedman/pi-subagents.git","type":"git"},"_npmVersion":"11.19.1","description":"Pi tools and package support for subagent orchestration.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"4.23.1","@earendil-works/pi-ai":"0.86.1","@earendil-works/pi-tui":"0.86.1","@earendil-works/pi-agent-core":"0.86.1","@earendil-works/pi-coding-agent":"0.86.1"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-agent-core":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.8.2_1789915260250_0.7673844587383056","host":"s3://npm-registry-packages-npm-production"}},"0.8.3":{"pi":{"skills":["./skills"],"extensions":["./extensions/index.ts"]},"_id":"@aefree/pi-subagents@0.8.3","bugs":{"url":"https://github.com/aefreedman/pi-subagents/issues"},"dist":{"shasum":"cc53b593ab69515404f8506c753e1129f29281f8","tarball":"https://registry.npmjs.org/@aefree/pi-subagents/-/pi-subagents-0.8.3.tgz","fileCount":18,"integrity":"sha512-N5vOXepnZru7TkT0IPQVWHuuNkjAcEwTvY+dIy214U4XcqBmqRSREpGZfQSiQsYXL5WGv7wtscD0U9fQe9KC8Q==","signatures":[{"sig":"MEUCIHukZbd4Zz9DEtKYyxEWmjE67wEweTX48RoARysCagLQAiEA6q0UEUJtGJbEXOls7zR2n0YINMo1jiQiacsb2nv56WA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDTATrSNkwsyMJfpSEP+7GYH4sUdi25IuTNx1YkibUMYwIgHRlIh9ZvAS/x5CsYBojkCdNFXHyZWZUbuN0Trt95lF8="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aefree%2fpi-subagents@0.8.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":153050},"name":"@aefree/pi-subagents","type":"module","engines":{"node":">=22.19.0"},"gitHead":"589f0f8b966fde9f292c2332eb812ca95d82e406","license":"MIT","scripts":{"test":"npx --yes tsx tests/using-subagents-skill.test.ts && npx --yes tsx tests/agent-discovery.test.ts && npx --yes tsx tests/package-agent-registry.test.ts && npx --yes tsx tests/execution-profile.test.ts && npx --yes tsx tests/project-agent-trust.test.ts && npx --yes tsx tests/child-extensions.test.ts && npx --yes tsx tests/child-resources.test.ts && npx --yes tsx tests/child-process.test.ts && npx --yes tsx tests/pi-launcher.test.ts && npx --yes tsx tests/packed-package.test.ts","pack:check":"npm pack --dry-run"},"version":"0.8.3","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4371f437-da8a-485b-936c-a2fd02f8d11a"}},"homepage":"https://github.com/aefreedman/pi-subagents#readme","keywords":["pi-package"],"repository":{"url":"git+https://github.com/aefreedman/pi-subagents.git","type":"git"},"_npmVersion":"11.19.1","description":"Pi tools and package support for subagent orchestration.","directories":{},"maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"_nodeVersion":"22.19.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"4.23.1","@earendil-works/pi-ai":"0.87.0","@earendil-works/pi-tui":"0.87.0","@earendil-works/pi-agent-core":"0.87.0","@earendil-works/pi-coding-agent":"0.87.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-agent-core":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-subagents_0.8.3_1790020854786_0.6071930675455317"}}},"time":{"created":"2026-08-05T23:22:17.150Z","modified":"2026-09-21T20:00:55.257Z","0.8.0":"2026-08-05T23:22:17.407Z","0.8.1":"2026-08-08T19:25:02.642Z","0.8.2":"2026-09-20T14:41:00.356Z","0.8.3":"2026-09-21T20:00:54.890Z"},"bugs":{"url":"https://github.com/aefreedman/pi-subagents/issues"},"license":"MIT","homepage":"https://github.com/aefreedman/pi-subagents#readme","keywords":["pi-package"],"repository":{"url":"git+https://github.com/aefreedman/pi-subagents.git","type":"git"},"description":"Pi tools and package support for subagent orchestration.","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"readme":"# Pi Subagents\n\nPi extension package for delegated specialist workflows.\n\nFor a deeper implementation and runtime walkthrough, see [`docs/architecture.md`](docs/architecture.md).\n\n## What this package provides\n\n- tool: `subagent`\n- tool: `subagent_list`\n- bundled fallback agent: `general`\n- skill: `using-subagents`\n\n## Intended audience\n\nThis README is for humans installing or maintaining the package. Use the `using-subagents` skill for host/orchestrator guidance such as:\n\n- when to use `scout` vs `general`\n- how to shape delegated tasks so they stay bounded\n- the Default-mode one-specialist review budget and direct verification after remediation\n- when to use single, parallel, or chain delegation without using delegation to activate a workflow\n\n## Discovery model\n\n`pi-subagents` can discover agents from:\n\n- user-global local agent definitions in `~/.pi/agent/agents/`\n- user-global package agent directories registered by installed packages\n- its own bundled package agents, including `general`\n- project-local agent definitions in `.pi/agents/`\n- additional project-declared agent directories from `.pi/subagents.json`\n- project-local package agent directories registered by project-installed packages\n\n## Child extension forwarding\n\nA trusted project can forward a bounded list of safety or workflow extensions into every delegated child Pi process, even when a task selects another working directory. Add explicit extension files to the nearest `.pi/settings.json`:\n\n```json\n{\n  \"piSubagents\": {\n    \"childExtensions\": [\n      \"../pi-plastic/extensions/bash-cm-diff-guard.ts\"\n    ]\n  }\n}\n```\n\nPaths resolve relative to the `.pi/settings.json` directory and must resolve to existing extension files physically contained by that project root. Directories, package specs, paths outside the project, malformed configuration, more than 16 files, and configuration from a project Pi has not trusted are rejected before a child launches. Each resolved file is forwarded with an explicit `-e` argument; agent frontmatter and tool-call arguments cannot add extension paths.\n\n## Package agent contract\n\nPi packages do not natively expose `agents/` directories.\n\nThis package supports a small package-agent contract:\n\n- canonical agent definitions stay as Markdown files under `agents/`\n- a package ships a small extension that registers its `agents/` directory on `session_start` and unregisters its exact token on `session_shutdown`\n- registrations live in a versioned registry keyed by `ctx.sessionManager`; snapshots are immutable and separate SDK loaders cannot see one another's package sets\n- registration provenance comes from the physical package manifest (name, version, canonical root, and registration source)\n- `pi-subagents` discovers only the current session's package directories and classifies them as user-global or project-scoped based on install context\n- physical/cross-owner duplicate names or source files remain visible as discovery diagnostics rather than silently winning by load order\n\nRecommended package shape:\n\n```text\nmy-agent-package/\n  package.json\n  agents/\n    scout.md\n  extensions/\n    register-subagents.ts\n```\n\nDiscovery precedence is:\n\n1. project-local `.pi/agents/`\n2. project-local `.pi/subagents.json` paths\n3. project-installed package agent dirs\n4. user-global `~/.pi/agent/agents/`\n5. user-installed package agent dirs\n\n## Project-agent trust\n\nProject agents are repository-controlled prompts. `pi-subagents` uses Pi's existing project-trust state before running them:\n\n- trusted project: run without an extra package prompt\n- untrusted interactive project: ask once per canonical project root and cache approval or denial for the Pi session\n- untrusted non-interactive project: deny; use saved Pi trust or launch Pi with `--approve`\n- user-scoped agent: no project-agent gate\n\n`confirmProjectAgents` now controls whether the one-time interactive fallback is available. Setting it to `false` denies untrusted project-agent execution rather than bypassing trust. This policy is an input-loading guard, not a sandbox or a change to agent tool permissions.\n\nBecause `.pi/agents/` and `.pi/subagents.json` are package conventions rather than Pi core trust-triggering resources, the package fallback remains necessary when Pi has no trust decision.\n\n## Install\n\nFrom npm:\n\n```bash\npi install npm:@aefree/pi-subagents\n```\n\nFrom GitHub:\n\n```bash\npi install git:github.com/aefreedman/pi-subagents@v0.8.1\n```\n\nLocal development install:\n\n```bash\npi install <path-to-pi-subagents>\n```\n\nProject-local install:\n\n```bash\npi install -l <path-to-pi-subagents>\n```\n\n## Model and thinking selection\n\nSubagent execution is restricted to the available OpenAI Codex GPT-5.6 variants: `gpt-5.6-luna`, `gpt-5.6-sol`, and `gpt-5.6-terra`. Unpinned agents inherit the parent session's provider/model and Pi thinking level when the parent uses one of those variants. The coordinator can call `subagent_list` with `includeModels: true` to retrieve the exact enabled identifiers that are currently available and see agent model pins. It may then set optional call-wide defaults or per-task selections:\n\n```text\nsubagent({\n  tasks: [\n    { agent: \"scout\", task: \"Locate the relevant files.\", model: \"openai-codex/gpt-5.6-luna\", thinking: \"low\" },\n    { agent: \"reviewer\", task: \"Review the narrowed change.\", model: \"openai-codex/gpt-5.6-terra\", thinking: \"high\" }\n  ],\n  agentScope: \"both\"\n})\n```\n\nModel selections and agent frontmatter pins must resolve to an enabled, currently available GPT-5.6 `provider/model` identifier. Agent frontmatter `model` declarations remain hard pins and take precedence over coordinator selections. Thinking uses Pi's `off | minimal | low | medium | high | xhigh` levels and may still be clamped by Pi to the selected model's capabilities.\n\n## Optional agent frontmatter\n\nSupported optional frontmatter fields include `class`, `output_format`, `required_sections`, and `strictness`. See [`docs/architecture.md`](docs/architecture.md) and `skills/using-subagents/SKILL.md` for details.\n\n## Testing\n\n```bash\nnpm test\n```\n\n## License\n\nMIT. See `LICENSE`.\n","readmeFilename":"README.md"}