@selesai/code 0.5.29 → 0.6.2

package/dist/extensions/pi-subagents/agents/recapper.md

@@ -1,12 +1,13 @@
 ---
 name: recapper
-description: Summarizes the current conversation and prepares a handoff document
+description: Read-only handoff and context synthesis
 tools: read, grep, find, ls
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-skill: ponytail, caveman
+skill: ponytail
 defaultContext: fork
+acceptanceRole: read-only
 ---
 
 Create a concise, self-contained handoff for a fresh agent. Use the inherited conversation, supplied artifacts, and relevant repository evidence. Do not edit project files, write output files, or launch subagents.

package/dist/extensions/pi-subagents/agents/researcher.md

@@ -1,13 +1,14 @@
 ---
 name: researcher
-description: Autonomous code-first researcher that produces a focused sourced brief
-tools: read, grep_app_search, grep_app_fetch, web_explore
+description: Read-only external and code-first research
+tools: read, mcp:grep_app_search, mcp:grep_app_fetch, web_explore
 thinking: medium
 systemPromptMode: replace
 inheritProjectContext: false
 inheritSkills: false
 defaultContext: fresh
-skill: ponytail, caveman
+skill: ponytail
+acceptanceRole: read-only
 ---
 
 You are a code-first research subagent. Answer the supplied question with a concise, well-sourced brief. Do not edit project files, write output files, or launch subagents.

package/dist/extensions/pi-subagents/skills/pi-subagents/SKILL.md

@@ -27,6 +27,8 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 
 Selesai default: use Fable-style parent orchestration for complex work (multiple moving parts, unclear acceptance, cross-cutting code, meaningful user impact, expensive validation, or broad review surface). Lightweight one-off delegation stays lightweight.
 
+Routing rule: keep tiny targeted reads and simple answers with the parent. For broad local investigation, external research, or mutation work, call `{ action: "list" }`, choose an executable entry from its runtime metadata, then delegate. Treat list output—not hardcoded role names—as the agent-selection authority.
+
 For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
 
 ## Always-on constraints

package/dist/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md

@@ -5,9 +5,10 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 ## Important Constraints
 
 - **Forking requires a persisted parent session.** If the current session does not
-  have a persisted session file, forked runs fail. Packaged `architect`, `builder`,
-  `commentator`, and `commentator` default to forked context, so use `context: "fresh"` explicitly
-  when that is not available or not wanted.
+  have a persisted session file, forked runs fail. Packaged `architect` and `recapper`
+  default to forked context; `builder`, `commentator`, `explorer`, and `researcher`
+  default to fresh context. Use explicit `context: "fork"` or `context: "fresh"` when
+  you intentionally want one context for every child.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
   filtered contexts. Use fresh context for adversarial commentators unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
@@ -18,7 +19,7 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 - **Keep conversational authority clear.** Advisory subagents should not silently
   become second decision-makers.
 
-Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `subagent_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `project` (default), `session`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Per-run `artifacts: false` disables artifact capture for that launch. Async status and result artifacts are versioned with fields such as `lifecycleArtifactVersion`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Child protocol failures expose a structured `protocolError`; `protocol_output_limit` means a child emitted a JSONL line above the 4 MiB live-parser cap. Prefer these artifacts and `status` views over scraping terminal output.
+Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `subagent_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `project` (default), `session`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Artifact capture is off by default; set per-run `artifacts: true` when debug files are needed. Async status and result artifacts are versioned with fields such as `lifecycleArtifactVersion`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Child protocol failures expose a structured `protocolError`; `protocol_output_limit` means a child emitted a JSONL line above the 4 MiB live-parser cap. Prefer these artifacts and `status` views over scraping terminal output.
 
 ## Best Practices
 
@@ -91,7 +92,7 @@ Fable mode is the default orchestration posture for complex work. It is not a se
 
 Run the work through seven gated phases:
 
-1. **Understand** — use `explorer` or `explorer` fanout for breadth, but the parent personally reads the load-bearing files and lets direct source reading decide disagreements. Gate: the parent can quote the exact code or behavior being changed and knows the repo's verification harness.
+1. **Understand** — use `explorer` fanout for breadth, but the parent personally reads the load-bearing files and lets direct source reading decide disagreements. Gate: the parent can quote the exact code or behavior being changed and knows the repo's verification harness.
 2. **Decide** — separate user-owned decisions from implementation judgments. Use `interview` for product, naming, cost, taste, or risk decisions; decide routine engineering details in the parent and state them. Gate: every user-owned decision needed for design is answered.
 3. **Design** — use `architect`, `explorer`, or read-only design/review children for parallel perspectives. Before parallel workstreams, write seam contracts: ownership boundaries, composition points, assumptions, and validation handoffs. Gate: one parent-synthesized plan and written seams for parallel work.
 4. **Implement** — capture a baseline first, then launch one async `builder` as the sole writer for the active worktree unless isolated worktrees were intentionally requested. Break large work into serial milestones instead of concurrent writes. Gate: build/typecheck is green and every output or diff delta is characterized as intended or fixed.
