@ferris1225/pi-subagents 4.3.0 → 4.3.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ Published versions of `@ferris1225/pi-subagents`. Unpublished numbers
 (`4.2.3`, `4.2.6`, `4.2.9`–`4.2.11`) never shipped on npm; their changes
 landed in the next published release.
 
+## 4.3.1
+
+- Make phase ownership explicit and reject an exact active duplicate by normalized
+  task plus resolved working directory, regardless of agent name.
+- Route each result exactly once: `wait: true` owns in-turn delivery, background
+  completions use follow-up wakeups, and immediate failures flush earlier successes.
+- Move worktree preparation under the bounded queue, release child-process slots
+  before Git finalization, and report repository-lane versus process-slot waits
+  accurately.
+- Keep missing restored worktrees failed, retained, and non-resumable; compute RPC
+  usage from generation-safe session-stat deltas.
+- Store the worktree recovery manifest under `ferris-pi-subagents/`, relocating
+  an existing agent-root manifest without losing retained artifact pointers.
+- Enforce a strict read-only scout tool set and strict declared-tool intersection.
+  Unknown custom tools remain conservatively write-capable for isolation.
+- Honor `enabledAgents`, including `[]`, without auto-enabling roles. Remove the
+  completed role/config migration bridge and shorten role prompts, tool metadata,
+  launch receipts, and handoffs.
+
 ## 4.3.0
 
 - Built-in team is `scout`, `artisan`, and `steward`. All three stay enabled.

package/README.md

@@ -12,17 +12,11 @@ isolation. You install it once and your main agent delegates on its own.
 
 ## What's new
 
-**4.3.0** — the team is `scout`, `artisan`, and `steward`. Existing
-`explorer`/`executor` configs migrate. Thinking is a role default you can
-change in `/subagents-setup` (no Auto, no per-call flag). All three roles
-start on. See [CHANGELOG.md](./CHANGELOG.md).
-
-**4.2.13** — this page now leads with current changes and keeps the 4.2 line
-in the changelog.
-
-**4.2.12**
-
-- Confirm-before-fix; honest footer counts; `main` publishes npm + GitHub Release.
+**4.3.1** — phase ownership prevents duplicate paid work, completion delivery
+is exactly once, worktree setup obeys the bounded queue, and final integration
+releases its child-process slot. Scout now has a strict read-only tool boundary;
+`enabledAgents` is authoritative, including `[]`. Role prompts and launch receipts
+are shorter and cost-aware. See [CHANGELOG.md](./CHANGELOG.md).
 
 ## Contents
 
@@ -48,17 +42,19 @@ at "spawn a child with a prompt" and leave the hard parts — when to delegate,
 wide to fan out, what happens when a model dies, how results come
 back — with you. This extension owns them:
 
-- The main model delegates without being asked, because a delegation directive is
-  always in its system prompt.
-- Dispatching never blocks or ends the main turn, so it can start several runs and
-  keep working while they execute.
-- Results deliver themselves. There is no status tool to poll and no lookup step.
-- Parallel writers get their own Git worktrees, so concurrent edits do not collide
-  and your index is never touched.
-- Threads keep their context across resume, stop, reload, and crash; a dead model
-  hands its session to the current main model instead of losing progress.
-- Crashes, partial starts, and integration failures come back as results with
-  recovery records — never as silent hangs.
+- The main model gets a cost-aware routing contract and delegates only when a leaf
+  context saves more work than its handoff costs.
+- One active normalized task and working directory owns its phase, so an exact
+  duplicate dispatch is rejected instead of paying twice.
+- Background completions wake the main model; `wait: true` returns the same result
+  in-turn instead. A run uses exactly one route.
+- Parallel writers use detached Git worktrees without touching your index.
+  Worktree setup obeys the bounded queue; final integration releases its process
+  slot.
+- Interrupted threads retain their session for resume after reload or crash; a
+  configured child-model failure continues the same session on the main model.
+- Start, restore, and integration failures surface with retained recovery paths
+  instead of becoming silent hangs.
 
 ## Install
 
