@selesai/code 0.5.28 → 0.6.1

package/docs/plans/subagent-delegation/phase-2-context-controls.md

@@ -0,0 +1,282 @@
+# Phase 2 Plan — Minimize Parent Context from Delegated Work
+
+## Verified findings
+
+- **High — foreground non-intercom results leak full child output:** `src/extensions/pi-subagents/src/runs/foreground/subagent-executor.ts:3237-3245` aggregates full parallel output; `runSinglePath` returns `finalizeSingleOutput(...).displayOutput`; `compactForegroundDetails()` retains `results[].finalOutput`.
+- **High — intercom moves, rather than minimizes, full output:** `src/extensions/pi-subagents/src/intercom/result-intercom.ts:244-269` places full `summary` text in the grouped event. The compact receipt only applies after acknowledged delivery.
+- **High — async notifications expose full summaries:** `background/subagent-runner.ts:4135-4146` builds a full-output summary; `background/notify.ts:137-151` sends it as a model-visible `subagent-notify` message.
+- **Medium — durable non-debug paths already exist:** explicit `output` persistence in `single-output.ts:173-208` works independently of `artifacts`; async always writes `asyncDir/output-<index>.log`.
+- **Medium — chain terminal content is already concise, but details/intercom are not:** `shared/formatters.ts:58-90` emits a chain summary, while `details.results`/`details.outputs` and grouped intercom payloads can retain child text.
+- **Medium — file-only is reusable but opt-in:** `finalizeSingleOutput()` emits only `SavedOutputReference.message` for `file-only`; tests cover read-only runtime persistence in `single-execution.test.ts:2478`.
+
+## Design decision
+
+Use the existing `output`, `outputMode: "file-only"`, saved-output reference, async output logs, `status`, transcript, and `resume` mechanisms. Do **not** add a new public “summary delivery” API, new artifact service, or dependency.
+
+New default policy:
+
+1. Every delegated child gets a durable result path unless the caller explicitly uses `output: false`.
+2. Omitted `outputMode` resolves to `file-only` when a result path exists; explicit `outputMode: "inline"` retains legacy full-output delivery.
+3. Full output is persisted independently of `artifacts: true`; debug artifacts remain opt-in.
+4. Successful normal delivery contains references and lifecycle/status information, not child prose.
+5. If persistence or reference reading fails, return a bounded fallback only: first **80 lines / 4 KiB**, prefixed with the persistence error and stating that full output is unavailable. Reuse `truncateOutput`; do not fall back to unbounded output.
+
+`output: false` remains a compatibility escape hatch: no generated output file and bounded inline delivery. Explicit `outputMode: "file-only"` plus `output: false` remains a pre-spawn validation error.
+
+## Data contract
+
+No new public tool parameter is required.
+
+| Field/surface | Contract |
+|---|---|
+| `SingleResult.savedOutputPath` / `outputReference` | Authoritative full-output location and byte/line metadata. Present for generated or explicit saved outputs, including failed children that produced output. |
+| `SingleResult.finalOutput` | `Output saved to: …` reference for default/file-only delivery; bounded fallback only when persistence failed; full text only with explicit `outputMode:"inline"`. |
+| `Details.results[]` | Terminal parent-facing details must omit raw `messages`, raw `finalOutput`, `truncation`, and chain `outputs` text. Keep status, error, output reference/path, session, transcript, acceptance, and compact tool-call metadata. |
+| Foreground tool-result `content` | Compact run receipt/reference list. No child prose by default. |
+| Intercom payload child `summary` | Saved-output/async-log reference plus process status; never full child output by default. |
+| Async `result.json` | May retain internal result text until watcher delivery, but parent-facing notifier/intercom delivery must use references to `asyncDir/output-<index>.log` or explicit saved outputs. |
+| Failure fallback | A bounded context slice with the write/read error and intended path. It must not claim a full artifact exists. |
+
+## Ordered implementation tasks
+
+### 1. Make saved-output persistence usable for default and failed delivery
+
+**Discovery**
+- Re-read `runs/shared/single-output.ts`, especially `resolveSingleOutput()` and `finalizeSingleOutput()`.
+- Trace all callers in `foreground/execution.ts` and background runner step execution before editing.
+- Confirm async `output-<index>.log` contains the child’s final output, not merely progress.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/runs/shared/single-output.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/foreground/execution.ts`.
+- Update `src/extensions/pi-subagents/test/unit/single-output.test.ts`.
+- Update focused cases in `test/integration/single-execution.test.ts`.
+
+**Change**
+- Export a small internal context-fallback limit (`bytes: 4096`, `lines: 80`) beside existing output helpers; reuse existing `truncateOutput()`.
+- Add a formatter that produces a bounded persistence-failure fallback containing:
+  - process error/status,
+  - intended output path,
+  - persistence/read error,
+  - bounded output slice.
+- Call `resolveSingleOutput()` whenever an output path is configured and meaningful child output exists, not only for `exitCode === 0`.
+- Preserve existing child-authored-file precedence and snapshot safety.
+- Update `finalizeSingleOutput()` so failed runs with a successfully persisted result return error/status plus the saved-output reference, rather than raw output.
+- Do not change `formatSavedOutputReference()` wording or make debug artifacts mandatory.
+
+**Verification**
+- Successful child-written and runtime-persisted outputs retain full file contents.
+- Failed child with output gets a reference and readable file.
+- Failed write/read produces only the bounded fallback.
+- Existing explicit inline behavior remains unchanged when selected.
+
+### 2. Resolve generated paths and default delivery consistently by execution mode
+
+**Discovery**
+- Trace `resolveSingleRunOutputBaseDir()` and top-level parallel path namespacing in `subagent-executor.ts`.
+- Trace foreground chain output resolution in `chain-execution.ts`.
+- Trace async step construction in `async-execution.ts` and result-log creation in `subagent-runner.ts`.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/runs/foreground/subagent-executor.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/foreground/chain-execution.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/background/async-execution.ts`.
+- Modify only necessary type declarations in `src/extensions/pi-subagents/src/shared/types.ts` and `runs/shared/parallel-utils.ts`.
+- Update `test/integration/single-execution.test.ts`, `parallel-execution.test.ts`, and `async-execution.test.ts`.
+
+**Change**
+- Resolve omitted output as a generated per-child relative file name:
+  - foreground single: `<singleRunOutputBaseDir>/<runId>/result.md`;
+  - foreground top-level parallel: existing per-task namespace plus `result.md`;
+  - foreground chain: `<chainDir>/outputs/<flat-index>-<agent>.md`;
+  - async single/parallel/chain: `<asyncDir>/outputs/<flat-index>-<agent>.md`, while retaining existing `output-<index>.log` as status/transcript recovery.
+- Preserve explicit absolute and relative `output` paths, existing duplicate-path validation, and `output: false`.
+- Resolve omitted `outputMode` to `file-only` when an output path is active. Preserve explicit `"inline"` exactly.
+- Keep chain handoff semantics valid: later `{previous}`/`{outputs.name}` consumers receive the existing file reference for file-only steps and can read the named path; do not re-inline child prose merely for chaining.
+- Ensure generated output paths are passed to child task and system-prompt instructions through existing `injectSingleOutputInstruction()` / `injectOutputPathSystemPrompt()`.
+- Do not add frontmatter-only defaults to builtin agents: those would collide in chains and fail to cover custom agents. Runtime-generated per-run paths own this behavior.
+
+**Mode acceptance matrix**
+- **Foreground single:** compact saved-output reference; explicit inline opt-out remains full text.
+- **Foreground parallel:** one compact result per child, each with status and output reference.
+- **Foreground chain:** existing chain completion summary plus chain/output paths; no step prose in terminal parent result.
+- **Async launch:** existing concise launch receipt unchanged.
+- **Async completion:** compact references to explicit saved output or `asyncDir/output-<index>.log`.
+- **Status/transcript:** remain the path to inspect output; `resume` continues using existing session persistence.
+- **Errors, pause, stop, timeout:** retain process error/status and recovery instructions; attach a saved-output/log reference if available, otherwise bounded fallback.
+
+### 3. Strip terminal foreground details and intercom payloads of raw output
+
+**Discovery**
+- Inspect `compactForegroundDetails()` in `shared/utils.ts`.
+- Inspect `maybeBuildForegroundIntercomReceipt()` and `resultSummaryForIntercom()` in `subagent-executor.ts`.
+- Inspect `stripDetailsOutputsForIntercomReceipt()` in `intercom/result-intercom.ts`.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/shared/utils.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/foreground/subagent-executor.ts`.
+- Modify `src/extensions/pi-subagents/src/intercom/result-intercom.ts`.
+- Update `test/integration/foreground-result-size.test.ts`.
+- Update `test/integration/intercom-result-delivery.test.ts`.
+
+**Change**
+- Add one shared terminal-result projection based on the existing intercom stripping pattern. It must remove raw child output from terminal `Details`, including chain `details.outputs` text/structured payloads, while retaining references and operational metadata.
+- Apply that projection for all completed foreground modes, not just acknowledged intercom receipts.
+- Keep remembered foreground state able to recover output from `savedOutputPath` first; do not retain full `finalOutput` in memory when an authoritative path exists.
+- Change foreground intercom child summaries from `getSingleResultOutput()` to the saved-output reference. Include error/status before the reference for failed children.
+- Keep the current 500 ms intercom acknowledgement behavior:
+  - acknowledged relay: compact receipt and stripped details;
+  - unavailable/unacknowledged relay: compact native foreground receipt, not legacy full child output;
+  - explicit `outputMode:"inline"` is the sole compatibility opt-out for full foreground output.
+- Do not alter supervisor-request/detached-run routing.
+
+**Verification**
+- Bridge-on and bridge-off foreground single, parallel, and chain responses contain no child prose by default.
+- Intercom payloads contain references, not full output.
+- Explicit inline still exposes legacy content.
+- `JSON.stringify(result)` remains below current payload-size protections.
+
+### 4. Make async notifier and grouped intercom delivery reference-only
+
+**Discovery**
+- Trace `summary` creation in `background/subagent-runner.ts`.
+- Trace result-file normalization and delivery in `background/result-watcher.ts`.
+- Trace `buildCompletionDetails()`, `formatSingleCompletion()`, and `formatGroupedCompletion()` in `background/notify.ts`.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/runs/background/subagent-runner.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/background/result-watcher.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/background/notify.ts`.
+- Update `test/integration/async-execution.test.ts`.
+- Update `test/integration/result-watcher.test.ts`.
+- Update `test/unit/notify.test.ts`.
+
+**Change**
+- Persist/retain each async child’s authoritative output location in the result payload: explicit `savedOutputPath` when present, otherwise its existing `asyncDir/output-<index>.log`.
+- At watcher delivery time, build compact child summaries from that path using `formatSavedOutputReference()`; do not use `results[].output` or run `summary` as parent-facing text.
+- Build the local `subagent-notify` content from the same compact run receipt so notification and intercom behavior match.
+- Preserve grouped intercom acknowledgement semantics:
+  - acknowledged grouped delivery suppresses duplicate local notification;
+  - unacknowledged or disabled grouped delivery sends the compact local notifier;
+  - session-lease and result-file retry/unlink behavior remains unchanged.
+- On absent/unreadable output log, include process error and bounded fallback only; do not emit raw `result.json.summary`.
+- Preserve full internal `result.json` data only until watcher consumption; the durable parent reference must be the output path/log, not the deletable result queue file.
+
+**Verification**
+- Async success emits a notification/intercom message with output-log or saved-output reference only.
+- Async failed, paused, stopped, and timed-out cases retain status, error, and recovery guidance.
+- Intercom acknowledgement still suppresses duplicate notifier delivery.
+- Watcher retry on notifier failure leaves the result file intact.
+
+### 5. Document migration and rebuild packaged assets
+
+**Discovery**
+- Re-read current output instructions in:
+  - `src/extensions/pi-subagents/README.md:647-671,1446-1486`;
+  - `src/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md:91,140-156`;
+  - `src/extensions/pi-subagents/src/extension/tool-description.ts`.
+- Coordinate with Phase 0/1 edits before resolving overlapping wording.
+
+**Files**
+- Modify `src/extensions/pi-subagents/README.md`.
+- Modify `src/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md`.
+- Modify `src/extensions/pi-subagents/src/extension/tool-description.ts` only if Phase 1 has not already incorporated the final contract.
+- Regenerate `dist/extensions/pi-subagents/**` with the root build; do not hand-edit generated copies.
+
+**Change**
+- State that normal delegated results are reference-first and full output is inspected through saved output, async status/transcript, or resume.
+- Document explicit `outputMode:"inline"` as compatibility opt-out.
+- Document `output:false` as disabling durable result persistence and causing bounded fallback visibility.
+- State that generated output paths persist with `artifacts:false`; debug `_input`, `_output`, metadata, and transcript artifacts remain opt-in.
+- Correct old claims that failed runs always return full inline debugging output.
+- Keep examples using explicit output paths where humans or later processes need stable project-owned names.
+
+## Migration and compatibility
+
+- This is an intentional behavior change for omitted `outputMode`: default delivery becomes file-only/reference-first.
+- Existing callers requiring full terminal text must set `outputMode:"inline"`.
+- Existing callers with explicit `output` keep that path; generated paths affect only omitted output.
+- Existing `output:false` behavior remains available, but loses full durable recovery by design.
+- No external protocol version bump is needed if new fields are additive and result files remain backward-readable. Treat absent saved-path fields as legacy and use bounded fallback.
+- Do not expose `maxOutput` as a new Phase 2 API; its current undocumented semantics are unrelated. Use a fixed internal fallback cap only.
+
+## Phase dependencies
+
+- **Phase 0:** must land its corrected role/output documentation first, or Phase 2 documentation will conflict with stale “write/no-write” and context claims. Runtime work is otherwise independent.
+- **Phase 1:** should land before the final `tool-description.ts` wording so the always-visible delegation contract can describe reference-first completion once, without duplicate edits. Runtime Phase 2 code does not depend on Phase 1 catalog changes.
+- **No dependency on Phase 3/4:** advisory routing and enforcement must not be coupled to output delivery.
+
+## Test commands
+
+```sh
+cd src/extensions/pi-subagents
+node --experimental-strip-types --test test/unit/single-output.test.ts test/unit/notify.test.ts
+node --experimental-strip-types --import ./test/support/register-loader.mjs --test \
+  test/integration/single-execution.test.ts \
+  test/integration/parallel-execution.test.ts \
+  test/integration/foreground-result-size.test.ts \
+  test/integration/intercom-result-delivery.test.ts \
+  test/integration/async-execution.test.ts \
+  test/integration/result-watcher.test.ts
+npm run test:all
+
+cd ../../..
+npm run build
+```
+
+## Acceptance criteria
+
+- Default foreground single, parallel, and chain completion contains no raw child output in `content`, terminal `details`, or intercom delivery.
+- Default async completion notification/intercom contains no raw child output.
+- Each successful child has a readable, authoritative result reference with byte/line metadata while `artifacts:false`.
+- Failure/timeout/stop/pause preserves status and recovery information and never emits unbounded output.
+- Persistence failure produces the specified 80-line/4-KiB fallback and does not falsely claim a full reference exists.
+- Explicit `outputMode:"inline"` preserves legacy inline delivery.
+- `output:false`, status, transcript, resume, intercom acknowledgement, session leases, chain output bindings, and structured output behavior remain covered by regression tests.
+- Root build regenerates `dist` from source.
+
+## Risks and rollback
+
+- **Risk:** reference-only chains require downstream children to read referenced outputs deliberately. Mitigate with injected authoritative output-path instructions and chain tests.
+- **Risk:** generated output files increase `.pi-subagents` disk use despite debug artifacts being disabled. Mitigate through documented paths and existing project/session/temp placement; do not silently delete authoritative outputs in this phase.
+- **Risk:** host behavior for tool `details` is not fully controlled. Mitigate by removing terminal raw output from details rather than relying on renderer behavior.
+- **Rollback:** restore omitted-mode resolution to `"inline"` and remove generated-path assignment; explicit output/file-only callers remain functional. Leave already-written result files in place; they are harmless and should not be deleted automatically.
+
+```acceptance-report
+{
+  "criteriaSatisfied": [
+    {
+      "id": "criterion-1",
+      "status": "satisfied",
+      "evidence": "Concrete findings verified in source and tests: high-risk raw-output surfaces in foreground executor, result-intercom, async runner, notifier, and details; reusable file-only, async-log, status, transcript, resume, and artifact-default-off mechanisms cited with exact paths."
+    }
+  ],
+  "changedFiles": [],
+  "testsAddedOrUpdated": [],
+  "commandsRun": [
+    {
+      "command": "read/grep static inspection of pi-subagents source, docs, and tests",
+      "result": "passed",
+      "summary": "Verified cited symbols, current mode behavior, artifact-default-off gates, and existing test seams. No implementation commands were run."
+    }
+  ],
+  "validationOutput": [
+    "Plan is implementation-ready and limited to Phase 2.",
+    "No files were edited."
+  ],
+  "residualRisks": [
+    "Reference-first defaults intentionally change omitted outputMode behavior; callers needing inline output must migrate.",
+    "Generated authoritative outputs require a retention policy decision outside this phase if disk growth becomes material."
+  ],
+  "noStagedFiles": false,
+  "diffSummary": "No diff produced; planning-only task.",
+  "reviewFindings": [
+    "high: foreground executor and intercom payloads currently expose full child output by default.",
+    "high: async completion notifier currently forwards full runner summaries.",
+    "medium: existing explicit output persistence and async output logs can satisfy Phase 2 without enabling debug artifacts."
+  ],
+  "manualNotes": "Staged-file state was not inspected because this session has no shell execution tool."
+}
+```
+
+⧉ copy assistant: /cp 5224d1

