pi-subagents 0.21.5 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-05-02
+
+### Fixed
+- Detect `pi-intercom` when installed through the documented `pi install npm:pi-intercom` package flow, instead of only checking the legacy local extension path.
+
+### Changed
+- Store and discover saved chain workflows from dedicated chain directories: user chains in `~/.pi/agent/chains/**/*.chain.md` and project chains in `.pi/chains/**/*.chain.md`.
+- Retry foreground subagent fallback models when Pi reports a retryable provider error, such as 429/quota, even if the child process exits successfully.
+- Align single-run async subagent widgets and `/subagents-status` rendering with foreground subagent result styling for parallel, chain, and grouped chain runs, including inline live detail when tool output expansion is enabled, while keeping multi-job async widgets compact.
+- Render async subagent widgets through an adaptive component so active parallel agent rows fit without Pi's fixed string-widget truncation marker.
+- Tell parent agents that async runs are detached and they should end the turn instead of running sleep/poll loops when no independent work remains.
+
+## [0.22.0] - 2026-05-02
+
+### Added
+- Added child-only supervisor contact support for delegated subagents through `contact_supervisor`, with `need_decision` for blocking supervisor replies and `progress_update` for concise non-blocking updates.
+- Pass supervisor intercom metadata into foreground, chain, parallel, and background child runs so the child-facing pi-intercom tool can resolve the delegating session automatically.
+
+### Changed
+- Builtin agents now inherit the user's configured default model instead of pinning `openai-codex/gpt-5.5`; use builtin overrides to pin a model for a role.
+- Hide unsupported thinking levels in subagent clarify and agent-manager pickers when Pi exposes per-model thinking metadata.
+- Updated builtin agent prompts, README, and bundled skill docs to prefer `contact_supervisor` for blocked decisions and avoid child-side routine completion handoffs.
+- Teach reviewer agents that repo-local `progress.md` files are intentional scratch files that should remain untracked and covered by `.gitignore`.
+
+### Fixed
+- Added regression coverage for supervisor metadata propagation into child process environments.
+
 ## [0.21.5] - 2026-05-02
 
 ### Fixed

package/README.md

@@ -112,12 +112,12 @@ A simple rule of thumb: use `scout` before you understand the code, `researcher`
 
 ## Changing a builtin agent's model
 
-You do not need to copy builtin agent files just to change their model.
+Builtin agents inherit your current Pi default model by default. This keeps new installs from depending on a provider you may not have configured. If you want a role to use a specific model, set an override instead of copying the bundled agent file.
 
 For one run, put the override in the command:
 
 ```text
-/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"
+/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"
 ```
 
 For a persistent override, use `/agents`:
@@ -128,7 +128,7 @@ For a persistent override, use `/agents`:
 
 Choose the builtin agent, press `e`, change the model or other fields, then save a user or project override. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
 
-You can also edit settings directly:
+You can also edit settings directly. This example pins the reviewer everywhere, adds a backup model for provider failures, and keeps the other builtins on your normal default model:
 
 ```json
 {
@@ -211,7 +211,7 @@ The package includes reusable prompt templates for common workflows. You do not
 pi install npm:pi-intercom
 ```
 
-Most users do not call `intercom` directly. After `pi-intercom` is installed, `pi-subagents` can automatically give child agents a private coordination channel back to the parent session.
+Most users do not call `intercom` directly. After `pi-intercom` is installed, `pi-subagents` can automatically give child agents a private coordination channel back to the parent session. The bridge recognizes the normal `pi install npm:pi-intercom` package install as well as legacy local extension checkouts.
 
 Use it for work where the child might need a decision instead of guessing:
 
@@ -223,10 +223,9 @@ Run this implementation in the background. If the worker gets blocked or needs a
 Ask oracle to review this plan. If it sees a decision I need to make, have it ask me instead of assuming.
 ```
 
-The child can use two kinds of coordination messages:
+The child can use one dedicated coordination tool:
 
-- `ask`: the child needs a decision or clarification from the parent session
-- `send`: the child sends a short update when blocked or explicitly asked for progress
+- `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan.
 
 Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
 