@@ -68,10 +64,10 @@ Requires **pi >= 0.84.4** and **Node.js >= 22.19.0**.
 pi install npm:@ferris1225/pi-subagents
 ```
 
-Open pi and run `/subagents-setup`. The first session tells you how: pick a
-model for `scout`, `artisan`, and `steward` (all three stay on). Each row in
-the wizard names the role and what it owns. Thinking has a role default you
-can change there. Then just ask for work:
+Open pi and run `/subagents-setup`. Choose the enabled roles, then pick a model
+and optional thinking override for each. Fresh installs select all three, but
+you can disable any role or use `[]` to disable delegation. Then just ask for
+work:
 
 ```text
 Map how authentication works, fix the refresh race, run the tests, and review the diff.
@@ -82,11 +78,11 @@ directly when you want exact control.
 
 ## The team
 
-| Agent      | Access    | Best for                                                                                                                                                                                                   |
-| ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scout`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof. A single artifact the main agent must fully absorb (one issue, one spec) stays an inline read. |
-| `artisan`  | Full      | One deliverable that changes the repository: implement, fix, refactor, or test — confirmed on current code, then verified, then a result-only handoff.                                                      |
-| `steward`  | Full      | Use only when that work exists: evidence-first cleanup, docs/comment sync, or merging a fan-out's result artifacts into one brief.                                                                          |
+| Agent     | Access    | Owns |
+| --------- | --------- | ---- |
+| `scout`   | Read-only | Broad or unfamiliar reconnaissance with compact findings and decisive citations. Its output is a retrieval lead, not proof. |
+| `artisan` | Full      | A substantial self-contained implementation, including affected tests, docs, comments, targeted checks, and local cleanup. |
+| `steward` | Full      | One pre-commit cleanup or cross-cutting docs/comments pass after a broad or multi-writer change is complete. |
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
 
@@ -94,17 +90,6 @@ Every child is an isolated leaf pi process with its own context window and no
 memory of your conversation, so the brief is its only input. A good brief carries
 the goal, exact paths, constraints, and expected output — which is what the
 injected delegation guidance produces when the main agent dispatches for you.
-A named defect is not yet a change: confirm it on current code before fixing
-or briefing a fix. The artisan re-reads before it edits. Steward is
-dispatched only when cleanup, docs sync, or a merge is actually needed.
-
-```text
-You
- └─ pi main agent
-     ├─ scout    ─── parallel recon, retrieval leads only
-     ├─ artisan  ─── implement, fix, refactor, or test → verify → deliver
-     └─ steward  ─── cleanup, docs sync, or merge fan-out results (when needed)
-```
 
 ## Dispatching work
 
@@ -115,12 +100,11 @@ subagent({
   task: "Fix the cache invalidation bug in src/cache, add regression tests, run the checks.",
 });
 
-// Parallel: as many genuinely independent units as the work has
+// Parallel only when each scope independently justifies a child
 subagent({
   tasks: [
-    { agent: "scout", task: "Trace model fallback from dispatch to completion." },
-    { agent: "artisan", task: "Add edge-case tests for config migration." },
-    { agent: "steward", task: "Merge the result artifacts under results/ into one brief." },
+    { agent: "scout", task: "Map model fallback across src/rpc-run.ts and src/spawn.ts." },
+    { agent: "artisan", task: "Fix config validation in src/config.ts and its tests." },
   ],
 });
 ```
@@ -131,16 +115,20 @@ paces execution instead, running a pool of child processes that scales with the
 machine (half its cores, bounded to 4–16) and starting queued runs automatically
 as slots free.
 