@@ -103,7 +104,7 @@ Run the work through seven gated phases:
 
 For straightforward non-trivial work, this sequence is the lightweight version of the parent-owned loop. When the task is complex, use Fable mode above. In either case, factor in the packaged prompt workflows without literally invoking slash commands. Use the same patterns through tools and subagents.
 
-Keep builtin agent defaults unless the user explicitly asks for a different model, thinking level, skills, output behavior, context mode, or other override. Do not add overrides just because you are orchestrating; the defaults encode the intended role behavior. In particular, packaged `architect`, `builder`, `commentator`, and `commentator` default to forked context.
+Keep builtin agent defaults unless the user explicitly asks for a different model, thinking level, skills, output behavior, context mode, or other override. Do not add overrides just because you are orchestrating; the defaults encode the intended role behavior. In particular, packaged `architect` and `recapper` default to forked context; `builder`, `commentator`, `explorer`, and `researcher` default to fresh context.
 
 When the user approves launching a subagent to carry out a plan or workflow, treat that as approval to generate a proper role-specific meta prompt for that subagent. Include the approved plan path or summary, clarified requirements, non-goals, relevant context, role boundaries, files or areas to inspect, acceptance criteria, expected output, and validation expectations. Do not pass vague instructions like “implement the plan fully” or “review this” by themselves.
 
@@ -125,7 +126,7 @@ The validation contract defines acceptance before code is written: expected beha
 
 Use the structured `acceptance` field when the run should carry an explicit acceptance contract. If omitted, subagents infer an effective policy from role, mode, and risk. Evidence levels end at `verified`: use `level: "checked"` for ordinary writer evidence and `level: "verified"` when the runtime should run explicit validation commands. Independent review is orthogonal; use `review: { required: true, agent: "commentator" }` and orchestrate the commentator separately. `review-required` means evidence passed but review is pending, while `reviewed` means a real independent result found no blockers. For commentator/read-only calls, omit `acceptance`. Never explicitly request `level: "reviewed"`; that value remains recognized only so preflight can return an actionable correction. To disable gates, use `{ level: "none", reason: "..." }`; the bare string `"none"` is rejected, and `false` is accepted only as a deprecated shorthand. Child-reported command success is evidence, not runtime verification.
 
-The first `builder` implements the approved plan. The parent continues with independent inspection or validation prep while it runs, not parallel edits to the same worktree. When the async builder completes, treat its handoff as the transition into review, not as final completion, unless the user explicitly asked for builder-only work, review-only output, or to stop after implementation. Parallel commentators inspect the resulting diff from fresh context. Validators check behavior with the best available evidence: commands, tests, browser/CLI interaction, screenshots, logs, or manual reproduction notes. The final `builder` applies synthesized review fixes in forked context, then the parent looks over the final diff before completing. The parent may launch these steps as an initial async chain when the workflow is already clear, or as follow-up subagent runs after each async completion. Initial chains should pass `async: true` so the main chat is unblocked; avoid `clarify: true` unless the user asked for foreground clarification. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
+The first `builder` implements the approved plan. The parent continues with independent inspection or validation prep while it runs, not parallel edits to the same worktree. When the async builder completes, treat its handoff as the transition into review, not as final completion, unless the user explicitly asked for builder-only work, review-only output, or to stop after implementation. Parallel commentators inspect the resulting diff from fresh context. Validators check behavior with the best available evidence: commands, tests, browser/CLI interaction, screenshots, logs, or manual reproduction notes. The final `builder` applies synthesized review fixes with an explicit `context: "fork"` when the fix needs inherited parent context, then the parent looks over the final diff before completing. The parent may launch these steps as an initial async chain when the workflow is already clear, or as follow-up subagent runs after each async completion. Initial chains should pass `async: true` so the main chat is unblocked; avoid `clarify: true` unless the user asked for foreground clarification. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
 
 For complex work, risky changes, broad refactors, or many changed lines, increase review and validation fanout rather than trusting one commentator. Use distinct angles such as correctness/regressions, tests/validation, simplicity/maintainability, security/privacy, performance, docs/API contracts, and user-flow behavior. When commentators find non-trivial issues or the fix builder touches many lines, run another focused review round before final validation.
 