@@ -333,6 +332,8 @@ You can combine them in either order:
 /run reviewer "review this diff" --bg --fork
 ```
 
+Background runs are detached. If the parent agent has other independent work, it should keep working. If it has nothing useful to do until the background result arrives, it should end the turn instead of running sleep or status-polling loops. Pi will deliver the completion when the run finishes.
+
 The `oracle` and `worker` builtins are designed for an explicit decision loop. A typical pattern is to ask `oracle` for diagnosis and a recommended execution prompt, then only run `worker` after the main agent approves that direction.
 
 ## Clarify and launch UI
@@ -402,9 +403,9 @@ Agent locations, lowest to highest priority:
 | User | `~/.pi/agent/agents/**/*.md` |
 | Project | `.pi/agents/**/*.md` |
 
-Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files are treated as chains, not agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
+Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files do not define agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
 
-Builtin agents load at the lowest priority, so a user or project agent with the same name overrides them. `oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `worker` is the implementation agent for normal tasks and approved oracle handoffs.
+Builtin agents load at the lowest priority, so a user or project agent with the same name overrides them. They do not pin a provider model; they inherit your current Pi default model unless you set `subagents.agentOverrides.<name>.model`. `oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `worker` is the implementation agent for normal tasks and approved oracle handoffs.
 
 The `researcher` builtin uses `web_search`, `fetch_content`, and `get_search_content`; those require [pi-web-access](https://github.com/nicobailon/pi-web-access):
 
@@ -532,14 +533,14 @@ When `extensions` is present, it takes precedence over extension paths implied b
 
 ## Chain files
 
-Chains are reusable `.chain.md` workflows stored next to agent files.
+Chains are reusable `.chain.md` workflows stored separately from agent files.
 
 | Scope | Path |
 |-------|------|
-| User | `~/.pi/agent/agents/**/*.chain.md` |
-| Project | `.pi/agents/**/*.chain.md` |
+| User | `~/.pi/agent/chains/**/*.chain.md` |
+| Project | `.pi/chains/**/*.chain.md` |
 
-Project discovery also reads legacy `.agents/**/*.chain.md` files. Nested subdirectories are discovered recursively. If both locations define the same parsed runtime chain name, `.pi/agents/` wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
+Nested subdirectories are discovered recursively. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
 
 Example:
 
@@ -633,7 +634,7 @@ The package bundles a `pi-subagents` skill that is automatically available to th
 What the bundled skill covers:
 - **Delegation patterns**: when to launch which agent, whether to use single, parallel, chain, or async mode, and whether to use fresh or forked context
 - **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup
-- **GPT-5.5 prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers
+- **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers
 - **Safety boundaries**: child agents must not run subagents, must not invent intercom targets, and must escalate unapproved decisions
 - **Intercom conventions**: when to ask vs send, and how parent-side result delivery works with `pi-intercom`
 - **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action
@@ -887,16 +888,16 @@ Sets the `/agents` list shortcut for opening the new agent/chain template picker
 }
 ```
 
