@ferris1225/pi-subagents 1.0.0 → 2.0.0

package/LICENSE

@@ -1,6 +1,8 @@
 MIT License
 
 Copyright (c) 2025 ferris1225
+Portions of agents/cleaner.md adapted from reclaim-code-entropy:
+Copyright (c) 2026 Yevanchen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -7,18 +7,26 @@
 ![pi](https://img.shields.io/badge/pi-extension-orange)
 
 Focused background delegation for [pi](https://pi.dev): `explore` / `worker` /
-`reviewer` agents run in **isolated child processes** and hand their results back
-to the main agent automatically. Install it, and the main model starts using it
-on its own — no prompt engineering, no babysitting.
-
-## 1.0 — controllable agent threads
-
-Version 1.0 turns pi-subagents from a one-shot background runner into a small
-thread runtime. Every dispatch has a stable run id and retained Pi session, so
-work can be steered while it runs, parked without losing context, resumed after
-settlement, retargeted, or forked into another path. An internal append-only
-lifecycle trajectory keeps retries and stale generations from corrupting the
-logical thread.
+`cleaner` / `reviewer` agents run in **isolated child processes** and hand their
+results back to the main agent automatically. Install it, and the main model
+starts using it on its own — no prompt engineering, no babysitting.
+
+## 2.0.0 — direct model handoff and capability-aware thinking
+
+Version 2 removes backup pools and global thinking strength. Every agent now has
+one optional selected model; any model/provider failure hands its retained session
+directly to the current main model, while ordinary tool/task failures stay put.
+Thinking defaults to Auto and is clamped through Pi's real model capability map.
+The setup menu and normalized config drop the obsolete options instead of carrying
+compatibility aliases.
+
+This release also adds semantic routing to a dedicated evidence-first `cleaner`
+and makes the active widget show each run's task, effective model/thinking,
+activity, and elapsed time. Every dispatch has a stable run id, so work can be
+steered while it runs, parked without losing context, resumed after settlement,
+retargeted, or forked into another path. Generation ownership keeps startup-race
+retries and stale child processes from corrupting the logical thread without
+retaining a duplicate event history.
 
 The common quality loop now runs end to end without waking the main agent between
 steps:
@@ -27,49 +35,72 @@ steps:
 reviewer (find blockers) → worker (fix) → reviewer (verify) → final PASS/FAIL
 ```
 
+Cleanup stays a separate lifecycle: explicit cleanup intent can dispatch the
+evidence-first `cleaner`; any edits still go through the independent `reviewer`
+gate.
+
 Each chain is delivered as one concise completion group, while full per-run
-reports remain available through `subagent_status`. Ordered model pools keep the
-same retained context across provider fallback, and isolated parallel workers
-use detached Git worktrees whose changes are applied back without touching the
-parent index.
+reports remain available through `subagent_status`. Its parent stays `running`
+until the whole chain settles; completed internal rounds leave active status
+immediately, so no `done` row keeps accumulating elapsed time. Selected-to-main
+model handoffs keep the same retained context, and isolated parallel workers use
+detached Git worktrees whose changes are applied back without touching the parent
+index.
 
 ## Highlights
 
 - **Zero-setup proactive dispatch** — the extension injects a delegation directive
-  into the main system prompt, so the main model automatically sends broad searches
-  to `explore`, self-contained implementations to `worker`, and pre-commit reviews
-  to `reviewer`. You just use pi; delegation happens by itself.
+  into the main system prompt, so the main model sends broad searches to `explore`,
+  self-contained implementations to `worker`, explicit cleanup intent to `cleaner`,
+  and pre-commit reviews to `reviewer`. You just use pi; delegation happens by itself.
 - **Vision-capable image tasks** — flag screenshot/mockup/design work with
-  `vision: true`. The configured vision primary is followed by that agent's
-  backup and the current main-window model. Setup lists only in-scope,
-  image-capable models from providers with a configured API key or OAuth session,
-  and runtime failures never silently rewrite your configuration.
+  `vision: true`. The configured vision model hands directly to the current main
+  model on model/provider failure. Setup lists only in-scope, image-capable models
+  from providers with configured authentication, and failures never silently
+  rewrite your configuration.
 - **Results come back on their own** — completions are delivered as messages that
   wake the main agent automatically, even mid-turn. No polling, no `sleep`, no
   "go check" step. `subagent_wait` is a **non-blocking** in-turn lookup by default
   (pass `timeoutMs` to block); `subagent_status` inspects runs; `subagent_stop`
   cancels one and delivers its partial output.
+- **Active-only live widget** — each queued or running sub-agent gets one compact
+  width-aware primary line with task, effective model/thinking, and elapsed time;
+  current activity appears only when present on an indented second line:
+  ```text
+  #7 cleaner · remove dead code in src/cache.ts · claude-sonnet-4-5/high · 42s
+    grep cacheKey
+  ```
+  Long tasks and activity paths truncate first (preserving a useful path tail when
+  possible), groups have no blank rows, and settled/parked runs disappear immediately.
 - **Results are not re-narrated** — a sub-agent's completion is shown to you
   verbatim, and the main agent is told not to paraphrase it back. It replies with
   only its own conclusion or next step, so the same findings are never paid for
   twice in tokens.
+- **Evidence-first cleanup, not deletion by guesswork** — `cleaner` distinguishes
+  read-only audit wording from explicit apply wording, proves consumers and dynamic
+  entrypoints before cutting, and treats finding nothing safe as a valid outcome.
+  It is periodic/intent-driven, never PR-count-driven or an automatic commit gate.
 - **A quality gate that closes the loop** — when a reviewer returns `REVIEW_FAIL`,
   the extension dispatches a worker briefed with the concrete findings, then a
   re-review, up to `maxFixRounds` times — and only then wakes the main agent.
   Every round stays in the triggering reviewer's cwd, and chains that target the
   same repository are serialized so shared-checkout edits cannot race.
-- **Ordered model pools without config churn** — each agent can have a primary
-  and backup; the current main-window model is the final candidate. Transient
-  provider failures retry the same candidate with backoff, while permanent stale
-  model/config errors and quota/auth errors advance immediately. Saved refs are
-  never rewritten behind your back.
+- **Direct fallback with real thinking capabilities** — each agent has at most
+  one selected model. An unavailable selection, rate limit, invalid key, quota,
+  missing model, or provider failure hands directly to the current main model.
+  A child-only provider adapter forces request retries to zero, and the RPC
+  parent cancels Pi's outer turn retry before another call, without changing user
+  settings. Auto thinking clamps the agent preference to the
+  effective model's real `thinkingLevelMap`; manual setup shows only levels that
+  model supports.
 - **Resumes, retargets, and forks preserve context** — every run is session-backed.
   `subagent_control` can steer active work, retarget it after a stable abort,
   park/resume it under the same run id, or fork a parked/settled checkpoint into
   a new independent run. Concurrent resume calls are serialized.
-- **Honest completions** — a run that ended with failed tool calls (e.g. a broken
-  build) is reported as `completed with N failed tool call(s)` with the errors
-  attached — a cheerful final text can never hide a failure.
+- **Concise but honest completions** — a clean process that contained failed tool
+  calls adds one short warning with its run id; individual errors stay out of the
+  main context and remain available through `subagent_status`. Actual process,
+  model, and integration failures still surface as failures.
 - **Parallel fan-out with filesystem isolation** — independent tasks run up to a
   configurable limit (default 4). Parallel workers default to detached Git
   worktrees; tracked, deleted, untracked, and binary changes are applied back
@@ -81,21 +112,39 @@ parent index.
 - **Update announcements** — when a new configurable feature ships, you are told
   about it once (a persisted marker stops the notice from nagging).
 
+## What this adds beyond generic subagent dispatch
+
+This package combines several concrete runtime behaviors rather than only exposing
+an undifferentiated child-agent launcher:
+
+- language-agnostic semantic role guidance for cleanup intent;
+- a dedicated evidence-first cleaner, with cleanup kept separate from the
+  independent reviewer gate;
+- isolated, retained threads that can be steered, parked, resumed, retargeted, or
+  forked under stable run ids;
+- the reviewer → worker auto-fix → reviewer loop;
+- compact failed-tool warnings with full diagnostics available by run id;
+- direct selected→main fallback plus capability-aware Auto thinking;
+- detached Git worktree isolation for parallel workers and opt-in write-capable
+  cleaner runs.
+
 ## Install
 
 ```bash
 pi install npm:@ferris1225/pi-subagents
 ```
 
-Requires pi **>= 0.80.6**. After installation, open the setup wizard in an
+Requires pi **>= 0.83.0**. After installation, open the setup wizard in an
 interactive TUI session:
 
 ```text
 /subagents-setup
 ```
 
-The default configuration enables `explore`, `worker`, and `reviewer` — you can
-start delegating immediately.
+Fresh installs enable `explore`, `worker`, `cleaner`, and `reviewer` — you can
+start delegating immediately. Existing explicit `enabledAgents` lists are never
+silently extended; users upgrading with an existing explicit list get a one-time
+notice to opt into `cleaner` with `/subagents-setup`.
 
 ## The agents
 
@@ -103,7 +152,8 @@ start delegating immediately.
 | --- | --- | --- |
 | `explore` | Read-only | Fast codebase reconnaissance: broad/open-ended search, multi-file lookups, mapping unfamiliar code. Returns compressed, structured findings. |
 | `worker` | Full | Implements, fixes, refactors, and tests a self-contained task end to end, then reports honest verification. |
-| `reviewer` | Read-only | Adversarial pre-commit quality gate: diff review, plus plans, proposed solutions, codebase health, and PR/issue validation. |
+| `cleaner` | Full | Evidence-first cleanup. Audits and ranks candidates read-only, or applies the smallest proven cuts when removal is explicit; supports worktree isolation. |
+| `reviewer` | Read-only | Adversarial pre-commit quality gate: independently reviews worker and cleaner edits, plus plans, proposed solutions, codebase health, and PR/issue validation. |
 
 Each agent runs in its own isolated `pi` process with a clean context window; it
 has no memory of your conversation, so briefs must be self-contained (goal, exact
@@ -116,6 +166,8 @@ paths, constraints, expected output).
 ```ts
 subagent({ agent: "explore", task: "Map the test setup: which files run what, and how is CI wired? Report exact paths." });
 subagent({ agent: "worker", task: "Implement X in src/foo.ts, add tests, run npm test." });
+subagent({ agent: "cleaner", task: "Audit src/cache for dead code and redundant state; report ranked evidence only." });
+subagent({ agent: "cleaner", task: "Remove the proven dead cache adapter, update its tests/docs, and verify the smallest then broad checks." });
 subagent({ agent: "reviewer", task: "Review the diff of src/index.ts and tests/load.test.ts for correctness and edge cases." });
 ```
 
@@ -124,12 +176,33 @@ subagent({ agent: "reviewer", task: "Review the diff of src/index.ts and tests/l
 ```ts
 subagent({
   tasks: [
-    { agent: "explore", task: "Where is the model fallback logic?" },
+    { agent: "explore", task: "Where is the selected-to-main handoff logic?" },
     { agent: "worker", task: "Add unit tests for models.ts." },
   ],
 });
 ```
 
+### Cleanup routing and lifecycle
+
+The injected guidance routes `cleaner` by explicit semantic intent: **code cleanup**,
+**dead code**, **代码清理**, **精简**, **清理冗余**, **简化**, or **去除过度设计**.
+Requested periodic maintenance passes also qualify; PR counts do not, and cleaner is
+never run automatically as the pre-commit gate.
+
+- **Audit mode:** audit/find/report/review or 审计/查找/检查/报告 wording produces
+  read-only ranked evidence.
+- **Apply mode:** explicit remove/clean/simplify/refactor or 清理/删除/移除/精简/简化/重构
+  wording permits the smallest proven edits plus narrow-then-broad verification.
+
+```text
+explicit cleanup intent → cleaner (audit or apply)
+cleaner apply → reviewer gate → worker auto-fix (on REVIEW_FAIL) → reviewer
+```
+
+`reviewer` remains the independent gate for non-trivial cleaner edits. The auto-fix
+portion runs only when enabled by `maxFixRounds`; cleaner itself is not a pre-commit
+hook or a PR-count scheduler.
+
 ### Vision tasks (screenshots / mockups / designs)
 
 When a task may require viewing images — frontend work, UI review, design
@@ -144,11 +217,10 @@ subagent({
 ```
 
 The sub-agent reads images with its `read` tool. Runtime order for a
-vision-flagged run is configured `visionModel` → that agent's configured backup
-→ current main-window model (deduplicated). A stale configured ref is attempted
-once, then skipped as a permanent candidate error; it is not rewritten. A
-vision-flagged auto-fix chain keeps the flag for worker/re-review rounds because
-they may need to inspect the same images.
+vision-flagged run is `visionModel` → current main-window model. A stale or
+currently unavailable vision selection is skipped immediately without rewriting
+it. A vision-flagged auto-fix chain keeps the flag for worker/re-review rounds
+because they may need to inspect the same images.
 
 ### Controlling and stopping
 
@@ -180,8 +252,10 @@ subagent_control({ action: "fork", id: 7, objective: "Try the smaller alternativ
 
 Single tasks default to `isolation: "shared"`. Parallel `worker` tasks default
 to `isolation: "worktree"`; opt into shared mode only when a worker must see the
-caller's live uncommitted tree. Worktree mode requires a Git repository with a
-committed `HEAD` and is rejected for read-only agents.
+caller's live uncommitted tree. `cleaner` is also write-capable and supports
+worktree mode when explicitly requested (its default remains shared). Worktree
+mode requires a Git repository with a committed `HEAD` and is rejected for the
+read-only `explore` and `reviewer` agents.
 
 A parked isolated thread keeps its current worktree. Resume it there; fork is
 available after that isolated checkpoint settles and its seed is integrated.
@@ -201,26 +275,23 @@ sessions show the recovery paths again until the artifacts are removed.
 ## Configuration
 
 Stored at `~/.pi/agent/pi-subagents.json` (follows `PI_CODING_AGENT_DIR` when
-set). The `/subagents-setup` wizard drives every field interactively — models, the
-default plus each enabled agent's thinking level, the vision model, concurrency,
-fix rounds, idle timeout, scope, and injection — with a per-agent "configure
-one" menu when the config already exists. Model pickers show only models in the
-current session scope that are available through a configured API key or OAuth
-session. `notifyOnReviewPass` and `maxResultLines` are edited directly in the file.
+set). `/subagents-setup` has five top-level choices: enable agents, configure one
+agent's model/thinking, choose a vision model, runtime settings, or full setup.
+There is no backup pool or global thinking menu. Model pickers show only in-scope
+models with configured authentication and display their real supported thinking
+levels. Thinking defaults to **Auto**; manual overrides show only levels supported
+by that agent's effective model. `notifyOnReviewPass` and `maxResultLines` remain
+direct-file settings.
 
 ```json
 {
-  "enabledAgents": ["explore", "worker", "reviewer"],
+  "enabledAgents": ["explore", "worker", "cleaner", "reviewer"],
   "agentModels": {
     "explore": "anthropic/claude-haiku-4-5"
   },
-  "agentBackupModels": {
-    "explore": "openai/gpt-5-mini"
-  },
   "agentThinkingLevels": {
-    "explore": "low"
+    "reviewer": "high"
   },
-  "thinkingLevel": "high",
   "visionModel": "anthropic/claude-sonnet-4-5",
   "notifyOnReviewPass": false,
   "maxResultLines": 80,
@@ -235,45 +306,64 @@ session. `notifyOnReviewPass` and `maxResultLines` are edited directly in the fi
 | Field | Description |
 | --- | --- |
 | `enabledAgents` | Agent names exposed to discovery and prompt injection. An empty array disables all agents. |
-| `agentModels` | Optional primary `provider/model-id` override per agent. |
-| `agentBackupModels` | Optional backup per agent, tried after its primary and before the current main-window model. |
-| `agentThinkingLevels` | Optional thinking level per agent; agents without an entry use the agent's frontmatter `thinking`, then `thinkingLevel`. |
-| `thinkingLevel` | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default `high`). |
+| `agentModels` | Optional selected `provider/model-id` per agent. Missing = current main model. Model-level failure hands directly to current main. |
+| `agentThinkingLevels` | Optional manual preference per agent. Missing = Auto (agent frontmatter preference, or `high`, clamped to the effective model's supported levels). |
 | `visionModel` | Optional vision-capable model for `vision: true` tasks (screenshots/mockups/designs). Unset = falls back to the main session's current model. |
 | `notifyOnReviewPass` | When `true`, a passing reviewer result is delivered without waking the main agent (default `false`). |
-| `maxResultLines` | Max lines of a sub-agent result carried in the completion message (default `80`). Longer results are truncated; the full text is written to a temp file whose path is included in the message. |
+| `maxResultLines` | Max lines of a sub-agent result carried in the completion message (default `80`). Longer results are truncated; full text is written to an extension-named temporary `.md`. At session start and on each write, only recognized result files older than 7 days are removed; each canonical project path has its own newest-50 bucket. |
 | `proactiveInjection` | Whether to add the delegation directive to the main system prompt. |
 | `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
 | `maxConcurrency` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
 | `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL` (default 2; `0` disables the loop). |
-| `idleTimeoutSec` | Idle watchdog: a sub-agent whose stdout goes silent for this long is terminated and retried. `0` disables it. Default 90. |
+| `idleTimeoutSec` | Idle watchdog: a sub-agent whose stdout goes silent for this long is terminated; a selected model then hands to current main. `0` disables it. Default 90. |
 
-### Model precedence and fallback
-
-Normal run pool:
+### Model routing and thinking
 
 ```text
-configured agent primary → configured agent backup → current main-window model
+selected agent/vision model → current main-window model
 ```
 
-If no primary is configured, the current main-window model is primary; the
-agent frontmatter model is used only when no current main model exists. For
-vision runs, `visionModel` replaces the first slot while the selected agent's
-backup and current main model remain the fallbacks. Duplicate refs are removed.
-
-Each candidate gets startup-race retries. Provider failures retry the same
-candidate up to five times only when transient (timeouts, network, 429, 5xx).
-Permanent model/config failures (`model not found`, unknown provider, 404) and
-quota/auth/billing failures skip that delay and advance immediately. No runtime
-outcome rewrites `pi-subagents.json`. If the whole pool fails, the result is
-handed to the main window with its retained run id and session.
+Without a selected model, current main runs immediately; agent frontmatter model
+is used only when no main model exists. A selection missing from Pi's live
+available catalog is skipped. Any model-level runtime failure — rate limit,
+quota, invalid key/auth, missing model, provider error, or idle model stream —
+hands directly to current main, including stream errors that retain partial text.
+A child-only Pi extension wraps the selected provider's registered API stream
+with `maxRetries: 0`; if Pi schedules its separate outer turn retry, the RPC parent
+immediately sends `abort_retry` before another provider call. This uses supported
+extension/RPC surfaces in Node and standalone/Bun builds, never rewrites global or
+project settings, and does not alter descendant tool environments. Tool/test
+failures stay on the same model because they are task failures, not model
+availability failures. Only a truly
+zero-activity process startup race can retry; an accepted prompt or any
+agent/turn/stream/tool activity forbids replay.
+
+Auto thinking starts from the Agent's declared preference (`low` for `explore`,
+`high` for the other built-ins) and uses Pi's capability map to clamp it to the
+actual model. Non-reasoning models resolve to `off`; `xhigh`/`max` appear in setup
+only when that model explicitly supports them. A selected→main handoff re-clamps
+thinking for the main model.
+
+### Choosing an explore model
+
+Choose a competent fast code model for `explore`, not automatically the cheapest
+model. Cheap reconnaissance is useful for mechanical symbol/path discovery, but
+a missed dynamic entrypoint or ownership edge can cost more through downstream
+rework. Direct main-model handoff handles provider/runtime failure; it cannot
+detect a plausible but incomplete answer.
+
+`explore` therefore returns an index of exact paths, lines, symbols, and explicit
+uncertainty. The main agent, worker, or cleaner must re-read load-bearing files
+before editing or deciding deletion, security, compatibility, persistence, or
+dynamic reachability. Prefer a stronger model or direct specialist for complex
+dynamic loading, concurrency, migrations, and security-sensitive code.
 
 ### Resuming retained context
 
-Every run stores its Pi session in a private temp directory. Same-model retries
-and pool fallbacks resume that session, so searches, reads, reasoning, and edits
-remain in context. A parked, completed, or failed thread can later be resumed
-under its stable id:
+Every run stores its Pi session in a private temp directory. A selected→main
+handoff resumes that same session, so searches, reads, reasoning, and edits remain
+in context. A parked, completed, or failed thread can later be resumed under its
+stable id:
 
 ```ts
 subagent_control({ action: "resume", id: 7 });
@@ -286,11 +376,14 @@ sessions live until the parent Pi session shuts down.
 
 ### Configuration migration
 
-The config file migrates itself on load — no manual steps after an upgrade:
-schema upgrades are normalized and saved back, removed agents are stripped,
-legacy keys (`maxParallelTasks`, `maxSubagentDepth`) are folded in or dropped,
-and new fields are filled with defaults. New features are announced to you once
-after an update via a toast (marker persisted in `announcedFeatures`).
+The config file normalizes itself on load — no manual steps after an upgrade.
+Configured non-empty agent names are preserved, while invalid and obsolete keys
+are removed. This release deletes `agentBackupModels` and global `thinkingLevel`
+in addition to older `maxParallelTasks` / `maxSubagentDepth`; per-agent thinking
+preferences remain and are capability-clamped at runtime. A pre-existing explicit
+`enabledAgents` array is still preserved without appending `cleaner`. Existing
+configs without it receive a one-time `/subagents-setup` notice, tracked internally
+in `announcedFeatures`.
 
 ## Agent discovery and overrides
 
@@ -305,14 +398,15 @@ after an update via a toast (marker persisted in `announcedFeatures`).
 
 ## How it stays reliable
 
-- **Ordered model resilience** — transient failures retry the same candidate,
-  then advance through configured backup and current-main candidates. Permanent
-  stale-model/config and quota/auth/billing errors skip same-model backoff.
+- **Direct model recovery** — unavailable selections skip immediately; any
+  selected-model provider/auth/quota/rate-limit failure hands directly to current
+  main with thinking re-clamped to the main model.
 - **Startup-race retries** — a silent zero-activity child exit (concurrent pi
   startup lock contention) is relaunched with backoff; only clean silent exits
   qualify, so real work is never duplicated.
-- **Idle watchdog** — a stalled provider stream (no output for `idleTimeoutSec`)
-  terminates the child and retries via the normal fallback path.
+- **Idle watchdog** — a stalled selected-model stream (no output for
+  `idleTimeoutSec`) terminates the child and hands the retained session to current
+  main.
 - **Dispatch failures surface** — partial parallel startup reports every failed
   item and reason; if none start, the tool throws so Pi records a real tool error.
   Dispatch crashes likewise produce a failed result instead of a silent hang.
@@ -328,11 +422,10 @@ npm test
 ```
 
 The source is modular: `dispatch.ts` (dispatch, controls, isolation, auto-fix),
-`rpc-run.ts` / `spawn.ts` (persistent child transport + model pools),
-`worktree.ts` / `session-fork.ts` (filesystem/session branching),
-`trajectory.ts` (internal lifecycle history), `tools.ts`
-(wait/status/control/stop), `announcements.ts` (recovery and feature notices),
-and `runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
+`rpc-run.ts` / `spawn.ts` (persistent child transport + selected→main handoff),
+`worktree.ts` / `session-fork.ts` (filesystem/session branching), `tools.ts`
+(wait/status/control/stop), `widget.ts` (active-only TUI status), `announcements.ts`
+(recovery and feature notices), and `runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
 dependencies.
 
 ## License

package/agents/cleaner.md

@@ -0,0 +1,51 @@
+---
+name: cleaner
+description: Evidence-first code cleanup agent with full tools. Use for explicit or periodic cleanup intent in any language, such as code cleanup, dead code, reducing redundancy, simplifying, or removing over-engineering. Audit/find/inspect/report wording means read-only ranked evidence; explicit remove/clean/simplify/refactor wording enables the smallest proven edits plus verification. Never trigger from PR counts or use it as the pre-commit gate; reviewer remains the gate and reviews cleaner edits.
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: REASONING + CODEBASE TRACING. Cleanup requires proving reachability
+# and ownership before editing. No `tools` field => all tools (write-capable).
+---
+
+You are a cleaner agent: an evidence-first specialist for reducing accidental codebase complexity. You have full tools but edit only in apply mode. You have NOT got the caller's conversation history; the task brief is your complete input.
+
+A candidate is not a deletion. Static tools, search counts, apparent duplication, and prior reconnaissance only produce leads. Never inherit deletion proof from an `explore` report: re-read load-bearing files and repeat the decisive searches yourself. Remove code only after proving consumers, reachability, ownership, history, boundaries, and verification. A result with no safe cuts is valid.
+
+## Choose the mode
+- **Audit mode** — cleanup wording such as audit, find, inspect, review, or report: do not edit. Return a short ranked set of evidence-backed candidates.
+- **Apply mode** — explicit cleanup wording such as remove, clean up, simplify, or refactor: make only the smallest proven cuts, then verify them.
+- If wording conflicts or would remove a user capability, public API, persisted format, wire contract, or compatibility path, stop at evidence and state the product tradeoff unless the brief explicitly approves it.
+- This agent is for explicit cleanup intent, including periodic maintenance passes. It is never scheduled by PR count and never replaces `reviewer` as the pre-commit gate.
+
+## Evidence-first workflow
+1. Read repository instructions, manifests, architecture/decision records, and test guidance. Inspect `git status` and preserve unrelated work. Identify generated, vendored, fixture, migration, and published surfaces.
+2. Trace real runtime paths through entrypoints, configuration, registries, dynamic imports, dependency injection, events, queues, persistence, processes, and protocols. Start with central production surfaces, not isolated unused-looking symbols.
+3. In apply mode, discover narrow and broad checks and run a proportional baseline when feasible. Record an already-red baseline; it cannot prove a regression later.
+4. Survey for unconsumed APIs/config, duplicate facts or lifecycle state, speculative abstractions, forwarding-only layers, abandoned compatibility/support residue, and hand-rolled infrastructure already covered by the platform or installed dependencies.
+5. For each candidate, search symbols, paths, strings, alternate call forms, docs, tests, and package metadata across the repository. Inspect callers and callees. Distinguish production consumers from support-only references and ambiguous dynamic/plugin/reflection/codegen entrypoints.
+6. Read relevant history and decisions. Map stateful or asynchronous ownership: who creates, mutates, cancels, disposes, and observes each state or terminal outcome. State what behavior a cut gives up, even when the answer is none observable.
+7. Reject or downgrade the cut when a real consumer exists; dynamic/external reachability is unresolved; current rationale still holds; complexity merely moves elsewhere; or the change is actually a product/API decision.
+
+Never simplify away authorization, validation at trust boundaries, security controls, accessibility basics, data-loss protection, durable-data compatibility, public contracts, or resource-quiescence cleanup without explicit approval.
+
+## Apply proven cuts
+- Work within one ownership boundary at a time and keep batches reviewable.
+- Delete an obsolete contract end to end: declaration, implementation, callers, branches, exports, config, dependencies, dedicated tests, docs, examples, snapshots, and generated inventories.
+- Preserve tests of surviving observable behavior. Prefer deletion, then platform features, then dependencies already present; do not add replacement glue that erases the net reduction.
+- Re-search removed names and stale documentation. Run the narrowest decisive check first, then the repository's relevant broad type/lint/test/build gates. Inspect the complete diff and run `git diff --check` when available.
+- Do not weaken a meaningful check to force a cut through. Repair or revert only the current batch when evidence fails.
+
+## Report
+For an audit, rank candidates by confidence, risk, and estimated net maintenance reduction using compact evidence:
+
+```text
+[confidence / risk] candidate
+evidence: consumers, dynamic/public/compatibility checks, history and owner
+cut: exact contracts, artifacts, dependencies, and concepts removed
+tradeoff: observable behavior lost, or none proven
+verify: smallest decisive check; estimated net reduction
+```
+
+For applied work, report exact files/contracts removed, measurable net reduction, tradeoffs, and every check actually run with its result. Name valuable candidates kept and why. Never equate green tests with proof, or deletion volume with value.
+
+Finish by recommending a fresh `reviewer` pass over any edits. The reviewer, not cleaner, is the pre-commit gate.

package/agents/explore.md

@@ -4,16 +4,17 @@ description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad o
 tools: read, grep, find, ls, bash
 model: claude-haiku-4-5
 thinking: low
-# Model selection: SPEED over depth. Pick the fastest available model.
-# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
+# Model selection: SPEED with reliable code comprehension. Pick a competent fast
+# model, not automatically the cheapest; missed architecture costs more in rework.
 ---
 
-You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
+You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. The caller still re-reads load-bearing sections before acting. You have NOT got the caller's conversation history — the task brief is your only input.
 
 ## Hard constraints
 - You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
 - Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
 - Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+- Treat every finding as a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions.
 
 ## When invoked
 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).
@@ -29,6 +30,7 @@ You are an explore agent: a fast, read-only reconnaissance specialist. You inves
 
 ## Collaboration
 - Your output feeds `worker` (or the main agent directly). Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
+- The caller must re-read load-bearing files before editing or making safety/reachability decisions. Make that verification boundary explicit instead of presenting reconnaissance as a final judgment.
 
 ## Output format
 ## Files Retrieved
@@ -41,4 +43,4 @@ A brief explanation of how the pieces connect.
 Which file to look at first, and why.
 
 ## Quality standards
-Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose.
+Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose. State uncertainty and missing coverage; a plausible guess is more expensive than an honest gap.

package/agents/reviewer.md

@@ -60,5 +60,7 @@ Understand the context first, then verify: the fix addresses the root cause, cha
 One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
 End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
 
+REQUEST_CHANGES (or review-blocking concern) on this extension automatically starts an auto-fix loop: a worker is briefed with your findings, then you re-review, up to the configured round limit. Choose REVIEW_PASS when nothing objectively blocks the change (style preferences, optional refactors, or items the caller can knowingly accept are not blockers) — do not force a verdict that would trigger another loop just to hedge.
+
 ## Quality standards
 Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "1.0.0",
-  "description": "Controllable background sub-agent threads for pi: explore, worker, reviewer, auto-fix chains, model pools, and Git worktree isolation.",
+  "version": "2.0.0",
+  "description": "Controllable background sub-agent threads for pi: specialized roles, capability-aware thinking, direct main-model fallback, auto-fix chains, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -12,7 +12,9 @@
     "pi-extension",
     "subagent",
     "sub-agent",
-    "delegation"
+    "delegation",
+    "code-cleanup",
+    "dead-code"
   ],
   "files": [
     "src",
@@ -31,10 +33,10 @@
     "prepack": "npm run check && npm test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.80.6",
-    "@earendil-works/pi-ai": ">=0.80.6",
-    "@earendil-works/pi-coding-agent": ">=0.80.6",
-    "@earendil-works/pi-tui": ">=0.80.6",
+    "@earendil-works/pi-agent-core": ">=0.83.0",
+    "@earendil-works/pi-ai": ">=0.83.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@earendil-works/pi-tui": ">=0.83.0",
     "typebox": "*"
   },
   "devDependencies": {

package/src/agents.ts

@@ -31,11 +31,6 @@ export interface AgentConfig {
 	filePath: string;
 }
 
-export interface AgentDiscoveryResult {
-	agents: AgentConfig[];
-	projectAgentsDir: string | null;
-}
-
 const here = dirname(fileURLToPath(import.meta.url));
 /** <package>/agents — the agents shipped with this extension. */
 export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
@@ -135,7 +130,7 @@ export interface DiscoverOptions {
  * Discover agents across scopes and apply the enabled-name filter.
  * Override priority for the same name: project > user > builtin.
  */
-export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
+export function discoverAgents(cwd: string, options: DiscoverOptions = {}): { agents: AgentConfig[] } {
 	const scope = options.scope ?? "user";
 	const builtinDir = options.builtinDir ?? BUILTIN_AGENTS_DIR;
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
@@ -160,7 +155,7 @@ export function discoverAgents(cwd: string, options: DiscoverOptions = {}): Agen
 		agents = agents.filter((agent) => enabled.has(agent.name));
 	}
 
-	return { agents, projectAgentsDir };
+	return { agents };
 }
 
 /** One-line catalog entry for system-prompt injection and error messages. */