{"_id":"@aphotic/pi-mux-subagents","_rev":"4-39a89b5003e40e94635a459cae09ee48","name":"@aphotic/pi-mux-subagents","dist-tags":{"latest":"0.4.0"},"versions":{"0.1.0":{"name":"@aphotic/pi-mux-subagents","version":"0.1.0","keywords":["pi-package"],"author":{"name":"David Lee"},"license":"MIT","_id":"@aphotic/pi-mux-subagents@0.1.0","maintainers":[{"name":"pangolinparty","email":"pangolinparty@gmail.com"}],"homepage":"https://github.com/davidsunglee/pi-mux-subagents#readme","bugs":{"url":"https://github.com/davidsunglee/pi-mux-subagents/issues"},"pi":{"extensions":["./src/index.ts"]},"bin":{"pi-mux-detect":"src/bin/pi-mux-detect.js"},"dist":{"shasum":"a142019de436a2271b7f5d03c9e5c8df5da436ea","tarball":"https://registry.npmjs.org/@aphotic/pi-mux-subagents/-/pi-mux-subagents-0.1.0.tgz","fileCount":47,"integrity":"sha512-69q8vmpCZmfQ1k+7reanypOEKZuU/g58ajSXScOgfTEg8KYO9YnSkNZhSRO4Y5lu+FzvJEmOdcaagONtVrvKVQ==","signatures":[{"sig":"MEUCIQDUCiVHiQJXMQN/HjO6EYzPI7ayvlaWY8MCshMmRH00QwIgPoxxtRidzA3dW//+xBcOKho/M+YcxaiO5P5vRCXnMBE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":436227},"type":"module","gitHead":"38acfdcc430afcd6d0d9815dab0ae0b265279e77","scripts":{"lint":"eslint \"src/**/*.ts\" \"test/**/*.ts\"","test":"node --test test/test.ts test/system-prompt-mode.test.ts test/plugin-*.test.ts test/orchestration/*.test.ts","build":"pnpm run lint && pnpm run typecheck && pnpm run build:plugin && pnpm run build:cli","check":"pnpm run build && pnpm test","build:cli":"esbuild src/bin/pi-mux-detect.ts --bundle --platform=node --format=esm --outfile=src/bin/pi-mux-detect.js --banner:js='#!/usr/bin/env node' && chmod +x src/bin/pi-mux-detect.js","typecheck":"tsc --noEmit","test:plugin":"node --test test/plugin-*.test.ts","build:plugin":"tsc -p src/claude-plugin","test:integration":"node --import ./test/integration/clear-subagent-env.ts --test test/integration/*.test.ts","test:integration:slow":"PI_RUN_SLOW=1 node --import ./test/integration/clear-subagent-env.ts --test test/integration/headless-prompt-composition.test.ts test/integration/orchestration-headless-async-backend.test.ts test/integration/orchestration-headless-block-backend.test.ts test/integration/orchestration-pane-async-backend.test.ts test/integration/orchestration-pane-block-backend.test.ts test/integration/claude-sentinel-roundtrip.test.ts test/integration/pane-claude-interactive.test.ts test/integration/orchestration-claude-pane-serial.test.ts test/integration/orchestration-claude-pane-parallel.test.ts test/integration/orchestration-claude-pane-spec-designer-e2e.test.ts test/integration/coordinator-orchestration-tools.test.ts"},"_npmUser":{"name":"pangolinparty","email":"pangolinparty@gmail.com"},"repository":{"url":"git+https://github.com/davidsunglee/pi-mux-subagents.git","type":"git"},"_npmVersion":"11.12.1","description":"Interactive + headless subagent framework for pi and Claude Code, with mux-pane support, sync/async orchestration, and a multi-CLI design.","directories":{},"_nodeVersion":"26.0.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.1.3","devDependencies":{"eslint":"^10.2.1","esbuild":"^0.25.0","typebox":"^1.1.34","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.6.0","typescript-eslint":"^8.59.1","@earendil-works/pi-tui":"0.75.3","@earendil-works/pi-coding-agent":"0.75.3"},"peerDependencies":{"typebox":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-mux-subagents_0.1.0_1779340741810_0.06939306314553328","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aphotic/pi-mux-subagents","version":"0.2.0","keywords":["pi-package"],"author":{"name":"David Lee"},"license":"MIT","_id":"@aphotic/pi-mux-subagents@0.2.0","maintainers":[{"name":"pangolinparty","email":"pangolinparty@gmail.com"}],"homepage":"https://github.com/davidsunglee/pi-mux-subagents#readme","bugs":{"url":"https://github.com/davidsunglee/pi-mux-subagents/issues"},"pi":{"extensions":["./src/index.ts"]},"bin":{"pi-mux-detect":"src/bin/pi-mux-detect.js"},"dist":{"shasum":"bee02e069b1261909c3174eeb594ba74a4d27746","tarball":"https://registry.npmjs.org/@aphotic/pi-mux-subagents/-/pi-mux-subagents-0.2.0.tgz","fileCount":49,"integrity":"sha512-H9xJFIQVUYdBt/TS8GLWCwrJcDLiu0tzZ1jK7iYOZJiulOcMLeRqMBpuJlcYmNpASw7I5QaP9nZJL+lXFAiNtQ==","signatures":[{"sig":"MEQCIEKFd+xC/lae5OuwUtjofXgTKpBQ5upzot63dbaZeacJAiBGNht25mYz9BoPWLvic8i64RsFJsiqfOhqHpTW3r4UVA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":471808},"type":"module","gitHead":"16f2687b3684c1b1aafc4974d50e035a094b65e0","scripts":{"lint":"eslint \"src/**/*.ts\" \"test/**/*.ts\"","test":"node --test test/test.ts test/system-prompt-mode.test.ts test/plugin-*.test.ts test/orchestration/*.test.ts","build":"pnpm run lint && pnpm run typecheck && pnpm run build:plugin && pnpm run build:cli","check":"pnpm run build && pnpm test","build:cli":"esbuild src/bin/pi-mux-detect.ts --bundle --platform=node --format=esm --outfile=src/bin/pi-mux-detect.js --banner:js='#!/usr/bin/env node' && chmod +x src/bin/pi-mux-detect.js","typecheck":"tsc --noEmit","test:plugin":"node --test test/plugin-*.test.ts","build:plugin":"tsc -p src/claude-plugin","test:integration":"node --import ./test/integration/clear-subagent-env.ts --test test/integration/*.test.ts","test:integration:slow":"PI_RUN_SLOW=1 node --import ./test/integration/clear-subagent-env.ts --test test/integration/headless-prompt-composition.test.ts test/integration/orchestration-headless-async-backend.test.ts test/integration/orchestration-headless-block-backend.test.ts test/integration/orchestration-pane-async-backend.test.ts test/integration/orchestration-pane-block-backend.test.ts test/integration/claude-sentinel-roundtrip.test.ts test/integration/pane-claude-interactive.test.ts test/integration/orchestration-claude-pane-serial.test.ts test/integration/orchestration-claude-pane-parallel.test.ts test/integration/orchestration-claude-pane-spec-designer-e2e.test.ts test/integration/coordinator-orchestration-tools.test.ts test/integration/headless-codex-smoke.test.ts test/integration/pane-codex-interactive.test.ts test/integration/orchestration-codex-pane.test.ts"},"_npmUser":{"name":"pangolinparty","email":"pangolinparty@gmail.com"},"repository":{"url":"git+https://github.com/davidsunglee/pi-mux-subagents.git","type":"git"},"_npmVersion":"11.12.1","description":"Interactive + headless subagent framework for pi and Claude Code, with mux-pane support, sync/async orchestration, and a multi-CLI design.","directories":{},"_nodeVersion":"26.0.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.1.3","devDependencies":{"eslint":"^10.2.1","esbuild":"^0.25.0","typebox":"^1.1.34","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.6.0","typescript-eslint":"^8.59.1","@earendil-works/pi-tui":"0.75.3","@earendil-works/pi-coding-agent":"0.75.3"},"peerDependencies":{"typebox":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-mux-subagents_0.2.0_1780455587215_0.27547748633948355","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@aphotic/pi-mux-subagents","version":"0.3.0","keywords":["pi-package"],"author":{"name":"David Lee"},"license":"MIT","_id":"@aphotic/pi-mux-subagents@0.3.0","maintainers":[{"name":"pangolinparty","email":"pangolinparty@gmail.com"}],"homepage":"https://github.com/davidsunglee/pi-mux-subagents#readme","bugs":{"url":"https://github.com/davidsunglee/pi-mux-subagents/issues"},"pi":{"extensions":["./src/index.ts"]},"bin":{"pi-mux-detect":"src/bin/pi-mux-detect.js"},"dist":{"shasum":"97778d8c7d9f35a1ccf88d8f26db20690961b4ed","tarball":"https://registry.npmjs.org/@aphotic/pi-mux-subagents/-/pi-mux-subagents-0.3.0.tgz","fileCount":52,"integrity":"sha512-LBrRWYVvPhkGxWAt/s8Hd1kznJzGXF16FteXPe32p0N4kKwzJwpWPI/0ON6xfRmNbug5O/qealCUvlaJqClMBw==","signatures":[{"sig":"MEUCIQDnu0OcmhJKJCWrlYtFWzEi8JBHkI6a+XQR+BRZokZsRQIgIWJWhspbTLy2u71hbcTCzbeJvGWWU/4qWaxl1yt94T0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":508380},"type":"module","gitHead":"3391b5d37ab466cb31c13279f350e76559ebc5c2","scripts":{"lint":"eslint \"src/**/*.ts\" \"test/**/*.ts\"","test":"node --import ./test/isolate-agent-dir.ts --test test/test.ts test/system-prompt-mode.test.ts test/plugin-*.test.ts test/orchestration/*.test.ts","build":"pnpm run lint && pnpm run typecheck && pnpm run build:plugin && pnpm run build:cli","check":"pnpm run build && pnpm test","build:cli":"esbuild src/bin/pi-mux-detect.ts --bundle --platform=node --format=esm --outfile=src/bin/pi-mux-detect.js --banner:js='#!/usr/bin/env node' && chmod +x src/bin/pi-mux-detect.js","typecheck":"tsc --noEmit","test:plugin":"node --test test/plugin-*.test.ts","build:plugin":"tsc -p src/claude-plugin","test:integration":"node --import ./test/integration/clear-subagent-env.ts --test --test-concurrency=1 test/integration/*.test.ts","test:integration:slow":"PI_RUN_SLOW=1 node --import ./test/integration/clear-subagent-env.ts --test --test-concurrency=1 test/integration/headless-prompt-composition.test.ts test/integration/orchestration-headless-async-backend.test.ts test/integration/orchestration-headless-block-backend.test.ts test/integration/orchestration-pane-async-backend.test.ts test/integration/orchestration-pane-block-backend.test.ts test/integration/claude-sentinel-roundtrip.test.ts test/integration/pane-claude-interactive.test.ts test/integration/orchestration-claude-pane-serial.test.ts test/integration/orchestration-claude-pane-parallel.test.ts test/integration/orchestration-claude-pane-spec-designer-e2e.test.ts test/integration/coordinator-orchestration-tools.test.ts test/integration/headless-codex-smoke.test.ts test/integration/pane-codex-interactive.test.ts test/integration/orchestration-codex-pane.test.ts"},"_npmUser":{"name":"pangolinparty","email":"pangolinparty@gmail.com"},"repository":{"url":"git+https://github.com/davidsunglee/pi-mux-subagents.git","type":"git"},"_npmVersion":"11.16.0","description":"Interactive + headless subagent framework for pi and Claude Code, with mux-pane support, sync/async orchestration, and a multi-CLI design.","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.1.3","devDependencies":{"eslint":"^10.4.1","esbuild":"^0.25.12","typebox":"^1.1.39","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.9.1","typescript-eslint":"^8.60.1","@earendil-works/pi-tui":"0.78.0","@earendil-works/pi-coding-agent":"0.78.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-tui":">=0.78.0","@earendil-works/pi-coding-agent":">=0.78.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-mux-subagents_0.3.0_1781046244219_0.7805298026775618","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@aphotic/pi-mux-subagents","version":"0.4.0","description":"Interactive + headless subagent framework for pi and Claude Code, with mux-pane support, sync/async orchestration, and a multi-CLI design.","keywords":["pi-package"],"license":"MIT","author":{"name":"David Lee"},"repository":{"type":"git","url":"git+https://github.com/davidsunglee/pi-mux-subagents.git"},"type":"module","packageManager":"pnpm@11.1.3","bin":{"pi-mux-detect":"src/bin/pi-mux-detect.js"},"scripts":{"lint":"eslint \"src/**/*.ts\" \"test/**/*.ts\"","test":"node --import ./test/isolate-agent-dir.ts --test test/test.ts test/system-prompt-mode.test.ts test/plugin-*.test.ts test/orchestration/*.test.ts","test:integration":"node --import ./test/integration/clear-subagent-env.ts --test --test-concurrency=1 test/integration/*.test.ts","test:integration:slow":"PI_RUN_SLOW=1 node --import ./test/integration/clear-subagent-env.ts --test --test-concurrency=1 test/integration/headless-prompt-composition.test.ts test/integration/orchestration-headless-async-backend.test.ts test/integration/orchestration-headless-block-backend.test.ts test/integration/orchestration-pane-async-backend.test.ts test/integration/orchestration-pane-block-backend.test.ts test/integration/claude-sentinel-roundtrip.test.ts test/integration/pane-claude-interactive.test.ts test/integration/orchestration-claude-pane-serial.test.ts test/integration/orchestration-claude-pane-parallel.test.ts test/integration/orchestration-claude-pane-spec-designer-e2e.test.ts test/integration/coordinator-orchestration-tools.test.ts test/integration/headless-codex-smoke.test.ts test/integration/pane-codex-interactive.test.ts test/integration/orchestration-codex-pane.test.ts","test:plugin":"node --test test/plugin-*.test.ts","typecheck":"tsc --noEmit","build:plugin":"tsc -p src/claude-plugin","build:cli":"esbuild src/bin/pi-mux-detect.ts --bundle --platform=node --format=esm --outfile=src/bin/pi-mux-detect.js --banner:js='#!/usr/bin/env node' && chmod +x src/bin/pi-mux-detect.js","build":"pnpm run lint && pnpm run typecheck && pnpm run build:plugin && pnpm run build:cli","check":"pnpm run build && pnpm test"},"peerDependencies":{"@earendil-works/pi-coding-agent":">=0.79.1","@earendil-works/pi-tui":">=0.79.1","typebox":"*"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"pi":{"extensions":["./src/index.ts"]},"devDependencies":{"@earendil-works/pi-coding-agent":"0.79.1","@earendil-works/pi-tui":"0.79.1","@eslint/js":"^10.0.1","@types/node":"^25.9.1","esbuild":"^0.25.12","eslint":"^10.4.1","typebox":"^1.1.39","typescript":"^6.0.3","typescript-eslint":"^8.60.1"},"gitHead":"e8cf5a90779434015fbd23d900434efc4b67fd9c","_id":"@aphotic/pi-mux-subagents@0.4.0","bugs":{"url":"https://github.com/davidsunglee/pi-mux-subagents/issues"},"homepage":"https://github.com/davidsunglee/pi-mux-subagents#readme","_nodeVersion":"26.3.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-k2HSVVouk5SrIkwVQ1y061rfvvkmmPc202dPNO+nxReZ3RVP5JCOc4ai7PsLKh6p4I7FgjUgXC10VANeuAZy0g==","shasum":"a827d4fce415baa4a63bf27123ed6a62c4057d3a","tarball":"https://registry.npmjs.org/@aphotic/pi-mux-subagents/-/pi-mux-subagents-0.4.0.tgz","fileCount":52,"unpackedSize":515573,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCoy97Z+1wSxTLRAPk23JKycz4dwc0HKHwo/C1taQswgAIgQfiM4M7NmwvqmiKhk5MbrHHWC5RNKrqJzDXCoR1DS+g="}]},"_npmUser":{"name":"pangolinparty","email":"pangolinparty@gmail.com"},"directories":{},"maintainers":[{"name":"pangolinparty","email":"pangolinparty@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-mux-subagents_0.4.0_1781230229106_0.3458335435847806"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T05:19:01.686Z","modified":"2026-06-12T02:10:29.542Z","0.1.0":"2026-05-21T05:19:01.960Z","0.2.0":"2026-06-03T02:59:47.375Z","0.3.0":"2026-06-09T23:04:04.390Z","0.4.0":"2026-06-12T02:10:29.384Z"},"bugs":{"url":"https://github.com/davidsunglee/pi-mux-subagents/issues"},"author":{"name":"David Lee"},"license":"MIT","homepage":"https://github.com/davidsunglee/pi-mux-subagents#readme","keywords":["pi-package"],"repository":{"type":"git","url":"git+https://github.com/davidsunglee/pi-mux-subagents.git"},"description":"Interactive + headless subagent framework for pi and Claude Code, with mux-pane support, sync/async orchestration, and a multi-CLI design.","maintainers":[{"name":"pangolinparty","email":"pangolinparty@gmail.com"}],"readme":"# pi-mux-subagents\n\nAn interactive and headless subagent framework for [pi](https://github.com/earendil-works/pi), Claude Code, and Codex with terminal-multiplexer pane support, sync and async orchestration, and a multi-CLI design. Mux pane execution—launching each subagent into its own live terminal pane—is the framework's primary differentiator: it gives you direct observability, manual intervention, and interruption semantics that headless subprocess execution cannot match.\n\n## Install\n\n```bash\nnpm install @aphotic/pi-mux-subagents\n```\n\nRegister the extension in your project's `package.json`:\n\n```json\n{\n  \"pi\": {\n    \"extensions\": [\"./node_modules/@aphotic/pi-mux-subagents/src/index.ts\"]\n  }\n}\n```\n\n## Quickstart\n\n### Subagent primitive (single launch)\n\nLaunch a single worker and receive its result asynchronously:\n\n```json\n{\n  \"name\": \"summarise-module\",\n  \"task\": \"Summarise the public API of src/orchestration/ in one paragraph.\",\n  \"agent\": \"researcher\"\n}\n```\n\nThe parent receives a steer-back message when the worker finishes. Do not invent its output.\n\n### Serial orchestrator\n\nRun tasks one after another. Use `{previous}` to pass each step's final message into the next:\n\n```json\n{\n  \"tasks\": [\n    { \"name\": \"Research\", \"task\": \"List all public exports in src/.\" },\n    { \"name\": \"Plan\",     \"task\": \"Write a migration plan based on: {previous}\" },\n    { \"name\": \"Review\",   \"task\": \"Review the plan for completeness: {previous}\" }\n  ]\n}\n```\n\nThe sequence stops on the first failure and returns all prior results alongside the failing one.\n\n### Parallel orchestrator\n\nRun independent tasks concurrently with a configurable cap:\n\n```json\n{\n  \"maxConcurrency\": 3,\n  \"tasks\": [\n    { \"name\": \"Auth review\",    \"task\": \"Review src/backends/ for security issues.\" },\n    { \"name\": \"Mux review\",     \"task\": \"Review src/mux/ for reliability issues.\" },\n    { \"name\": \"Tooling review\", \"task\": \"Review src/tools/ for correctness.\" }\n  ]\n}\n```\n\n`maxConcurrency` defaults to `4` and is capped at `8`. Partial failures do not cancel sibling tasks. Results are returned in input order.\n\n### Sync vs async subagent calls\n\nBy default (`wait: true`) the orchestration tool blocks until all tasks complete. Set `wait: false` to return immediately with an `orchestrationId`:\n\n```json\n{ \"wait\": false, \"tasks\": [ { \"name\": \"Background probe\", \"task\": \"...\" } ] }\n```\n\nThe tool returns:\n\n```json\n{ \"orchestrationId\": \"7a3f91e2\", \"state\": \"pending\", \"tasks\": [...] }\n```\n\nCompletion arrives later as a single aggregated steer-back message. Cancel with:\n\n```json\n{ \"orchestrationId\": \"7a3f91e2\" }\n```\n\n### CLI selection\n\nChoose which CLI each subagent runs under with the `cli` field:\n\n```json\n{ \"name\": \"pi worker\",     \"task\": \"...\", \"cli\": \"pi\" }\n{ \"name\": \"claude worker\", \"task\": \"...\", \"cli\": \"claude\" }\n{ \"name\": \"codex worker\",  \"task\": \"...\", \"cli\": \"codex\" }\n```\n\n`cli: \"pi\"` (default) gives access to pi lifecycle tools (`subagent_done`, `caller_ping`), skills, and coordinator spawning. `cli: \"claude\"` runs the Claude Code CLI in headless or pane mode; it trades pi lifecycle features for Claude-native tool access. `cli: \"codex\"` runs the Codex CLI in headless (codex exec) or pane mode. Like Claude, it trades pi lifecycle features (skills, caller_ping/block-resume) for native Codex tooling; pi skills and tool allowlists are warned-and-ignored. The framework is designed to support additional CLIs (opencode) in the future.\n\nCodex-specific notes:\n\n- Pane completion is tool-first: Codex pane prompts instruct the model to call `subagent_done(message=…)` with the final summary before any final answer, then send no further output. The MCP completion tool and Codex policy/model/thinking settings are injected per launch with `codex -c` overrides; pi-mux-subagents does not persist its own configuration to `~/.codex/config.toml`.\n- To run unattended, launches pass a per-launch `-c projects.\"<cwd>\".trust_level=\"trusted\"` override so Codex skips its interactive project-trust prompt. This is a flag, not a config write, though Codex itself may still record unrelated project-trust metadata.\n- Codex has no dedicated system-prompt channel. Agent identity that would normally be delivered with `system-prompt: append` or `system-prompt: replace` is delivered additively in the task body instead; `replace` emits a runtime warning because exact base-instruction replacement is not representable on Codex.\n\n### Execution policy\n\n`executionPolicy` (tool parameter) / `execution-policy` (agent frontmatter) is a CLI-agnostic control over how much autonomy a subagent's backend is granted. It takes two values:\n\n```json\n{ \"name\": \"worker\", \"task\": \"...\", \"cli\": \"claude\", \"executionPolicy\": \"guarded\" }\n{ \"name\": \"worker\", \"task\": \"...\", \"cli\": \"claude\", \"executionPolicy\": \"unrestricted\" }\n```\n\n```yaml\n# agent frontmatter\nexecution-policy: guarded\n```\n\n- **`guarded` (default)** prefers the backend's safest practical autonomous mode. For Claude this maps to `--permission-mode auto`, which keeps Claude's permission classifier in the loop for risky actions instead of bypassing it.\n- **`unrestricted`** explicitly opts into bypass/full-access behavior for trusted, sandboxed, or otherwise controlled runs. For Claude this restores the legacy bypass path: `--dangerously-skip-permissions` for pane launches and `--permission-mode bypassPermissions` for headless launches.\n\nResolution order is **tool parameter → agent frontmatter → `guarded` default**. The same `executionPolicy` option is exposed on the bare `subagent` tool and on `subagent_run_serial` / `subagent_run_parallel` steps, so direct and orchestrated launches behave identically. Pane launches still export `CLAUDE_CODE_SANDBOXED=1`; that only bypasses Claude's interactive workspace-trust dialog and does **not** bypass tool permissions, so it applies under both policies.\n\n> **Migration note.** The default changed from bypass-by-default to `guarded`. Workflows that relied on Claude bypassing permissions may now see Claude refuse or pause on risky actions — destructive git operations, credential exploration, production access, or irreversible deletes. If a run is genuinely trusted and sandboxed, set `executionPolicy: \"unrestricted\"` (or `execution-policy: unrestricted` in agent frontmatter) to restore the previous behavior.\n\n#### Backend mappings\n\nThe policy is intentionally CLI-agnostic because the safe mode differs per backend, and the mappings below are **not** exact equivalents:\n\n| Backend | `guarded` (intended) | `unrestricted` (intended) |\n| --- | --- | --- |\n| **Claude** (implemented) | `--permission-mode auto` | `--dangerously-skip-permissions` (pane) / `--permission-mode bypassPermissions` (headless) |\n| **Codex** (implemented) | `--sandbox workspace-write` + `-c approval_policy=\"never\"` (headless) / `--sandbox workspace-write --ask-for-approval on-request` (pane) | `--dangerously-bypass-approvals-and-sandbox` |\n| **OpenCode** (future) | best-effort conservative permission profile (no true classifier-backed `auto` equivalent exists) | broadly `permission: \"allow\"` |\n| **pi** (current) | no guarded mode yet — runs unrestricted, subject only to tool availability and deny-tool config | unrestricted (current behavior) |\n\nCodex guarded mode is sandbox-enforced (workspace-write filesystem + approval policy) but, unlike Claude's --permission-mode auto, is not classifier-backed — there is no per-action risk classifier, only the sandbox boundary and approval policy. Codex configuration (MCP completion server, policy, model, thinking) is applied exclusively through per-launch codex -c overrides — including the per-launch `projects.\"<cwd>\".trust_level=\"trusted\"` override that lets unattended runs skip Codex's interactive project-trust prompt — so pi-mux-subagents never persists its own MCP/policy/model/thinking configuration to ~/.codex/config.toml or other persistent Codex state. (Codex itself may still update unrelated project-trust metadata.)\n\nFor backends without an implemented guarded mode (pi today), an explicit `guarded` request emits a one-line warning and continues with current behavior rather than rejecting the launch. The implicit default does not warn.\n\n### Project trust\n\nProject trust and execution policy are **separate** dimensions. Project trust is a launch-time *input-loading* decision — whether a backend may read project-local settings, resources, packages, extensions, and skills from the directory it starts in. Execution policy (above) is the *autonomy/sandbox* decision — how much the backend may do once running. A subagent can be trusted to load a repo's local config while still running under `guarded` autonomy, and vice versa.\n\nBackends prompt for project trust the first time they start in an unfamiliar directory. Since subagents run unattended, an unanswered prompt would stall the launch, and a non-interactive backend might instead silently skip project-local input. pi-mux-subagents therefore applies a **per-launch** trust approval for each backend it starts on your behalf — for this run only, never writing your persistent trust state (though a backend may record its own trust metadata as a side effect):\n\n| Backend | Per-launch trust handling |\n| --- | --- |\n| **pi** | Pane and headless launches pass `--approve`, Pi's one-run project-trust override (Pi ≥ 0.79.1), so the child loads project-local input without stalling on the trust prompt. |\n| **Claude** | Headless launches run with `-p` (Claude skips the workspace-trust dialog in non-interactive mode); pane launches export `CLAUDE_CODE_SANDBOXED=1`, which short-circuits Claude's trust check. Both only bypass the trust dialog, not tool permissions. |\n| **Codex** | Pane and headless launches pass a per-launch `-c projects.\"<cwd>\".trust_level=\"trusted\"` override so Codex skips its interactive project-trust prompt. This is a flag, not a config write. |\n| **OpenCode** (future) | Will follow the same pattern: a per-launch trust approval for the child run, kept separate from execution policy. |\n\nThis extension also performs its **own** project-local `.pi/agents/` discovery to resolve agent frontmatter (model, tools, skills, `execution-policy`, `cwd`, …) before launching. That parent-side discovery is gated on Pi's effective project-trust decision via `ctx.isProjectTrusted()` (Pi ≥ 0.79.1): when the parent's project is **not** trusted, project-local `.pi/agents/` files are ignored so an untrusted repository cannot bootstrap launch behavior — including `execution-policy: unrestricted` or a `cwd` override — before trust is established. Global `~/.pi/agent/agents/` and bundled agents are unaffected.\n\n### Runtime diagnostics and warnings\n\nWarnings are routed through one diagnostics path. In an interactive TUI they appear via `ui.notify`; in headless or non-UI contexts they fall back to stderr. Caller-relevant warnings — such as dropped `skills`/`tools`, an explicit `guarded` request on a backend without guarded mode, or Codex `system-prompt: replace` fallback — are also surfaced additively as `details.warnings` on the bare `subagent` result or per task in `subagent_run_serial` / `subagent_run_parallel` results. Human-only process diagnostics are not mirrored into `details.warnings`.\n\n### Headless vs mux\n\nControl the execution backend with the `PI_SUBAGENT_MODE` environment variable:\n\n```bash\nexport PI_SUBAGENT_MODE=auto      # default: use a mux pane when one is detected, otherwise headless\nexport PI_SUBAGENT_MODE=pane      # require a mux; fail if none is available\nexport PI_SUBAGENT_MODE=headless  # always run as a child process\n```\n\nHeadless mode works in CI, IDE terminals, and SSH sessions. It produces structured `usage` and `transcript` fields. Pane mode opens each subagent in a live terminal surface where you can watch, type, and intervene directly.\n\n### Interactive flag and autoexit interplay\n\n`interactive` and `autoExit` control how a subagent behaves after completing its turn:\n\n```json\n{ \"interactive\": false, \"autoExit\": true }   // autonomous one-shot worker — exits after one turn\n{ \"interactive\": true,  \"autoExit\": false }  // user-driven session — stays open for follow-up\n```\n\nWhen both are set, `autoExit: true` takes precedence on turn completion. An `interactive: true` child suppresses intermediate status steer-back messages so the parent is not repeatedly woken by expected pauses. If neither is set, `interactive` defaults to `true` unless `autoExit: true` is explicitly present.\n\n## Backend selection\n\nThe framework auto-detects an available mux when an interactive subagent is requested and falls back to headless when no mux is found.\n\nCompatible mux implementations:\n\n1. `herdr`\n2. `cmux`\n3. `tmux`\n4. `zellij`\n5. `wezterm`\n\nThe same order is used for auto-detection. Override the selection with `PI_SUBAGENT_MUX=<name>` to force one of those adapters or fail fast if that adapter is unavailable.\n\n### `pi-mux-detect`\n\nThe package ships a standalone `pi-mux-detect` CLI that exposes the same detection logic used at runtime as machine-readable JSON:\n\n```bash\nnpx pi-mux-detect\n```\n\nSample output:\n\n```json\n{\n  \"backend\": \"pane\",\n  \"mux\": \"herdr\",\n  \"modeForced\": null,\n  \"muxPreference\": null,\n  \"muxPreferenceInvalid\": null,\n  \"reason\": \"auto-selected pane backend; mux=herdr from detection order [herdr,cmux,tmux,zellij,wezterm]\"\n}\n```\n\nFields: `backend` (`\"pane\"` or `\"headless\"`), `mux` (detected adapter name or `null`), `modeForced` (`\"pane\"`, `\"headless\"`, or `null` depending on `PI_SUBAGENT_MODE`), `muxPreference` (value of `PI_SUBAGENT_MUX` when set and valid), `muxPreferenceInvalid` (the invalid raw `PI_SUBAGENT_MUX` value, or `null`), `reason` (human-readable explanation of the detection outcome).\n\nDownstream packages should call `pi-mux-detect` rather than duplicating mux env-var checks.\n\n## Ecosystem\n\n[`pi-flow-core`](https://github.com/aphotic/pi-flow-core) provides a curated library of ready-made agents and skills that build on this package. The dependency direction is `pi-flow-core → pi-mux-subagents`, not the reverse: `pi-mux-subagents` has no runtime dependency on `pi-flow-core`. If you want a batteries-included setup with pre-built agent definitions, start with `pi-flow-core`; if you want only the launch and orchestration primitives, this package is self-contained.\n\n## Attribution\n\nThis project began as a fork of [`HazAT/pi-interactive-subagents`](https://github.com/HazAT/pi-interactive-subagents). Thanks to the upstream maintainer for the foundation this work builds on.\n\n## License\n\nMIT. The LICENSE file at the package root preserves the upstream copyright notice as required by MIT.\n","readmeFilename":"README.md"}