-Controls whether subagents receive runtime intercom coordination instructions and whether `intercom` is auto-added to their tool allowlist when needed.
+Controls whether subagents receive runtime intercom coordination instructions and whether `intercom` and `contact_supervisor` are auto-added to their tool allowlist when needed.
 
 Fields:
 
 - `mode`: default `always`; use `fork-only` to inject only for forked runs, or `off` to disable the bridge.
 - `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated. Relative paths resolve from `~/.pi/agent/extensions/subagent/`.
 
-Bridge activation also requires `pi-intercom` to be installed and enabled, a targetable current session name or fallback alias, and `pi-intercom` in any explicit agent `extensions` allowlist.
+Bridge activation also requires `pi-intercom` to be installed and enabled through `pi install npm:pi-intercom` or a legacy local extension checkout, a targetable current session name or fallback alias, and `pi-intercom` in any explicit agent `extensions` allowlist.
 
-The default injected guidance tells children to use intercom only for coordination: ask when blocked or needing a decision, send updates only when blocked or explicitly asked, and avoid routine completion handoffs.
+The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates, generic `intercom` as fallback plumbing, and avoid routine completion handoffs.
 
 ### `worktreeSetupHook`
 

package/agents/context-builder.md

@@ -2,7 +2,6 @@
 name: context-builder
 description: Analyzes requirements and codebase, generates context and meta-prompt
 tools: read, grep, find, ls, bash, write, web_search, intercom
-model: openai-codex/gpt-5.5
 thinking: medium
 systemPromptMode: replace
 inheritProjectContext: true
@@ -12,7 +11,7 @@ output: context.md
 
 You are a requirements-to-context subagent.
 
-Analyze the user request against the codebase, gather the relevant high-value context, and produce structured handoff material for planning and GPT-5.5 subagent prompts. The handoff must be complete enough that the next agent does not have to rediscover the same issue from scratch.
+Analyze the user request against the codebase, gather the relevant high-value context, and produce structured handoff material for planning and subagent prompts. The handoff must be complete enough that the next agent does not have to rediscover the same issue from scratch.
 
 Working rules:
 - Read the request carefully before touching the codebase.
@@ -41,7 +40,7 @@ When running in a chain, expect to generate two files in the chain directory:
 - stop/escalation rules: when to ask via `intercom`, when enough evidence is enough, and when to stop
 - resolved questions and assumptions
 
-The goal is to hand the planner or another GPT-5.5 subagent exactly enough code and requirement context to act without rediscovering the same ground. Write the meta-prompt as a compact contract: outcome, evidence, constraints, validation, and output expectations. Avoid long procedural scripts unless each step is a real requirement.
+The goal is to hand the planner or another role subagent exactly enough code and requirement context to act without rediscovering the same ground. Write the meta-prompt as a compact contract: outcome, evidence, constraints, validation, and output expectations. Avoid long procedural scripts unless each step is a real requirement.
 
-## Pi-intercom handoff
-If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed context summary back with a blocking `intercom({ action: "ask", ... })` before finishing. Keep the message concise, include the output path, and ask whether the orchestrator wants clarification or deeper context. If no safe target is available, do not guess; return normally.
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed context normally.

package/agents/delegate.md

@@ -3,9 +3,10 @@ name: delegate
 description: Lightweight subagent that inherits the parent model with no default reads
 systemPromptMode: append
 inheritProjectContext: true
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
 inheritSkills: false
 ---
 
 You are a delegated agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
 
-If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed result back with a blocking `intercom({ action: "ask", ... })` before finishing. Stay alive for the reply so you can clarify or do a small follow-up if asked. If no safe target is available, do not guess; return normally.
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return normally when no coordination is needed.

package/agents/oracle.md

@@ -2,7 +2,6 @@
 name: oracle
 description: High-context decision-consistency oracle that protects inherited state and prevents drift
 tools: read, grep, find, ls, bash, intercom
-model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -16,11 +15,9 @@ Your primary job is to prevent the main agent from making hidden, conflicting, o
 
 Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
 
-If you need clarification from the main agent, use `intercom`. If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to phrase coordination.
+If you need clarification from the main agent and runtime bridge instructions are present, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
 
-Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom.
-
-If runtime bridge instructions or the task name a safe orchestrator target, send your final oracle recommendation back with a blocking `intercom({ action: "ask", ... })` before finishing. Stay alive for the reply so you can clarify, revise the recommendation, or produce a worker prompt if asked. If no safe target is available, do not guess; return normally.
+Do not send routine completion handoffs. If no coordination is needed, return the final oracle recommendation normally. Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target.
 
 Core responsibilities:
 - reconstruct inherited decisions, constraints, and open questions from the context
@@ -41,9 +38,9 @@ What you do not do by default:
 
 Working rules:
 - Use `bash` only for inspection, verification, or read-only analysis.
-- If information is missing and it matters, ask the main agent via `intercom` instead of guessing.
-- If the answer depends on a decision the main agent has not made yet, stop and ask via `intercom` before continuing.
-- When bridge instructions are present, send concise intercom messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
+- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` instead of guessing.
+- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` before continuing.
+- When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
 - Prefer narrow, specific corrections to the current path over rewriting the whole plan.
 
 Your output should follow this shape. If no executor handoff is warranted, say so plainly.

package/agents/planner.md

@@ -2,7 +2,6 @@
 name: planner
 description: Creates implementation plans from context and requirements
 tools: read, grep, find, ls, write, intercom
-model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -52,5 +51,5 @@ Anything likely to go wrong, need clarification, or need careful verification.
 
 Keep the plan concrete. Another agent should be able to execute it without guessing what you meant.
 
-## Pi-intercom handoff
-If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send the completed plan back with a blocking `intercom({ action: "ask", ... })` before finishing. Include the plan path or concise plan summary and ask whether the orchestrator wants clarification, revisions, or approval to proceed. If no safe target is available, do not guess; return normally.
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed plan normally.

package/agents/researcher.md

@@ -2,7 +2,6 @@
 name: researcher
 description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
 tools: read, write, web_search, fetch_content, get_search_content, intercom
-model: openai-codex/gpt-5.5
 thinking: medium
 systemPromptMode: replace
 inheritProjectContext: true
@@ -49,5 +48,5 @@ Numbered findings with inline source citations.
 ## Gaps
 What could not be answered confidently. Suggested next steps.
 
-## Pi-intercom handoff
-If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed research brief back with a blocking `intercom({ action: "ask", ... })` before finishing. Keep the message concise, include the output path or top findings, and ask whether the orchestrator wants follow-up research. If no safe target is available, do not guess; return normally.
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed research brief normally.

package/agents/reviewer.md

@@ -2,7 +2,6 @@
 name: reviewer
 description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
 tools: read, grep, find, ls, bash, edit, write, intercom
-model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -54,33 +53,17 @@ Review a PR or issue by understanding the context, then verifying:
 
 ## Working rules
 - Read the plan, progress, and relevant files first when available.
+- Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
 - Use `bash` only for read-only inspection (e.g., `git diff`, `git log`, `git show`, test runs).
 - Do not invent issues. Only report problems you can justify from evidence.
 - Prefer small corrective edits over broad rewrites.
 - If everything looks good, say so plainly.
 - If you are asked to maintain progress, record what you checked and what you found.
 
-## Pi-intercom handoff
-If the `intercom` tool is available and pi-intercom is active, send your completed review back to the orchestrator through pi-intercom before finishing.
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
 
-Use a blocking `ask`, not a fire-and-forget `send`, so you stay alive long enough for the orchestrator to reply with follow-up questions or approval:
-
-```ts
-intercom({
-  action: "ask",
-  to: "<orchestrator-or-parent-session>",
-  message: "Review complete.\n\n<your review feedback>\n\nReply if you want me to inspect a follow-up or clarify anything."
-})
-```
-
-How to pick the target:
-- Prefer an explicit target named in the task or inherited intercom bridge instructions.
-- Otherwise use `intercom({ action: "list" })` and choose the obvious planner/orchestrator/parent session in the same repo.
-- If no safe target is discoverable, do not guess. Return the review normally and note that pi-intercom was unavailable or no target was clear.
-
-After the `ask` returns:
-- If the orchestrator requests clarification or a follow-up review, answer or inspect further, then use `intercom ask` again if another reply is useful.
-- If the orchestrator confirms or does not need more, finish with the same concise review summary.
+Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
 
 ## Review output format
 Structure your findings clearly:

package/agents/scout.md

@@ -2,7 +2,6 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff
 tools: read, grep, find, ls, bash, write, intercom
-model: openai-codex/gpt-5.5
 thinking: low
 systemPromptMode: replace
 inheritProjectContext: true
@@ -47,5 +46,5 @@ Explain how the pieces connect.
 ## Start Here
 Name the first file another agent should open and why.
 
-## Pi-intercom handoff
-If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed scout findings back with a blocking `intercom({ action: "ask", ... })` before finishing. Keep the message concise, include the output path or top findings, and ask whether the orchestrator wants more context. If no safe target is available, do not guess; return normally.
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed scout findings normally.

package/agents/worker.md

@@ -1,11 +1,11 @@
 ---
 name: worker
 description: Implementation agent for normal tasks and approved oracle handoffs
-model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
 defaultContext: fork
 defaultReads: context.md, plan.md
 defaultProgress: true
@@ -19,7 +19,7 @@ Use the provided tools directly. First understand the inherited context, supplie
 
 If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
 
-If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which parent session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed, and stay alive to receive the reply before continuing. Use `intercom({ action: "send", ... })` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Do not finish your final response with a question that requires the orchestrator to choose before you can continue.
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Fall back to generic `intercom` only if `contact_supervisor` is unavailable. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
 
 Default responsibilities:
 - validate the task or approved direction against the actual code
@@ -35,11 +35,11 @@ Working rules:
 - Do not leave placeholder code, TODOs, or silent scope changes.
 - Use `bash` for inspection, validation, and relevant tests.
 - If there is supplied context or a plan, read it first.
-- If implementation reveals a gap in the approved direction, pause and escalate with `intercom({ action: "ask", ... })` instead of silently patching around it with an implicit decision.
-- If implementation reveals an unapproved product or architecture choice, use `intercom({ action: "ask", ... })` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
-- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, ask the orchestrator if blocked, or explicitly report that no edits were made.
-- If you send a blocked/progress update through intercom, keep it short and still return the full structured task result normally.
-- If `intercom` is available and runtime bridge instructions or the task name a safe orchestrator target, send your completed implementation summary back with a blocking `intercom({ action: "ask", ... })` before finishing. Stay alive for the reply so you can clarify or handle a small follow-up if requested. If no safe target is available, do not guess; return normally.
+- If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
+- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
+- If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
+- Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
 
 When running in a chain, expect instructions about:
 - which files to read first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.21.5",
+  "version": "0.23.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/prompts/parallel-context-build.md

@@ -42,7 +42,7 @@ Ask each builder to produce a compact handoff file with:
 - constraints and invariants;
 - risks and unknowns;
 - validation commands or next-best checks;
-- a `meta-prompt` section for the next planner or GPT-5.5 subagent.
+- a `meta-prompt` section for the next planner or role subagent.
 
 After the builders return, synthesize their outputs into:
 - the most important context the next agent needs;

package/prompts/parallel-handoff-plan.md

@@ -2,7 +2,7 @@
 description: Parallel research/context builders into an implementation handoff plan
 ---
 
-Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final GPT-5.5-ready meta-prompt.
+Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final implementation-ready meta-prompt.
 
 Primary request, target, or focus:
 
@@ -48,7 +48,7 @@ Implementation-strategy context-builder, when used:
 Final synthesis context-builder:
 - Read the parallel outputs and produce one concise handoff plan.
 - Include what the feature/change should do, what the external reference teaches, what the local codebase implies, the recommended approach, likely files to change, constraints, non-goals, validation, risks, and unresolved questions.
-- End with a compact GPT-5.5-ready meta-prompt for the next worker/planner.
+- End with a compact implementation-ready meta-prompt for the next worker/planner.
 
 After the chain returns, synthesize the result for me with:
 - the recommended approach;

package/skills/pi-subagents/SKILL.md

@@ -44,7 +44,7 @@ Packaged prompt shortcuts are also available for repeatable workflows. Treat the
 - `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
 - `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
 - `/parallel-context-build` — parallel `context-builder` passes that produce planning handoff context and meta-prompts
-- `/parallel-handoff-plan` — external-reference research plus local `context-builder` passes, followed by a synthesis handoff plan and GPT-5.5-ready meta-prompt
+- `/parallel-handoff-plan` — external-reference research plus local `context-builder` passes, followed by a synthesis handoff plan and implementation-ready meta-prompt
 - `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
 - `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
 
@@ -81,7 +81,7 @@ subagent({
 
 ### Parallel handoff-plan technique
 
-Use this when the user needs a solution brief or implementation-ready handoff from an external reference plus local code context, such as “study this library behavior, inspect our codebase, then produce a GPT-5.5 worker prompt.” Run a chain with a first parallel group and a second synthesis `context-builder` step. The first group usually includes `researcher` for external projects/docs/prompt guidance and `context-builder` for local code context; add a second `context-builder` for implementation strategy only when the scope is large enough to benefit. Use distinct output paths under `handoff/`, then have the synthesis `context-builder` read those outputs and write `handoff/final-handoff-plan.md` with the recommended approach, likely files, constraints, non-goals, validation, risks, unresolved questions, and final compact GPT-5.5-ready meta-prompt.
+Use this when the user needs a solution brief or implementation-ready handoff from an external reference plus local code context, such as “study this library behavior, inspect our codebase, then produce a worker prompt.” Run a chain with a first parallel group and a second synthesis `context-builder` step. The first group usually includes `researcher` for external projects/docs/prompt guidance and `context-builder` for local code context; add a second `context-builder` for implementation strategy only when the scope is large enough to benefit. Use distinct output paths under `handoff/`, then have the synthesis `context-builder` read those outputs and write `handoff/final-handoff-plan.md` with the recommended approach, likely files, constraints, non-goals, validation, risks, unresolved questions, and final compact implementation-ready meta-prompt.
 
 Example shape:
 
@@ -93,7 +93,7 @@ subagent({
       { agent: "context-builder", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
       { agent: "context-builder", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
     ] },
-    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and GPT-5.5-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
+    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and implementation-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
   ],
   context: "fresh"
 })
@@ -114,16 +114,16 @@ and user/project agents override builtins with the same name.
 
 | Agent | Purpose | Model | Typical output / role |
 |-------|---------|-------|------------------------|
-| `scout` | Fast codebase recon | `openai-codex/gpt-5.5` | Writes `context.md` handoff material |
-| `planner` | Creates implementation plans | `openai-codex/gpt-5.5` | Writes `plan.md` |
-| `worker` | Implementation and approved oracle handoffs | `openai-codex/gpt-5.5` | Single-writer implementation with decision escalation |
-| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.5` | Can edit/fix reviewed code |
-| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.5` | Writes structured context files |
-| `researcher` | Web research brief generator | `openai-codex/gpt-5.5` | Writes `research.md` |
-| `delegate` | Lightweight generic delegate | inherits parent model | No fixed output; generic delegated work |
-| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.5` | Advisory review, intercom coordination |
+| `scout` | Fast codebase recon | inherits default | Writes `context.md` handoff material |
+| `planner` | Creates implementation plans | inherits default | Writes `plan.md` |
+| `worker` | Implementation and approved oracle handoffs | inherits default | Single-writer implementation with decision escalation |
+| `reviewer` | Review-and-fix specialist | inherits default | Can edit/fix reviewed code |
+| `context-builder` | Requirements/codebase handoff builder | inherits default | Writes structured context files |
+| `researcher` | Web research brief generator | inherits default | Writes `research.md` |
+| `delegate` | Lightweight generic delegate | inherits default | No fixed output; generic delegated work |
+| `oracle` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination |
 