package/docs/plans/subagent-delegation/phase-3-advisory-routing.md

@@ -0,0 +1,362 @@
+# Phase 3 Plan — Optional Task-Aware Advisory Routing
+
+## Decision
+
+Use **`subagent({ action: "list", task?, agentScope? })`** as the only Phase 3 advisory surface.
+
+It is the smallest robust design because `task` and `action:"list"` already exist in `SubagentParams`, list already discovers the effective runnable agent set, and it already emits advisory text. This adds no launch path, RPC method, preflight-contract field, persistence, metadata schema, or new action.
+
+### Alternatives rejected
+
+| Option | Decision | Reason |
+|---|---|---|
+| Extend `action:"list"` with optional `task` | **Select** | Existing schema/action/output surface; model already instructed to call list; no API-version changes. |
+| Add `action:"recommend"` or `action:"route"` | Reject | Adds action registry, dispatch, child-safe policy, docs, and a second advisory surface without a functional benefit. |
+| Add generic role aliases such as `writer`/`reviewer` as runnable aliases | Reject | Would alter `resolveAgentName` ambiguity/precedence behavior and can collide with user/package aliases. Existing `acceptanceRole` plus established name heuristics are sufficient. |
+| Add recommendation to launch preflight/RPC | Reject | Would require public contract/protocol version changes and digest compatibility work for advisory-only behavior. |
+
+## Public behavior and API
+
+### Supported call
+
+```ts
+subagent({
+  action: "list",
+  task: "Inspect the authentication flow and report findings only.",
+  agentScope: "both", // optional; existing behavior
+})
+```
+
+- `task` remains optional.
+- With no task, or a whitespace-only task, preserve current list output and behavior.
+- With a non-empty task, append a text-only advisory section after the existing agents/chains/proactive-skill/diagnostic sections.
+- The caller must make a separate explicit execution call to launch anything:
+
+```ts
+subagent({ agent: "architect", task: "..." })
+```
+
+### Output shape
+
+Keep the existing management result shape unchanged:
+
+```ts
+{
+  content: [{ type: "text", text: "<existing list text plus optional advisory>" }],
+  isError: false,
+  details: { mode: "management", results: [] }
+}
+```
+
+Do **not** add a `recommendations` field to `Details`, a result-content JSON schema, telemetry payload, or launch contract.
+
+For a safe recommendation, append exactly this conceptual structure:
+
+```text
+Task-aware advisory routing:
+- Intent: implementation | read-only
+- Recommended: <canonical runtime agent name> (<source>)
+- Reason: <declared/inferred role and safety basis>
+- Advisory only: no subagent was launched. To proceed, explicitly call subagent with this canonical agent name and the task.
+```
+
+For unclear intent or no safe candidate:
+
+```text
+Task-aware advisory routing:
+- Intent: unknown | implementation | read-only
+- Recommendation: none
+- Next: <clarification or configuration/capability explanation>
+- Advisory only: no subagent was launched.
+```
+
+Never echo the complete task in the response; this avoids enlarging output and reflecting untrusted text.
+
+## Eligibility and deterministic routing algorithm
+
+Create a pure recommender that receives the already discovered effective agents and current capability ceiling. It must not read files, mutate discovery results, resolve aliases, modify params, or launch agents.
+
+1. **Normalize task**
+   - `task.trim() === ""` means no advisory section.
+   - Otherwise classify the task with `classifyTaskMutationIntent("builder", task)`.
+   - This deliberately uses the existing broad writer grammar as a task-level signal:
+     - `implementation`
+     - `read-only`
+     - `unknown`
+
+2. **Use only effective executable candidates**
+   - Start from the same `scopedAgents` produced by:
+     `mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package)`.
+   - Exclude `agent.disabled === true`.
+   - Exclude agents denied by `isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling)`.
+   - This preserves project > user > package > builtin collision resolution already performed by discovery/selection.
+   - Do not consider chains in Phase 3.
+   - Do not inspect or route individual chain steps/templates.
+
+3. **Determine candidate role without adding aliases or metadata**
+   - Reuse the existing `acceptanceRole` field where set:
+     - `"writer"` is a writer candidate.
+     - `"read-only"` is a read-only candidate.
+   - When it is unset, reuse the existing acceptance name heuristics:
+     - names matching `builder` are writer candidates;
+     - names matching `architect|commentator|explorer|recapper|researcher|analyst` are read-only candidates.
+   - Refactor this shared heuristic into one exported helper so advisory routing and acceptance inference cannot drift.
+   - Alias values are never used as role signals. They remain input-only name resolution sugar.
+
+4. **Apply conservative write safety**
+   - Reuse `agentHasWriteTools` from `src/agents/agent-memory.ts`.
+   - For an `implementation` task, retain only writer-role candidates with write capability.
+   - If `capabilityCeiling.allowedTools` is present, retain a writer only when its allowlist includes at least one recognized writer tool: `edit`, `write`, or `bash`.
+   - For a `read-only` task, retain only read-only-role candidates for which `agentHasWriteTools(agent) === false`.
+   - This is intentionally conservative: an agent with unset tools or `bash` is not recommended as the safe read-only choice.
+   - Do not claim that arbitrary MCP/custom tools are provably non-mutating; actual launch preflight remains authoritative.
+
+5. **Select or recover**
+   - For `unknown`, return no recommendation and request clarification: whether the task is read-only analysis/review or implementation allowed to edit files.
+   - For a known intent with zero safe candidates, return no recommendation and explain the missing role/capability condition. Point to the executable/restricted sections already emitted by list.
+   - Sort valid candidates deterministically:
+     1. source precedence: `project`, `user`, `package`, `builtin`;
+     2. explicit `acceptanceRole` before inferred name heuristic;
+     3. canonical runtime `agent.name` ascending with a fixed lexical comparator.
+   - Recommend `agent.name` only—the canonical runtime name accepted by execution. Never output an alias as the launch target.
+
+6. **Preserve user control**
+   - Do not write to `params.agent`.
+   - Do not touch `canonicalizeExecutionParams`.
+   - Do not invoke `resolveAgentName` for a generic role.
+   - An explicit later execution request remains authoritative, including existing canonical-name/alias handling and its ambiguity errors.
+   - Existing preflight and execution checks remain the final enforcement point for agent/tool restrictions.
+
+## Implementation tasks
+
+### Task 1 — Centralize the existing role heuristic
+
+**Discovery**
+- Inspect `src/extensions/pi-subagents/src/runs/shared/task-intent.ts`.
+- Inspect `src/extensions/pi-subagents/src/runs/shared/acceptance.ts:76-134`.
+- Confirm the current reviewer-name and builder-name regex behavior before changing it.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/runs/shared/task-intent.ts`.
+- Modify `src/extensions/pi-subagents/src/runs/shared/acceptance.ts`.
+- Update `src/extensions/pi-subagents/test/unit/task-intent.test.ts`.
+- Existing `test/unit/acceptance.test.ts` is the regression suite; only alter it if current behavior needs an explicit regression assertion.
+
+**Change**
+- Add and export a narrow helper such as:
+  ```ts
+  resolveAgentRoutingRole(
+    agentName: string,
+    acceptanceRole?: AcceptanceRole,
+  ): "writer" | "read-only" | undefined
+  ```
+- Preserve current acceptance semantics exactly:
+  - declared `acceptanceRole` wins;
+  - otherwise builder-name heuristic means writer;
+  - otherwise existing reviewer-name heuristic means read-only;
+  - otherwise undefined.
+- Refactor `inferLevel` to use this helper in place of its duplicated `readOnlyAgent`/builder-name checks.
+- Do not change task mutation grammar, acceptance levels, evidence requirements, or `acceptanceRole` schema.
+
+**Verification**
+- Declared writer/read-only roles still override name inference.
+- `builder` remains a writer and `commentator` remains reviewer-style.
+- Existing acceptance tests retain their current levels/reasons.
+
+### Task 2 — Add the pure advisory recommender
+
+**Discovery**
+- Inspect:
+  - `src/extensions/pi-subagents/src/agents/proactive-skills.ts` for pure-function/formatter conventions.
+  - `src/extensions/pi-subagents/src/agents/agent-memory.ts:33-39` for `agentHasWriteTools`.
+  - `src/extensions/pi-subagents/src/runs/shared/capability-ceiling.ts:300-315` for allowlist checks.
+  - `src/extensions/pi-subagents/src/agents/agent-selection.ts` for effective-set precedence.
+- Do not add frontmatter fields, settings fields, tags, or role aliases.
+
+**Files**
+- Add `src/extensions/pi-subagents/src/agents/task-aware-routing.ts`.
+- Add `src/extensions/pi-subagents/test/unit/task-aware-routing.test.ts`.
+
+**Change**
+- Export a small typed pure API, for example:
+  - `recommendTaskAwareAgent({ task, agents, capabilityCeiling })`
+  - `formatTaskAwareAgentRecommendation(recommendation)`
+- Keep returned data internal to the extension; do not add it to public `Details`.
+- Implement the algorithm above, including:
+  - empty-task no-op;
+  - task intent;
+  - disabled and capability-agent filtering;
+  - conservative role/write-tool matching;
+  - capability `allowedTools` writer check;
+  - deterministic ordering;
+  - unknown/no-candidate recovery text.
+- Include source, canonical agent name, role basis (`declared` or `inferred`), and reason in the returned recommendation object so formatting never reimplements selection logic.
+- Do not access aliases, chains, filesystem discovery, executor APIs, RPC, preflight, telemetry, or user settings in this module.
+
+**Verification**
+- Implementation task recommends a canonical writer, never a reviewer.
+- Read-only task recommends a role-compatible agent without known write tools, never a writer.
+- Unknown intent yields no recommendation and a clarification message.
+- Disabled agents and agents outside `allowedAgents` cannot be selected.
+- A ceiling without `edit`, `write`, or `bash` prevents a writer recommendation.
+- A project candidate outranks an otherwise-equivalent user/package/builtin candidate.
+- Equal candidates sort by canonical name.
+- An alias such as `developer` is never output as the recommended launch name.
+
+### Task 3 — Attach advice only to list management output
+
+**Discovery**
+- Inspect `handleList` in `src/extensions/pi-subagents/src/agents/agent-management.ts:675-714`.
+- Inspect management dispatch at `handleManagementAction`.
+- Inspect the executor management dispatch at `subagent-executor.ts:4064-4083` to confirm no execution path needs modification.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/agents/agent-management.ts`.
+- Modify `src/extensions/pi-subagents/src/extension/schemas.ts`.
+- Update `src/extensions/pi-subagents/test/unit/agent-management.test.ts`.
+- Update `src/extensions/pi-subagents/test/unit/capability-ceiling-agent-allowlist.test.ts`.
+- Update `src/extensions/pi-subagents/test/unit/schemas.test.ts`.
+- Update `src/extensions/pi-subagents/test/unit/index-child-registration.test.ts`.
+
+**Change**
+- Extend internal `ManagementParams` with `task?: string`.
+- In `handleList`, reuse its already computed `agents` array, `capabilityCeiling`, and scope-specific effective discovery.
+- When `params.task?.trim()` is non-empty, call the new pure recommender and append its formatter lines after proactive-skill suggestions and before chain diagnostics.
+- Leave no-task list output structurally unchanged.
+- Update the top-level `task` schema description to state that it is a single-execution task **or an optional advisory intent for `action:"list"`; it never launches work in management mode**.
+- Keep `action` as a free string schema; do not add an action enum.
+- Keep `SUBAGENT_ACTIONS`, `ManagementAction`, mutating-action gates, and executor dispatch unchanged.
+
+**Verification**
+- `handleManagementAction("list", { task: "Implement the fix" }, ctx)` returns management details with `results: []`, no error, and an advisory recommendation.
+- `handleManagementAction("list", { task: "Review only; do not edit files" }, ctx)` emits a read-only recommendation.
+- `handleManagementAction("list", { task: "Look into this" }, ctx)` emits no agent name recommendation and asks for intent clarification.
+- `handleManagementAction("list", {}, ctx)` retains current executable/restricted/chains/proactive output.
+- Existing restricted-agent list behavior remains; a restricted builder must not be recommended.
+- The fanout-child registration test calls list with a task and confirms it remains a permitted read-only management action.
+
+### Task 4 — Document explicit-only use
+
+**Discovery**
+- Inspect both built-in descriptions in `src/extensions/pi-subagents/src/extension/tool-description.ts`.
+- Inspect management examples and parameter reference in `src/extensions/pi-subagents/README.md:1377-1442`.
+
+**Files**
+- Modify `src/extensions/pi-subagents/src/extension/tool-description.ts`.
+- Modify `src/extensions/pi-subagents/README.md`.
+- Update `src/extensions/pi-subagents/test/unit/tool-description.test.ts`.
+
+**Change**
+- In full and compact descriptions:
+  - show `{ action: "list", task: "..." }` as optional advice;
+  - state that it only recommends and never launches;
+  - state the caller must explicitly execute the returned canonical agent.
+- Adjust “management action fields” wording so list’s optional task is documented as the sole exception.
+- Add a README management example and revise the `task` parameter reference.
+- Do not change custom-description loading behavior; mandatory safety guidance naturally remains appended to custom descriptions.
+
+**Verification**
+- Full and compact descriptions both mention task-aware list advice and explicit launch.
+- Existing safety guidance, proactive-skill text, and no-hardcoded-builtin-name assertions remain valid.
+- README does not imply automatic routing or execution.
+
+## Compatibility and dependency impact
+
+- No dependency changes.
+- No new config/settings schema.
+- No agent frontmatter changes.
+- No new aliases.
+- No new tool action.
+- No RPC version bump.
+- No preflight contract version/digest change.
+- No delegation API version change.
+- No telemetry: the extension has no matching event/metric convention for advisory list reads, and telemetry would add privacy and API surface without an execution decision.
+
+## Commands
+
+Run from `src/extensions/pi-subagents`:
+
+```bash
+node --experimental-strip-types --test \
+  test/unit/task-intent.test.ts \
+  test/unit/acceptance.test.ts \
+  test/unit/task-aware-routing.test.ts \
+  test/unit/agent-management.test.ts \
+  test/unit/capability-ceiling-agent-allowlist.test.ts \
+  test/unit/schemas.test.ts \
+  test/unit/tool-description.test.ts \
+  test/unit/index-child-registration.test.ts
+npm run test:unit
+npm run test:integration
+npm run test:all
+```
+
+## Acceptance criteria
+
+1. `action:"list"` accepts optional `task` advice without creating a new action or schema object.
+2. Recommendations use only the dynamically discovered, effective, enabled, capability-allowed set.
+3. Project/user/package/builtin precedence, canonical names, and existing alias resolution remain intact.
+4. A read-only task is never recommended to a known writer; an implementation task is never recommended to a read-only agent.
+5. Unknown intent and missing safe candidates produce recovery guidance, not guesses.
+6. List advice never launches, schedules, persists, mutates params, or changes executor agent selection.
+7. Existing list, acceptance, capability-ceiling, and child-safe management behavior pass regression tests.
+8. No metadata/tag schema, dependency, protocol, telemetry, or contract version is added.
+
+## Risks and rollback
+
+- **Heuristic limitation:** task wording and name-based roles remain heuristic. Mitigation: no recommendation for unknown intent and existing `acceptanceRole` is preferred when configured.
+- **Tool limitation:** `agentHasWriteTools` only recognizes core write tools; custom/MCP tools cannot be proven read-only. Mitigation: conservative filtering and explicit-launch/preflight enforcement.
+- **Usability limitation:** a restrictive `allowedTools` ceiling can yield no writer recommendation. This is safer than recommending a writer that cannot write.
+- **Rollback:** remove the `handleList` call/formatting and new routing module; leave the shared role-helper refactor only if acceptance behavior is verified identical. No stored data, API version, or migration requires cleanup.
+
+## Review findings
+
+- **No blocker** — `src/extensions/pi-subagents/src/agents/agent-management.ts:675-714` already owns advisory list output and receives the effective executable/capability-filtered agent set.
+- **No blocker** — `src/extensions/pi-subagents/src/runs/foreground/subagent-executor.ts:4078-4083` routes management actions without invoking execution; leaving it unchanged preserves explicit-only launch behavior.
+- **Finding (medium)** — `src/extensions/pi-subagents/src/runs/shared/acceptance.ts:89-101` duplicates role-name heuristics that a recommender would otherwise need to copy. Centralize the existing heuristic before using it for routing to prevent behavior drift.
+- **Finding (medium)** — `src/extensions/pi-subagents/src/agents/agent-memory.ts:33-39` treats unset tools as write-capable and treats `bash` as write-capable. Advisory routing must retain this conservative interpretation for read-only recommendations.
+
+```acceptance-report
+{
+  "criteriaSatisfied": [
+    {
+      "id": "criterion-1",
+      "status": "satisfied",
+      "evidence": "Verified concrete Phase 3 ownership and constraints in src/extensions/pi-subagents/src/agents/agent-management.ts:675-714, agents/agent-selection.ts, agents/agents.ts:477-510, runs/shared/task-intent.ts, runs/shared/acceptance.ts:76-134, runs/shared/capability-ceiling.ts:300-315, extension/schemas.ts:263-349, extension/tool-description.ts, and targeted unit tests."
+    }
+  ],
+  "changedFiles": [],
+  "testsAddedOrUpdated": [],
+  "commandsRun": [
+    {
+      "command": "Targeted read/grep inspection of Phase 3 source and tests",
+      "result": "passed",
+      "summary": "Verified list discovery, precedence, alias handling, capability ceilings, task-intent/acceptance heuristics, tool safety helper, schema, descriptions, and test seams."
+    },
+    {
+      "command": "npm run test:unit",
+      "result": "not-run",
+      "summary": "Planning-only task; no implementation was made."
+    }
+  ],
+  "validationOutput": [
+    "No code changes were made.",
+    "Selected extension of action:'list' with optional task because it avoids action, RPC, preflight-contract, digest, metadata, and dependency changes."
+  ],
+  "residualRisks": [
+    "Task and name-role classification is heuristic; unknown intent must remain non-recommending.",
+    "The existing core write-tool classifier cannot prove arbitrary MCP/custom tools are non-mutating.",
+    "A restrictive allowedTools ceiling can intentionally result in no writer recommendation."
+  ],
+  "noStagedFiles": true,
+  "diffSummary": "No diff; implementation-ready Phase 3 plan only.",
+  "reviewFindings": [
+    "no blocker: agent-management.ts:675-714 is the existing advisory list owner.",
+    "medium: acceptance.ts:89-101 duplicates role heuristics; centralize the existing rule before advisory routing uses it.",
+    "medium: agent-memory.ts:33-39 provides a conservative core-tool write signal and should be reused rather than reimplemented."
+  ],
+  "manualNotes": "Phase 3 deliberately remains advisory-only. No automatic execution, generic role aliases, telemetry, metadata schema, RPC/preflight surface, or contract-version changes are planned."
+}
+```
+
+⧉ copy assistant: /cp 4055a2