@@ -135,10 +136,10 @@ For very large work, split into serial milestones instead of launching a swarm o
 
 Keep orchestration authority in the parent session. Child subagents should not launch more subagents, read this skill, or run their own orchestration loops unless the parent intentionally selected a fanout agent whose builtin `tools` includes `subagent`. Spawned subagents do not receive the `pi-subagents` skill, parent-only status/control/slash messages, or prior parent `subagent` tool-call/tool-result artifacts. Ordinary children also do not receive the `subagent` extension tool. Child context filtering strips old hidden orchestration-instruction messages when they appear in inherited history. Every child receives a boundary instruction: ordinary children are told the parent owns orchestration and they must not propose or run subagents; explicit fanout children are told to use `subagent` only for the assigned fanout work, with `maxSubagentDepth` still enforced. Implementation children must call real edit/write tools instead of printing pseudo tool calls. Pass children concrete role-specific work instead.
 
-1. Clarify first. This is mandatory. Gather code context with `explorer` or `explorer`, add `researcher` only when external evidence matters, then ask the user clarifying questions with `interview` until scope, acceptance criteria, constraints, and non-goals are clear.
+1. Clarify first. This is mandatory. Gather code context with `explorer`, add `researcher` only when external evidence matters, then ask the user clarifying questions with `interview` until scope, acceptance criteria, constraints, and non-goals are clear.
 2. Define the validation contract. State acceptance before implementation: expected behavior, checks to run, user flows to exercise, and evidence required in the builder handoff. For UI, CLI, integration, or workflow changes, include at least one validator angle that uses the product the way a user would rather than only reading code.
 3. Plan when useful. For complex work, call `architect` or write a plan doc yourself and get approval before implementation. For simple work, confirm shared understanding and explicitly note why planning is skipped.
-4. Implement with one writer. After approval, launch `builder` asynchronously with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. Packaged `builder` defaults to forked context; pass `context: "fresh"` only when you intentionally want a fresh child. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
+4. Implement with one writer. After approval, launch `builder` asynchronously with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. Packaged `builder` defaults to fresh context; pass `context: "fork"` only when inherited parent context is intentionally required. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
 5. Require a useful builder handoff. Ask the builder to report changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises or new risks, decisions made inside approved scope, and decisions needing parent approval.
 6. Review after implementation. After the builder completes, launch parallel async fresh-context `commentator` agents for correctness/regressions, tests/validation, and simplicity/maintainability. Add security, performance, docs/API, domain-specific, or user-flow validators for complex work, risky changes, broad refactors, or many changed lines. Use `output: false` unless review artifacts are explicitly needed.
 7. Synthesize, then run the fix builder. Separate blockers, fixes worth doing now, optional improvements, and feedback to ignore/defer, then launch an async forked `builder` to apply fixes worth doing now when the workflow is implementation-authorized. If commentators found scope/product/architecture choices that were not approved, ask the user first instead of applying them.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md

@@ -6,12 +6,12 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 
 Agent files can live in:
 - `~/.selesai/agent/agents/**/*.md` — user scope
-- `.pi/agents/**/*.md` — canonical project scope
-- legacy `.agents/**/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
+- `.selesai/agents/**/*.md` — canonical project scope
+- legacy `.agents/**/*.md` — still read for compatibility, but `.selesai/agents/` wins on conflicts
 
 Chains live in:
 - `~/.selesai/agent/chains/**/*.chain.md` and `~/.selesai/agent/chains/**/*.chain.json` — user scope
-- `.pi/chains/**/*.chain.md` and `.pi/chains/**/*.chain.json` — project scope
+- `.selesai/chains/**/*.chain.md` and `.selesai/chains/**/*.chain.json` — project scope
 
 Discovery is recursive. `.chain.md` files do not define agents. Use `.chain.md` for simple saved chains and `.chain.json` for dynamic fanout or inline schema objects. Agents and chains can set optional frontmatter/package metadata; `name: explorer` plus `package: code-analysis` registers as runtime name `code-analysis.explorer` while serialization keeps `name` and `package` separate.
 
@@ -20,7 +20,7 @@ Precedence is by parsed runtime name:
 2. user scope
 3. builtin agents
 
-Project settings resolve from the nearest parent directory containing `.pi` or `.agents` by default. In monorepos or git worktrees where an incidental nested `.pi` directory should not shadow the repository config, set `subagents.projectRootResolution: "git-root"` in the repository root `.selesai/settings.json`; a nested project can opt back with `"nearest"` in its own settings.
+Project settings resolve from the nearest parent directory containing a `.selesai` config dir or a legacy `.agents` agent dir by default. In monorepos or git worktrees where an incidental nested `.selesai` directory should not shadow the repository config, set `subagents.projectRootResolution: "git-root"` in the repository root `.selesai/settings.json`; a nested project can opt back with `"nearest"` in its own settings.
 
 ## Running Subagents
 
@@ -88,7 +88,7 @@ subagent({
 })
 ```
 
-Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file. For large saved outputs, set `outputMode: "file-only"` together with an `output` path. The parent result then contains only a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` instead of the full saved content. Do not use `output: false` for this; `output: false` means no file output. In chains, relative `output` paths are chain-artifact paths under `{chain_dir}`, not project CWD paths; use an absolute `output` path or a persistent `chainDir` when a saved artifact must outlive the temp chain directory. Read-only children return the complete artifact in their final response and the runtime persists it, so missing write tools are not a supervisor blocker. Mutation-capable children still receive direct-write instructions. Failed runs and save errors still return inline details for debugging.
+Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file. Delivery is reference-first by default: every child gets a durable saved output unless `output: false`, omitted `output` uses a generated per-run path, omitted `outputMode` resolves to `file-only`, and the parent result contains only a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Inspect full output through the saved path, async status/transcript, or resume. Explicit `outputMode: "inline"` keeps the legacy full inline delivery; `output: false` disables durable result persistence (follow-up visibility falls back to bounded excerpts). Failed runs with a persisted result return the error/status plus the saved-output reference; persistence or read-back failures return only a bounded excerpt (first 80 lines / 4 KiB) together with the error, never raw unbounded output. Do not use `output: false` to get a file-only return; use file-only mode with an output path. In chains, relative `output` paths are chain-artifact paths under `{chain_dir}`, not project CWD paths; use an absolute `output` path or a persistent `chainDir` when a saved artifact must outlive the temp chain directory. Read-only children return the complete artifact in their final response and the runtime persists it, so missing write tools are not a supervisor blocker. Mutation-capable children still receive direct-write instructions.
 
 ### Chain execution
 
@@ -137,7 +137,7 @@ subagent({
 })
 ```
 
-File-only output mode also works for async single runs, top-level parallel task items, sequential chain steps, and chain parallel task items. In chains, `{previous}` receives the compact saved-file reference when the prior step used file-only mode. Relative chain output paths are resolved under `{chain_dir}`; pass a persistent `chainDir` or an absolute `output` path when a later human or process needs a stable path outside the temp chain run.
+File-only output mode also works for async single runs, top-level parallel task items, sequential chain steps, and chain parallel task items. In chains, `{previous}` receives the compact saved-file reference when the prior step used file-only mode. Relative chain output paths are resolved under `{chain_dir}`; pass a persistent `chainDir` or an absolute `output` path when a later human or process needs a stable path outside the temp chain run. Async completion delivery is reference-first: the completion notification and grouped intercom payload carry per-child saved-output references (or `output-<index>.log` references) plus process status, never full child output. Inspect full output through the saved path, `{ action: "status", id, view: "transcript" }`, or resume.
 
 For review fanout where the parent continues a local audit:
 
@@ -353,20 +353,20 @@ worktree, first confirm dependencies were linked, installed, or provisioned by
 ## The commentator Workflow
 
 The intended commentator loop is:
-1. the main agent forks to `commentator`
+1. the main agent launches `commentator` (fresh context by default; pass `context: "fork"` only when a branched advisory thread that inherits the parent session history is intended)
 2. `commentator` reviews direction, drift, assumptions, and risks
 3. `commentator` can coordinate back through `contact_supervisor` when the bridge injects it
 4. the main agent decides what direction to approve
 5. only then should `builder` implement
 
 ```typescript
-// Advisory review in a branched thread. commentator defaults to forked context.
+// Advisory review. commentator defaults to fresh context; fork explicitly when a branched advisory thread is intended.
 subagent({
   agent: "commentator",
   task: "Review my current direction, challenge assumptions, and propose the best next move."
 })
 
-// Implementation only after explicit approval. builder defaults to forked context.
+// Implementation only after explicit approval. builder defaults to fresh context; pass context: "fork" when inherited parent context is intentionally required.
 subagent({
   agent: "builder",
   task: "Implement the approved approach: ..."
@@ -374,8 +374,9 @@ subagent({
 ```
 
 `commentator` is not a fresh-context commentator in the Cognition article sense. It is
