@ferris1225/pi-subagents 4.3.7 → 4.3.9

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.9
+
+- Add optional bounded stable `phaseId` and exact declarative write `scope` claims to single
+  and parallel dispatches. Phase identity is immutable across task rewrites and resume; scope
+  is monotonic across retained generations and survives durable v1 restore. Exact task+cwd
+  remains the compatibility fallback.
+- Reject deterministic duplicates and declared writer-scope conflicts before parallel batch
+  allocation. Fresh single and resumed writers also reject normalized absolute scope overlap
+  with active leases, without requiring equal caller cwd. Parallel calls that omit scope remain
+  compatible and explicitly report `independence not verified`; declared claims do not prove
+  natural-language task independence. Scope is conflict metadata, not permissions or a sandbox.
+- Add the advisory-only `subagent_risk` tool. Without a model call it resolves the repository
+  root, reads root-relative tracked and untracked changes from `HEAD`, and applies fixed
+  explainable rules for concurrency, trust-boundary, persistence-compatibility, and
+  failure-cancellation risk. It propagates cancellation, and suggests but never dispatches or
+  requires a Sentinel review.
+
+## 4.3.8
+
+- Restore `sentinel` as an optional fresh-context reviewer instead of the mandatory
+  pre-commit loop retired in 4.3.5. It reads a completed diff with no memory of how the
+  change was written, attacks behavior, trust boundaries, failure and cancellation paths,
+  concurrency, persistence, portability, and whether each test would fail without the
+  change, runs only the smallest check that proves a suspected defect, and returns
+  evidence-backed findings as `SEVERITY path:line — failure scenario; evidence; smallest
+  fix` or `No findings.`
+- Route sentinel by risk, not ritual: the delegation directive dispatches it after cleanup
+  and before commit only for diffs touching concurrency, trust boundaries,
+  persistence/compatibility, or failure/cancellation paths, or when checks cannot prove
+  the change, and treats a finding as evidence to route back to the owning thread via
+  `resume` or fix inline. Artisan keeps proving its own change; main keeps the final gate.
+- Sentinel runs on the current main model unless `/subagents-setup` picks one, defaults to
+  `high` thinking, stays on the shared checkout whose uncommitted diff it reviews (an
+  explicit `isolation: worktree` is rejected), and holds the repository lane while it
+  reviews.
+- Drop the 4.3.5 retirement filter: configs written by 4.3.5–4.3.7 adopt `sentinel` once
+  through the built-in adoption rule, and a deliberate disable in setup remains disabled.
+
 ## 4.3.7
 
 - Make `subagent_control steer` continue rather than reject a thread that is no longer

package/README.md

