{"_id":"@danchamorro/pi-subagents","_rev":"10-c80c4a34bf16693c62d9b156fed1b632","name":"@danchamorro/pi-subagents","dist-tags":{"latest":"0.9.1"},"versions":{"0.1.0":{"name":"@danchamorro/pi-subagents","version":"0.1.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.1.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"6a92700ffc50b22353bbea76755c646352f0db5a","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.1.0.tgz","fileCount":18,"integrity":"sha512-YOnA8/GxWX3VJ7ukRak78AVlBO/8/0kdwE2t3+EgPj1jWCklN8d5lfz5ap5VA1QbwwWNqH5eeZoZqbL3Pnkfbg==","signatures":[{"sig":"MEUCIQDGJYAnrWC7yizT5kSzbwWlmLYFd6wcHtqT1OIUqAa0BAIgW15R4i+ntmgiOOkfphxVV7+t7W3Liv5EJbFh3AU8bz8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":87437},"type":"module","gitHead":"ffb55ba48edca8f5ed1780fa59007eb738886546","_npmUser":{"name":"danchamorro","email":"i@danchamorro.com"},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.8.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.1.0_1780029218512_0.9035321608793045","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@danchamorro/pi-subagents","version":"0.2.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.2.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"0afe11aaa7bbd65d319ce20285231c17e4e46470","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.2.0.tgz","fileCount":18,"integrity":"sha512-dCEyXEp6t7uxLCa0WRfIrf/FpZeXYH/tKc76st2R194O86cWbpL1xpTHzTQh6EsL7NUHnJBJqfyTajAxFGtBhQ==","signatures":[{"sig":"MEQCIBij2QgNoy+oVz4L7bATs5t9CIv+peqkBD9uNe/cAVqPAiANigta8BYtz94f/KR6L70Qy7Up8ObjFSdF/4Ux03fDnw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":96851},"type":"module","gitHead":"bcfae7699c3e3e1b87a04ecd1bc7c39652fed58a","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.13.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.2.0_1780036781664_0.43884086996344207","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@danchamorro/pi-subagents","version":"0.4.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.4.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"2fbd9b47f3749399727baddef90a0ea9cb027683","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.4.0.tgz","fileCount":18,"integrity":"sha512-OXnJW5Gqh+pWoinOxCaa+P6znmZGKnTPEAvftJNrJLmG6Bp3sSpzzi0qSIoy1n2ML+y/ql8KC2I4BGp5mHOygQ==","signatures":[{"sig":"MEUCICqpk2g8M8EdXpQ7DoZ6ecl/yXrJXiL1xf9rpBeca8tOAiEA4Hg7om78Cg3cdkZpgZRJxbLrD6tAoTkTjYEMw/MP1gA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":112577},"type":"module","gitHead":"364a5d44b6099fec1b4f619526ed838f4756cd54","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.13.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.4.0_1780118622671_0.9987814832110695","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@danchamorro/pi-subagents","version":"0.4.1","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.4.1","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"d1a13be8ed7ea6f23e2b973f72efb5dd8411e67d","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.4.1.tgz","fileCount":19,"integrity":"sha512-QY/7esTK+gRtIO7O2GWas6oUd3orTcNbzq5iO4+q9fQzBmco326xZ67m2W9/gpWskX6Util0o3xBZdK7XI2ufw==","signatures":[{"sig":"MEUCIHzRXmaPLklRYsbLYUxn85AMOivgfHGVW+pJfc4Yg142AiEA6KqL9kzTS1EEq0JJpSseylJt18pp4gs9mT2UiMOZKP0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":119180},"type":"module","gitHead":"6ef2439a20bfd9e168a10b98f0c5b1644bb75c84","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.13.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.4.1_1780123556415_0.8798975022736215","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@danchamorro/pi-subagents","version":"0.5.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.5.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"18e0cdcaa5a6fcaa3d6ee9f66cdc2acab718bacf","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.5.0.tgz","fileCount":20,"integrity":"sha512-Qz3YDpCYVDzzzeUy23brkIAWm+k0vMeUrKDEeApT62/irqeUE/nDjXE4j/aKi3KZCGZEsy3ubIR023jPixBe8g==","signatures":[{"sig":"MEYCIQCz1VkfgpwGw3nVSWSNXggGaqJW1VmH+LVSvyGt4abCGwIhALKtpf95oMZVUwhxrNE8neFJkhH5WffC0jwyrDjRRD1N","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":127723},"type":"module","gitHead":"9d53c1a5e7011fb166e8d08536df065aa10de27e","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.13.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.5.0_1780181821100_0.02944504804803305","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@danchamorro/pi-subagents","version":"0.6.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.6.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"783c3c48112d0b8d41b71125c3841dca8bb247fc","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.6.0.tgz","fileCount":23,"integrity":"sha512-WAZk9WtYQf/xePRRZwOK9QGE8A2AJgn7L2rp2C2lkLl+FffWDhZGoK2jujI77ncVVSsi8TwR8+kGPqsKLppmyQ==","signatures":[{"sig":"MEQCIAox0kKGNvFTYkew04qG3paaAuRs3JnCRI/LzMU3L4wZAiBKRw4VpDnaZ867SfZXDydqOd3ItF6g3IF2REkx5mAqFg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":139424},"type":"module","gitHead":"dc0d7c85ad475af9208bde4b4e81a75179ea98d5","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.13.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.6.0_1780203637632_0.8190328451638931","host":"s3://npm-registry-packages-npm-production"}},"0.7.0":{"name":"@danchamorro/pi-subagents","version":"0.7.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.7.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"9cf4d8e5ca85ef9030a03288c6cf77727cfcf5a6","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.7.0.tgz","fileCount":23,"integrity":"sha512-BNefIeidjtqxxDNsrf1263x08hlFmfhAwwbO+5W/XGIJ4N0Ybp3etPAcwvN0juXWtLAYiOLazUkR0pZ5NfzdPw==","signatures":[{"sig":"MEUCIBhHMLvy8RwFNgk7qUDb8OKcBxgS9kOgbfZ9OH1V5YU5AiEAu0HZbX79RjnpqEtC9L4jS5gA6ZkVOCPU89YnGUdJkmc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.7.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":141149},"type":"module","gitHead":"5f3e5eb5fe89b2337f625275772eb9c00580ef16","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.16.0","description":"In-process background sub-agents for Pi with role prompts, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.7.0_1784081666418_0.13762828609018785","host":"s3://npm-registry-packages-npm-production"}},"0.8.0":{"name":"@danchamorro/pi-subagents","version":"0.8.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.8.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"080f859b04f36e11e68ad110cc4b68687427650f","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.8.0.tgz","fileCount":30,"integrity":"sha512-r7ZDnLWz8Za0brl+AsumKArspqAz01Fsett9xbb3sanZM3OKslHoQeCqwiaJR1uBFkP1YXfZ4Knks982zxIElg==","signatures":[{"sig":"MEYCIQDRXDHQhg/Szgh8JOdFLgOpCBPRnHso325viAH46+1DmgIhANnC4O8SRextUz6qHnbj+icJfByiZQtFrrLZJLZ+hOT1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.8.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":229446},"type":"module","gitHead":"69f9709519897a4256b369d853c8777b5bbaf649","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.16.0","description":"Background Pi sub-agents with optional interactive Herdr sessions, feedback handoff, and compact status visibility","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":">=0.82.0","@earendil-works/pi-tui":">=0.82.0","@earendil-works/pi-coding-agent":">=0.82.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.8.0_1785002606176_0.6207802323756126","host":"s3://npm-registry-packages-npm-production"}},"0.9.0":{"name":"@danchamorro/pi-subagents","version":"0.9.0","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent","claude-code","codex"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-subagents@0.9.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"c1796f5a0e0f1ade2f6b09f81522b0ce93d74634","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.9.0.tgz","fileCount":35,"integrity":"sha512-O7pjPoOnDEAVFOD97jzPj+tOIIzE9iJL9bdBQILLcehQybTDnMC6OkyqC4+MWz4b+0yIPPSvy72wfPZKyOJHgw==","signatures":[{"sig":"MEQCIHJN9wetj4nUEiaXpI4bXsTQy20wHPFVf7pdnGNd3D3mAiBQze1QLLAIraZGlRX0kO0j0rtwOL1nuCfVSvXh+WY7Ow==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.9.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":295308},"type":"module","gitHead":"ebf748a9b1cca16d4cfafd0f3859cc843df10956","scripts":{"test":"node --test test/*.test.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f3e8b519-fbaf-4a26-ba5d-9287e61877d1"}},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/subagents"},"_npmVersion":"11.16.0","description":"Background Pi, Claude Code, and Codex sub-agents with shared lifecycle and feedback controls","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"4.4.3"},"_hasShrinkwrap":false,"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":">=0.82.0","@earendil-works/pi-tui":">=0.82.0","@earendil-works/pi-coding-agent":">=0.82.0"},"optionalDependencies":{"@anthropic-ai/claude-agent-sdk":"0.3.220"},"_npmOperationalInternal":{"tmp":"tmp/pi-subagents_0.9.0_1785041836124_0.8394699453072016","host":"s3://npm-registry-packages-npm-production"}},"0.9.1":{"name":"@danchamorro/pi-subagents","version":"0.9.1","description":"Background Pi, Claude Code, and Codex sub-agents with shared lifecycle and feedback controls","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent","claude-code","codex"],"license":"MIT","author":{"name":"Daniel Chamorro"},"repository":{"type":"git","url":"git+https://github.com/danchamorro/pi-subagents.git"},"type":"module","scripts":{"test":"node --test test/*.test.ts","typecheck":"tsc --noEmit"},"pi":{"extensions":["./index.ts"]},"dependencies":{"zod":"4.4.3"},"optionalDependencies":{"@anthropic-ai/claude-agent-sdk":"0.3.220"},"peerDependencies":{"@earendil-works/pi-ai":">=0.82.0","@earendil-works/pi-coding-agent":">=0.82.0","@earendil-works/pi-tui":">=0.82.0","typebox":"*"},"devDependencies":{"@earendil-works/pi-ai":"0.84.0","@earendil-works/pi-coding-agent":"0.84.0","@earendil-works/pi-tui":"0.84.0","@types/node":"^24.10.0","typebox":"^1.1.24","typescript":"^5.9.3"},"gitHead":"6bd6108233448125eef342bfb56e3bebfe988e25","_id":"@danchamorro/pi-subagents@0.9.1","bugs":{"url":"https://github.com/danchamorro/pi-subagents/issues"},"homepage":"https://github.com/danchamorro/pi-subagents#readme","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-mE5sorrjD/oGcdv5NtS+eDvOTB6ZDgE1SHWG7w8bpIFv/0He20ykPHxSbOrVPpSYQRpJ23v1UL7EL+Es5n8YRQ==","shasum":"131431ab52e3b77c578ff3957cd30cbbfa0e2be0","tarball":"https://registry.npmjs.org/@danchamorro/pi-subagents/-/pi-subagents-0.9.1.tgz","fileCount":36,"unpackedSize":296187,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danchamorro%2fpi-subagents@0.9.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICaWfLBFCPa9HoVIVhLNyvcqTWR6102UejRcBihVoZYMAiEAmEnBptzdEwIHAdnYr/vhwylfFPwuqpg+EGSjienindE="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:dcd85933-afbc-430e-b642-97e39ff3f68a"}},"directories":{},"maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-subagents_0.9.1_1787512886344_0.9481494079650286"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-29T04:33:38.322Z","modified":"2026-08-23T19:21:26.883Z","0.1.0":"2026-05-29T04:33:38.692Z","0.2.0":"2026-05-29T06:39:41.801Z","0.4.0":"2026-05-30T05:23:42.828Z","0.4.1":"2026-05-30T06:45:56.550Z","0.5.0":"2026-05-30T22:57:01.265Z","0.6.0":"2026-05-31T05:00:37.789Z","0.7.0":"2026-07-15T02:14:26.543Z","0.8.0":"2026-07-25T18:03:26.350Z","0.9.0":"2026-07-26T04:57:16.281Z","0.9.1":"2026-08-23T19:21:26.500Z"},"bugs":{"url":"https://github.com/danchamorro/pi-subagents/issues"},"author":{"name":"Daniel Chamorro"},"license":"MIT","homepage":"https://github.com/danchamorro/pi-subagents#readme","keywords":["pi-package","pi","pi-extension","subagents","sub-agents","background-agents","coding-agent","claude-code","codex"],"repository":{"type":"git","url":"git+https://github.com/danchamorro/pi-subagents.git"},"description":"Background Pi, Claude Code, and Codex sub-agents with shared lifecycle and feedback controls","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"readme":"# @danchamorro/pi-subagents\n\nBackground sub-agents for Pi that run focused tasks while the main session\nstays in control. Pi remains the default harness through fresh in-process\nsessions or optional interactive Herdr children. Explicit launches can instead\nuse the user's native Claude Code or Codex CLI subscription login while keeping\nthe same Pi-owned lifecycle, controls, and completion path.\n\nThis package adds a practical delegation layer to Pi. You can start a scout to\nmap unfamiliar code, ask a planner for an implementation plan, run a reviewer\nagainst a diff, or send a worker to execute a bounded change. The main session\ncan delegate these jobs through tools, and users can still inspect or control\neverything manually through `/subagent`.\n\nThe important design choice is that each sub-agent starts with a fresh\nconversation context. It receives the assigned task, role instructions, working\ndirectory, allowed tools, and explicit follow-up feedback. It does not inherit\nthe main session transcript, which keeps background work focused and avoids\nburning the main session's remaining context.\n\n## Contents\n\n- [Highlights](#highlights)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Roles](#roles)\n- [Custom Agents](#custom-agents)\n- [Role Settings](#role-settings)\n- [Session Limits](#session-limits)\n- [Native Claude and Codex Harnesses](#native-claude-and-codex-harnesses)\n- [Interactive Herdr Session](#interactive-herdr-session)\n- [User Commands](#user-commands)\n- [Main-Agent Tools](#main-agent-tools)\n- [How It Works](#how-it-works)\n- [Examples](#examples)\n- [Development](#development)\n- [Current Scope](#current-scope)\n- [Source Layout](#source-layout)\n\n## Highlights\n\n- **Fresh context for every child session.** Sub-agents run as new Pi sessions\n  with a task-specific system prompt instead of inheriting the full parent\n  transcript.\n- **Pi stays the default.** Calls without `harness` retain the existing\n  in-process or Herdr behavior. Explicit `claude` and `codex` launches use the\n  native authenticated tools without routing through Pi's model registry.\n- **Safe default plus interactive Herdr mode.** Pi sub-agents run in-process by\n  default. Opt-in Herdr mode launches real isolated Pi TUIs in one owned Herdr\n  session while preserving the same parent controls and completion reporting.\n  On cmux, one helper surface shows the complete Herdr UI.\n- **Visible but compact status.** A small below-editor widget shows active and\n  recently finished sub-agents, elapsed time, cwd, latest activity, status, and\n  context usage.\n- **Bundled role prompts.** The package includes `planner`, `scout`,\n  `reviewer`, and `worker` roles with role-specific tools, models, thinking\n  levels, and output expectations.\n- **Custom agents.** Users can drop Markdown agents into their Pi agent\n  directory and have them show up beside the bundled roles.\n- **Per-role settings.** Built-in and custom roles can override model,\n  thinking level, and tools without editing package files.\n- **Bounded concurrency.** A configurable soft cap limits how many sub-agents\n  run at once, with an optional idle auto-stop for stalled background work.\n- **Manual and agent-driven control.** Users can type `/subagent ...` commands,\n  while the main agent can use `start_subagent`, `stop_subagent`, and\n  `reply_subagent` tools on the user's behalf.\n- **Feedback handoff.** A sub-agent can pause and ask the main session for a\n  decision through `ask_main_session`. The user can answer naturally, and the\n  main agent can route that answer back with `reply_subagent`.\n- **Scoped working directories.** Sub-agents stay anchored to their launch cwd.\n  If a relative path is missing there, the child is instructed to ask for\n  direction instead of wandering across unrelated folders.\n- **Completion handoff.** Sub-agents launched by the main agent report\n  completion or failure back into the main session as one hidden follow-up\n  bundle, so the main agent can produce a single synthesis instead of competing\n  per-agent summaries. Users can still inspect full output later with\n  `/subagent view <id>`.\n\n## Quick Start\n\nInstall the package:\n\n```bash\npi install npm:@danchamorro/pi-subagents\n```\n\nStart a fresh Pi session, then confirm the command is loaded:\n\n```text\n/subagent agents\n```\n\nYou should see the bundled roles:\n\n```text\nplanner\nreviewer\nscout\nworker\n```\n\nStart a background scout manually:\n\n```text\n/subagent start scout Map this package and summarize its design.\n```\n\nAsk the main agent to delegate naturally:\n\n```text\nUse a scout subagent to map this repo's extension architecture. Launch it in the\nbackground and do not duplicate the scout's investigation yourself.\n```\n\n## Installation\n\n### Standalone Install\n\nMost users should install the package directly from npm. Pi 0.82.0 or newer is\nrequired. You do not need to clone `pi-agent-toolkit` or copy any files into\nyour Pi config.\n\n```bash\npi install npm:@danchamorro/pi-subagents\n```\n\nThen start or restart Pi in any project:\n\n```bash\npi\n```\n\nVerify that the extension loaded:\n\n```text\n/subagent agents\n```\n\nThe package is available to every Pi session after installation. You can start\nPi inside any repo and use `/subagent` there:\n\n```bash\ncd /path/to/your/project\npi\n```\n\n```text\n/subagent start scout Map the repo structure and identify the main entrypoints.\n```\n\n### Update\n\nUse Pi's package updater when a new version is published:\n\n```bash\npi update npm:@danchamorro/pi-subagents\n```\n\nYou can also update all installed Pi packages:\n\n```bash\npi update\n```\n\n### Remove\n\nRemove the package from your Pi settings:\n\n```bash\npi remove npm:@danchamorro/pi-subagents\n```\n\n### Local Development Install\n\nIf you are developing this package locally, install its checkout instead of the\nnpm package:\n\n```bash\ngit clone https://github.com/danchamorro/pi-subagents.git\ncd pi-subagents\npi install .\n```\n\nPi will pick up local edits after a restart or `/reload`.\n\n## Roles\n\nRoles are Markdown prompt files in [agents/](agents/) with frontmatter for\nmetadata and a body for behavior. The package loads them at startup, validates\ntheir tools/model/thinking settings, and exposes them through `/subagent agents`.\n\n| Role | Purpose | Default tools | Thinking | Output |\n|---|---|---|---|---|\n| `planner` | Clarifies a request, reads relevant code, compares implementation options, and returns todos. | `read`, `bash`, `ask_main_session` | `high` | `plan.md` |\n| `scout` | Performs fast read-only reconnaissance and returns file maps, facts, conventions, and gotchas. | `read`, `bash`, `ask_main_session` | `off` | `context.md` |\n| `reviewer` | Reviews changes for bugs, regressions, security issues, and missing validation. | `read`, `bash`, `ask_main_session` | `high` | `review.md` |\n| `worker` | Implements a well-scoped task, runs narrow validation, and reports the changed files. | `read`, `bash`, `write`, `edit`, `ask_main_session` | `minimal` | final result |\n\nRole files support these fields:\n\n| Field | Meaning |\n|---|---|\n| `name` | Role name used by `/subagent start <role> <task>` and `start_subagent.role`. |\n| `description` | Short role description shown in `/subagent agents`. |\n| `tools` | Maximum Pi tools requested by that role. Pi children receive only tools also active in the parent; `ask_main_session` is added automatically. Native harnesses do not apply this Pi allowlist. |\n| `model` | Optional `provider/model` override. If omitted, the child uses the active model. |\n| `thinking` | Optional thinking level override, including `off`. |\n| `auto-exit` | Tells the role to return a final result when the task is done. |\n| `output` | Human-readable expected output artifact, such as `plan.md` or `review.md`. |\n\n## Custom Agents\n\nCustom agents use the same Markdown format as bundled roles. Put them in the Pi\nagent directory under `agents/*.md`:\n\n```text\n~/.pi/agent/agents/thermos-review.md\n```\n\nIf you use `pi-agent-toolkit`, keep repo-managed custom agents under\n`dotfiles/agents/*.md` and run `npm run dev:sync`. Setup links those files into\n`~/.pi/agent/agents/`.\n\nExample:\n\n```markdown\n---\nname: thermos-review\ndescription: Review a change with a strict correctness and maintainability lens.\ntools: read, bash, grep, find, ls\nmodel: openai-codex/gpt-5.6-sol\nthinking: high\nauto-exit: true\noutput: review.md\n---\n\nYou are a focused review sub-agent. Inspect the requested change, report\nconcrete defects first, cite files and lines when possible, and keep the final\nanswer concise.\n```\n\nAfter adding or editing a custom agent, restart Pi or run `/reload`, then check:\n\n```text\n/subagent agents\n```\n\nCustom agents are additive. A custom file cannot silently replace a bundled\nrole such as `scout` or `reviewer`; conflicting custom roles are skipped and\nshown as warnings in `/subagent agents`. If you want to change a bundled role's\nmodel, thinking level, or tools, use role settings instead.\n\nThis is the intended place to test external agent collections such as\nThermos-style Cursor agents. Keep those prompts outside the package at first,\nconvert one prompt into this Markdown format, reload Pi, and confirm it appears\nas a custom role before deciding whether any behavior belongs in core.\n\n## Role Settings\n\nRole settings live in the Pi agent settings file:\n\n```text\n~/.pi/agent/settings.json\n```\n\nAdd a `subagents.agentOverrides` object keyed by role name:\n\n```json\n{\n  \"subagents\": {\n    \"agentOverrides\": {\n      \"scout\": {\n        \"model\": \"openai-codex/gpt-5.6-sol\",\n        \"thinking\": \"off\",\n        \"tools\": [\"read\", \"bash\", \"grep\", \"find\", \"ls\"]\n      },\n      \"thermos-review\": {\n        \"thinking\": \"xhigh\"\n      }\n    }\n  }\n}\n```\n\nSupported override fields are:\n\n| Field | Meaning |\n|---|---|\n| `model` | Optional Pi `provider/model` override for that role. Native harnesses ignore role model fields. |\n| `thinking` | Optional Pi thinking level override, including `off`. Native harnesses use their own effort setting. |\n| `tools` | Optional Pi tool allowlist as an array or comma-separated string. Native harnesses ignore it. |\n\nInvalid override values are ignored with a warning and the role keeps its last\nvalid value. Unknown role names are also reported in `/subagent agents`, which\nhelps catch typos after a reload.\n\n## Session Limits\n\nTwo optional settings in `~/.pi/agent/settings.json` bound background work:\n\n| Field | Meaning | Default |\n|---|---|---|\n| `subagents.maxConcurrent` | Maximum number of simultaneously active sub-agents. New launches are refused with a clear message once the cap is reached. | `5` |\n| `subagents.idleTimeoutMinutes` | Auto-stop a working sub-agent after this many minutes with no activity. `0` disables it. Sub-agents waiting for feedback are never auto-stopped. | `0` (off) |\n\n```json\n{\n  \"subagents\": {\n    \"maxConcurrent\": 3,\n    \"idleTimeoutMinutes\": 15\n  }\n}\n```\n\nEach active sub-agent is a full background model session, so the concurrency cap\nguards against runaway cost and provider rate limits. Idle auto-stop is opt-in\nso background work is never killed unless you ask for it. Invalid values are\nignored with a warning in `/subagent agents` and the default is used.\n\n## Native Claude and Codex Harnesses\n\nNative harnesses are explicit and local-only. They are not Herdr transports and\ndo not use Pi model providers.\n\n```json\n{\n  \"subagents\": {\n    \"harnesses\": {\n      \"claude\": {\n        \"model\": \"claude-opus-5\",\n        \"reasoningEffort\": \"high\"\n      },\n      \"codex\": {\n        \"executable\": \"~/.local/bin/codex\",\n        \"model\": \"gpt-5.6-sol\",\n        \"reasoningEffort\": \"high\"\n      }\n    }\n  }\n}\n```\n\nClaude requires Claude Code 2.1.219 or newer, the optional\n`@anthropic-ai/claude-agent-sdk` 0.3.220 dependency, and an authenticated\nClaude subscription from `claude auth status` on the first-party API. Provider,\nendpoint, and credential environment overrides (including `ANTHROPIC_API_KEY`)\nmust be unset so the launch cannot silently change backend or billing source;\nthey are also stripped from the preflight and SDK child environments. Claude\nruns with the native `claude_code` prompt, adaptive thinking, the requested effort, and\n`bypassPermissions`. Role Pi tool allowlists do not constrain native tools.\nClaude mechanically denies the native `Agent` and `Task` tools. The configured\nmodel must appear in Claude's initialization model catalog; no fallback model\nis configured or accepted.\n\nCodex requires the configured executable to be an absolute executable path and\nexactly Codex CLI 0.145.0 while app-server remains experimental. Every child\nowns one `codex app-server --stdio` process and ephemeral thread. The client\nvalidates ChatGPT authentication, `model/list`, and advertised effort values\nbefore dispatch. It uses `approvalPolicy: \"never\"` and\n`sandbox: \"danger-full-access\"`; unexpected approval requests are declined.\nThe app-server protocol is bounded, fail-closed, and pinned to the observed\n0.145.0 method shapes. Role Pi tool allowlists do not constrain Codex's native\ntools; the child prompt forbids nested agents, but that restriction is not a\nCodex tool allowlist.\n\nBoth native harnesses have broad filesystem and command authority under the\nuser's native configuration. The selected cwd is an execution anchor, not a\nsandbox or trust check, so the caller remains responsible for selecting a\ntrusted directory. Claude subscription routing is experimental for the local\nuser's own login and must not be published without a separate current\nAnthropic terms review. The pinned SDK does not declare an open-source SPDX\nlicense: its package metadata says `SEE LICENSE IN README.md`, and that README\npoints to Anthropic's Commercial Terms. It adds about 4.1 MB itself plus a\nroughly 257 MB native platform package when installed. npm resolves its declared\nAnthropic and MCP SDK peers transitively when the optional Agent SDK is\ninstalled; this package depends directly only on Zod for its feedback schema.\n\nSupported native reasoning efforts are `low`, `medium`, `high`, `xhigh`, and\n`max`. `off` and `minimal` are rejected rather than rounded. The pinned Codex\n0.145.0 catalog advertises those five values for `gpt-5.6-sol` (plus native\n`ultra`, which this uniform public API does not expose). The pinned Claude SDK\nexposes those five values and the selected model catalog is checked at launch.\n\nBoth adapters expose `ask_main_session`: Claude through an in-process SDK MCP\ntool, Codex through the app-server's experimental dynamic-tool request. Status\nuses each native runtime's current context snapshot rather than cumulative token\nusage, so compaction can reduce the displayed percentage. Stop, reload, and\nshutdown cancel pending feedback and terminate native resources.\n\nExamples:\n\n```text\n/subagent start --harness=claude reviewer Review the current diff.\n/subagent start --harness=codex worker Implement the requested change.\n```\n\n```ts\nstart_subagent({\n  harness: \"claude\",\n  role: \"reviewer\",\n  task: \"Review the current diff.\",\n});\n```\n\nThe `pi-agent-toolkit` repository also contains a host-aware personal routing\nskill for natural-language selection. That skill is installed by the toolkit's\nsetup process and does not ship in this npm package. The extension itself still\ndefaults every omitted `harness` to Pi.\n\n## Interactive Herdr Session\n\nInteractive children are opt-in and require [Herdr](https://herdr.dev/) 0.7.5\nor newer on `PATH`. Enable them in `~/.pi/agent/settings.json`:\n\n```json\n{\n  \"subagents\": {\n    \"openInHerdr\": true\n  }\n}\n```\n\nThe extension creates one named Herdr session owned by the exact parent Pi\nsession. Each cwd receives a Herdr workspace, and each child receives a named\ntab such as `sa-1: scout`. The child tab is a normal Pi TUI, so you can watch it,\ntype follow-up prompts directly, or use `stop_subagent` and `reply_subagent`\nfrom the parent.\n\nWhen the parent runs inside cmux, the first child creates one non-focused helper\nsurface containing the Herdr client. Every later child appears inside that same\nHerdr UI; the extension does not create another cmux tab per child. It never\nequalizes splits or resizes unrelated panes. Outside cmux, the owned Herdr\nserver runs headlessly and the parent prints its `herdr session attach <name>`\ncommand. This keeps child orchestration cross-platform while retaining the\nsingle-surface cmux experience on macOS.\n\nThe external child is intentionally isolated. Pi resource discovery is disabled\nfor extensions, skills, prompt templates, themes, context files, and project\ntrust prompts. The parent passes the resolved model, thinking level, tool\nallowlist, private task file, and exact private system prompt. Herdr receives\nonly explicit argv, environment values, and private artifact paths; task and\nsystem-prompt contents are not interpolated into a shell command.\n\nIf Herdr or terminal setup fails before the first `agent start` attempt, the\npackage falls back once to the in-process runner. It never starts a duplicate\nfallback after agent dispatch may have occurred. Disabling `openInHerdr`\nrestores the default in-process path.\n\nWhen the final interactive child finishes, fails, or stops, the extension stops\nand deletes its owned Herdr session and closes the optional cmux host so the\nparent pane returns to full width. A later child recreates both automatically.\n`/reload` and parent shutdown perform the same cleanup. An abrupt parent-process\ncrash can leave the cmux host behind. The next launch reclaims a named Herdr\nsession only when its private ownership marker proves that the previous owning\nprocess exited. The extension never adopts foreign sessions or deletes Herdr's\ndefault session.\n\n## User Commands\n\nThe package registers one slash command namespace: `/subagent`.\n\n| Command | What it does |\n|---|---|\n| `/subagent` | Shows current sub-agent status. |\n| `/subagent help` | Lists available sub-agent commands. |\n| `/subagent agents` | Lists bundled and custom roles, tools, model, thinking settings, source, and warnings. |\n| `/subagent start <task>` | Starts a generic Pi background sub-agent using the current model and thinking level. |\n| `/subagent start --harness=claude [role] <task>` | Starts a native Claude Code child. The flag must lead the start arguments. |\n| `/subagent start --harness=codex [role] <task>` | Starts a native Codex app-server child. The flag must lead the start arguments. |\n| `/subagent start <role> <task>` | Starts a role-specific background sub-agent. |\n| `/subagent start <name>: <task>` | Starts a named sub-agent; if `<name>` matches a role, that role is used. |\n| `/subagent list` | Lists all known active and recent sub-agents. |\n| `/subagent view [id]` | Shows details for one sub-agent, or status for all sub-agents when `id` is omitted. |\n| `/subagent stop <id>` | Stops a running or waiting sub-agent. |\n| `/subagent reply <id> <feedback>` | Sends feedback to a sub-agent waiting on `ask_main_session`. |\n\nSub-agent ids are parent-session-local and look like `sa-1`, `sa-2`, and so on.\nThe command handlers accept exact ids and unambiguous prefixes. Records from a\nseparate Pi session are never loaded merely because it uses the same cwd.\n\n## Main-Agent Tools\n\nThe extension also registers tools for the main agent. These are what make the\nfeature feel natural: the user can say \"stop it\" or \"tell the scout to inspect\nthe other repo\" without typing slash commands.\n\n| Tool | Purpose |\n|---|---|\n| `start_subagent` | Starts a preset or task-specialized sub-agent for a bounded task and returns after launch. |\n| `stop_subagent` | Stops a running or waiting sub-agent. If exactly one is active, the id can be omitted. |\n| `reply_subagent` | Replies to a waiting feedback request. If exactly one sub-agent is waiting, the id can be omitted. |\n| `ask_main_session` | Child-only tool that lets a sub-agent ask the main session for a decision, missing path, credential, or preference. |\n\n`start_subagent` accepts `harness`, `model`, and `reasoning_effort` in addition\nto the existing fields. Missing `harness` means `pi`. Explicit native model or\neffort values override harness settings and never cause cross-harness fallback.\n\nThe main agent can omit `role` and pass ephemeral `instructions` that define a\nsub-agent's perspective, scope, and expected output for one run. These\ninstructions specialize the child without creating a persistent role or\nchanging its tool permissions, model, or thinking level. Configured roles remain\navailable as reusable presets.\n\n`start_subagent` is intentionally nonblocking. Natural-language delegation\nshould feel like starting any other background job: the tool result shows which\nsub-agent started, then terminates the launch turn so the main session becomes\nidle and the user can stop or reply to the child while it runs. When one or more\ntool-started children from the same launch group complete or fail, the package\nposts one hidden follow-up report back into the main session and triggers the\nmain agent to synthesize it for the user. The status widget stays visible while\nthe child runs, and the full result remains available through\n`/subagent view <id>` after completion.\n\n## How It Works\n\n1. The package registers `/subagent`, parent controls, renderers, and lifecycle\n   handlers in [index.ts](index.ts#L1).\n2. Each record is owned by the exact parent Pi session id. Lightweight recovery\n   metadata, including native harness, executable, and session id display\n   fields, lives under that session's directory, so concurrent same-cwd sessions\n   cannot see or overwrite each other's `sa-N` records. Credentials, native\n   session objects, and conversation transcripts are never persisted.\n3. A discriminated launch configuration separates the user-facing harness from\n   its execution backend. Only Pi resolves Pi models, tools, prompt guidelines,\n   and `openInHerdr`; native adapters receive harness-neutral child instructions.\n4. The default Pi backend creates a fresh `SessionManager.inMemory(...)` child in\n   the parent process. It does not persist the child conversation.\n5. With Herdr enabled, the package starts a parent-owned named Herdr server,\n   creates a workspace/tab for the child, and uses Herdr's `agent start` with an\n   explicit Pi argv array. On cmux, one shared helper surface attaches to that\n   Herdr session.\n6. The child runs with a narrow tool set. Role tools are loaded from the role\n   file, while `ask_main_session` and `subagent_done` are supplied by the\n   explicit child runtime extension. The required-only `subagent_done` tool\n   prefers provider-side strict JSON-schema sampling and falls back normally on\n   unsupported models. It requires the complete final result rather than relying\n   on another assistant turn before shutdown.\n7. Atomic, token-scoped files carry activity, feedback, stop, completion, and\n   explicit completion results between parent and child. Malformed, oversized,\n   stale, or mismatched files never mutate another record.\n8. The status widget refreshes while work is active and keeps recent terminal\n   records visible. Tool-launched results still flow through one grouped hidden\n   completion report.\n9. Native Claude and Codex children normalize activity, context usage, feedback,\n   cancellation, and terminal results into the same record and reporter path.\n10. On completion, failure, stop, or interruption, the parent records final\n   status, cancels pending feedback, and removes private run artifacts. After\n   the final interactive child reaches a terminal state, it stops/deletes the\n   named Herdr session and closes its optional cmux host.\n\n## Examples\n\nRun a read-only scout:\n\n```text\n/subagent start scout Map dotfiles/extensions and summarize the extension\nregistration patterns.\n```\n\nRun a planner before implementation:\n\n```text\n/subagent start planner Plan how to split index.ts into smaller modules\nwithout changing behavior.\n```\n\nReview the current diff:\n\n```text\n/subagent start reviewer Review the current git diff for correctness,\nmaintainability, and missing validation.\n```\n\nStart a named generic task:\n\n```text\n/subagent start docs-pass: Read README.md and suggest gaps.\n```\n\nInspect status:\n\n```text\n/subagent list\n/subagent view sa-1\n```\n\nStop or reply manually:\n\n```text\n/subagent stop sa-1\n/subagent reply sa-1 Use /Users/me/project-a instead; the first cwd was wrong.\n```\n\nLet the main agent create task-specific specializations:\n\n```text\nExplore the codebase with focused background sub-agents. Choose the useful\nspecializations and expected output for each instead of assigning every task\nthe same preset role.\n```\n\nUse an explicit preset when its reusable prompt and tool policy fit:\n\n```text\nUse a scout subagent to map the package source. Launch it in the background,\nthen tell me how to inspect or stop it. Do not repeat its work in the main\nsession.\n```\n\n## Development\n\nInstall the checkout once during local development:\n\n```bash\ncd /Users/danielchamorro/Documents/Personal/Code/pi-subagents\npi install .\n```\n\nRestart Pi or run `/reload` after an edit, then test `/subagent` again.\n\nFor a focused session with only this package loaded:\n\n```bash\npi --no-extensions -e ./index.ts\n```\n\nFor non-interactive smoke tests:\n\n```bash\npi --offline --mode json --no-session --no-extensions \\\n  -e ./index.ts \\\n  -p \"/subagent agents\"\n```\n\nReal Herdr integration tests are opt-in because they create temporary named\nsessions and the model-backed cases make live provider requests:\n\n```bash\nPI_SUBAGENTS_REAL_HERDR=1 \\\nPI_SUBAGENTS_REAL_MODEL=xai/grok-4.5 \\\nnode --test test/herdr-integration.test.ts\n```\n\nThe harness uses a unique named Herdr session, never touches the default\nsession, and stops/deletes every session and workspace it creates.\n\nNative completion, feedback, and stop smoke tests are also opt-in because they\nconsume subscription usage:\n\n```bash\nPI_SUBAGENTS_REAL_CLAUDE=1 node --test test/native-live.test.ts\nPI_SUBAGENTS_REAL_CODEX=1 node --test test/native-live.test.ts\n```\n\nRecommended validation before committing package changes:\n\n```bash\nnpm test\nnpm run typecheck\nnpm pack --dry-run\n```\n\nThe published package is installed with `pi install npm:@danchamorro/pi-subagents`.\nUse `pi install .` only when developing from a checkout.\n\n## Current Scope\n\n- Pi in-process execution remains the default. Interactive Herdr mode is Pi-only,\n  opt-in, and requires Herdr 0.7.5 or newer.\n- Native Claude and Codex are explicit, local, non-resumable harnesses. No\n  requested native launch falls back to Pi or another model.\n- Recovery metadata is scoped to the owning parent Pi session and retains native\n  executable/session-id display fields. Full child conversations, credentials,\n  and resumable native session objects are not persisted.\n- External child JSONL and coordination files are private and deleted\n  immediately after bounded result extraction. Transcript retention and\n  automatic orphan adoption are not supported.\n- Concurrency is bounded by `subagents.maxConcurrent` (default 5), and idle\n  auto-stop (`subagents.idleTimeoutMinutes`) is opt-in.\n- The final terminal external child triggers owned Herdr-session and optional\n  cmux-host cleanup. Graceful parent shutdown performs the same cleanup. Abrupt\n  process death has no heartbeat cleanup and can leave an orphaned session.\n- On cmux, layout changes are limited to one right-side Herdr host surface. All\n  child tabs live inside Herdr. The package never equalizes workspace splits.\n- Outside cmux, Herdr runs headlessly and reports an attach command instead of\n  attempting terminal-emulator-specific automation.\n- Dynamic model providers available only through a parent-loaded extension are\n  unavailable to isolated external children; their exact child error is shown.\n- The package does not route sub-agents across arbitrary directories. If the cwd\n  is unclear, the child should ask for direction.\n\nThese boundaries keep the feature predictable while the package matures.\n\n## Source Layout\n\n| File | Responsibility |\n|---|---|\n| [index.ts](index.ts#L1) | Parent extension entrypoint: command/tool registration, backend selection, controls, status, completion, and shutdown. |\n| [child-runtime.ts](child-runtime.ts#L1) | Explicit isolated-child extension for activity, feedback, stop, completion, and session naming. |\n| [herdr.ts](herdr.ts#L1) | Parent-owned named Herdr server, workspace/tab topology, agent launch, ID re-resolution, and cleanup. |\n| [herdr-runner.ts](herdr-runner.ts#L1) | Child artifacts, dispatch boundary, coordination supervision, result extraction, and cleanup. |\n| [cmux.ts](cmux.ts#L1) | Optional focus-safe single-surface host for the Herdr client. |\n| [coordination.ts](coordination.ts#L1), [herdr-controls.ts](herdr-controls.ts#L1) | Private atomic file protocol and token-scoped parent controls. |\n| [launch-config.ts](launch-config.ts#L1) | Discriminated Pi, Claude, and Codex launch decisions. |\n| [harness.ts](harness.ts#L1) | Shared native runner terminal, callback, and effort-mapping contract. |\n| [claude-runner.ts](claude-runner.ts#L1) | Claude Code version/auth/model preflight, Agent SDK streaming, feedback, and cleanup. |\n| [codex-app-server.ts](codex-app-server.ts#L1), [codex-runner.ts](codex-runner.ts#L1) | Bounded Codex JSON-RPC process client and native adapter. |\n| [agents/](agents/) | Bundled role prompts for planner, scout, reviewer, and worker. |\n| [roles.ts](roles.ts#L1) | Built-in/custom role loading, settings overrides and limits, frontmatter validation, and `/subagent start` argument parsing. |\n| [record-store.ts](record-store.ts#L1) | In-memory sub-agent record store: id allocation, lookups, recovery loading, and debounced/eager persistence scheduling. |\n| [completion-reporter.ts](completion-reporter.ts#L1) | Batches tool-launched completions into one hidden main-session report and captures streaming-aware delivery at launch time. |\n| [reload-safe-timer.ts](reload-safe-timer.ts#L1) | Single live status-widget refresh timer that survives Pi hot reloads. |\n| [resource-loader.ts](resource-loader.ts#L1) | Builds the child session resources and task-specific system prompt. |\n| [persistence.ts](persistence.ts#L1) | Persists parent-session-scoped recovery metadata and prunes old runs cheaply. |\n| [status-widget.ts](status-widget.ts#L1) | Compact below-editor status widget for active and recent sub-agents. |\n| [views.ts](views.ts#L1) | `/subagent list`, `/subagent agents`, and `/subagent view` text formatting. |\n| [tool-rendering.ts](tool-rendering.ts#L1) | Compact and expanded rendering for main-agent tool calls/results. |\n| [schemas.ts](schemas.ts#L1) | TypeBox schemas for `start_subagent`, `stop_subagent`, `reply_subagent`, and `ask_main_session`. |\n| [types.ts](types.ts#L1) | Shared types for roles, records, feedback requests, and tool details. |\n| [format.ts](format.ts#L1), [paths.ts](paths.ts#L1), [details.ts](details.ts#L1) | Small helpers for names, elapsed time, paths, details, and display text. |\n","readmeFilename":"README.md"}