-a forked advisory thread that inherits the parent session history and uses that
-history as a baseline contract.
+an advisory thread that reviews direction, drift, and risks against the task/plan.
+Pass `context: "fork"` when the review should inherit the parent session history and
+use that history as a baseline contract; otherwise fresh context is the default.
 
 Use `commentator` as a smart-friend escalation when the parent needs help with trajectory rather than diff inspection: architectural boundaries, model capability routing, merge conflicts, commentator disagreement, context drift after long work, a builder about to invent a pattern, or fixes that require product/scope tradeoffs. Ask broad questions when the right concern is unclear, and let `commentator` point out missing context or files the parent should inspect before asking again. Keep `commentator` advisory unless it has been explicitly assigned the single writer role.
 

package/dist/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md

@@ -11,7 +11,7 @@ Parent extensions may register a session-scoped, out-of-band ceiling through `pi
 - **Complex work orchestration**: use Fable mode as the default parent-agent loop for complex work. Complex means the task has multiple moving parts, unclear acceptance, cross-cutting code, meaningful user-visible impact, expensive or irreversible validation, broad review surface, or the user asks for orchestration. Lightweight one-off delegation can stay lightweight.
 - **Advisory review**: use fresh-context `commentator` agents for adversarial code review, or fork to `commentator` when inherited decisions and drift matter
 - **Implementation handoff**: have `commentator` advise, then `builder` implement only after an approved direction
-- **Recon and planning**: use `explorer` or `explorer`, then `architect`
+- **Recon and planning**: use `explorer`, then `architect`
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
 - **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
 - **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard turn and tool-call caps for explicitly read-only children.
@@ -179,17 +179,16 @@ and user/project agents override builtins with the same name.
 
 | Agent | Purpose | Model | Typical output / role |
 |-------|---------|-------|------------------------|
-| `explorer` | Fast codebase recon | inherits default | Writes `context.md` handoff material |
-| `architect` | Creates implementation plans | inherits default | Writes `plan.md` |
+| `architect` | Creates implementation plans | inherits default | Read-only planning; returns the complete plan in its final response |
 | `builder` | Implementation and approved commentator handoffs | inherits default | Single-writer implementation with decision escalation |
-| `commentator` | Review specialist | inherits default | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
-| `explorer` | Requirements/codebase handoff builder | inherits default | Writes structured context files |
-| `researcher` | Web research brief generator | inherits default | Writes `research.md` |
-| `builder` | Lightweight generic builder | inherits default | No fixed output; generic delegated work |
-| `commentator` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination |
-| `commentator` | Claude Code-compatible alias for `commentator` | inherits default | Same advisory role as `commentator` |
+| `commentator` | Review specialist | inherits default | Review-only findings in its final response; no edit/write tools |
+| `explorer` | Fast codebase recon | inherits default | Read-only recon findings in its final response |
+| `recapper` | Current-state handoff specialist | inherits default | Fork-context handoff; returns a self-contained handoff in its final response |
+| `researcher` | Sourced research brief generator | inherits default | Read-only brief in its final response |
 
-Builtin `builder` and `builder` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
+Only `architect` and `recapper` resolve to forked context when a launch omits `context`; `builder`, `commentator`, `explorer`, and `researcher` default to fresh context. Read-only builtins return their output in the final response; output files are written only when the caller configures output persistence.
+
+Explicit `tools` is an allowlist, but ambient extension discovery remains possible unless `extensions`, `subagentOnlyExtensions`, or a capability ceiling constrains it; naming a tool alone does not load its provider. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
 
 Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. Set `subagents.defaultModel` when subagents should use a different default model than the parent session. Override builtin defaults before copying full agent files when a small tweak is enough.
 
@@ -266,7 +265,7 @@ agent with the same name only when you want a substantially different agent.
 When several providers are available, route agents by task shape instead of one model for everything:
 
 1. **Fast workhorse** — cheapest capable model at low thinking for recon, lookups, and mechanical edits (for example on `explorer`).
-2. **Standard well-scoped** — mid-tier model at medium thinking for most delegations: routine multi-file edits, focused reviews, straightforward implementation (for example on `builder`, `commentator`, `builder`).
+2. **Standard well-scoped** — mid-tier model at medium thinking for most delegations: routine multi-file edits, focused reviews, straightforward implementation (for example on `builder` and `commentator`).
 3. **Deep but bounded** — top reasoning model at high thinking only for hard tasks that arrive with explicit goals and completion criteria; these models loop on vague goals (for example on `architect` and commentator-style agents).
 4. **Taste and intent** — a model that reads human intent well for ambiguous work: UX/design judgment, product tradeoffs, planning from vague requirements, writing quality.
 

package/dist/extensions/pi-subagents/src/agents/agent-management.ts

@@ -28,13 +28,14 @@ import { discoverAvailableSkills, resolveSkills } from "./skills.ts";
 import {
 	buildProactiveSkillSubagentRecommendationLines,
 } from "./proactive-skills.ts";
+import { formatTaskAwareAgentRecommendation, recommendTaskAwareAgent } from "./task-aware-routing.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
 import { toModelInfo } from "../shared/model-info.ts";
 import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
 import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
-import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
+import type { AcceptanceInput, CatalogAgentMetadata, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
 import { getProjectConfigDir } from "../shared/utils.ts";
 import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 
@@ -48,10 +49,12 @@ interface ManagementParams {
 	chainName?: string;
 	agentScope?: string;
 	config?: unknown;
+	/** Optional advisory intent for action:'list' only; never launches work. */
+	task?: string;
 }
 
-function result(text: string, isError = false): AgentToolResult<Details> {
-	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
+function result(text: string, isError = false, extraDetails: Partial<Details> = {}): AgentToolResult<Details> {
+	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [], ...extraDetails } };
 }
 
 function parseCsv(value: string): string[] {
@@ -585,8 +588,13 @@ function renamePath(
 	return { filePath };
 }
 
+/** Effective declared tools: normal tools plus mcp:-prefixed direct MCP tools. */
+function effectiveAgentTools(agent: AgentConfig): string[] {
+	return [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
+}
+
 function formatAgentDetail(agent: AgentConfig): string {
-	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
+	const tools = effectiveAgentTools(agent);
 	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
 	if (agent.packageName) {
 		lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
@@ -672,6 +680,33 @@ function formatChainDetail(chain: ChainConfig): string {
 	return lines.join("\n");
 }
 
+function formatCatalogAgentLine(agent: AgentConfig): string {
+	const parts: string[] = [agent.source, `context: ${agent.defaultContext ?? "fresh"}`];
+	if (agent.acceptanceRole) parts.push(`role: ${agent.acceptanceRole}`);
+	if (agent.aliases?.length) parts.push(`aliases: ${agent.aliases.join(", ")}`);
+	const tools = effectiveAgentTools(agent);
+	if (tools.length) parts.push(`tools: ${tools.join(", ")}`);
+	return `- ${agent.name} (${parts.join(", ")}): ${agent.description}`;
+}
+
+function catalogAgentMetadata(
+	agent: AgentConfig,
+	executable: boolean,
+	restrictionSources: string[] | undefined,
+): CatalogAgentMetadata {
+	return {
+		name: agent.name,
+		source: agent.source,
+		description: agent.description,
+		executable,
+		...(restrictionSources?.length ? { restrictionSources } : {}),
+		...(agent.aliases?.length ? { aliases: [...agent.aliases] } : {}),
+		defaultContext: agent.defaultContext ?? "fresh",
+		...(agent.acceptanceRole ? { acceptanceRole: agent.acceptanceRole } : {}),
+		tools: effectiveAgentTools(agent),
+	};
+}
+
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
@@ -690,23 +725,35 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		config: ctx.config?.proactiveSkillSubagents,
 		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
 	});
+	const taskAdvice = params.task?.trim()
+		? formatTaskAwareAgentRecommendation(recommendTaskAwareAgent({ task: params.task, agents, capabilityCeiling }))
+		: [];
 	const lines = [
 		"Executable agents:",
-		...(agents.length
-			? agents.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}${a.aliases?.length ? `, aliases: ${a.aliases.join(", ")}` : ""}): ${a.description}`)
-			: ["- (none)"]),
+		...(agents.length ? agents.map(formatCatalogAgentLine) : ["- (none)"]),
 		...(restrictedAgents.length ? [
 			"",
 			`Restricted agents (not executable in this session${restrictedSources?.length ? `; capability ceiling: ${restrictedSources.join(", ")}` : ""}):`,
-			...restrictedAgents.map((a) => `- ${a.name} (${a.source}${a.aliases?.length ? `, aliases: ${a.aliases.join(", ")}` : ""}): ${a.description}`),
+			...restrictedAgents.map(formatCatalogAgentLine),
 		] : []),
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
 		...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