+An active run leases its normalized task and resolved working directory across
+agent names. Dispatching the same pair again is rejected and names the existing
+run id; it does not use fuzzy matching, and resuming that thread remains allowed.
+
 Because queueing is pacing rather than refusal, it is always reported as such.
 Dispatch confirmations name each waiting run's real reason — waiting for a free
 process slot, serialized behind the shared-checkout write lane, or already
 starting its child — alongside the slot capacity. A run that waits for the write
 lane releases its slot first, so serialized writers never starve new dispatches.
 
-One child owns one coherent deliverable and its files. Dependent work starts only
-after its prerequisite delivers. Verification belongs to whoever did the work:
-every child runs the checks it can and reports exactly which ones ran, and the
-main agent inspects the actual changes before calling anything done.
+One child owns one coherent phase. Dependent work starts only after its
+prerequisite delivers. Artisan owns the affected tests, docs, comments, targeted
+checks, and local cleanup for its implementation. Scout stays read-only. Main
+inspects the integrated diff and runs the final gate.
 
 ## Parallel edits
 
@@ -162,7 +150,7 @@ main agent inspects the actual changes before calling anything done.
   one repository lane, so two of them never race. A run waiting there is reported
   as a lane wait, not as slot queueing, and its process slot is already released.
 - Setup and integration failures keep the useful patch and worktree, and record
-  where they are in `~/.pi/agent/pi-subagents-recovery.json`. Every later session
+  where they are in `~/.pi/agent/ferris-pi-subagents/pi-subagents-recovery.json`.
   start repeats that notice until you remove the artifacts. When the changes had
   already been applied and only the cleanup failed, the next session start
   removes the retained copy itself and clears the notice.