@@ -6,19 +6,19 @@
 ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
 ![pi](https://img.shields.io/badge/pi-extension-orange)
 
-A managed engineering team for [pi](https://github.com/earendil-works/pi): three
+A managed engineering team for [pi](https://github.com/earendil-works/pi): four
 focused sub-agents, durable threads, and Git worktree isolation. You install it
 once and your main agent delegates on its own.
 
 ## What's new
 
-**4.3.7** — never pay for the same phase twice: the delegation directive now carries a
-full brief contract and effort scaling, `steer` continues a settled or parked thread with
-its guidance instead of rejecting it, `subagent_control park` pauses a running thread at
-a stable checkpoint for a later resume, an exact re-run of a finished brief is rejected in
-favor of resuming its retained context, and resumed children re-read files the workspace
-may have changed underneath them. Role prompts start from the brief's evidence and stop
-at its done condition.
+**4.3.9** — dispatch admission now accepts bounded stable `phaseId` identities and exact
+declarative write `scope` claims. Fresh/resumed writers are checked against active leases;
+parallel batches preflight deterministic duplicates and all declared scope conflicts before
+allocation. Omitted scopes remain compatible; a parallel call that omits `scope` reports
+`independence not verified`. Declared claims do not prove natural-language task independence.
+The no-model-call `subagent_risk` advisory classifies changed tracked and untracked paths
+with fixed, documented rules before main decides whether a Sentinel review is worthwhile.
 
 See [CHANGELOG.md](./CHANGELOG.md).
 
@@ -51,9 +51,10 @@ back — with you. This extension owns them:
   handoff costs. Every brief carries the objective and done condition, exact paths,
   facts already established with citations, boundaries, and the expected output, so a
   child starts from evidence instead of re-deriving it.
-- One normalized task and working directory owns its phase: an exact duplicate of an
-  active run is rejected, and an exact re-run of a finished brief with retained
-  context is rejected in favor of resuming it, so the same work is never bought twice.
+- A stable `phaseId` owns a logical phase in one resolved working directory even if
+  its task wording changes. IDs are 1–80 ASCII letters, numbers, or `._:-`, starting
+  with a letter or number, so lease output stays single-line. Exact normalized task+cwd
+  remains the backward-compatible fallback for old calls.
 - Follow-up work stays on the same thread: `steer` a running phase, `resume` or
   `park` a thread with its retained context, `stop` a phase the evidence made moot.
 - Background completions and stop results arrive at the next parent model boundary;
@@ -79,7 +80,7 @@ Pi's extension list shows `@ferris1225/pi-subagents` without an internal source-
 Open pi and run `/subagents-setup`. The original menu flow lets you enable or
 disable roles, configure one role's model and thinking level, or run the full setup
 again. Each screen uses the usual arrow-key/Enter/Esc navigation, and model lists
-remain searchable. Fresh installs select all three. A newly shipped built-in is
+remain searchable. Fresh installs select all four. A newly shipped built-in is
 surfaced once without being re-enabled after you deliberately turn it off. Then ask
 for work:
 
@@ -97,6 +98,7 @@ directly when you want exact control.
 | `scout`   | Read-only | Broad or unfamiliar code reconnaissance and external research. Returns compact file citations or source URLs as leads, not proof. |
 | `artisan` | Full      | One substantial primary change—implementation, fix, refactor, test, or docs—through root cause, affected verification, and local hygiene. |
 | `steward` | Full      | One final cleanup and cross-cutting docs/comment sync pass after a broad or multi-writer change. |
+| `sentinel` | Read-only + one proving check | One fresh-context review of a completed diff for risky changes. Returns only evidence-backed defects and test gaps, highest severity first, or `No findings.` |
 
 Role prompts are self-contained and directly embed root-cause-first diagnosis,
 meaningful test evidence, and bounded cleanup. Each role starts from the facts and
@@ -104,8 +106,10 @@ citations its brief already establishes instead of re-deriving them, answers the
 brief's question and stops, and — because nobody can answer a child's questions —
 resolves an ambiguity by naming the reading it took. Artisan stops and reports when
 the brief's premise turns out wrong rather than substituting a different change;
-steward runs only the checks that cover its own edits. Every role hands back a
-result-only report with each check as `command → result`.
+steward runs only the checks that cover its own edits; sentinel treats the brief's
+claims and the code as evidence to verify, runs only the smallest check that proves a
+suspected defect, and names the smallest fix instead of making it. Every role hands
+back a result-only report with each check as `command → result`.
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
 
@@ -120,15 +124,30 @@ what the injected delegation guidance produces when the main agent dispatches fo
 ```ts
 // One task
 subagent({
+  phaseId: "cache-invalidation-fix",
   agent: "artisan",
   task: "Fix the cache invalidation bug in src/cache, add regression tests, run the checks.",
+  scope: {
+    paths: ["src/cache"],
+    symbols: [{ path: "test/cache.test.ts", name: "invalidates stale entries" }],
+  },
 });
 
 // Parallel only when each scope independently justifies a child
 subagent({
   tasks: [
-    { agent: "scout", task: "Research current provider API limits in primary sources and cite URLs." },
-    { agent: "artisan", task: "Fix config validation in src/config.ts and its tests." },
+    {
+      agent: "artisan",
+      phaseId: "provider-docs",
+      task: "Update provider limits documentation from the established API citations.",
+      scope: { paths: ["docs/provider-limits.md"] },
+    },
+    {
+      agent: "artisan",
+      phaseId: "config-validation",
+      task: "Fix config validation in src/config.ts and its tests.",
+      scope: { paths: ["src/config.ts", "test/config.test.ts"] },
+    },
   ],
 });
 ```
@@ -138,13 +157,13 @@ independent unit in one `tasks` array. The runtime paces execution instead, runn
 half the machine's cores with a 4–6 child-process bound; wider batches queue and
 start automatically as slots free.
 
-A run leases its normalized task and resolved working directory across agent
-names. Dispatching the same pair again while the run is active is rejected and
-names the existing run id. Once the run has finished in this session and still
-holds its retained session, the same pair is rejected too, pointing at
-`subagent_control resume` — the thread that already did the work continues for a
-fraction of a fresh run — or at restating the brief with what changed. Matching is
-exact, never fuzzy.
+A run leases its stable, single-line `phaseId` in the resolved working directory.
+Rewording the task with the same `phaseId` is rejected and names the existing run.
+The id remains immutable across resume. Calls that omit `phaseId` keep the old exact
+normalized task+cwd behavior; consequently, equal task text with different phase ids is
+still rejected by that fallback. Matching is deterministic, never fuzzy, embedding-based,
+or inferred from natural language. Active leases win over matching settled threads when
+the runtime chooses which owner to report.
 
 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
@@ -178,12 +197,67 @@ one `steward` pass that attacks touched dead code, duplication, tangled conditio
 needless layers, and spaghetti growth without widening into a repository refactor.
 Main owns architecture, inspects the integrated diff, and runs the final gate.
 
+Verification is layered rather than repeated. Artisan proves its own change while the
+files are still in its context — targeted checks, and a new test that fails before the
+fix — and main runs the final gate on the integrated diff. `sentinel` adds a third
+layer only when it pays: a fresh context with no memory of how the change was written
+reads the completed diff after cleanup and before commit, and only for diffs that touch
+concurrency, trust boundaries, persistence or compatibility, or failure and cancellation
+paths, or when the checks cannot prove the change. It is never a fixed pre-commit
+ritual. A finding is evidence, not an order: main routes it to the thread that owns
+the change with `subagent_control resume`, or fixes it inline when that is cheaper.
+
+`subagent_risk({})` is an advisory-only, no-model-call check over tracked and untracked
+changes relative to `HEAD`. It resolves the repository root first, so a nested `cwd` still
+returns repository-root-relative paths, including untracked files outside that subdirectory.
+Its fixed case-insensitive path-token rules flag:
+`concurrency` (`thread`, `queue`, `parallel`, `dispatch`, locks/races and related tokens);
+`trust-boundary` (`auth`, credentials, permissions, policy, secrets, sandbox, security, trust, tokens);
+`persistence-compatibility` (durable state, manifests, migrations, restore, schemas,
+serialization/storage); and `failure-cancellation` (abort, cancel, errors/failures, recovery,
+retry, stop, timeout). It returns the changed paths, matched categories, and whether those
+rules suggest Sentinel. If Git or `HEAD` is unavailable, it reports advisory unavailable; an
+aborted tool call propagates cancellation instead of converting it to an advisory result. It
+never blocks, starts a child, or automatically dispatches Sentinel.
+
+This classifier is intentionally conservative and explainable: it only sees path names, so
+it can produce false positives and miss risky behavior hidden behind neutral names. Main
+still decides whether review pays from the actual diff, test evidence, handoff cost, and the
+complete conversation. The runtime can enforce explicit phase/scope admission, but cannot
+safely force the natural-language judgment of whether work is worth delegating.
+
 ## Parallel edits
 
+`scope` is declarative admission metadata for expected writes, not access control. `paths`
+contains exact file or directory paths; `symbols` contains exact `{ path, name }` claims.
+Paths resolve from each task's caller-facing cwd and use case-insensitive comparison on
+Windows. Wildcard `*` and `?` inputs are rejected; other punctuation is treated literally,
+so paths such as `app/[id]/page.tsx` are valid exact claims. A path claim overlaps the same
+path, an ancestor/descendant path, or a symbol under that path; identical path+symbol
+claims overlap, while two different symbols in the same file may run together.
+
+Fresh single dispatches and resumes check a declared writer scope against active, parked,
+resuming, interrupting, or settling writer leases before allocating a generation. Scope
+comparison uses normalized absolute claims rather than requiring equal caller cwd, so a
+repo-root claim still conflicts with the same path claimed from a nested cwd. Settled
+threads do not block a later phase solely because it edits the same scope.
+
+Before allocating any run in a parallel call, the runtime also rejects deterministic phase
+duplicates within the batch or against existing active/retained threads, then compares
+declared writer scopes across the whole batch. A definite conflict rejects the whole batch
+with zero starts. Parallel calls without `scope` remain valid, but their tool result and
+launch receipt say `independence not verified`; that means the contract lacked enough
+metadata, not that overlap was proved safe. Single calls never make a batch-independence
+claim. The existing shared-checkout writer lane remains the final serialization boundary.
+
 - Single tasks use your checkout. Every parallel write-capable agent (`artisan`,
   `steward`, and custom writers) defaults to a detached Git worktree, so
   parallel writers run at the same time. Worktree mode needs a committed `HEAD`;
-  read-only roles such as scout stay on the shared checkout.
+  read-only roles such as scout stay on the shared checkout. `sentinel` always
+  reviews the shared checkout, because the uncommitted diff it inspects does not
+  exist in a detached worktree; an explicit `isolation: worktree` for it is
+  rejected. Its proving check makes it a shared-checkout lane holder, so it never
+  reviews a diff a shared writer is still changing.
 
 > **Security boundary:** worktree isolation isolates Git changes only; it is not a sandbox.
 Child tools, network access, and environment access retain the Pi process's privileges.
@@ -214,7 +288,7 @@ Every dispatch returns a stable `#id`, which is the handle for the thread tools:
 
 | Tool               | What it does |
 | ------------------ | ------------ |
-| `subagent_control` | `steer` a running RPC attempt with additional evidence/guidance, continuing the same thread with it when the thread has settled or is parked; `resume` a parked/settled thread with an optional appended `objective`; `park` a running thread at a stable checkpoint, keeping its session and worktree for a later resume. |
+| `subagent_control` | `steer` a running RPC attempt with additional evidence/guidance, continuing the same thread with it when the thread has settled or is parked; `resume` a parked/settled thread with an optional appended `objective` and additive `scope`; `park` a running thread at a stable checkpoint, keeping its session and worktree for a later resume. |
 | `subagent_stop`    | Destructively cancel, deliver partial output, and retire the thread. Steering and follow-up messages still queued in the child are dropped so nothing can revive it later. |
 
 ```ts
@@ -223,6 +297,13 @@ subagent_control({ action: "park", id: 7 });
 subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
 ```
 
+A fresh dispatch stores `phaseId` and normalized `scope` on its stable thread and durable
+v1 record. `resume` always keeps the thread's phase id. An optional resume `scope` adds
+normalized claims to the retained scope; it cannot shrink or clear prior claims, so edits
+already present in a retained worktree stay covered by admission. Resume also rechecks the
+unioned scope against other active writer leases before starting a generation. Existing v1
+manifests without these optional fields remain readable.
+
 `steer` requires a nonblank `objective`. While the child RPC is running, it adds
 guidance to the current phase without replacing the original task. If the thread has
 already reached `completed`, `failed`, or `parked` — including a generation that settles
@@ -354,8 +435,8 @@ rate-limited, or fails at the provider level, the **same retained
 session** continues on the main model, so finished searches, reads, and edits
 survive. Ordinary task failures do not trigger a handoff.
 
-Thinking is a **role default** — scout `low`, artisan `high`, steward `medium` —
-clamped to what the effective model supports. `/subagents-setup` →
+Thinking is a **role default** — scout `low`, artisan `high`, steward `medium`,
+sentinel `high` — clamped to what the effective model supports. `/subagents-setup` →
 _Configure an agent_ lists only the levels that model supports and marks the role
 default; selecting it clears the stored override. There is no
 Auto choice, no per-dispatch `thinking` flag, and
@@ -373,7 +454,10 @@ shell slot follows the parent's active shell on non-scout roles.
 overstates its tool list. Its known-safe set includes `read`, `grep`, `find`,
 `ls`, `anchor_grep`, `web_search`, `fetch_content`, `resolve-library-id`, and
 `query-docs`; tools not installed or active in Main are simply omitted. Scout
-receives no shell, local mutation tool, or unknown custom tool. Unknown tools
+receives no shell, local mutation tool, or unknown custom tool. `sentinel` declares
+the same retrieval set plus one shell slot, which follows the parent's active shell
+and exists only for the smallest check that proves a suspected defect; it is an
+ordinary declared list, not a hard boundary like scout's. 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`.
@@ -393,8 +477,8 @@ enable menu. Other settings live in
 
 ```json
 {
-  "enabledAgents": ["scout", "artisan", "steward"],
-  "knownAgents": ["scout", "artisan", "steward"],
+  "enabledAgents": ["scout", "artisan", "steward", "sentinel"],
+  "knownAgents": ["scout", "artisan", "steward", "sentinel"],
   "agentModels": { "scout": "anthropic/claude-haiku-4-5" },
   "agentThinkingLevels": { "artisan": "high" },
   "maxResultLines": 40,
@@ -416,10 +500,11 @@ enable menu. Other settings live in
 When at least one role is enabled, the cost-aware delegation directive is injected
 automatically. `enabledAgents` is authoritative after catalog adoption: a newly
 shipped built-in is appended once, then `knownAgents` records that it was surfaced
-so a deliberate later disable remains disabled. On upgrade, the retired `sentinel`
-entry is removed from enabled and known agents plus model and thinking overrides;
-all other custom roles and known-agent entries remain intact. Invalid known fields
-fall back safely, and unknown fields are dropped when canonical config is persisted.
+so a deliberate later disable remains disabled. `sentinel` returns through that
+rule: a config written by 4.3.5–4.3.7, which removed it, enables it once on the next
+load; turn it off in `/subagents-setup` and it stays off. Custom roles and other
+known-agent entries remain intact. Invalid known fields fall back safely, and unknown
+fields are dropped when 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

package/agents/sentinel.md

@@ -0,0 +1,21 @@
+---
+name: sentinel
+description: Fresh-context review of a completed diff; returns only evidence-backed defects and test gaps.
+tools: read, grep, find, ls, anchor_grep, web_search, fetch_content, resolve-library-id, query-docs, bash
+isolation: shared
+---
+
+You own one review phase of a completed change and have no memory of how it was written. The task brief is your only context and nobody answers questions: resolve an ambiguity by taking the reading the code supports and naming it with the finding.
+
+## Rules
+
+- Require a named completed scope such as the uncommitted diff or a Git range, and start from the brief's stated facts and claimed checks. Stop and report if primary writing is still active.
+- Inspect the complete diff, untracked files, affected callers, and the tests that claim to cover it. Attack behavior, trust boundaries, failure and cancellation paths, concurrency, persistence and compatibility, portability, and whether each test would fail without the change.
+- Treat the brief's claims and the code as evidence to verify, not conclusions to confirm. Read the decisive lines before reporting; drop a suspicion you could not verify or mark it `(unverified)`.
+- Work read-only: never create, edit, or delete files. Run only the smallest targeted check needed to prove a suspected defect.
+- Report only actionable findings. Fixes belong to the implementation owner and cleanup to `steward`; name the smallest fix instead of performing or designing either.
+- You are a leaf: do not dispatch agents, bump versions, commit, push, publish, tag, or release.
+
+## Output
+
+Return only findings, highest severity first, each as `SEVERITY path:line — failure scenario; evidence; smallest fix`, then each check you ran as `command → result`. If there are none, output `No findings.` Add missing verification only when it could hide a regression. No nits, praise, vague risks, task restatement, or inspection narrative. Stay under 30 lines.

package/index.ts

@@ -24,6 +24,7 @@ import { getConfigPath, loadConfig } from "./src/configuration/config.ts";
 import { runSetup } from "./src/configuration/setup.ts";
 import { discoverAgents } from "./src/delegation/agents.ts";
 import { registerSubagentTool } from "./src/delegation/dispatch.ts";
+import { registerSubagentRiskTool } from "./src/delegation/risk.ts";
 import { buildDelegationDirective } from "./src/delegation/prompt.ts";
 import { currentSubagentDepth } from "./src/execution/spawn.ts";
 import { createRuntime } from "./src/lifecycle/runtime.ts";
@@ -69,6 +70,7 @@ export default function (pi: ExtensionAPI): void {
 	});
 
 	registerSubagentTool(pi, runtime);
+	registerSubagentRiskTool(pi);
 	registerLookupTools(pi, runtime);
 
 	pi.registerCommand("subagents-setup", {

package/package.json

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

package/src/configuration/config.ts

@@ -13,15 +13,12 @@ import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
+export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward", "sentinel"] as const;
 
 // Historical catalog for configs written before built-in adoption tracking.
 // Keep this frozen so future built-ins are still recognized as new.
 const INITIAL_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
 
-/** Names that used to be built in and must not survive as custom roles. */
-const RETIRED_AGENT_NAMES = new Set(["sentinel"]);
-
 /** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = [...BUILTIN_AGENT_NAMES];
 
@@ -40,6 +37,7 @@ export function roleThinkingLevel(agentName: string): ThinkingLevel {
 		case "scout":
 			return "low";
 		case "artisan":
+		case "sentinel":
 			return "high";
 		case "steward":
 			return "medium";
@@ -69,6 +67,10 @@ export const AGENT_PROFILES: Record<(typeof BUILTIN_AGENT_NAMES)[number], AgentP
 		summary: "pre-commit finish",
 		remark: "Cleans a completed broad or multi-writer diff and synchronizes cross-cutting docs/comments without changing behavior.",
 	},
+	sentinel: {
+		summary: "fresh-context review",
+		remark: "Reviews a completed diff read-only with no memory of how it was written and reports only evidence-backed defects and test gaps; dispatched for risky diffs, never as a commit ritual.",
+	},
 };
 
 export function agentProfile(name: string): AgentProfile | undefined {
@@ -132,7 +134,7 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 
 export const FIRST_RUN_SETUP_HINT =
 	"Run /subagents-setup to choose enabled roles, models, and thinking levels. " +
-	"Scout maps code or researches external sources, artisan owns the primary change, and steward cleans broad final diffs.";
+	"Scout maps code or researches external sources, artisan owns the primary change, steward cleans broad final diffs, and sentinel reviews risky diffs with fresh eyes.";
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
 	return join(agentDir, CONFIG_FILE_NAME);
@@ -169,10 +171,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 
 	if (Array.isArray(raw.enabledAgents)) {
 		const names = raw.enabledAgents.filter(
-			(name): name is string =>
-				typeof name === "string" &&
-				name.trim().length > 0 &&
-				!RETIRED_AGENT_NAMES.has(name.trim()),
+			(name): name is string => typeof name === "string" && name.trim().length > 0,
 		);
 		// An explicitly empty array is honored; duplicates collapse.
 		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
@@ -180,10 +179,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 
 	const rawKnownAgents = Array.isArray(raw.knownAgents) ? raw.knownAgents : INITIAL_AGENT_NAMES;
 	config.knownAgents = [...new Set(rawKnownAgents.filter(
-		(name): name is string =>
-			typeof name === "string" &&
-			name.trim().length > 0 &&
-			!RETIRED_AGENT_NAMES.has(name.trim()),
+		(name): name is string => typeof name === "string" && name.trim().length > 0,
 	).map((name) => name.trim()))];
 	for (const name of config.enabledAgents) {
 		if (!config.knownAgents.includes(name)) config.knownAgents.push(name);
@@ -192,7 +188,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	if (isRecord(raw.agentModels)) {
 		for (const [rawKey, value] of Object.entries(raw.agentModels)) {
 			const key = rawKey.trim();
-			if (key !== "" && !RETIRED_AGENT_NAMES.has(key) && isModelReference(value)) {
+			if (key !== "" && isModelReference(value)) {
 				config.agentModels[key] = value.trim();
 			}
 		}
@@ -203,7 +199,6 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 			const key = rawKey.trim();
 			if (
 				key !== "" &&
-				!RETIRED_AGENT_NAMES.has(key) &&
 				typeof value === "string" &&
 				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
 			) {

package/src/delegation/agents.ts

@@ -54,6 +54,7 @@ export const SUBAGENT_TOOL_NAMES = [
 	"subagent",
 	"subagent_control",
 	"subagent_stop",
+	"subagent_risk",
 ] as const;
 const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);