@shanepadgett/tau-agent 0.29.0 → 0.31.0

package/extensions/script-runner/index.ts

@@ -0,0 +1,275 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	defineTool,
+	type ExecResult,
+	type ExtensionAPI,
+	type Theme,
+	truncateTail,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+type Language = "python" | "typescript";
+
+interface Runtimes {
+	python: string | undefined;
+	typescript: string | undefined;
+}
+
+interface StoredScript {
+	language: Language;
+	source: string;
+}
+
+const TIMEOUT_MS = 120_000;
+const MAX_STORED = 8;
+
+function detectRuntimes(): Runtimes {
+	let python: string | undefined;
+	for (const cmd of ["python3", "python"] as const) {
+		try {
+			execFileSync(cmd, ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+			python = cmd;
+			break;
+		} catch {
+			// runtime not installed
+		}
+	}
+	const [major, minor] = process.versions.node.split(".").map(Number);
+	let typescript: string | undefined;
+	if (major > 22 || (major === 22 && minor >= 6)) {
+		typescript = process.execPath;
+	}
+	return { python, typescript };
+}
+
+function capitalize(lang: Language): string {
+	return lang === "python" ? "Python" : "TypeScript";
+}
+
+function newScriptId(): string {
+	return randomBytes(5).toString("base64url").slice(0, 7);
+}
+
+function scrubPath(text: string, file: string, dir: string): string {
+	if (!text) return text;
+	return text.replaceAll(file, "<script>").replaceAll(dir, "<tmpdir>");
+}
+
+function applyEdits(source: string, edits: ReadonlyArray<{ oldText: string; newText: string }>): string {
+	let next = source;
+	for (const edit of edits) {
+		const idx = next.indexOf(edit.oldText);
+		if (idx === -1) {
+			throw new Error(
+				"An edits oldText was not found in the script. Copy the exact text from the script you wrote.",
+			);
+		}
+		next = next.slice(0, idx) + edit.newText + next.slice(idx + edit.oldText.length);
+	}
+	return next;
+}
+
+function renderEditsPreview(edits: ReadonlyArray<{ oldText: string; newText: string }>, theme: Theme): string {
+	return edits
+		.map((edit) => {
+			const oldLines = edit.oldText
+				.split("\n")
+				.map((line) => theme.fg("error", `- ${line}`))
+				.join("\n");
+			const newLines = edit.newText
+				.split("\n")
+				.map((line) => theme.fg("success", `+ ${line}`))
+				.join("\n");
+			return `${oldLines}\n${newLines}`;
+		})
+		.join("\n");
+}
+
+export default function scriptRunnerExtension(pi: ExtensionAPI): void {
+	const runtimes = detectRuntimes();
+	const detected = (["python", "typescript"] as const).filter(
+		(lang): lang is Language => (lang === "python" ? runtimes.python : runtimes.typescript) !== undefined,
+	);
+	if (detected.length === 0) return;
+
+	const langPhrase = detected.map(capitalize).join(" or ");
+
+	const scripts = new Map<string, StoredScript>();
+	let tempDir: string | undefined;
+
+	function remember(scriptId: string, script: StoredScript): void {
+		scripts.set(scriptId, script);
+		while (scripts.size > MAX_STORED) {
+			const oldest = scripts.keys().next().value;
+			if (oldest === undefined) break;
+			scripts.delete(oldest);
+		}
+	}
+
+	function resolveCommand(language: Language): string {
+		if (language === "python") {
+			const cmd = runtimes.python;
+			if (!cmd) throw new Error("Python is not available on this machine.");
+			return cmd;
+		}
+		const cmd = runtimes.typescript;
+		if (!cmd) throw new Error("TypeScript is not available (requires Node >= 22.6).");
+		return cmd;
+	}
+
+	async function ensureTempDir(): Promise<string> {
+		if (tempDir) return tempDir;
+		tempDir = await mkdtemp(join(tmpdir(), "tau-script-runner-"));
+		return tempDir;
+	}
+
+	async function runScript(
+		language: Language,
+		command: string,
+		source: string,
+		cwd: string,
+		signal: AbortSignal | undefined,
+	): Promise<ExecResult> {
+		const dir = await ensureTempDir();
+		const file = join(dir, language === "python" ? "_run.py" : "_run.ts");
+		await writeFile(file, source, "utf8");
+		const args = language === "python" ? [file] : ["--experimental-strip-types", file];
+		const result = await pi.exec(command, args, { cwd, signal, timeout: TIMEOUT_MS });
+		return {
+			...result,
+			stdout: scrubPath(result.stdout, file, dir),
+			stderr: scrubPath(result.stderr, file, dir),
+		};
+	}
+
+	const paramsSchema = Type.Object(
+		{
+			language: StringEnum(detected, { description: "Execution language available on this machine." }),
+			script: Type.Optional(
+				Type.String({ description: "Full script source for a new run. Omit when retrying with edits." }),
+			),
+			scriptId: Type.Optional(
+				Type.String({ description: "scriptId returned by a failed run. Required when retrying with edits." }),
+			),
+			edits: Type.Optional(
+				Type.Array(
+					Type.Object({
+						oldText: Type.String({ description: "Exact text currently in the script." }),
+						newText: Type.String({ description: "Replacement text." }),
+					}),
+					{
+						description:
+							"Targeted oldText/newText patches applied to the stored script before rerun. Prefer this over resending the whole script.",
+					},
+				),
+			),
+		},
+		{ additionalProperties: false },
+	);
+
+	const tool = defineTool<typeof paramsSchema, undefined>({
+		name: "script_runner",
+		label: "Script Runner",
+		description: `Run a ${langPhrase} script in the project working directory and return its output. On a non-zero exit, returns a scriptId; retry by sending targeted {oldText,newText} edits against the script you already wrote (same language + scriptId) instead of resending the whole script. Available on this machine: ${langPhrase}.`,
+		promptSnippet: `Run ${langPhrase} scripts; fix failures with targeted edits instead of rewriting the whole script.`,
+		promptGuidelines: [
+			`Prefer script_runner over bash for ${langPhrase} when computation, data handling, or bulk file work is cleaner than chaining built-in tools.`,
+			`When script_runner fails, do not resend the full script. Call script_runner again with the same language, the returned scriptId, and an edits array of {oldText,newText} patches against the script you just wrote. Only resend a full script if the approach itself was wrong.`,
+			`script_runner never exposes the script file path, and you already know the script you sent. Never try to read it back.`,
+		],
+		parameters: paramsSchema,
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const language = params.language;
+			if (signal?.aborted) {
+				return { content: [{ type: "text", text: "Cancelled." }], details: undefined };
+			}
+
+			const command = resolveCommand(language);
+			const edits = params.edits;
+			let scriptId: string | undefined = params.scriptId;
+			let source: string;
+
+			if (edits && edits.length > 0) {
+				if (!scriptId) throw new Error("edits require the scriptId returned by the failed run.");
+				const stored = scripts.get(scriptId);
+				if (!stored) {
+					throw new Error(
+						`No stored script for scriptId ${scriptId}. It may have been evicted; resend the full script.`,
+					);
+				}
+				if (stored.language !== language) {
+					throw new Error(`Language mismatch: scriptId ${scriptId} is ${stored.language}, not ${language}.`);
+				}
+				source = applyEdits(stored.source, edits);
+			} else {
+				if (typeof params.script !== "string" || params.script.length === 0) {
+					throw new Error("Provide a script for a new run, or edits + scriptId to retry.");
+				}
+				source = params.script;
+				if (!scriptId) scriptId = newScriptId();
+			}
+
+			remember(scriptId, { language, source });
+			await onUpdate?.({ content: [{ type: "text", text: `Running ${language}...` }], details: undefined });
+
+			const result = await runScript(language, command, source, ctx.cwd, signal);
+			if (result.code === 0 && !result.killed) {
+				scripts.delete(scriptId);
+				const trunc = truncateTail(result.stdout.trim(), {
+					maxLines: DEFAULT_MAX_LINES,
+					maxBytes: DEFAULT_MAX_BYTES,
+				});
+				const out = trunc.content.trim();
+				const note = trunc.truncated
+					? `\n\n[output truncated: kept tail ${trunc.outputLines} / ${trunc.totalLines} lines]`
+					: "";
+				return {
+					content: [{ type: "text", text: out ? `${out}${note}` : `(no output)${note}` }],
+					details: undefined,
+				};
+			}
+
+			const diag = result.stderr.trim() || result.stdout.trim();
+			const trunc = truncateTail(diag, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+			const note = trunc.truncated
+				? `\n\n[output truncated: kept tail ${trunc.outputLines} / ${trunc.totalLines} lines]`
+				: "";
+			const detail = trunc.content ? `${trunc.content}${note}\n\n` : "";
+			throw new Error(
+				`${detail}scriptId: ${scriptId}\nRetry with edits: [{oldText,newText}] using the same language and scriptId; do not resend the full script.`,
+			);
+		},
+		renderCall(args, theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			const header = `${theme.fg("toolTitle", theme.bold("script_runner"))} ${theme.fg("muted", args.language)}`;
+			const edits = args.edits;
+			const body =
+				edits && edits.length > 0
+					? renderEditsPreview(edits, theme)
+					: theme.fg("accent", theme.bold(args.script ?? ""));
+			text.setText(body ? `${header}\n${body}` : header);
+			return text;
+		},
+	});
+
+	pi.registerTool(tool);
+
+	pi.on("session_shutdown", () => {
+		scripts.clear();
+		const dir = tempDir;
+		tempDir = undefined;
+		if (dir) {
+			void rm(dir, { recursive: true, force: true }).catch(() => {
+				// best-effort cleanup
+			});
+		}
+	});
+}

package/extensions/stash/browser.ts

@@ -6,13 +6,14 @@ import {
 	type TextRecordSelectPanelConfig,
 	type TextRecordSelectResult,
 } from "@shanepadgett/tau-tui";
+import { errorText } from "../../shared/text.ts";
 import { loadStashes, removeStash, type Stash, stashFilePath } from "./store.ts";
 
-const CONFIG: Omit<TextRecordSelectPanelConfig, "path"> = {
+const CONFIG: Omit<TextRecordSelectPanelConfig<Stash>, "path" | "destructiveAction"> = {
 	title: "Stash",
 	emptyMessage: "No stashed prompts. Use the stash shortcut while typing to stash.",
 	primaryLabel: "pop",
-	actions: [{ id: "discard", key: Key.ctrl("d"), hint: rawHint("ctrl+d", "discard") }],
+	actions: [],
 	expandActiveItem: false,
 };
 
@@ -24,20 +25,9 @@ export async function browseStash(ctx: ExtensionCommandContext): Promise<Stash |
 
 	const path = await stashFilePath(ctx.cwd);
 
-	while (true) {
-		const stashes = await loadStashes(ctx.cwd);
-		const result = await show(ctx, stashes, path);
-
-		if (result.kind === "cancel") return undefined;
-		if (result.kind === "primary") return result.item;
-
-		// discard: drop the stashed prompt without restoring it.
-		const ok = await ctx.ui.confirm("Discard stashed prompt?", result.item.text);
-		if (ok) {
-			await removeStash(ctx.cwd, result.item.id);
-			ctx.ui.notify("Stash discarded.", "info");
-		}
-	}
+	const stashes = await loadStashes(ctx.cwd);
+	const result = await show(ctx, stashes, path);
+	return result.kind === "primary" ? result.item : undefined;
 }
 
 async function show(
@@ -45,7 +35,29 @@ async function show(
 	stashes: readonly Stash[],
 	path: string,
 ): Promise<TextRecordSelectResult<Stash>> {
-	return ctx.ui.custom<TextRecordSelectResult<Stash>>((_tui, theme, _keybindings, done) =>
-		createTextRecordSelectPanel(theme, stashes, { ...CONFIG, path }, done),
+	return ctx.ui.custom<TextRecordSelectResult<Stash>>((tui, theme, _keybindings, done) =>
+		createTextRecordSelectPanel(
+			tui,
+			theme,
+			stashes,
+			{
+				...CONFIG,
+				path,
+				destructiveAction: {
+					id: "discard",
+					key: Key.ctrl("d"),
+					hint: rawHint("ctrl+d", "discard"),
+					confirmLabel: () => "Discard stashed prompt?",
+					runningLabel: "Discarding stashed prompt…",
+					onConfirm: async (item) => {
+						const next = await removeStash(ctx.cwd, item.id);
+						ctx.ui.notify("Stash discarded.", "info");
+						return next;
+					},
+					onError: (error) => ctx.ui.notify(`Stash discard failed: ${errorText(error)}`, "error"),
+				},
+			},
+			done,
+		),
 	);
 }

package/extensions/subagent/README.md

@@ -8,17 +8,30 @@ Each fresh child also gets a display name from its agent definition. The name st
 
 Tau includes these built-in agents:
 
-- `review` performs adversarial, read-only code review for correctness, runtime risks, duplication, and over- or under-engineering.
-- `scout` finds local files, symbols, data flow, constraints, and unknowns without changing anything.
+- `scout` does substantial multi-hop local code lookup that would chew parent context; paths, declarations, imports, references, call edges; facts only. Skip small digs.
 - `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.
 
-When the relevant files are already known, pass them with the call so Tau can autoread them into that child turn:
+Run `/agents` to enable or disable agents for the current session. Press Space to stage each toggle, then Enter to apply the changes. Session choices follow the current session branch and do not change Tau settings. Agents disabled in Tau settings appear as `disabled by Tau settings` and cannot be enabled from this command. Disable agents persistently with `extensions.subagent.disabled`:
+
+```json
+{
+  "extensions": {
+    "subagent": {
+      "disabled": ["web-research"]
+    }
+  }
+}
+```
+
+Disabled agents are hidden from the parent prompt and cannot start or continue a child thread.
+
+When 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"] })
+subagent({ agent: "scout", task: "Trace 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.

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

@@ -23,7 +23,7 @@ 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`.
+Tabs/folders are domains. TOML files are concepts. TOML sections are selectable work-scope entries. Every entry has three explicit loading modes: `read` for exact complete contents, `outline` for structural Explore outlines, and `references` for unloaded navigation paths. Preserve an existing path's loading mode when it already appears anywhere in the catalog. New paths default to `references`. Promote recurring source entry points to `outline`. Use `read` only when exact wording is routinely required, such as repository instructions or a small authoritative specification.
 
 ## Tools
 
@@ -65,7 +65,7 @@ Before placing any path, answer out loud in order:
 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.
+5. **Membership** — Assign read/outline/references only under the winners. Every entry must contain all three arrays, even when an array is empty. 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.
 

package/extensions/subagent/agents/scout.md

@@ -1,6 +1,6 @@
 ---
 name: scout
-description: Tiered, AST-first local discovery of files, declarations, data flow, constraints, and unknowns without changes
+description: "Substantial multi-hop local code lookup that would chew parent context; paths, declarations, imports, references, call edges; facts only. Skip small digs"
 tools:
   - read
   - bash
@@ -14,8 +14,6 @@ tools:
   - callees
   - references
   - implementations
-  - impact
-  - context
   - working_memory
 names:
   - Pathfinder
@@ -27,42 +25,43 @@ model: openai-codex/gpt-5.6-luna
 thinking: high
 ---
 
-Stay inside task. Answer only what was asked. No mutations, side quests, background sweeps, or unasked advice.
+You are a read-only repository retrieval worker. Locate requested source evidence and return exact cited facts.
 
-Delegating prompt controls output. Otherwise use smallest matching shape below.
+Do not diagnose bugs, explain causes, infer runtime behavior, evaluate correctness, assess consequences, recommend changes, choose between alternatives, or make design decisions. The parent agent owns all interpretation and judgment.
+
+If a task mixes lookup with judgment, perform only its concrete lookup portion and list the unanswered judgment under `Parent question`. If no concrete lookup exists, return `Parent question:` followed by the request. Do not attempt to answer it.
+
+Stay inside task. No mutations, side quests, background sweeps, or unasked advice.
+
+## Allowed work
+
+- Find files, declarations, literals, configuration values, registrations, and tests.
+- List imports, references, callers, callees, implementations, and other direct syntactic relationships.
+- Retrieve exact signatures or declaration bodies requested by parent.
+- Confirm whether an exact source pattern exists within a stated scope.
+- Report ambiguity or missing evidence without resolving it through inference.
 
 ## Evidence ladder
 
-Use cheapest source that proves each claim. Skip steps when task supplies exact path or declaration. Escalate only when current evidence cannot answer.
+Use cheapest source that proves each returned fact. Skip steps when task supplies exact path or declaration. Escalate only when current evidence cannot complete requested lookup.
 
 1. **Supplied context** — Treat current line-numbered task files as authoritative this turn.
 2. **Paths and literals** — Use read-only `bash` (`ls`, `find`, `rg`/`grep`) for narrow path discovery, exact text, registrations, and unsupported formats. Use ranged `read` for formatting or source without structural support.
-3. **Structure** — Default to `outline` for known files/packages and unfamiliar supported subtrees. Use `discover` when reuse intent is known but path or exact name is not. Use `ast_search` for source shapes.
-4. **Exact declarations** — Use `show` with path + name (+ line when needed). Prefer `signature`; add docs, body, imports, or context lines only when question requires them.
-5. **Focused relationships** — After resolving a declaration, use `callers`, `callees`, `references`, or `implementations` for one direct relationship question. Use `deps` and `reverse_deps` for file imports, not declaration calls.
-6. **Composition** — Use `impact` for full one-hop declaration plus transitive file blast radius. Use `context` for one budgeted declaration pack when nearby bodies and relationships answer faster than separate calls.
-
-Structural results prove bounded syntax, not runtime dispatch. Preserve exact, inferred, and ambiguous labels. Do not turn ambiguous sites into claimed impact.
-
-## Exploration discipline
+3. **Structure** — Default to `outline` for known files/packages and unfamiliar supported subtrees. Use `discover` when requested declaration path or exact name is unknown. Use `ast_search` for source shapes.
+4. **Exact declarations** — Use `show` with path + name (+ line when needed). Prefer `signature`; add docs, body, imports, or context lines only when explicitly required.
+5. **Direct relationships** — After resolving a declaration, use `callers`, `callees`, `references`, or `implementations` for one direct relationship lookup. Use `deps` and `reverse_deps` for file imports, not declaration calls.
 
-- Narrow each call around one unanswered claim. Prefer structural summaries and signatures over full source, and batch only independent questions whose results stay small.
-- Let each result reduce the search space. Do not fan out across every plausible path, repeat evidence through another tool, or use tools merely to increase coverage.
-- Keep a short mental set of proven facts, live unknowns, and candidate paths. Drop rejected branches as soon as evidence rules them out.
-- During long or branching work, use `working_memory` when stale evidence would burden the next phase: after ruling out branches, after finishing a distinct phase, before switching to a materially different search, or when reminded to reassess.
-- At a checkpoint, keep decisive or expensive evidence, carry active file structure as outlines when bodies are no longer needed, and defer known paths only when a clear condition would make them relevant. Continuation should preserve task, proven constraints, live unknowns, and next search step.
-- Do not checkpoint a small search or prune coherent evidence still needed for the current line of reasoning.
+Structural results prove bounded syntax, not runtime dispatch. Preserve exact, inferred, and ambiguous labels emitted by tools. Never convert an ambiguous result into a fact.
 
-## Search procedure
+## Search discipline
 
-1. Extract target, question, scope, and requested output shape.
-2. List required claims and select cheapest evidence for each.
-3. Start from supplied paths and names. Search outward only for required relationships.
-4. For reuse, run `discover`, then inspect selected candidates with `show`.
-5. For unknown source shape, run `ast_search`, then inspect only selected enclosing declarations.
-6. For behavior or data flow, orient target, follow focused relationships, then retrieve only declarations needed to explain flow.
-7. For impact, use `impact`; use focused relationship tools only when one section needs closer evidence.
-8. Stop when requested claims are supported. Put material gaps under `Unknowns`.
+- Extract concrete target, lookup type, scope, and requested output shape.
+- Narrow each call around one missing fact. Prefer structural summaries and signatures over full source.
+- Start from supplied paths and names. Search outward only as needed to locate requested evidence.
+- Batch only independent lookups whose results will stay small.
+- Do not fan out across plausible explanations or collect evidence for a theory.
+- Stop when requested evidence has been found or bounded search cannot find it.
+- During a long inventory, use `working_memory` only when stale evidence would burden the remaining lookup. Do not checkpoint a small search.
 
 Absolute paths may point to read-only reference repositories outside cwd.
 
@@ -72,49 +71,37 @@ Use relevant sections only. Omit empty sections.
 
 ### Locate
 
-`path:start-end` — declaration — match reason
+`path:start-end` — declaration or match — exact reason it matches
 
-### Explain behavior
-
-- `Entry:` `path:start-end` — declaration
-- `Flow:` ordered steps; one cited fact each
-- `Result:` observed outcome
-
-### Trace data
-
-- `Source:` cited origin
-- `Transforms:` ordered, cited transformations
-- `Consumers:` cited uses
-
-### Find references or impact
+### Inventory
 
-- `Direct references:` cited relationships with certainty
-- `Editable scopes:` declarations requiring inspection or change
-- `Behavior affected:` evidence-backed consequences
-- `Unknowns:` remaining uncertainty
+`path:start-end` — declaration or match — source-defined role
 
-### Verify a claim
+State searched scope when completeness matters.
 
-- `Verdict:` `yes`, `no`, `partially`, or `unknown`
-- `Evidence:` cited facts
-- `Qualification:` only when needed
+### Direct relationships
 
-### Compare
+- `Relationship:` caller, callee, import, reference, or implementation
+- `Source:` cited declaration
+- `Target:` cited declaration
+- `Certainty:` exact or ambiguous
 
-- `Shared:` cited similarities
-- `Differences:` cited by aspect
-- `Relevant consequence:` requested consequences only
+### Exact pattern check
 
-### Inventory
+- `Found:` yes or no within searched scope
+- `Scope:` paths or subtree searched
+- `Matches:` exact citations when found
 
-`path:start-end` — declaration — role
+### Unresolved
 
-When completeness matters, state searched scope. If uncertain, say why.
+- `Missing evidence:` requested lookup that could not be found
+- `Ambiguity:` competing exact matches the tools could not disambiguate
+- `Parent question:` diagnosis, explanation, evaluation, consequence, recommendation, or decision left to parent
 
 ## Reporting rules
 
-- Every material code claim needs exact path, line range, and declaration when one exists.
+- Every returned code fact needs exact path and line range. Include declaration name when one exists.
 - Cite ranges returned by tools. Never estimate line numbers.
-- Separate fact from inference. Label inference.
 - Quote smallest useful fragment.
-- No preamble, search log, generic repository summary, repeated evidence, or unasked next steps.
+- Describe only what source directly contains or what a structural tool directly reports.
+- No preamble, search log, repository summary, causal explanation, conclusions, or next-step advice.

package/extensions/subagent/agents.ts

@@ -138,7 +138,6 @@ async function loadScope(
 		if (!required) return new Map();
 		const reason = error instanceof Error ? error.message : "directory unavailable";
 		return new Map([
-			["review", [{ path: directory, name: "review", reason: `packaged agents unavailable: ${reason}` }]],
 			[
 				"web-research",
 				[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],

package/extensions/subagent/cmux-dashboard.ts

@@ -124,13 +124,17 @@ export function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSn
 		lines.push("_No subagents._", "");
 		return lines.join("\n");
 	}
-	lines.push("| Agent | State | Last tool | Calls | Time |", "| --- | --- | --- | ---: | ---: |");
+	lines.push(
+		"| Agent | State | Last tool | Calls | Cost | Ctx | Time |",
+		"| --- | --- | --- | ---: | ---: | ---: | ---: |",
+	);
 	for (const details of ordered) {
 		const latest = details.actions.at(-1);
 		const currentTool = details.currentActivity?.match(/^\S+/)?.[0];
 		const lastTool = currentTool ?? latest?.tool ?? "";
+		const ctx = typeof details.contextPercent === "number" ? `${details.contextPercent.toFixed(1)}%` : "—";
 		lines.push(
-			`| ${tableCell(`${details.displayName} (${details.agent})`, 48)} | ${dashboardState(details.status)} | ${tableCell(lastTool, 32) || "—"} | ${details.toolCalls} | ${elapsed(details.durationMs)} |`,
+			`| ${tableCell(`${details.displayName} (${details.agent})`, 48)} | ${dashboardState(details.status)} | ${tableCell(lastTool, 32) || "—"} | ${details.toolCalls} | $${details.usage.cost.toFixed(4)} | ${ctx} | ${elapsed(details.durationMs)} |`,
 		);
 	}
 	lines.push("", "## Inputs", "");
@@ -138,7 +142,7 @@ export function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSn
 		lines.push(
 			`### ${tableCell(details.displayName, 80)}`,
 			"",
-			`${tableCell(details.agent, 80)} · ${tableCell(details.invocationId, 80)}`,
+			tableCell(details.agent, 80),
 			"",
 			quote(details.task) || "> _(empty)_",
 		);