@shanepadgett/tau-agent 0.16.0 → 0.17.0

package/extensions/footer/index.ts

@@ -4,7 +4,6 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
-import type { AssistantMessage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { onTauEvent } from "../../shared/events.ts";
@@ -278,17 +277,20 @@ function isConflict(x: string | undefined, y: string | undefined): boolean {
 	return x === "U" || y === "U" || (x === "A" && y === "A") || (x === "D" && y === "D");
 }
 
-function sessionCost(ctx: ExtensionContext): UsageSummary {
+export function sessionCost(ctx: Pick<ExtensionContext, "sessionManager">): UsageSummary {
 	let usage = zeroUsage();
-	for (const entry of ctx.sessionManager.getBranch()) {
-		if (entry.type !== "message") continue;
-		if (entry.message.role === "assistant") {
-			usage = addUsage(usage, normalizeUsage((entry.message as AssistantMessage).usage));
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type === "message" && entry.message.role === "assistant") {
+			usage = addUsage(usage, normalizeUsage(entry.message.usage), true);
 			continue;
 		}
-		if (entry.message.role !== "toolResult" || entry.message.toolName !== "subagent") continue;
-		const childUsage = subagentUsage(entry.message.details);
-		if (childUsage) usage = addUsage(usage, childUsage);
+		if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+			usage = addUsage(usage, normalizeUsage(entry.message.usage), false);
+			continue;
+		}
+		if ((entry.type === "compaction" || entry.type === "branch_summary") && entry.usage) {
+			usage = addUsage(usage, normalizeUsage(entry.usage), false);
+		}
 	}
 	return usage;
 }
@@ -339,37 +341,7 @@ async function scanDailyCost(): Promise<number> {
 		try {
 			if ((await stat(path)).mtimeMs < range.startMs) continue;
 			const raw = await readFile(path, "utf8");
-			for (const line of raw.split("\n")) {
-				const entry = parseRecord(line);
-				if (!entry || entry.type !== "message") continue;
-				const message = asRecord(entry.message);
-				if (!message) continue;
-				const timestamp = timestampMs(message.timestamp, entry.timestamp);
-				if (timestamp < range.startMs || timestamp >= range.endMs) continue;
-				let usage: UsageSummary;
-				let identity: unknown[];
-				if (message.role === "assistant") {
-					usage = normalizeUsage(message.usage);
-					identity = [message.provider, message.model];
-				} else if (message.role === "toolResult" && message.toolName === "subagent") {
-					const childUsage = subagentUsage(message.details);
-					if (!childUsage) continue;
-					usage = childUsage;
-					identity = ["subagent", message.toolCallId];
-				} else continue;
-				const key = [
-					...identity,
-					timestamp,
-					usage.input,
-					usage.output,
-					usage.cacheRead,
-					usage.cacheWrite,
-					usage.cost,
-				].join(":");
-				if (seen.has(key)) continue;
-				seen.add(key);
-				total += usage.cost;
-			}
+			total += dailyCostFromJsonl(raw, range, seen);
 		} catch {
 			// One bad session file should not break the footer.
 		}
@@ -378,6 +350,52 @@ async function scanDailyCost(): Promise<number> {
 	return total;
 }
 
+export function dailyCostFromJsonl(
+	raw: string,
+	range: { startMs: number; endMs: number },
+	seen: Set<string> = new Set<string>(),
+): number {
+	let total = 0;
+	for (const line of raw.split("\n")) {
+		const entry = parseRecord(line);
+		if (!entry) continue;
+		let usageValue: unknown;
+		let timestamp: number;
+		let identity: unknown[];
+		if (entry.type === "message") {
+			const message = asRecord(entry.message);
+			if (!message) continue;
+			timestamp = timestampMs(message.timestamp, entry.timestamp);
+			if (message.role === "assistant" && asRecord(message.usage)) {
+				usageValue = message.usage;
+				identity = ["assistant", message.provider, message.model];
+			} else if (message.role === "toolResult" && asRecord(message.usage)) {
+				usageValue = message.usage;
+				identity = ["toolResult", message.toolName, message.toolCallId];
+			} else continue;
+		} else if ((entry.type === "compaction" || entry.type === "branch_summary") && asRecord(entry.usage)) {
+			usageValue = entry.usage;
+			timestamp = timestampMs(undefined, entry.timestamp);
+			identity = [entry.type, entry.id];
+		} else continue;
+		if (timestamp < range.startMs || timestamp >= range.endMs) continue;
+		const usage = normalizeUsage(usageValue);
+		const key = [
+			...identity,
+			timestamp,
+			usage.input,
+			usage.output,
+			usage.cacheRead,
+			usage.cacheWrite,
+			usage.cost,
+		].join(":");
+		if (seen.has(key)) continue;
+		seen.add(key);
+		total += usage.cost;
+	}
+	return total;
+}
+
 async function sessionFiles(): Promise<string[]> {
 	const root = join(homedir(), ".pi", "agent", "sessions");
 	const files: string[] = [];
@@ -429,31 +447,15 @@ function normalizeUsage(value: unknown): UsageSummary {
 	};
 }
 
-function subagentUsage(details: unknown): UsageSummary | undefined {
-	const usage = asRecord(asRecord(details)?.usage);
-	if (!usage) return undefined;
-	const input = numberOrZero(usage.input);
-	const output = numberOrZero(usage.output);
-	const cacheRead = numberOrZero(usage.cacheRead);
-	const cacheWrite = numberOrZero(usage.cacheWrite);
-	const promptTokens = input + cacheRead + cacheWrite;
-	return {
-		input,
-		output,
-		cacheRead,
-		cacheWrite,
-		latestCacheHitRate: promptTokens > 0 ? (cacheRead / promptTokens) * 100 : undefined,
-		cost: numberOrZero(usage.cost),
-	};
-}
-
-function addUsage(left: UsageSummary, right: UsageSummary): UsageSummary {
+function addUsage(left: UsageSummary, right: UsageSummary, updateCacheHitRate: boolean): UsageSummary {
 	return {
 		input: left.input + right.input,
 		output: left.output + right.output,
 		cacheRead: left.cacheRead + right.cacheRead,
 		cacheWrite: left.cacheWrite + right.cacheWrite,
-		latestCacheHitRate: right.latestCacheHitRate ?? left.latestCacheHitRate,
+		latestCacheHitRate: updateCacheHitRate
+			? (right.latestCacheHitRate ?? left.latestCacheHitRate)
+			: left.latestCacheHitRate,
 		cost: left.cost + right.cost,
 	};
 }

package/extensions/run-summary/index.ts

@@ -49,7 +49,7 @@ export default function runSummaryExtension(pi: ExtensionAPI): void {
 				continue;
 			}
 			if (message.role !== "toolResult" || message.toolName !== "subagent") continue;
-			subagentCost += readSubagentCost(message.details);
+			subagentCost += readUsageCost(message.usage);
 		}
 	});
 