+		...(taskAdvice.length ? ["", ...taskAdvice] : []),
 		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
 	];
-	return result(lines.join("\n"));
+	return result(lines.join("\n"), false, {
+		catalog: {
+			version: 1,
+			agents: [
+				...agents.map((a) => catalogAgentMetadata(a, true, undefined)),
+				...restrictedAgents.map((a) => catalogAgentMetadata(a, false, restrictedSources)),
+			],
+			chains: chains.map((c) => ({ name: c.name, source: c.source, description: c.description })),
+			...(restrictedSources?.length ? { capabilityCeilingSources: restrictedSources } : {}),
+		},
+	});
 }
 
 function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {

package/dist/extensions/pi-subagents/src/agents/task-aware-routing.ts

@@ -0,0 +1,125 @@
+/**
+ * Pure task-aware advisory agent recommender.
+ *
+ * Given an already-discovered, effective agent set and the current capability
+ * ceiling, deterministically selects at most one canonical agent to recommend
+ * for a task, or returns recovery guidance when intent is unknown or no safe
+ * candidate exists. This module is deliberately pure: it performs no
+ * filesystem/discovery access, no alias/chains/executor/RPC/preflight/settings
+ * access, no mutation, launch, scheduling, or persistence, and never writes to
+ * params. Launching stays explicit: the caller must make a separate execution
+ * call with the recommended canonical `agent.name`.
+ */
+
+import type { AgentConfig, AgentSource } from "./agents.ts";
+import { agentHasWriteTools } from "./agent-memory.ts";
+import { classifyTaskMutationIntent, resolveAgentRoutingRole } from "../runs/shared/task-intent.ts";
+import { isAgentAllowedByCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
+
+/** Core tools that make an implementation agent able to write (matches agent-memory). */
+const WRITER_TOOLS = new Set(["edit", "write", "bash"]);
+
+/** Source precedence for deterministic ordering: project > user > package > builtin. */
+const AGENT_SOURCE_PRECEDENCE: Record<AgentSource, number> = { builtin: 0, package: 1, user: 2, project: 3 };
+
+export type TaskAwareAgentIntent = "implementation" | "read-only" | "unknown";
+
+export interface TaskAwareAgentRecommendationAgent {
+	/** Canonical runtime agent name accepted by execution; never an alias. */
+	name: string;
+	source: AgentSource;
+	role: "writer" | "read-only";
+	roleBasis: "declared" | "inferred";
+	reason: string;
+}
+
+export interface TaskAwareAgentRecommendation {
+	intent: TaskAwareAgentIntent;
+	agent?: TaskAwareAgentRecommendationAgent;
+	/** Recovery guidance when no safe recommendation exists (unknown intent or no candidate). */
+	next?: string;
+}
+
+/**
+ * Recommend a canonical agent for a trimmed non-empty task, or `undefined` for
+ * an empty/whitespace task (no-op). Never recommends disabled or
+ * capability-disallowed agents, never guesses for unknown intent, and never
+ * outputs an alias or a role-incompatible agent.
+ */
+export function recommendTaskAwareAgent(input: {
+	task: string;
+	agents: AgentConfig[];
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+}): TaskAwareAgentRecommendation | undefined {
+	const task = input.task.trim();
+	if (!task) return undefined;
+
+	const intent = classifyTaskMutationIntent("builder", task).kind;
+	if (intent === "unknown") {
+		return {
+			intent,
+			next: "Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
+		};
+	}
+
+	const candidates: TaskAwareAgentRecommendationAgent[] = [];
+	for (const agent of input.agents) {
+		if (agent.disabled) continue;
+		if (!isAgentAllowedByCapabilityCeiling(agent.name, input.capabilityCeiling)) continue;
+		const role = resolveAgentRoutingRole(agent.name, agent.acceptanceRole);
+		if (!role) continue;
+		const hasWriteTools = agentHasWriteTools(agent);
+		if (intent === "implementation") {
+			if (role !== "writer" || !hasWriteTools) continue;
+			const allowedTools = input.capabilityCeiling?.allowedTools;
+			if (allowedTools !== undefined && !allowedTools.some((tool) => WRITER_TOOLS.has(tool))) continue;
+		} else {
+			if (role !== "read-only" || hasWriteTools) continue;
+		}
+		const roleBasis = agent.acceptanceRole !== undefined ? "declared" : "inferred";
+		candidates.push({
+			name: agent.name,
+			source: agent.source,
+			role,
+			roleBasis,
+			reason: intent === "implementation"
+				? `${roleBasis} writer role with write tools`
+				: `${roleBasis} read-only role without known write tools`,
+		});
+	}
+
+	candidates.sort((a, b) => {
+		const sourceOrder = AGENT_SOURCE_PRECEDENCE[b.source] - AGENT_SOURCE_PRECEDENCE[a.source];
+		if (sourceOrder !== 0) return sourceOrder;
+		const declaredOrder = (a.roleBasis === "declared" ? 0 : 1) - (b.roleBasis === "declared" ? 0 : 1);
+		if (declaredOrder !== 0) return declaredOrder;
+		return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+	});
+
+	const agent = candidates[0];
+	if (!agent) {
+		return {
+			intent,
+			next: intent === "implementation"
+				? "No executable agent has a writer role with write tools for this task. Check the executable/restricted sections above or adjust the capability ceiling."
+				: "No executable agent has a read-only role without known write tools for this task. Check the executable/restricted sections above.",
+		};
+	}
+	return { intent, agent };
+}
+
+/** Text-only advisory lines; `undefined` (empty-task no-op) renders nothing. */
+export function formatTaskAwareAgentRecommendation(recommendation: TaskAwareAgentRecommendation | undefined): string[] {
+	if (!recommendation) return [];
+	const lines = ["Task-aware advisory routing:", `- Intent: ${recommendation.intent}`];
+	if (recommendation.agent) {
+		lines.push(`- Recommended: ${recommendation.agent.name} (${recommendation.agent.source})`);
+		lines.push(`- Reason: ${recommendation.agent.reason}`);
+		lines.push("- Advisory only: no subagent was launched. To proceed, explicitly call subagent with this canonical agent name and the task.");
+	} else {
+		lines.push("- Recommendation: none");
+		lines.push(`- Next: ${recommendation.next ?? "Refine the task wording and retry."}`);
+		lines.push("- Advisory only: no subagent was launched.");
+	}
+	return lines;
+}

package/dist/extensions/pi-subagents/src/api/preflight.ts

@@ -284,7 +284,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		diagnostics.push({ code: "denied_required_tool", severity: "error", message });
 		return { ok: false, code: "denied_required_tool", message, diagnostics };
 	}
-	const artifactsEnabled = input.artifacts !== false;
+	const artifactsEnabled = input.artifacts === true;
 	const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir ?? "project") : undefined;
 	const artifactPaths = artifactsDir ? getArtifactPaths(artifactsDir, runId, agent.name, 0) : undefined;
 	const outputPath = resolveSingleOutputPath(behavior.output, effectiveCwd, effectiveCwd, artifactsDir ? path.join(artifactsDir, "outputs", runId) : undefined);

