{"_id":"@adamjen/pi-interactive-subagents","_rev":"3-2aadd2ebc85d97240c2b67b5c657baf7","name":"@adamjen/pi-interactive-subagents","dist-tags":{"latest":"3.8.2"},"versions":{"3.8.0":{"name":"@adamjen/pi-interactive-subagents","version":"3.8.0","keywords":["pi-package"],"author":{"name":"HazAT"},"license":"MIT","_id":"@adamjen/pi-interactive-subagents@3.8.0","maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"homepage":"https://github.com/HazAT/pi-interactive-subagents#readme","bugs":{"url":"https://github.com/HazAT/pi-interactive-subagents/issues"},"pi":{"extensions":["./pi-extension/subagents/index.ts"]},"dist":{"shasum":"d6b86ba8ba1c0f7148fbfe927b8a587c827216a4","tarball":"https://registry.npmjs.org/@adamjen/pi-interactive-subagents/-/pi-interactive-subagents-3.8.0.tgz","fileCount":31,"integrity":"sha512-jCnoprS1etCOhNDsrWbYB6ONT81nHoVjZTPyP78c+A3LNAqYfh8lDpxUp52/0J1ULtT8vDafwCxw/tk3C4DM9A==","signatures":[{"sig":"MEUCIQCNWlaKws3IZKz5+JrRujcTiwIN2D1VkO5SuFfebn5LgAIgd5gwoqGLDLxO82QA82CcSEhZTkVj5l0q/8IXSWqZZ54=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":389622},"type":"module","gitHead":"c100577ebf7393a11d098ad9810ec6c269dcfc30","scripts":{"test":"node --test test/test.ts","test:integration":"node --test --test-concurrency=1 test/integration/*.test.ts"},"_npmUser":{"name":"adamjen","email":"adamjentv@gmail.com"},"repository":{"url":"git+https://github.com/HazAT/pi-interactive-subagents.git","type":"git"},"_npmVersion":"10.9.7","description":"Interactive subagents for pi - spawn, orchestrate, and manage sub-agent sessions in cmux/tmux/zellij terminals","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"@sinclair/typebox":"^0.34.49","@earendil-works/pi-tui":"^0.65.0","@earendil-works/pi-coding-agent":"^0.65.0"},"peerDependencies":{"@sinclair/typebox":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-interactive-subagents_3.8.0_1780529288897_0.3062537712516129","host":"s3://npm-registry-packages-npm-production"}},"3.8.1":{"name":"@adamjen/pi-interactive-subagents","version":"3.8.1","keywords":["pi-package"],"author":{"name":"HazAT"},"license":"MIT","_id":"@adamjen/pi-interactive-subagents@3.8.1","maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"homepage":"https://github.com/HazAT/pi-interactive-subagents#readme","bugs":{"url":"https://github.com/HazAT/pi-interactive-subagents/issues"},"pi":{"extensions":["./pi-extension/subagents/index.ts"]},"dist":{"shasum":"7343a1a97960489aa06cd2d800a2a6789dde6b62","tarball":"https://registry.npmjs.org/@adamjen/pi-interactive-subagents/-/pi-interactive-subagents-3.8.1.tgz","fileCount":31,"integrity":"sha512-4ThL7fCpL4wDylFsQ9ZcrkJAw5QapbRQgowZo9cxxCSpPba6Ud8gWK6OWbkviMAc3EcqZbG9n47v1cxwap7a7Q==","signatures":[{"sig":"MEUCIQCzj79DgS1OI8d0Ageo8Q12caJ5O51fu7VF4r0L20NyeQIgaVOQ7MK05OKSlFbfBI7MAYNU8PfhaQSF5kfXcoBpYfM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":389602},"type":"module","gitHead":"c100577ebf7393a11d098ad9810ec6c269dcfc30","scripts":{"test":"node --test test/test.ts","test:integration":"node --test --test-concurrency=1 test/integration/*.test.ts"},"_npmUser":{"name":"adamjen","email":"adamjentv@gmail.com"},"repository":{"url":"git+https://github.com/HazAT/pi-interactive-subagents.git","type":"git"},"_npmVersion":"10.9.7","description":"Interactive subagents for pi - spawn, orchestrate, and manage sub-agent sessions in cmux/tmux/zellij terminals","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"@sinclair/typebox":"^0.34.49","@mariozechner/pi-tui":"^0.65.0","@mariozechner/pi-coding-agent":"^0.65.0"},"peerDependencies":{"@sinclair/typebox":"*","@mariozechner/pi-tui":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-interactive-subagents_3.8.1_1780529323013_0.34878656316166223","host":"s3://npm-registry-packages-npm-production"}},"3.8.2":{"name":"@adamjen/pi-interactive-subagents","version":"3.8.2","description":"Interactive subagents for pi - spawn, orchestrate, and manage sub-agent sessions in cmux/tmux/zellij terminals","keywords":["pi-package"],"license":"MIT","author":{"name":"HazAT"},"repository":{"type":"git","url":"git+https://github.com/HazAT/pi-interactive-subagents.git"},"type":"module","scripts":{"test":"node --test test/test.ts","test:integration":"node --test --test-concurrency=1 test/integration/*.test.ts"},"peerDependencies":{"@mariozechner/pi-coding-agent":"*","@mariozechner/pi-tui":"*","@sinclair/typebox":"*"},"pi":{"extensions":["./pi-extension/subagents/index.ts"]},"devDependencies":{"@mariozechner/pi-coding-agent":"^0.65.0","@mariozechner/pi-tui":"^0.65.0","@sinclair/typebox":"^0.34.49"},"_id":"@adamjen/pi-interactive-subagents@3.8.2","gitHead":"c100577ebf7393a11d098ad9810ec6c269dcfc30","bugs":{"url":"https://github.com/HazAT/pi-interactive-subagents/issues"},"homepage":"https://github.com/HazAT/pi-interactive-subagents#readme","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-EQ7TgidfyZa2lq1Ns3JxWrAOdd+r430JD0B1FOENpE74H3V/lYeVXwGfqyR5kXBsRr+iw7i/OazpS7RwTVkM+g==","shasum":"8dc86efba5ba9911ec857b9692953c1e567a8d0d","tarball":"https://registry.npmjs.org/@adamjen/pi-interactive-subagents/-/pi-interactive-subagents-3.8.2.tgz","fileCount":31,"unpackedSize":389718,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCYIAkXFw0ei0DM1KRHad9CPRfsTtwWUtrKm6pVRC9CGQIgYw4Hs3Z0Hwf15mpjzA5V5w/8y+XgWqroAi28iLsxBXc="}]},"_npmUser":{"name":"adamjen","email":"adamjentv@gmail.com"},"directories":{},"maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-interactive-subagents_3.8.2_1780529540774_0.6174889826379866"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T23:28:08.781Z","modified":"2026-06-03T23:32:21.046Z","3.8.0":"2026-06-03T23:28:09.054Z","3.8.1":"2026-06-03T23:28:43.163Z","3.8.2":"2026-06-03T23:32:20.926Z"},"bugs":{"url":"https://github.com/HazAT/pi-interactive-subagents/issues"},"author":{"name":"HazAT"},"license":"MIT","homepage":"https://github.com/HazAT/pi-interactive-subagents#readme","keywords":["pi-package"],"repository":{"type":"git","url":"git+https://github.com/HazAT/pi-interactive-subagents.git"},"description":"Interactive subagents for pi - spawn, orchestrate, and manage sub-agent sessions in cmux/tmux/zellij terminals","maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"readme":"# pi-interactive-subagents\n\nForked from [HazAT/pi-interactive-subagents](https://github.com/HazAT/pi-interactive-subagents) — original author HazAT.\n\nAsync subagents for [pi](https://github.com/badlogic/pi-mono) — spawn, orchestrate, and manage sub-agent sessions in multiplexer panes. **Fully non-blocking** — the main agent keeps working while subagents run in the background.\n\nhttps://github.com/user-attachments/assets/30adb156-cfb4-4c47-84ca-dd4aa80cba9f\n\n## How It Works\n\nCall `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it.\n\n```\n╭─ Subagents ──────────────────────────── 2 running ─╮\n│ 00:23 Scout: Auth (scout) active · bash 7m │\n│ 00:45 Scout: DB (scout) waiting 2m │\n╰────────────────────────────────────────────────────╯\n```\n\nFor parallel execution, just call `subagent` multiple times — they all run concurrently:\n\n```typescript\nsubagent({ name: \"Scout: Auth\", agent: \"scout\", task: \"Analyze auth module\" });\nsubagent({ name: \"Scout: DB\", agent: \"scout\", task: \"Map database schema\" });\n// Both return immediately, results steer back independently\n```\n\n## Install\n\n```bash\npi install npm:@adamjen/pi-interactive-subagents\n```\n\nSupported multiplexers:\n\n- [cmux](https://github.com/manaflow-ai/cmux)\n- [tmux](https://github.com/tmux/tmux)\n- [zellij](https://zellij.dev)\n- [WezTerm](https://wezfurlong.org/wezterm/) (terminal emulator with built-in multiplexing)\n\nStart pi inside one of them:\n\n```bash\ncmux pi\n# or\ntmux new -A -s pi 'pi'\n# or\nzellij --session pi # then run: pi\n# or\n# just run pi inside WezTerm — no wrapper needed\n```\n\nOptional: set `PI_SUBAGENT_MUX=cmux|tmux|zellij|wezterm` to force a specific backend.\n\nIf your shell startup is slow and subagent commands sometimes get dropped before the prompt is ready, set `PI_SUBAGENT_SHELL_READY_DELAY_MS` to a higher value (defaults to `500`):\n\n```bash\nexport PI_SUBAGENT_SHELL_READY_DELAY_MS=2500\n```\n\nSubagent panes are created without stealing keyboard focus (cmux, tmux). Launch commands target child surfaces by explicit ID, so focus and command delivery are independent. Note: the `interactive` option controls parent status notifications, not terminal focus.\n\n## What's Included\n\n### Extensions\n\n**Subagents** — 4 main-session tools + 3 commands, plus 1 subagent-only tool:\n\n| Tool | Description |\n| -------------------- | ------------------------------------------------------------------------------------------- |\n| `subagent` | Spawn a sub-agent in a dedicated multiplexer pane (async — returns immediately) |\n| `subagent_interrupt` | Interrupt a running Pi-backed subagent's current turn |\n| `subagents_list` | List available agent definitions |\n| `subagent_resume` | Resume a previous sub-agent session (async) |\n\n| Command | Description |\n| -------------------------- | ------------------------------------ |\n| `/plan` | Start a full planning workflow |\n| `/iterate` | Fork into a subagent for quick fixes |\n| `/subagent ` | Spawn a named agent directly |\n\n### Bundled Agents\n\n| Agent | Model | Role |\n| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------- |\n| **planner** | llama-swap/qwen3.6-27b-qwopus (max) | Brainstorming — clarifies requirements, explores approaches, writes plans, creates todos |\n| **scout** | llama-swap/gemma-4-E4B (cheap) | Fast codebase reconnaissance — maps files, patterns, conventions |\n| **worker** | llama-swap/qwen3.6-27b-coder (balanced) | Implements tasks from todos — writes code, runs tests, makes polished commits |\n| **reviewer** | llama-swap/qwen3.6-27b-qwopus (max) | Reviews code for bugs, security issues, correctness |\n| **visual-tester** | llama-swap/qwen3.6-27b-coder (balanced) | Visual QA via Chrome CDP — screenshots, responsive testing, interaction testing |\n\nAgent discovery follows priority: **project-local** (`.pi/agents/`) > **global** (`~/.pi/agent/agents/`) > **package-bundled**. Override any bundled agent by placing your own version in the higher-priority location.\n\n---\n\n## Async Subagent Flow\n\n```\n1. Agent calls subagent() → returns immediately (\"started\")\n2. Sub-agent runs in mux pane → widget shows live status\n3. User keeps chatting → main session fully interactive\n4. Sub-agent finishes → result steered back as a normal completion/failure\n5. Main agent processes result → continues with new context\n```\n\nMultiple subagents run concurrently — each steers its result back independently as it finishes. The live widget above the input tracks all running agents:\n\n```\n╭─ Subagents ───────────────────────────────── 3 running ─╮\n│ 01:23 Scout: Auth (scout) active · write 7m │\n│ 00:45 Researcher (researcher) stalled 4m │\n│ 00:12 Scout: DB (scout) starting… │\n╰─────────────────────────────────────────────────────────╯\n```\n\nCompletion messages render with a colored background and are expandable with `Ctrl+O` to show the full summary and session file path.\n\n### In-progress status updates\n\nThe widget tracks each Pi-backed sub-agent from a child-written runtime snapshot and labels it with a coarse state:\n\n- `starting` — launched, but no valid child snapshot has been observed yet\n- `active` — the child is doing observed runtime work: agent turn, provider request, streaming, or tool execution\n- `waiting` — the child finished a turn and is intentionally open for more input or another stage\n- `stalled` — the parent has gone too long without a valid current child snapshot and can no longer trust the run is healthy\n- `running` — fallback for backends without child snapshots (e.g. Claude)\n\nThese labels are no longer derived from session-file growth. Session JSONL is still used for transcript, resume, lineage, and result extraction, but Pi-backed liveness now comes from a small activity snapshot written by the child extension. A fixed internal watchdog marks a run as `stalled` when valid snapshots never appear, stop being readable, or stop matching the current child; valid long-running `active` or `waiting` states do not become `stalled` just because time passes. When a run enters `stalled` or recovers from it, the parent agent receives a steer message so it can react. All other status transitions stay in the widget only.\n\n**Interactive subagents stay silent.** Long-running user-driven subagents (e.g. `planner`, or any `/iterate` fork) do not wake the parent session on `stalled`/`recovered` transitions — the user is working directly in the subagent's pane, and a steer message there would just burn an orchestrator turn on a no-op \"still waiting\" ping. The widget still updates normally, and child snapshots are still recorded/classified regardless of the `interactive` setting. By default, agents with `auto-exit: true` are treated as autonomous and get stall pings; agents without it are treated as interactive and stay quiet. Override per-agent with `interactive: true|false` in frontmatter, or per-spawn with `interactive: true|false` on the tool call.\n\n#### Configuration\n\nStatus display is controlled by `config.json` in the extension directory. Copy `config.json.example` to get started:\n\n```bash\ncp config.json.example config.json\n```\n\n```json\n{\n \"status\": {\n \"enabled\": true\n }\n}\n```\n\n`config.json` is gitignored so local overrides don't get committed.\n\n---\n\n## Spawning Subagents\n\n```typescript\n// Named agent with defaults from agent definition\nsubagent({ name: \"Scout\", agent: \"scout\", task: \"Analyze the codebase...\" });\n\n// Force a full-context fork for this spawn\nsubagent({ name: \"Iterate\", fork: true, task: \"Fix the bug where...\" });\n\n// Agent defaults can choose a different session-mode via frontmatter\nsubagent({ name: \"Planner\", agent: \"planner\", task: \"Work through the design with me\" });\n\n// Custom working directory\nsubagent({ name: \"Designer\", agent: \"game-designer\", cwd: \"agents/game-designer\", task: \"...\" });\n```\n\n### Parameters\n\n| Parameter | Type | Default | Description |\n| ---------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------- |\n| `name` | string | required | Display name (shown in widget and pane title) |\n| `task` | string | required | Task prompt for the sub-agent |\n| `agent` | string | — | Load defaults from agent definition |\n| `fork` | boolean | `false` | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter |\n| `interactive` | boolean | derived | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |\n| `model` | string | — | Override agent's default model |\n| `systemPrompt` | string | — | Append to system prompt |\n| `skills` | string | — | Comma-separated skill names |\n| `tools` | string | — | Comma-separated tool names |\n| `cwd` | string | — | Working directory for the sub-agent (see [Role Folders](#role-folders)) |\n\n### Model Preferences\n\nConfigure model overrides for subagent spawns in `~/.pi/settings.json`:\n\n```json\n{\n \"extensions\": {\n \"subagent\": {\n \"defaultModel\": \"llama-swap/orchestrator\",\n \"modelTiers\": {\n \"cheap\": \"llama-swap/gemma-4-E4B\",\n \"balanced\": \"llama-swap/qwen3.6-27b-coder\",\n \"max\": \"llama-swap/qwen3-80b-thinking-128k\"\n },\n \"agentTiers\": {\n \"scout\": \"cheap\",\n \"worker\": \"balanced\",\n \"planner\": \"max\",\n \"reviewer\": \"max\",\n \"visual-tester\": \"balanced\"\n }\n }\n }\n}\n```\n\n**Priority:** `params.model` > `agentTiers` lookup > agent frontmatter `model` > `defaultModel`\n\n- `defaultModel`: Global fallback when no other model is specified\n- `modelTiers`: Named tiers mapping to model strings\n- `agentTiers`: Maps agent names to tier names for automatic model assignment\n\nConfig is cached at module load time and refreshed on `/reload`. A malformed `settings.json` silently falls back to no config.\n\n---\n\n## Interrupting a running subagent\n\nUse `subagent_interrupt` to cancel the active turn of a running Pi-backed subagent:\n\n```typescript\nsubagent_interrupt({ id: \"abcd1234\" });\n// or\nsubagent_interrupt({ name: \"Scout\" });\n```\n\nThis sends Escape to the child pane, cancelling the in-progress model turn. The subagent session stays alive — the pane, session file, and background polling all remain intact. After the interrupt, the widget immediately moves the child back to `waiting`, and stale pre-interrupt snapshots are ignored. If the child starts work later, newer snapshots return it to `active`; completion, failure, and `caller_ping` still flow through normally.\n\nThis is a turn-level interrupt, not a method for forcibly terminating a subagent session.\n\n> **Note:** Only Pi-backed subagents are supported. Claude-backed runs will return an error.\n\n---\n\n## caller_ping — Child-to-Parent Help Request\n\nThe `caller_ping` tool lets a subagent request help from its parent agent. When called, the child session **exits** and the parent receives a notification with the help message. The parent can then **resume** the child session with a response using `subagent_resume`.\n\n**`caller_ping` parameters:**\n- `message` (required): What you need help with\n\n**`subagent_resume` parameters:**\n- `sessionPath` (required): Path to the child session `.jsonl` file\n- `name` (optional): Display name for the resumed pane (defaults to `Resume`)\n- `message` (optional): Follow-up prompt to send after resuming\n- `autoExit` (optional): Whether the resumed session should auto-exit after its next response. Defaults to `true` for autonomous follow-up work; set `false` when resuming for an interactive handoff.\n\n**Interaction flow:**\n1. Child calls `caller_ping({ message: \"Not sure which schema to use\" })`\n2. Child session exits (like `subagent_done`)\n3. Parent receives a steer notification: *\"Sub-agent Worker needs help: Not sure which schema to use\"*\n4. Parent resumes the child session via `subagent_resume` with the response\n5. Child picks up where it left off with the parent's guidance\n\n**Example:**\n```typescript\n// Inside a worker subagent\nawait caller_ping({\n message: \"Found two conflicting migration files — should I use v1 or v2?\"\n});\n// Session exits here. Parent receives the ping, then resumes this session\n// with guidance like \"Use v2, v1 is deprecated\"\n```\n\n> **Note:** `caller_ping` is only available inside subagent contexts. Calling it from a standalone pi session returns an error.\n\n---\n\n## The `/plan` Workflow\n\nThe `/plan` command orchestrates a full planning-to-implementation pipeline.\n\n```\n/plan Add a dark mode toggle to the settings page\n```\n\n```\nPhase 1: Investigation → Quick codebase scan\nPhase 2: Planning → Interactive planner subagent (user collaborates)\nPhase 3: Review Plan → Confirm todos, adjust if needed\nPhase 4: Execute → Scout + sequential workers implement todos\nPhase 5: Review → Reviewer subagent checks all changes\n```\n\nTab/window titles update to show current phase:\n\n```\n🔍 Investigating: dark mode → 💬 Planning: dark mode\n→ 🔨 Executing: 1/3 → 🔎 Reviewing → ✅ Done\n```\n\n---\n\n## The `/iterate` Workflow\n\nFor quick, focused work without polluting the main session's context.\n\n```\n/iterate Fix the off-by-one error in the pagination logic\n```\n\nThis always forks the current session into a subagent with full conversation context. It does not inherit an agent default `session-mode`. Make the fix, verify it, and exit to return. The main session gets a summary of what was done.\n\n---\n\n## Custom Agents\n\nPlace a `.md` file in `.pi/agents/` (project) or `~/.pi/agent/agents/` (global):\n\n```markdown\n---\nname: my-agent\ndescription: Does something specific\nmodel: llama-swap/qwen3.6-27b-coder\nthinking: minimal\ntools: read, bash, edit, write\nsession-mode: lineage-only\nspawning: false\n---\n\n# My Agent\n\nYou are a specialized agent that does X...\n```\n\n### Frontmatter Reference\n\n| Field | Type | Description |\n| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | string | Agent name (used in `agent: \"my-agent\"`) |\n| `description` | string | Shown in `subagents_list` output |\n| `model` | string | Default model (e.g. `llama-swap/qwen3.6-27b-coder`) |\n| `thinking` | string | Thinking level: `minimal`, `medium`, `high` |\n| `tools` | string | Comma-separated **native pi tools only**: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` |\n| `skills` | string | Comma-separated skill names to auto-load |\n| `session-mode` | string | Default child-session mode: `standalone`, `lineage-only`, or `fork` |\n| `spawning` | boolean | Set `false` to deny all subagent-spawning tools |\n| `deny-tools` | string | Comma-separated extension tool names to deny |\n| `auto-exit` | boolean | Auto-shutdown when the agent finishes its turn — no `subagent_done` call needed. If the user sends any input, auto-exit is permanently disabled and the user takes over the session. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |\n| `interactive` | boolean | derived | Override whether stall/recovery transitions wake the parent session. Defaults to the inverse of `auto-exit`: autonomous agents (`auto-exit: true`) are non-interactive and get stall pings; agents without `auto-exit` are interactive and stay quiet. Explicit values take precedence. |\n| `cwd` | string | Default working directory (absolute or relative to project root) |\n| `disable-model-invocation` | boolean | Hide this agent from discovery surfaces like `subagents_list`. The agent still remains directly invokable by explicit name via `subagent({ agent: \"name\", ... })`. |\n\n---\n\nDiscovery still resolves precedence before visibility filtering. If a project-local hidden agent has the same name as a visible global or bundled agent, the hidden project agent wins and the lower-precedence agent does not appear in `subagents_list`.\n\n### `session-mode`\n\nChoose how a subagent session starts:\n\n- `standalone` — default fresh session with no lineage link to the caller\n- `lineage-only` — fresh blank child session with `parentSession` linkage, but no copied turns from the caller\n- `fork` — linked child session seeded with the caller's prior conversation context\n\n`lineage-only` is useful when you want session discovery and fork lineage UX to show the relationship later, but you do **not** want the child to inherit the parent's turns.\n\n`fork: true` on the tool call always forces the `fork` mode for that specific spawn. `/iterate` uses this explicit override on purpose.\n\n```yaml\n---\nname: planner\nsession-mode: lineage-only\n---\n```\n\n### `auto-exit`\n\nWhen set to `true`, the agent session shuts down automatically as soon as the agent finishes its turn — no explicit `subagent_done` call is needed.\n\n**Behavior:**\n\n- The session closes after the agent's final message (on the `agent_end` event)\n- If the user sends **any input** before the agent finishes, auto-exit is permanently disabled for that session — the user takes over interactively\n- The modeHint injected into the agent's task is adjusted accordingly: autonomous agents see \"Complete your task autonomously.\" rather than instructions to call `subagent_done`\n\n**When to use:**\n\n- ✅ Autonomous agents (scout, worker, reviewer) that run to completion\n- ❌ Interactive agents (planner, iterate) where the user drives the session\n\n```yaml\n---\nname: scout\nauto-exit: true\n---\n```\n\n### `interactive`\n\nControls whether status transitions (`stalled`, `recovered`) wake the parent session with a steer message.\n\n**Default:** the inverse of `auto-exit`. Autonomous agents (`auto-exit: true`) are non-interactive and ping the parent on stall/recovery; agents without `auto-exit` are interactive and stay quiet. Bare spawns with no agent defs (e.g. `/iterate` with `fork: true`) are treated as interactive.\n\n**Why it exists:** Interactive agents can run for minutes or hours while the user thinks, types, and reads in the subagent's pane. Child snapshots still update the widget, but stalled/recovered supervision messages rarely need to wake the parent for user-driven sessions. Skipping the steer keeps the parent quiet until the child actually finishes.\n\n**When to override:**\n\n- Set `interactive: false` on an agent that doesn't auto-exit but you still want stall pings for\n- Set `interactive: true` on an autonomous agent you'd rather check on yourself\n\n```yaml\n---\nname: planner\n# interactive defaults to true because auto-exit is not set\n---\n```\n\nOr per spawn:\n\n```typescript\nsubagent({ name: \"Scout\", agent: \"scout\", interactive: true, task: \"...\" });\n```\n\n---\n\n## Tool Access Control\n\nBy default, every sub-agent can spawn further sub-agents. Control this with frontmatter:\n\n### `spawning: false`\n\nDenies all subagent lifecycle tools (`subagent`, `subagent_interrupt`, `subagents_list`, `subagent_resume`):\n\n```yaml\n---\nname: worker\nspawning: false\n---\n```\n\n### `deny-tools`\n\nFine-grained control over individual extension tools:\n\n```yaml\n---\nname: focused-agent\ndeny-tools: subagent\n---\n```\n\n### Recommended Configuration\n\n| Agent | `spawning` | Rationale |\n| ---------- | ----------- | -------------------------------------------- |\n| planner | _(default)_ | Legitimately spawns scouts for investigation |\n| worker | `false` | Should implement tasks, not delegate |\n| researcher | `false` | Should research, not spawn |\n| reviewer | `false` | Should review, not spawn |\n| scout | `false` | Should gather context, not spawn |\n\n---\n\n## Role Folders\n\nThe `cwd` parameter lets sub-agents start in a specific directory with its own configuration:\n\n```\nproject/\n├── agents/\n│ ├── game-designer/\n│ │ └── CLAUDE.md ← \"You are a game designer...\"\n│ ├── sre/\n│ │ ├── CLAUDE.md ← \"You are an SRE specialist...\"\n│ │ └── .pi/skills/ ← SRE-specific skills\n│ └── narrative/\n│ └── CLAUDE.md ← \"You are a narrative designer...\"\n```\n\n```typescript\nsubagent({ name: \"Game Designer\", cwd: \"agents/game-designer\", task: \"Design the combat system\" });\nsubagent({ name: \"SRE\", cwd: \"agents/sre\", task: \"Review deployment pipeline\" });\n```\n\nSet a default `cwd` in agent frontmatter:\n\n```yaml\n---\nname: game-designer\ncwd: ./agents/game-designer\nspawning: false\n---\n```\n\n---\n\n## Tools Widget\n\nEvery sub-agent session displays a compact tools widget showing available and denied tools. Toggle with `Ctrl+J`:\n\n```\n[scout] — 12 tools · 4 denied (Ctrl+J) ← collapsed\n[scout] — 12 available (Ctrl+J to collapse) ← expanded\n read, bash, edit, write, todo, ...\n denied: subagent, subagents_list, ...\n```\n\n---\n\n## Requirements\n\n- [pi](https://github.com/badlogic/pi-mono) — the coding agent\n- One supported multiplexer:\n - [cmux](https://github.com/manaflow-ai/cmux)\n - [tmux](https://github.com/tmux/tmux)\n - [zellij](https://zellij.dev)\n - [WezTerm](https://wezfurlong.org/wezterm/)\n\n```bash\ncmux pi\n# or\ntmux new -A -s pi 'pi'\n# or\nzellij --session pi # then run: pi\n# or\n# just run pi inside WezTerm\n```\n\nOptional backend override:\n\n```bash\nexport PI_SUBAGENT_MUX=cmux # or tmux, zellij, wezterm\n```\n\n---\n\n## Acknowledgements\n\nThe sub-agent status supervision and turn-only interruption features were inspired by [RepoPrompt](https://repoprompt.com/)'s sub-agent snapshot polling and run cancellation features.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}