@@ -68,11 +68,11 @@ export default function runSummaryExtension(pi: ExtensionAPI): void {
 	});
 }
 
-function readSubagentCost(value: unknown): number {
+function readUsageCost(value: unknown): number {
 	if (!value || typeof value !== "object") return 0;
-	const usage = (value as Record<string, unknown>).usage;
-	if (!usage || typeof usage !== "object") return 0;
-	return finiteNonNegative((usage as Record<string, unknown>).cost);
+	const cost = (value as Record<string, unknown>).cost;
+	if (!cost || typeof cost !== "object") return 0;
+	return finiteNonNegative((cost as Record<string, unknown>).total);
 }
 
 function readRunSummary(value: unknown): RunSummary | undefined {

package/extensions/silent-command-runner/README.md

@@ -22,4 +22,4 @@ Configure it in Tau settings under `extensions.silentCommandRunner`:
 }
 ```
 
-Passes are notifications only. Failures are shown in chat and sent to the agent.
+Passes are notifications only. Failures are shown in chat and sent to the agent. Tau's ready-for-input notification waits for these checks and stays quiet when a failure starts another agent turn.

package/extensions/silent-command-runner/index.ts

@@ -2,6 +2,7 @@ import { readdir, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { type ExecResult, type ExtensionAPI, keyText, type Theme } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
+import { emitTauEvent } from "../../shared/events.ts";
 import { matchGlob, posixPath } from "../../shared/glob.ts";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { resolveProjectRoot } from "../../shared/settings/paths.ts";
@@ -78,10 +79,11 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 	let settings: Settings = normalizeSettings(silentCommandRunnerSettings.defaults);
 	let turnStart = Date.now();
 	let turnPaths = new Set<string>();
-	let run: Promise<void> | undefined;
 	let abortController: AbortController | undefined;
-	let lastRunAborted = false;
+	let sessionActive = false;
 	let chainActive = false;
+	let attentionHoldSequence = 0;
+	let attentionHoldId: string | undefined;
 
 	pi.registerMessageRenderer<FailureDetails>(MESSAGE_TYPE, (message, { expanded }, theme) =>
 		renderFailure(asFailureDetails(message.details), expanded, theme),
@@ -89,10 +91,12 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		settings = normalizeSettings(await loadTauExtensionSettings(ctx, silentCommandRunnerSettings));
+		sessionActive = true;
 		turnStart = Date.now();
 		turnPaths = new Set();
-		lastRunAborted = false;
 		chainActive = false;
+		attentionHoldSequence = 0;
+		attentionHoldId = undefined;
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
@@ -102,43 +106,44 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("agent_start", async (_event, ctx) => {
-		lastRunAborted = false;
-		if (chainActive) return;
+		const startingChain = !chainActive;
 		chainActive = true;
 		turnStart = Date.now();
 		if (!settings.enabled || settings.commands.length === 0) {
 			turnPaths = new Set();
 			return;
 		}
+		if (startingChain) {
+			attentionHoldId = `silent-command-runner:${++attentionHoldSequence}`;
+			emitTauEvent(pi, "tau:attention.hold.acquire", { id: attentionHoldId });
+		}
 		const projectRoot = await resolveProjectRoot(ctx.cwd);
 		turnPaths = new Set(await walkFiles(projectRoot));
 	});
 
-	pi.on("agent_end", (event) => {
-		lastRunAborted = hasAbortedAssistantMessage(event.messages);
+	pi.on("agent_end", async (event, ctx) => {
+		if (hasAbortedAssistantMessage(event.messages)) return;
+		try {
+			await runChangedCommands(ctx.cwd, turnStart, ctx.ui.notify);
+		} catch (error: unknown) {
+			ctx.ui.notify(`silent-command-runner: ${errorMessage(error)}`, "error");
+		}
 	});
 
-	pi.on("agent_settled", async (_event, ctx) => {
+	pi.on("agent_settled", () => {
 		chainActive = false;
-		if (lastRunAborted) return;
-		if (run) return;
-		run = runChangedCommands(ctx.cwd, turnStart, ctx.ui.notify)
-			.catch((error: unknown) => {
-				ctx.ui.notify(`silent-command-runner: ${errorMessage(error)}`, "error");
-			})
-			.finally(() => {
-				run = undefined;
-			});
-		await run;
+		const holdId = attentionHoldId;
+		attentionHoldId = undefined;
+		if (holdId) emitTauEvent(pi, "tau:attention.hold.release", { id: holdId, disposition: "notify" });
 	});
 
 	pi.on("session_shutdown", () => {
+		sessionActive = false;
 		abortController?.abort();
 		abortController = undefined;
-		run = undefined;
 		turnPaths = new Set();
-		lastRunAborted = false;
 		chainActive = false;
+		attentionHoldId = undefined;
 	});
 
 	async function runChangedCommands(
@@ -151,7 +156,7 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 		const projectRoot = await resolveProjectRoot(cwd);
 		const paths = await walkFiles(projectRoot);
 		const changed = await scanChangedCommands(projectRoot, settings.commands, paths, turnPaths, turnStart);
-		if (changed.length === 0) return;
+		if (!sessionActive || changed.length === 0) return;
 
 		notify(
 			changed.length === 1
@@ -160,14 +165,26 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 			"info",
 		);
 
-		abortController = new AbortController();
 		const failures: FailedCommandDetails[] = [];
-		for (const command of changed) {
-			if (changed.length > 1) notify(`silent-command-runner: running ${command.name}`, "info");
-			const result = await runCommand(pi, projectRoot, command, abortController.signal, settings.maxOutputBytes);
-			if (result.code !== 0 || result.killed) failures.push(result);
+		const controller = new AbortController();
+		abortController = controller;
+		try {
+			for (const command of changed) {
+				if (changed.length > 1) notify(`silent-command-runner: running ${command.name}`, "info");
+				let result: FailedCommandDetails;
+				try {
+					result = await runCommand(pi, projectRoot, command, controller.signal, settings.maxOutputBytes);
+				} catch (error: unknown) {
+					if (controller.signal.aborted) return;
+					throw error;
+				}
+				if (controller.signal.aborted) return;
+				if (result.code !== 0 || result.killed) failures.push(result);
+			}
+		} finally {
+			if (abortController === controller) abortController = undefined;
 		}
-		abortController = undefined;
+		if (!sessionActive) return;
 
 		const failedNames = new Set(failures.map((failure) => failure.name));
 		const passed = changed.filter((command) => !failedNames.has(command.name));
@@ -181,7 +198,7 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 				display: true,
 				details: { failed: failures },
 			},
-			{ triggerTurn: true },
+			{ deliverAs: "followUp" },
 		);
 	}
 }

package/extensions/soul/prompt.ts

@@ -12,7 +12,7 @@ Human interrupts. Human sometimes idiot. Human sometimes has good idea. Rok thin
 
 Build only what human specifically asked for. User ask approves that scope only. No bonus features, new option categories, settings, APIs, UI, commands, docs, output, or public behavior unless human explicitly approved. If Rok sees missing public surface that truly helps, ask first in one line. Do not sneak it into diff.
 
-Every read has job. Start from task path or symbol. Grep for broad search, not for rereading known files. Read only files likely to answer current decision or be edited. Do not chase imports, shared helpers, docs, or callers unless current evidence says they matter. Aimless explore wastes context and dulls Rok. If exploration wandered, prune memory and keep only useful facts.
+Every read has job. Start from task path or symbol. Grep for broad search, not for rereading known files. Read only files likely to answer current decision or be edited. Once file is relevant, request whole file by omitting \`offset\`, \`limit\`, and \`lineNumbers\`. One whole-file read beats repeated ranged reads. Supplied eager snapshot counts as initial read. After file changes, request whole file again; read cache returns useful diff or current source instead of blindly repeating old content. Use ranged reads only for targeted inspection of peripheral files or to continue after tool truncation. Do not chase imports, shared helpers, docs, or callers unless current evidence says they matter. Aimless explore wastes context and dulls Rok. If exploration wandered, prune memory and keep only useful facts.
 
 Selected snapshots are authoritative unless edited, changed, or missing needed content.
 
@@ -20,6 +20,8 @@ Never cut validation, data safety, security, accessibility, explicit user ask, h
 
 Question asked? Answer and stop. Simple question gets simple answer. If one sentence works, use one sentence. No plan, caveat list, or options unless needed. Change requested? Smallest correct change. Ambiguous? Ask one practical question.
 
+Idea, plan, or concept talk: short back-and-forth. Shape first. Add detail only as next layer needs it. Do not expand into full plan, option tree, or writeup unless asked.
+
 If instructed not to run checks or not to do something, obey silently. Do not report the omission in meta-speak.
 
 Final chat tiny. User saw tools and will inspect code. Do not tour work. Say only non-obvious thing human needs now. If nothing needs saying, one word.`;

package/extensions/subagent/README.md

@@ -4,15 +4,25 @@ Subagent delegates one focused task to an isolated child Pi session. It keeps th
 
 Agent definitions can override the parent model and thinking level. If an override is unavailable, Tau warns once per session and uses the corresponding parent value.
 
-Tau includes three built-in agents:
+Each fresh child also gets a display name from its agent definition. The name stays with a retained thread. Tau cycles through the configured pool and adds `-2`, `-3`, and so on when a pool name is reused, so parallel calls never collide.
 
-- `generalist` handles focused analysis, review, implementation, or mixed work when no narrower agent fits. Delegated tasks should state their scope and desired depth.
-- `scout` explores local files and code with `read`, `grep`, `find`, and `ls`.
+Tau includes these built-in agents:
+
+- `review` performs adversarial, read-only code review for correctness, runtime risks, duplication, and over- or under-engineering.
 - `web-research` researches web and code sources with `websearch`, `codesearch`, and `webfetch`.
+- `context-sync` maps meaningful uncommitted work into `.pi/contexts`. Agent-driven use is `extensions.context.sync.automation` (requires `sync.enabled`). `/context-sync` is the manual/nudge path when sync is enabled. Validation can auto-run it when validation and sync are enabled.
 
 Ask Tau to delegate a task, or let it call `subagent` with an agent name and task. Children use the parent's current working directory and inherit its model and thinking level unless their definition overrides either value. They do not receive the parent conversation. Tau loads only the extensions that own a child's declared tools, so unrelated extension hooks do not run in child sessions. When a child must inspect another repository, put its exact absolute path in the delegated task.
 
-Fresh calls return a thread ID. Tau can send feedback or follow-up work to that thread, preserving the child's conversation, prior reads, and tool results. It starts a fresh thread for unrelated work or when retained context is stale or oversized. Threads live for the current parent session. Tau retains up to 16 and evicts the least recently used idle thread when needed. Calls to one thread run sequentially.
+When the relevant files are already known, pass them with the call so Tau can autoread them into that child turn:
+
+```text
+subagent({ agent: "review", task: "Review the runtime change", files: ["src/runtime.ts", "test/runtime.test.ts"] })
+```
+
+Paths may be relative to the parent's current working directory or absolute. Tau reads current snapshots when the turn starts and includes line numbers so the child can cite them without another read. Missing files appear as failed autoread context; they do not stop the child. Keep the list focused because the complete snapshots use the child's context window. Files can also be supplied on a retained-thread follow-up.
+
+Fresh calls return a thread ID. Follow-ups within five minutes preserve the complete child conversation. After that, Tau replaces the child session and resumes from prior tasks, exact terminal results, and the paths supplied through `files`. Old file contents, tool calls, intermediate responses, and thinking are dropped without a summarization request. The resumed child reads current source before relying on a retained path. Threads live for the current parent session. Tau retains up to 16 and evicts the least recently used idle thread when needed. Calls to one thread run sequentially.
 
 ## Agent definitions
 
@@ -25,6 +35,10 @@ description: Inspect API declarations and usage
 tools:
   - read
   - grep
+names:
+  - Ledger
+  - Quill
+  - Beacon
 model: openai-codex/gpt-5.6-sol
 thinking: medium
 ---
@@ -32,6 +46,8 @@ thinking: medium
 Stay within the delegated task. Return exact paths and symbols.
 ```
 
-`name`, `description`, and `tools` are required. Optional `model` uses `provider/model`; optional `thinking` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Tool names must be unique, and `subagent` cannot be delegated. Named tools and configured models must exist in the normally loaded child Pi environment.
+`name`, `description`, and `tools` are required. Optional `names` is a non-empty list of unique display names; without it, Tau uses the agent name. Optional `model` uses `provider/model`; optional `thinking` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Tool names and display names must be unique within their lists, and `subagent` cannot be delegated. Named tools and configured models must exist in the normally loaded child Pi environment.
 
 At most four children run at once. Additional calls wait in order. Returned text is limited to 50 KB or 2,000 lines; complete truncated output is saved to a private temporary file outside project repositories.
+
+When Tau runs interactively inside cmux, a single temporary Markdown surface shows waiting and running subagent work beside the parent terminal. It does not change child scheduling, concurrency, or results. The surface closes a couple of seconds after the active cohort finishes. Print mode and non-cmux sessions never open it.

package/extensions/subagent/agents/context-sync.md

@@ -0,0 +1,90 @@
+---
+name: context-sync
+description: >-
+  Map meaningful uncommitted work into `.pi/contexts` (domains/concepts/entries).
+  Call after a coherent batch that adds, moves, renames, or changes ownership of code/docs—not after every trivial edit to paths already correctly filed.
+  Prefer once per batch or before commit; skip pure refactors that keep the same membership, typos, and already-covered single-file polish.
+  Task may include a short human/steer note. Harness may also auto-run this when context validation is enabled.
+tools:
+  - read
+  - ls
+  - find
+  - grep
+  - bash
+  - patch
+  - context_sync_evidence
+names:
+  - Cartographer
+  - Archivist
+  - Indexer
+  - Surveyor
+  - Curator
+model: openai-codex/gpt-5.6-luna
+thinking: high
+---
+
+You maintain the living repository context map under `.pi/contexts`.
+
+Tabs/folders are domains. TOML files are concepts. TOML sections are selectable work-scope entries. Entry `files` are eager autoread paths. Entry `anchors` are lazy navigation paths. Preserve an existing path's loading class when it already appears anywhere in the catalog. New paths default to eager `files`.
+
+## Tools
+
+- `context_sync_evidence` — git dirty set, catalog skeleton, deps, diffs, invariants. Prefer this first.
+- `read` / `ls` / `find` / `grep` — default explore tools for boundary judgment when evidence is not enough.
+- `bash` — only when explore tools cannot answer the question.
+- `patch` — create/update/move/delete only under `.pi/contexts/**` (including whole concept TOML via `*** Delete File`).
+
+### Bash limits
+
+Prefer `ls`, `find`, `grep`, and `read` first. Use bash only when those cannot cover the need.
+
+Allowed bash beyond explore:
+
+- Read-only inspection those tools miss — e.g. `git log` / `git blame` / `git show` on existing commits, `file`, `wc`, small read-only pipelines
+- After `patch` deletes the last file in a `.pi/contexts/**` directory, remove that empty directory with `rmdir` (repeat upward only while dirs stay empty under `.pi/contexts`). Prefer `rmdir` over `rm -r`.
+
+Forbidden with bash:
+
+- Anything `ls` / `find` / `grep` / `read` already do cleanly
+- Creating, editing, moving, or deleting files (catalog files use `patch` only)
+- Non-empty directory deletes; deletes outside `.pi/contexts`
+- `git add` / `commit` / `push` / `checkout` / `restore` / `reset` / `stash` / branch changes
+- Installers, package managers, builds, tests, formatters, codegen, servers
+- Network fetches that change the tree; secrets; credential or config mutation
+
+Catalog file mutations go through `patch` under `.pi/contexts` only. The harness restores out-of-scope writes and fails the run.
+
+## Forced ladder
+
+Before placing any path, answer out loud in order:
+
+1. **Domain** — Does this changeset reuse an existing domain tab, birth a new one (core, platform, infrastructure, docs, a feature grown into its own domain), or split a bloated domain?
+2. **Concept** — Inside that domain, which subsystem TOML? Reuse, new, split, or merge?
+3. **Entry** — Which work scope? Update, new, split, delete, or move between concepts/domains?
+4. **Bloat** — Did this touch make an entry/concept a junk drawer? Split now if yes.
+5. **Membership** — Assign files/anchors only under the winners. Every eligible changed non-deleted file must belong somewhere. Remove every stale catalog path.
+
+Path stuffing into the nearest feature bucket without climbing the ladder is failure.
+
+## Change classes
+
+- **Additive / local edit** — mostly membership or a new entry under a stable concept.
+- **Semantic move / refactor** — meaning moved even if paths stayed covered. Re-evaluate domain/concept. Moves and splits are required verbs, not optional polish.
+
+## Working loop
+
+1. `context_sync_evidence` section `overview`.
+2. `catalog` for the full skeleton. Do not invent domains you never inspected.
+3. Pull `dirty`, `file`, `dependencies`, or `previews` as needed. Use `read` / `ls` / `find` / `grep` for neighbor inspection. Use `bash` only when those cannot cover the question.
+4. Edit catalog TOML with `patch`.
+5. `context_sync_evidence` section `invariants`. If failed, continue until it holds or you can explain a hard blocker.
+6. Final reply: short summary of domain/concept/entry decisions and files touched under `.pi/contexts`. If no catalog edit was required, say why.
+
+## Nudge
+
+If the task includes a human nudge, treat it as soft steer. It does not override evidence, eligibility, or the ladder. If the nudge conflicts with the changeset, say so and choose the honest map.
+
+## Stop conditions
+
+- Invariants hold and the map reflects honest typology for this changeset, or
+- Hard blocker (secrets, conflicts, missing tools/model) — report it clearly without half-applying a broken map.

package/extensions/subagent/agents/{generalist.md → dormant/generalist.md}

@@ -7,6 +7,12 @@ tools:
    - grep
    - find
    - ls
+names:
+  - Tinker
+  - Rivet
+  - Patch
+  - Wrench
+  - Mender
 model: openai-codex/gpt-5.6-sol
 thinking: high
 ---

package/extensions/subagent/agents/{scout.md → dormant/scout.md}

@@ -6,6 +6,12 @@ tools:
   - grep
   - find
   - ls
+names:
+  - Pathfinder
+  - Trailblazer
+  - Lookout
+  - Tracker
+  - Ranger
 model: openai-codex/gpt-5.6-luna
 thinking: high
 ---

package/extensions/subagent/agents/review.md

@@ -0,0 +1,48 @@
+---
+name: review
+description: Perform an adversarial, read-only review for correctness, runtime risks, duplication, and over- or under-engineering
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - bash
+  - context_prune
+names:
+  - Auditor
+  - Inspector
+  - Skeptic
+  - Examiner
+  - Sentinel
+model: openai-codex/gpt-5.6-sol
+thinking: xhigh
+---
+
+Treat the implementation as untrusted. Try to disprove its correctness before accepting it. Review the delegated scope at full depth, then report only findings supported by concrete evidence.
+
+## Review procedure
+
+1. Establish the requested scope. When reviewing uncommitted work, inspect the relevant diff before reading surrounding code.
+2. Read every changed path in scope. Trace direct callers, consumers, state transitions, error paths, and tests where they can change the verdict.
+3. Compare behavior with the stated request, repository rules, and existing conventions.
+4. Look specifically for:
+   - incorrect behavior, runtime failures, races, stale state, bad boundaries, and unsafe error handling;
+   - over-engineering, needless wrappers, option bags, tiny single-use helpers, duplicated logic, and abstractions that make the code harder to reason about;
+   - under-engineering, missing validation, incomplete wiring, weak tests, and assumptions that should be enforced;
+   - tests that only mirror the implementation, miss realistic sequences, or fail to protect the requested behavior;
+   - dead code, stale documentation, and obsolete resources left behind by the change.
+5. Use read-only shell commands for evidence when the other tools cannot answer the question. Do not run formatters, generators, installers, or commands that rewrite the repository.
+6. After broad exploration converges, use `context_prune` before continuing when substantial stale evidence would otherwise remain.
+
+Do not modify files. Do not reward review volume. Reject speculative findings and personal style preferences without a concrete maintenance, correctness, or runtime consequence.
+
+## Output
+
+List findings first, ordered by severity. For each finding include:
+
+- severity and a direct title;
+- exact file and line evidence;
+- the failure mechanism or maintenance cost;
+- the smallest credible fix direction.
+
+Then list unresolved questions that materially affect correctness. If there are no findings, say so plainly and state what you inspected. Do not add a summary that repeats the findings.

package/extensions/subagent/agents/web-research.md

@@ -5,6 +5,12 @@ tools:
   - websearch
   - codesearch
   - webfetch
+names:
+  - Spider
+  - Linkhound
+  - Crawler
+  - Netscout
+  - Wayfinder
 model: openai-codex/gpt-5.6-sol
 thinking: medium
 ---

package/extensions/subagent/agents.ts

@@ -8,6 +8,7 @@ export interface AgentDefinition {
 	name: string;
 	description: string;
 	tools: string[];
+	names: string[];
 	model?: string;
 	thinking?: ThinkingLevel;
 	prompt: string;
@@ -64,7 +65,7 @@ function parseDefinition(
 		const name = typeof rawName === "string" && rawName.trim() ? rawName.trim() : fallbackName;
 		const reasons: string[] = [];
 		for (const field of fields) {
-			if (!new Set(["name", "description", "tools", "model", "thinking"]).has(field))
+			if (!new Set(["name", "description", "tools", "names", "model", "thinking"]).has(field))
 				reasons.push(`unsupported field "${field}"`);
 		}
 		if (typeof rawName !== "string" || !rawName.trim()) reasons.push("name must be a non-empty string");
@@ -81,6 +82,17 @@ function parseDefinition(
 			if (new Set(tools).size !== tools.length) reasons.push("tools must be unique");
 			if (tools.includes("subagent")) reasons.push("tool subagent is forbidden");
 		}
+		const rawNames = parsed.frontmatter.names;
+		if (rawNames !== undefined) {
+			if (!Array.isArray(rawNames) || rawNames.length === 0) reasons.push("names must be a non-empty array");
+			else {
+				const names = rawNames
+					.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+					.map((item) => item.trim());
+				if (names.length !== rawNames.length) reasons.push("names must contain non-empty strings");
+				if (new Set(names).size !== names.length) reasons.push("names must be unique");
+			}
+		}
 		if (!parsed.body.trim()) reasons.push("prompt body must be non-empty");
 		const rawModel = parsed.frontmatter.model;
 		if (rawModel !== undefined && (typeof rawModel !== "string" || !/^[^/\s]+\/[^/\s]+$/.test(rawModel.trim())))
@@ -95,6 +107,7 @@ function parseDefinition(
 				name,
 				description: (rawDescription as string).trim(),
 				tools: (rawTools as string[]).map((tool) => tool.trim()),
+				names: Array.isArray(rawNames) ? (rawNames as string[]).map((item) => item.trim()) : [name],
 				model: typeof rawModel === "string" ? rawModel.trim() : undefined,
 				thinking: rawThinking as ThinkingLevel | undefined,
 				prompt: parsed.body.trim(),
@@ -125,7 +138,7 @@ async function loadScope(
 		if (!required) return new Map();
 		const reason = error instanceof Error ? error.message : "directory unavailable";
 		return new Map([
-			["scout", [{ path: directory, name: "scout", reason: `packaged agents unavailable: ${reason}` }]],
+			["review", [{ path: directory, name: "review", reason: `packaged agents unavailable: ${reason}` }]],
 			[
 				"web-research",
 				[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],