package/dist/extensions/pi-subagents/src/extension/index.ts

@@ -51,7 +51,7 @@ import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/
 import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
-import { buildSubagentToolDescription } from "./tool-description.ts";
+import { buildSubagentToolDescription, SUBAGENT_PARENT_ROUTING_GUIDANCE } from "./tool-description.ts";
 import {
 	type Details,
 	type SubagentState,
@@ -405,6 +405,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		name: "subagent",
 		label: "Subagent",
 		description: buildSubagentToolDescription(config),
+		// Always-visible active-tool path: rendered into the main system prompt by
+		// buildSystemPrompt (default and custom-prompt branches). Parent-only; the
+		// child-safe fanout registration must not receive this guidance.
+		promptGuidelines: [SUBAGENT_PARENT_ROUTING_GUIDANCE],
 		parameters: SubagentParams,
 
 		prepareArguments(args) {

package/dist/extensions/pi-subagents/src/extension/schemas.ts

@@ -262,7 +262,7 @@ const ControlOverrides = Type.Object({
 
 const SubagentParamsSchema = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
-	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	task: Type.Optional(Type.String({ description: "Task for SINGLE-mode execution, or an optional advisory intent for action:'list' (list only appends a task-aware recommendation and never launches work; explicitly call subagent with the recommended canonical agent name and the task to execute)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
 		description: "Optional management/control action. Omit this field entirely for execution/delegation ({agent, task}, {tasks}, or {chain}); use it only for management/control actions."
@@ -321,7 +321,7 @@ const SubagentParamsSchema = Type.Object({
 	usageBudget: Type.Optional(UsageBudgetOverride),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
-	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
+	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: false)" })),
 	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
 	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
 	sessionDir: Type.Optional(