@@ -180,25 +168,27 @@ Every dispatch returns a stable `#id`, which is the handle for the thread tools:
 subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
 ```
 
-There is deliberately no status, polling, or wait tool. Every result delivers
-itself as a completion that wakes the main model, so a turn never blocks on a
-running subagent — keep working or end the turn, and the completion continues
-it. The one in-turn block is `wait: true` on a dispatch, which holds that call
-until the runs it started settle: the escape hatch for one-shot `pi -p`
-parents, which exit at end of turn and would otherwise never see them. That
-wait runs on no timer and no timeout the model picks: it resolves the instant
-its run settles, a parked run answers immediately with its resume handle, and
-aborting the turn is the escape hatch. Control operations are all bounded, so
-they never hang on a generation that is still settling.
+There is no status, polling, or separate wait tool. A background dispatch returns
+a launch receipt, then its completion is delivered as a follow-up that wakes the
+main model. `wait: true` instead holds that tool call until its new runs settle,
+which is useful for one-shot `pi -p` sessions. It claims the delivery route before
+launch, so the same result cannot also arrive as a background completion; if the
+parent turn is aborted, delivery falls back to the completion path.
+
+The wait has no timer chosen by the model: it resolves when its run settles, and
+a parked run returns its resume handle. Control operations are bounded so they do
+not hang on a generation that is still settling.
 
 A thread stays durable while its work is unfinished. Parked sessions, worktree
-checkpoints, and result excerpts are recorded in a manifest beside your config, so
-a pi reload, restart, or crash interrupts a run into a resumable checkpoint
-instead of losing it, and an isolated thread resumes in the worktree it was
-already working in. Restore happens at load, and everything that answers for a run
-waits for it — `subagent_control`, `subagent_stop`, and a new dispatch before it
-takes an id — so the first call after a reload can never report parked work as
-missing or hand its id to something else.
+checkpoints, and result excerpts are recorded under the per-project storage root,
+so reload, restart, or crash produces a resumable checkpoint. An isolated thread
+continues in its original worktree.
+
+Restore runs at session start. `subagent_control`, `subagent_stop`, prompt
+injection, and new dispatches wait for it, so a parked id cannot be reported
+missing or reused. If a recorded worktree is gone, the run is surfaced as failed
+and non-resumable while its retained session and recovery record remain available
+for inspection or destructive stop.
 
 Only interrupted work needs a record, so a thread that completes or fails cleanly
 drops its own. That also means a reload keeps interrupted threads resumable, while
@@ -282,33 +272,27 @@ no `thinking` field in agent Markdown. Precedence: your setup override > the
 role default, then the model clamp. There is no separate vision mode — assign
 a multimodal model and name the image paths in the task.
 
-Every dispatch, resume, retry, and fallback snapshots the parent's
-currently active tools. A role with no explicit list inherits the full set. An
-explicit list keeps its pi built-in boundary and gains active extension tools,
-while its shell slot follows the parent: a role file naming `bash` runs
-`powershell` when that is the shell you enabled. When you run both, the child gets
-the one that fits the host — PowerShell on Windows, Bash elsewhere — rather than
-two terminals to choose between. A child never receives a shell you disabled,
-since pi's `--tools` allowlist overrides its own `defaultTools`. Read-only roles
-never gain `edit` or `write`, and all `subagent*` tools are stripped so children
-stay leaves. An empty snapshot starts the child with `--no-tools`.
-
-Shell guidance in the shipped roles is portable for the same reason: they reach
-for pi's own `read`/`grep`/`find`/`ls` tools, which behave identically everywhere,
-and keep shell examples to `git` queries instead of POSIX binaries a PowerShell
-child cannot run.
+Every dispatch, resume, retry, and fallback snapshots the parent's active tools,
+and all `subagent*` tools are removed so children remain leaves. A role without
+an explicit list inherits that snapshot; an explicit list is a strict
+intersection, so active extension tools are available only when named. A declared
+shell slot follows the parent's active shell on non-scout roles.
+
+`scout` is a hard read-only boundary even when a project override omits or
+overstates its tool list. The shipped scout uses only `read`, `grep`, `find`, and
+`ls`; it receives no shell or unknown custom tool. Unknown tools declared by other
+roles are conservatively treated as write-capable when isolation is chosen. An
+empty resolved snapshot starts the child with `--no-tools`.
 
 ## Configuration
 
-`/subagents-setup` stays one level deep: the team (all three stay on), plus a
-model and optional thinking override per agent. First run explains each role
-before you pick models. Everything else is config-file only, stored at
+`/subagents-setup` enables or disables roles and configures a model plus optional
+thinking override for each enabled role. The same settings live in
 `~/.pi/agent/pi-subagents.json` (following `PI_CODING_AGENT_DIR`):
 
 ```json
 {
   "enabledAgents": ["scout", "artisan", "steward"],
-  "knownAgents": ["scout", "artisan", "steward"],
   "agentModels": { "scout": "anthropic/claude-haiku-4-5" },
   "agentThinkingLevels": { "artisan": "high" },
   "maxResultLines": 40,
@@ -320,33 +304,20 @@ before you pick models. Everything else is config-file only, stored at
 | Field                 | Meaning                                                                           |
 | --------------------- | --------------------------------------------------------------------------------- |
 | `enabledAgents`       | Agents available for discovery and delegation. `[]` disables all.                 |
-| `knownAgents`         | Built-ins this config has seen; automatic bookkeeping — never edit it.            |
 | `agentModels`         | Optional `provider/model-id` per agent; missing = current main model.             |
 | `agentThinkingLevels` | Optional setup override per agent; missing = the role default.                    |
 | `maxResultLines`      | Lines kept in a completion message before the artifact takes over. Default `40`.  |
 | `agentScope`          | Discover `user`, `project`, or `both` agent directories. Default `user`.          |
 | `idleTimeoutSec`      | Seconds without child RPC output before termination; `0` disables. Default `90`.  |
 
-The delegation directive is always injected; there is no toggle. Invalid values
-fall back safely, and stale keys — including the former `proactiveInjection`,
-`maxConcurrency`, `maxFixRounds`, and `notifyOnReviewPass` knobs — are dropped
-automatically. Built-in roles a newer package no longer ships (such as the
-retired `worker`/`cleaner`/`documenter`/`synthesizer`/`reviewer` set, and the
-renamed `explorer`/`executor` names after they have been mapped) are pruned
-from `enabledAgents`, `knownAgents`, and the model/thinking tables at first
-load, so the setup wizard never mixes old and new roles; custom agents are
-untouched. A 4.2 config that still says `explorer`/`executor` is rewritten to
-`scout`/`artisan` and gains `steward`; their model and thinking overrides move
-with the names. That rename lives in `src/config.ts` and will be deleted in
-the next major. At session
-start, model overrides pi no longer reports are removed with a one-time notice. If
-pi's own session compaction fails mid-thread, a notice surfaces the error and the
-automatic retry instead of failing quietly.
-
-Agents shipped by a newer package version turn themselves on at the next
-session. Scout, artisan, and steward stay enabled even if a stale allow-list
-left one off. A one-shot notice then points at `/subagents-setup` so you can
-pick a model for each.
+When at least one role is enabled, the cost-aware delegation directive is injected
+automatically. `enabledAgents` is authoritative: the extension neither re-enables
+a disabled role nor adopts or renames roles. Invalid known fields fall back safely,
+and unknown fields are dropped when the canonical config is persisted.
+
+At session start, model overrides that pi no longer reports are removed with a
+one-time notice. If pi's own session compaction fails mid-thread, a notice surfaces
+the error and automatic retry instead of failing quietly.
 
 ## Custom agents
 
@@ -361,7 +332,7 @@ Built-ins ship with the package. Add or replace them with Markdown files:
 name: scout
 description: Fast read-only codebase reconnaissance
 isolation: shared
-tools: read, bash
+tools: read, grep, find, ls
 ---
 …additional system prompt…
 ```
@@ -369,8 +340,9 @@ tools: read, bash
 `description` is the routing line the main model reads. `isolation` pins the
 role's default boundary as described under [Parallel edits](#parallel-edits).
 Models come only from `/subagents-setup`; an agent file cannot pin one. An
-explicit `tools` list is the capability boundary, and omitting it inherits the
-parent's complete active set.
+explicit `tools` list is intersected with the parent's active set; omitting it
+inherits the active set. A role named `scout` is always reduced to the fixed
+read-only tool set described above.
 
 ## Storage and cleanup
 
@@ -381,15 +353,15 @@ that removes it, so this directory does not grow without bound:
 | Path                                       | Holds                                                | Removed                                                          |
 | ------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
 | `pi-subagents.json`                        | Your configuration                                   | Never — it is yours                                              |
-| `pi-subagents-recovery.json`               | Worktree integration and cleanup failures            | When the retained patch or worktree it points at is gone         |
+| `ferris-pi-subagents/pi-subagents-recovery.json` | Worktree integration and cleanup failures | When the retained patch or worktree it points at is gone |
 | `ferris-pi-subagents/<project>/pi-subagents-threads.json` | One record per interrupted thread     | When the thread settles, or after 30 days                        |
-| `ferris-pi-subagents/<project>/sessions/`  | Retained child sessions that a resume continues from | When the pi session that produced it ends, or its owner is gone  |
-| `ferris-pi-subagents/<project>/worktrees/` | Isolated checkouts for parallel writers              | On integration, or when its owning process is gone               |
+| `ferris-pi-subagents/<project>/sessions/`  | Retained child sessions that a resume continues from | When the thread settles or its retained record is removed        |
+| `ferris-pi-subagents/<project>/worktrees/` | Isolated checkouts for parallel writers              | On integration, or when no retained record claims them           |
 | `ferris-pi-subagents/<project>/results/`   | Full text of truncated results                       | After 7 days, or beyond 50 per project                           |
 | `ferris-pi-subagents/<project>/tmp/`       | Child prompt copies and the no-retry policy shim     | When its owning process exits                                    |
 | `ferris-pi-subagents/<project>/`           | All of the above for one checkout                     | When the whole directory has been idle for 3 days                |
 
-Cleanup runs at extension load and is deliberately conservative. A directory goes
+Cleanup runs at session start and is deliberately conservative. A directory goes
 away only when the process that created it is gone and no manifest record still
 claims it, so a live sibling pi instance never loses state and parked work
 outlives its own process by design — a reference from the threads manifest always
@@ -409,25 +381,11 @@ transport, worktree integration, completion delivery, tools, and TUI status.
 
 ## Changelog
 
-The 4.3 line lives in [CHANGELOG.md](./CHANGELOG.md). Latest published
-version is **4.3.0**.
-
-| Version | What changed |
-| ------- | ------------ |
-| 4.3.0   | Team is `scout` + `artisan` + `steward`; role thinking defaults; config migrate. |
-| 4.2.13  | README navigation, What's new, and this changelog. |
-| 4.2.12  | Confirm-before-fix; honest footer counts; `main` publishes npm + GitHub Release. |
-| 4.2.8   | Footer roll-up; wait-path token usage; hold completions across compaction. |
-| 4.2.7   | Sharper executor routing; per-dispatch `thinking`. |
-| 4.2.5   | Per-project threads manifest. |
-| 4.2.4   | One-line explorer findings; recovery cleanup retry. |
-| 4.2.2   | Single-artifact reads stay inline. |
-| 4.2.1   | Prune retired roles from upgraded configs. |
-| 4.2.0   | Team is `explorer` + `executor`; two-line live widget. |
+See [CHANGELOG.md](./CHANGELOG.md) for published release notes.
 
 ## Release
 
-Merging to `main` publishes `@ferris1225/pi-subagents` when `package.json`
+Pushing to `main` publishes `@ferris1225/pi-subagents` when `package.json`
 carries a version npm does not have yet, then opens a matching GitHub Release.
 Do not `npm publish` from a laptop. The workflow is
 `.github/workflows/publish.yml` (npm trusted publisher or `NPM_TOKEN`).

package/agents/artisan.md

@@ -1,47 +1,19 @@
 ---
 name: artisan
-description: A self-contained unit that changes the repository — implement, fix, refactor, or test — carried through verification to a result-only handoff.
-# No `tools` field => inherits all tools (full capability).
+description: Owns a substantial implementation scope, including directly affected tests, docs, comments, and verification.
 ---
 
-You are an artisan with full capabilities in an isolated context window. You own one delegated implementation task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+You own one implementation phase. The task brief is your only context.
 
-Repository instructions (AGENTS.md) and any skills available in this session apply to you as to any agent: follow their process for the domains they own (language style, tests, debugging, cleanup discipline, verification). Where a skill covers the same ground as this brief, the skill's discipline wins — except for the release boundary below, which always wins.
+## Rules
 
-Cleanup, documentation sync, and merging fan-out results belong to `steward`. If the brief is only that work, do not improvise it here — say so and stop.
+- Inspect current code and confirm the defect before editing; a disproved issue means zero edits.
+- Make the smallest coherent root-cause change. Preserve unrelated work and existing conventions; avoid speculative abstractions and unrelated cleanup.
+- Own code refactors, directly affected tests, README/docs, comments, and local diff hygiene. Remove debug output, dead code, stale comments, and other debris introduced in your scope.
+- Leave standalone docs and cross-cutting pre-commit cleanup for a completed broad or multi-writer change to `steward`.
+- Run the smallest targeted check, then relevant project gates. Report unrun or pre-existing failures exactly; never imply a check passed when it did not run.
+- You are a leaf: do not dispatch agents, bump versions, commit, push, publish, tag, or release.
 
-## Procedure
+## Output
 
-1. **Context.** Read the brief fully, plus referenced files and images, before acting. If critical context is missing, state what is missing rather than guessing.
-2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity over one that rearranges it. No unrelated refactors or standalone docs work unless the brief asks.
-3. **Confirm.** A finding is not a change. Re-read the current code and confirm each defect you are about to fix is real — not a misread, a stale report, or an intended tradeoff — even when the brief said "fix it". A false positive means zero edits and a note.
-4. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
-5. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
-
-## Boundaries
-
-- Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action, even when repository instructions normally automate release after green checks.
-- Children are leaf processes: you cannot dispatch sub-agents.
-- Never change runtime behavior to make documentation true; report the defect instead.
-
-## Output format
-
-Return only the concrete outcome. Do not repeat the task brief, the plan, the root-cause investigation, or the tool chronology.
-
-## Completed
-
-What was done, in a few lines.
-
-## Files Changed
-
-- `path/to/file.ts` — what changed.
-
-## Verification
-
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean). State explicitly anything you could not run and why.
-
-## Notes (only when material)
-
-Unresolved blockers, rejected requirements, or decisions the caller must know. Omit when nothing actionable.
-
-Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.
+Return only the outcome, changed paths, checks run, and material blockers. No task restatement, plan, investigation narrative, or tool chronology.

package/agents/scout.md

@@ -1,36 +1,18 @@
 ---
 name: scout
-description: Fast read-only reconnaissance for broad or multi-file search in unfamiliar areas; returns exact paths and compressed findings as retrieval leads.
-tools: read, grep, find, ls, bash
-# At launch, this shell slot follows the parent and parent-active plugin tools
-# are appended; the listed non-shell Pi built-ins remain the permission boundary.
+description: Read-only reconnaissance for broad or unfamiliar code; returns compact, decisive citations.
+tools: read, grep, find, ls
 ---
 
-You are a scout: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. You have NOT got the caller's conversation history — the task brief is your only input.
+You own one broad reconnaissance phase. Atomic lookups and known locations stay with main. The task brief is your only context.
 
-## Hard constraints
+## Rules
 
-- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Reach for your `read`/`grep`/`find`/`ls` tools before the shell — they behave the same on every platform, while the shell you were given may be POSIX or PowerShell. Keep shell use to read-only inspection (`git log/show/diff/status` and that shell's own read-only commands); no installs, builds, or state changes. Permissions are not perfectly enforceable — keep every command strictly read-only by intent.
-- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read the cited line ranges before acting on your results.
+- Stay read-only: never create, edit, delete, install, build, or run commands. Use `read`/`grep`/`find`/`ls` only.
+- Findings are retrieval leads, not proof for deletion, security, compatibility, or persistence decisions. Cite decisive lines so main can plan without repeating the search; a later actor rechecks only source needed for its own decision or edit.
+- Search broadly once, then read key sections and follow relevant imports, callers, tests, and types. Cluster related questions instead of running a series of small searches.
+- Read requested images when relevant. State real gaps instead of guessing.
 
-## Workflow
+## Output
 
-1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
-2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
-3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
-4. Record exact paths and line ranges so the caller can jump straight in.
-5. If the brief asks you to inspect images (screenshots, mockups, designs), `read` them — the model receives them as attachments when it supports vision.
-
-Thoroughness scales with the task (default medium): quick = targeted lookups in key files; medium = follow imports and callers, read critical sections; thorough = trace dependencies across modules, check tests and types.
-
-## Final response
-
-Return only retrieval results, one bare bullet per finding — a single line: path, the fact, nothing else:
-
-```text
-- `path/to/file.ts:10-50` — the fact
-Start here: `path/to/file.ts` — entry symbol and why (only when the caller could not guess it)
-Gaps: unresolved uncertainty (only when real)
-```
-
-No preamble or closing summary. Do not repeat the task brief, inventory every file opened, paste nonessential code, or narrate the search; every line must carry a path with a fact or name a gap — delete anything else. State uncertainty and missing coverage — a plausible guess is more expensive than an honest gap. Stay under 15 lines by default; go longer only when the brief genuinely demands a wide survey — the 40-line delivery cap truncates your tail (usually the Gaps) and the caller pays for every line.
+Return at most 15 evidence bullets as ``- `path:line-range` — fact``. Add `Start here:` or `Gaps:` only when useful. No preamble, task restatement, file inventory, chronology, or nonessential code excerpts.

package/agents/steward.md

@@ -1,51 +1,19 @@
 ---
 name: steward
-description: Condenses a finished change or a pile of inputs — evidence-first cleanup, docs/comment sync, or merging fan-out results into one brief.
-# No `tools` field => inherits all tools (full capability).
+description: Pre-commit cleanup and cross-cutting docs/comment sync for a completed broad or multi-writer change.
 ---
 
-You are a steward: you tidy, document, or fold inputs together so the caller does not. You have NOT got the caller's conversation history — the task brief is your source of truth.
+You own one final hygiene phase after primary writing has finished. The task brief is your only context.
 
-Pick one mode from the brief and skip the others. Finding nothing safe to do and making zero edits is valid.
+## Rules
 
-## Cleanup
+- Require a named completed scope such as an uncommitted diff, Git range, or directory. Stop if primary writing is still active.
+- Start from that diff; never repeat implementation or reconnaissance. For a deletion candidate, read only load-bearing lines and search consumers before removing it. Keep uncertain dynamic behavior, public APIs, persisted formats, and compatibility outside the brief.
+- Remove dead code, duplication, debug residue, stale comments, and needless complexity without changing product behavior.
+- Synchronize cross-cutting comments, README, examples, and user docs. Code-local comments and directly affected docs belong to the artisan; do not rewrite them merely for style.
+- Report behavior changes, fixes, refactors, or missing tests for an artisan instead of performing them.
+- Run relevant checks and report failures exactly. You are a leaf: do not dispatch agents, bump versions, commit, push, publish, tag, or release.
 
-A candidate is not a deletion. Re-read the load-bearing files and repeat the decisive searches yourself — never inherit proof from another agent's report — and search the whole repository for consumers first. Keep a candidate when a real consumer exists, dynamic reachability is unresolved, or the cut removes a user capability, public API, persisted format, or compatibility path the brief did not explicitly approve.
+## Output
 
-Honor an explicit scope (uncommitted diff, Git range, directory). With no scope, use the uncommitted work; if the tree is clean, report that nothing is in scope instead of roaming the repository.
-
-## Docs sync
-
-Update comments, README, examples, and user docs to match the code. Never change runtime behavior to make the documentation true. Prefer the current implementation over another document. Do not start a standalone docs pass the brief did not ask for.
-
-## Merging inputs
-
-Read every named input fully before writing. Deduplicate restatements into one attributed entry. Report surviving conflicts side by side instead of averaging them away. Stay within the named inputs; report what they cannot answer as a gap.
-
-## Boundaries
-
-- Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action.
-- Children are leaf processes: you cannot dispatch sub-agents.
-- Implementation, fixes, refactors, and tests belong to `artisan`. If the brief is only that work, say so and stop.
-
-## Output format
-
-Return only the concrete outcome. Do not repeat the task brief, the investigation, or the tool chronology.
-
-## Completed
-
-What was done, in a few lines. For a merge, one brief with conflicts and gaps (omit empty sections).
-
-## Files Changed
-
-- `path/to/file.ts` — what changed. Omit when the mode was read-only merge.
-
-## Verification
-
-Which checks you ACTUALLY ran and their result. State explicitly anything you could not run and why.
-
-## Notes (only when material)
-
-Unresolved blockers, kept candidates that need a product decision, or gaps in the inputs. Omit when nothing actionable.
-
-Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.
+Return only cleaned or synchronized paths, checks run, kept candidates needing a decision, and material blockers. No task restatement, investigation narrative, or tool chronology.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "A managed sub-agent team for pi: scout, artisan, and steward roles, durable threads, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",