-Override builtin defaults before copying full agent files when a small tweak is enough.
+Builtin agents inherit the current Pi default model unless a run, user setting, or project setting overrides `model`. Override builtin defaults before copying full agent files when a small tweak is enough.
 
 For one run, use inline config:
 
@@ -133,11 +133,11 @@ For one run, use inline config:
 
 For persistent tweaks, prefer `/agents`: choose the builtin, press `e`, change the model or other fields, then save a user or project override. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
 
-## Prompting GPT-5.5 Subagents
+## Prompting role subagents
 
-Most builtin role agents use GPT-5.5. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
+Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
 
-A strong GPT-5.5 subagent prompt usually includes:
+A strong subagent prompt usually includes:
 - **Goal**: the concrete outcome the child should produce.
 - **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved.
 - **Success criteria**: what must be true before the child can finish.
@@ -183,11 +183,10 @@ Agent files can live in:
 - legacy `.agents/**/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
 
 Chains live in:
-- `~/.pi/agent/agents/**/*.chain.md`
-- `.pi/agents/**/*.chain.md`
-- legacy `.agents/**/*.chain.md`
+- `~/.pi/agent/chains/**/*.chain.md` — user scope
+- `.pi/chains/**/*.chain.md` — project scope
 
-Discovery is recursive. `.chain.md` files are chains, not agents. Agents and chains can set optional frontmatter `package: code-analysis`; `name: scout` plus `package: code-analysis` registers as runtime name `code-analysis.scout` while serialization keeps `name` and `package` separate.
+Discovery is recursive. `.chain.md` files do not define agents. Agents and chains can set optional frontmatter `package: code-analysis`; `name: scout` plus `package: code-analysis` registers as runtime name `code-analysis.scout` while serialization keeps `name` and `package` separate.
 
 Precedence is by parsed runtime name:
 1. project scope
@@ -263,7 +262,9 @@ without forcing each step to rediscover everything.
 
 ### Async/background
 
-Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`. Do not end your turn immediately after launching that async child if you promised to keep working; continue the local inspection or other independent work, then check the async run when its result is needed.
+Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`.
+
+Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection or other independent work, then check the async run when its result is needed. If there is no independent work left and you would only be running `sleep` or status polling commands to wait, end your turn instead. Pi will deliver the async completion when it arrives.
 
 ```typescript
 subagent({
@@ -375,7 +376,7 @@ prefer a single-writer pattern instead.
 The intended oracle loop is:
 1. the main agent forks to `oracle`
 2. `oracle` reviews direction, drift, assumptions, and risks
-3. `oracle` can coordinate back to the orchestrator via `intercom`
+3. `oracle` can coordinate back through `contact_supervisor` when the bridge injects it
 4. the main agent decides what direction to approve
 5. only then should `worker` implement
 
@@ -401,25 +402,28 @@ history as a baseline contract.
 
 `pi-subagents` works without `pi-intercom`. When `pi-intercom` is installed and enabled, the intercom bridge can automatically give child agents a private coordination channel back to the parent session.
 
-Most agents should not call `intercom` directly unless bridge instructions provide a target. Do not invent a target. Use the target from the injected bridge instructions or from a visible needs-attention notice.
+Most agents should not call generic `intercom` directly unless bridge instructions provide a target and `contact_supervisor` is unavailable. Do not invent a target. Prefer the tool from the injected bridge instructions.
 
-Use `intercom` when:
+Use `contact_supervisor` with `reason: "need_decision"` when:
 - a subagent is blocked on a decision
 - a child needs clarification instead of guessing
-- a detached or async child needs to coordinate without waiting for normal tool return flow
-- an advisory agent was explicitly asked to send a concise progress update
+- an approval, product, API, or scope choice is required before continuing safely
+
+Use `contact_supervisor` with `reason: "progress_update"` when:
+- a child is explicitly asked for progress
+- a meaningful discovery changes the plan
+- a long-running child needs to report a blocked/progress checkpoint without waiting for normal tool return flow
 
 Message conventions:
-- `ask` means the child needs a decision or clarification from the parent session.
-- `send` means a short blocked/progress update, only when blocked or explicitly asked.
+- `reason: "need_decision"` waits for the parent reply and returns it to the child.
+- `reason: "progress_update"` is non-blocking and should stay concise.
 - Child-side routine completion handoffs are not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
 
-If a bridge target is available, a child can ask:
+If bridge instructions provide the child-facing tool, a child can ask:
 
 ```typescript
-intercom({
-  action: "ask",
-  to: "<bridge-provided-target>",
+contact_supervisor({
+  reason: "need_decision",
   message: "Should I optimize for readability or performance here?"
 })
 ```
@@ -607,7 +611,7 @@ When the user approves launching a subagent to carry out a plan or workflow, tre
 - `/parallel-review` maps to: launch fresh-context `reviewer` agents with distinct review angles; synthesize the feedback before applying anything.
 - `/parallel-research` maps to: combine local `scout` context with external `researcher` evidence when current docs, ecosystem behavior, or API details matter.
 - `/parallel-context-build` maps to: run a chain-mode parallel group of `context-builder` agents with distinct temp output paths, then synthesize their context and meta-prompt sections.
-- `/parallel-handoff-plan` maps to: run external `researcher` plus local/strategy `context-builder` passes, then a synthesis `context-builder` that writes an implementation handoff plan and GPT-5.5-ready meta-prompt.
+- `/parallel-handoff-plan` maps to: run external `researcher` plus local/strategy `context-builder` passes, then a synthesis `context-builder` that writes an implementation handoff plan and implementation-ready meta-prompt.
 - `/parallel-cleanup` maps to: use review-only cleanup passes after implementation, especially for simplicity, verbosity, and redundant tests.
 
 For feature work, use this sequence as scaffolding for parent-agent behavior:

package/src/agents/agent-management.ts

@@ -459,7 +459,9 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const scope = scopeRaw as ManagementScope;
 	const isChain = hasKey(cfg, "steps");
 	const d = discoverAgentsAll(ctx.cwd);
-	const targetDir = scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
+	const targetDir = isChain
+		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(ctx.cwd, ".pi", "chains")
+		: scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
 	fs.mkdirSync(targetDir, { recursive: true });
 	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
 	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);