one-code-extension 0.1.4 → 0.3.0

package/extensions/subagents/runs.ts

@@ -19,8 +19,23 @@ export interface AgentRunRecord {
 	/** Resolved session file, once known. */
 	sessionFile?: string;
 	cwd: string;
+	/** True when `cwd` is an isolation worktree, so a resume re-applies the git-isolation guard. */
+	worktree?: boolean;
 	model?: string;
 	thinking?: string;
+	/**
+	 * Nesting level: 0 = spawned by main, 1 = spawned by a child's own Agent
+	 * tool. Set once at creation and read by every spawn-tool handout (the
+	 * MAX_SPAWN_DEPTH gate), so a RESUMED grandchild stays capped too. Absent
+	 * on records from before nesting existed (treated as 0).
+	 */
+	depth?: number;
+	/**
+	 * The run completed inline in a one-shot session (`-p` / `--mode json`): its
+	 * report was returned in the tool result and no background task was ever
+	 * registered, so `task_output` does not know its id.
+	 */
+	inline?: boolean;
 }
 
 /** `<agent>-<n>` with the lowest n not already taken. */
@@ -32,6 +47,37 @@ export function nextRunName(existing: Iterable<string>, agent: string): string {
 	}
 }
 
+/**
+ * The name a new run gets: the requested one when free, else a fresh
+ * `<agent>-<n>`. A run name is an identifier for the whole session, so a reused
+ * one is replaced rather than shadowing the older run (which would vanish from
+ * list_agents while still running). `note` is the model-facing explanation
+ * when the request was overridden; the caller prepends it to the spawn result.
+ * Shared by the main Agent tool and the nested spawn tool.
+ */
+export function resolveRunName(
+	registry: Pick<RunRegistry, "names" | "resolve" | "reserve">,
+	agent: string,
+	requested: string | undefined,
+): { name: string; note?: string } {
+	const taken = new Set(registry.names());
+	const wanted = requested?.trim();
+	// Reserved synchronously: pi runs a message's tool calls in parallel, and the
+	// record is only added after async work (worktree creation, model checks), so
+	// two same-turn spawns would otherwise both pick "explore-1".
+	if (wanted && !taken.has(wanted)) {
+		registry.reserve(wanted);
+		return { name: wanted };
+	}
+	const name = nextRunName(taken, agent);
+	registry.reserve(name);
+	if (!wanted) return { name };
+	return {
+		name,
+		note: `Note: the name "${wanted}" is already used by task ${registry.resolve(wanted)?.taskId ?? "?"} in this session; this run is named "${name}".`,
+	};
+}
+
 /** Newest .jsonl under `dir` (recursive) — the child session pi created there. */
 export function findSessionFile(dir: string): string | undefined {
 	let newest: { path: string; mtime: number } | undefined;
@@ -63,15 +109,36 @@ export function findSessionFile(dir: string): string | undefined {
 export class RunRegistry {
 	private byName = new Map<string, AgentRunRecord>();
 	private byId = new Map<string, AgentRunRecord>();
+	/** Names picked for runs whose record has not been added yet (see resolveRunName). */
+	private reserved = new Set<string>();
+
+	/** Drop every record — a new session (/clear) starts with no runs to address. */
+	clear(): void {
+		this.byName.clear();
+		this.byId.clear();
+		this.reserved.clear();
+	}
+
+	/** Hold a name until its record is added (a spawn that fails validation leaves it held — harmless). */
+	reserve(name: string): void {
+		this.reserved.add(name);
+	}
 
 	/** Latest wins per name, matching Claude Code's semantics. */
 	add(record: AgentRunRecord): void {
+		this.reserved.delete(record.name);
 		this.byName.set(record.name, record);
 		this.byId.set(record.taskId, record);
 	}
 
+	/** Every name in use: recorded runs plus names reserved for runs being spawned. */
 	names(): string[] {
-		return [...this.byName.keys()];
+		return [...new Set([...this.byName.keys(), ...this.reserved])];
+	}
+
+	/** Every spawned run, latest-per-name (what list_agents enumerates). */
+	list(): AgentRunRecord[] {
+		return [...this.byName.values()];
 	}
 
 	/** Resolve by name, exact task id, or unique task-id prefix (3+ chars). */

package/extensions/subagents/send-to-main-tool.ts

@@ -0,0 +1,55 @@
+/**
+ * The child-only `send_message` tool, injected as a custom tool into an
+ * in-process subagent session. From inside a subagent, `to: "main"` reports
+ * progress/findings/questions to the main conversation mid-run — the subagent's
+ * plain text output is not visible to the main conversation until it finishes.
+ *
+ * In-process this needs no IPC or event-stream parsing (unlike the spawned RPC
+ * child, where the parent re-parsed the child's tool_execution_end): the tool's
+ * execute() calls the parent's `onMessage` callback directly. The main
+ * conversation's own `send_message`/`SendMessage` tool (agent→agent addressing)
+ * is a different tool registered on the parent session.
+ */
+
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export function sendToMainTool(onMessage: (message: string, summary?: string) => void): ToolDefinition {
+	return {
+		name: "SendMessage",
+		label: "Send Message",
+		description:
+			'Report progress, findings, or a question to the main conversation mid-run (to: "main"). Your plain text output is NOT visible to the main conversation until you finish, so use this to surface something before then.',
+		parameters: Type.Object({
+			to: Type.Optional(Type.String({ description: 'Recipient — only "main" is valid from inside a subagent' })),
+			message: Type.String({ description: "Plain text message for the main conversation" }),
+			summary: Type.Optional(Type.String({ description: "5-10 word preview shown in the UI" })),
+		}) as never,
+		async execute(_toolCallId: string, params: unknown) {
+			const p = (params ?? {}) as { to?: unknown; message?: unknown; summary?: unknown };
+			// Fail loud (docs/decisions/tools.md): a wrong recipient or a missing
+			// message returns isError with the fix named, never a silent success.
+			if (p.to !== undefined && p.to !== "main") {
+				return {
+					content: [{ type: "text" as const, text: `From inside a subagent the only recipient is "main" — got ${JSON.stringify(p.to)}. Omit \`to\` or pass "main".` }],
+					details: {},
+					isError: true,
+				};
+			}
+			const message = typeof p.message === "string" ? p.message.trim() : "";
+			if (!message) {
+				return {
+					content: [{ type: "text" as const, text: "`message` is required: pass the plain text to deliver to the main conversation." }],
+					details: {},
+					isError: true,
+				};
+			}
+			const summary = typeof p.summary === "string" ? p.summary : undefined;
+			onMessage(message, summary);
+			return {
+				content: [{ type: "text" as const, text: "Message delivered to the main conversation." }],
+				details: { toMain: true, message, summary },
+			};
+		},
+	} as ToolDefinition;
+}

package/extensions/subagents/session-turns.ts

@@ -0,0 +1,138 @@
+/**
+ * In-process turn tracking for a resident subagent session — the successor to
+ * rpc-turns.ts's `RpcTurnTracker`, which parsed a `pi --mode rpc` child's JSONL
+ * wire. Here it consumes `AgentSession.subscribe` events directly (no JSON
+ * parsing, no process).
+ *
+ * Turn-end fires on `agent_settled`, not `agent_end`: `agent_end` can be
+ * followed by an internal retry/auto-compaction/continue loop before the run is
+ * really done, whereas `agent_settled` is emitted exactly once the session
+ * becomes idle (see pi's AgentSession `_emitAgentSettled`). Busy/idle is read
+ * from the live `AgentSession` getters, so this only accumulates per-turn stats.
+ */
+
+import { recordAction, type ChildAction } from "../auto-mode/actions.ts";
+import { type ChildOutcome, OUTPUT_CAP } from "./outcome.ts";
+import { addUsage, emptyUsage, type UsageTotals } from "./usage.ts";
+
+/** The subset of AgentSession events this tracker reads. */
+interface TrackedEvent {
+	type?: string;
+	toolName?: string;
+	args?: unknown;
+	message?: { role?: string; content?: unknown; usage?: unknown; stopReason?: string; errorMessage?: string };
+}
+
+export class SessionTurnTracker {
+	toolCalls = 0;
+	/** What the child did this turn, for auto mode's return review. */
+	actions: ChildAction[] = [];
+	readonly usage: UsageTotals = emptyUsage();
+	/** Final assistant text of the turn in progress (or the last finished one). */
+	turnText = "";
+	/** Set when the turn's last assistant message ended with a provider error; cleared by a later success. */
+	providerError: string | undefined;
+	/**
+	 * Set when the turn was cut short, so its partial text is never reported as
+	 * a completion (SUBAGENT-REVIEW M3). The runner's `markAborted` is the
+	 * authoritative setter: every `session.abort()` the runner issues marks the
+	 * tracker first, and an abort that lands during a tool call leaves no
+	 * aborted assistant message to observe. The `stopReason: "aborted"` branch
+	 * in `process` is belt-and-braces for an abort the runner did not initiate.
+	 */
+	aborted: string | undefined;
+	/** Every turn's final text joined, for task_output on a resident agent. */
+	transcript = "";
+
+	/** Call when a new turn is started (a prompt sent while idle). */
+	beginTurn(): void {
+		this.turnText = "";
+		this.providerError = undefined;
+		this.aborted = undefined;
+		// Per turn, not per session: the review that reads this judges the turn just finished.
+		this.actions = [];
+	}
+
+	/** The runner cut this turn short (kill, wall-clock cap, cancelled signal); `reason` is the suffix the report carries. */
+	markAborted(reason = "terminated before the turn finished"): void {
+		// First reason wins: a wall-clock cap followed by a shutdown kill in the same
+		// abort-settling window keeps the more specific explanation.
+		this.aborted ??= reason;
+	}
+
+	/** Feed one subscribed event. Returns true when a turn just settled. */
+	process(event: TrackedEvent): boolean {
+		switch (event.type) {
+			case "tool_execution_start": {
+				this.toolCalls++;
+				if (event.toolName) recordAction(this.actions, event.toolName, event.args);
+				return false;
+			}
+			case "message_end": {
+				if (event.message?.role !== "assistant") return false;
+				addUsage(this.usage, event.message.usage);
+				this.providerError =
+					event.message.stopReason === "error" ? event.message.errorMessage || "unknown provider error" : undefined;
+				if (event.message.stopReason === "aborted") this.aborted ??= "terminated before the turn finished";
+				const blocks = Array.isArray(event.message.content) ? event.message.content : [];
+				const text = blocks
+					.filter((b): b is { type: string; text: string } => (b as { type?: string }).type === "text")
+					.map((b) => b.text)
+					.join("");
+				if (text.trim()) this.turnText = text;
+				return false;
+			}
+			case "agent_settled": {
+				if (this.turnText.trim()) {
+					this.transcript = this.transcript ? `${this.transcript}\n\n---\n\n${this.turnText}` : this.turnText;
+				}
+				return true;
+			}
+			default:
+				return false;
+		}
+	}
+
+	/** The outcome of the turn that just settled. */
+	turnOutcome(): ChildOutcome {
+		return finishOutcome(this.turnText, this.providerError, this.toolCalls, this.usage, this.actions, this.aborted);
+	}
+}
+
+/**
+ * Shape a run/turn's collected state into a ChildOutcome, matching the spawned
+ * child's messages. `aborted` (a reason) wins over everything: an aborted turn's
+ * partial text is reported as terminated and failed, never as the answer.
+ */
+export function finishOutcome(
+	rawOutput: string,
+	providerError: string | undefined,
+	toolCalls: number,
+	usage: UsageTotals,
+	actions: ChildAction[],
+	aborted?: string,
+): ChildOutcome {
+	const output = rawOutput.slice(0, OUTPUT_CAP);
+	if (aborted) {
+		return {
+			output: output.trim() ? `${output}\n\n[${aborted}]` : `Subagent ${aborted}.`,
+			toolCalls,
+			usage,
+			actions,
+			failed: true,
+		};
+	}
+	if (providerError) {
+		return {
+			output: output.trim()
+				? `${output}\n\n[The subagent's last request ended with a provider error: ${providerError}]`
+				: `Subagent failed with a provider error (its model could not be called — an auth/billing/rate-limit problem, not a task failure): ${providerError}`,
+			toolCalls,
+			usage,
+			actions,
+			failed: true,
+		};
+	}
+	if (output.trim()) return { output, toolCalls, usage, actions };
+	return { output: "Subagent produced no output.", toolCalls, usage, actions, failed: true };
+}

package/extensions/subagents/shell-panel.ts

@@ -0,0 +1,198 @@
+/**
+ * Pure state + rendering for the background-shells side of the below-editor
+ * panel — Claude Code's shell manager. Three stages, entered with the FIRST
+ * down-arrow (a second ↓ moves on to the agent rows):
+ *
+ *   chip     "2 shells · ↓ to manage" → focused: "[2 shells] · Enter to view tasks"
+ *   list     the Background panel: selectable command rows, x stops, Esc backs out
+ *   details  one shell: Status/Runtime/Command + a live bordered output box
+ *
+ * Task objects arrive over TASK_REGISTER_CHANNEL (lib/shell-tasks.ts) and stay
+ * live — output()/status are read at render time. Key wiring lives in
+ * index.ts; this file owns layout and the focus reducer only.
+ */
+
+import type { BackgroundTask } from "../background/registry.ts";
+import { countNoun, cutPlainText as cut, formatDuration, padPlainText } from "../lib/tui-render.ts";
+import type { StripKey } from "./panel-keys.ts";
+import type { Paint } from "./panel-render.ts";
+
+export interface ShellPaint extends Paint {
+	inverse(text: string): string;
+}
+
+export type ShellFocus =
+	| { stage: "chip" }
+	| { stage: "list"; selectedId: string }
+	| { stage: "details"; selectedId: string };
+
+/** A finished shell stays listed this long, so its terminal status is seen. */
+export const SHELL_LIST_LINGER_MS = 60_000;
+
+/** Output-box height in the details view (content rows, borders excluded). */
+export const OUTPUT_BOX_ROWS = 10;
+
+/** Most list rows shown at once; the selection slides a window over the rest. */
+export const MAX_SHELL_LIST_ROWS = 8;
+
+/** Only this much of the spool is split per frame — the box shows 10 lines. */
+const OUTPUT_TAIL_CHARS = 8192;
+
+/** The list rows: running shells first, newest-first within each group. */
+export function shellRows(tasks: BackgroundTask[], now: number): BackgroundTask[] {
+	return tasks
+		.filter((t) => t.status === "running" || (t.finishedAt ?? now) > now - SHELL_LIST_LINGER_MS)
+		.sort((a, b) => Number(b.status === "running") - Number(a.status === "running") || b.startedAt - a.startedAt);
+}
+
+/**
+ * Re-anchor a focus whose selected shell left the rows (lingered out or never
+ * existed): fall back to the first row, or to the chip when the list emptied.
+ */
+export function anchorShellFocus(focus: ShellFocus, ids: string[]): ShellFocus {
+	if (focus.stage === "chip" || ids.includes(focus.selectedId)) return focus;
+	return ids.length ? { ...focus, selectedId: ids[0] } : { stage: "chip" };
+}
+
+export interface ShellTransition {
+	/** The next focus; undefined closes the shell section entirely. */
+	focus: ShellFocus | undefined;
+	/** stopSelected: stop the selected task; toAgents: hand ↓ on to the agent
+	 * rows; passthrough: unhandled byte — drop focus and let the editor have it. */
+	effect?: "stopSelected" | "toAgents" | "passthrough";
+}
+
+/**
+ * The focus reducer — Claude Code's shell-manager keys. `ids` is the current
+ * row order (shellRows), `focus` is already anchored against it.
+ */
+export function reduceShellKey(focus: ShellFocus, key: StripKey | undefined, ids: string[]): ShellTransition {
+	const index = focus.stage === "chip" ? -1 : ids.indexOf(focus.selectedId);
+	switch (focus.stage) {
+		case "chip":
+			if (key === "down") return { focus: undefined, effect: "toAgents" };
+			if (key === "open") return { focus: ids.length ? { stage: "list", selectedId: ids[0] } : focus };
+			if (key === "up" || key === "leave") return { focus: undefined };
+			return { focus: undefined, effect: "passthrough" };
+		case "list":
+			if (key === "up") return { focus: index > 0 ? { stage: "list", selectedId: ids[index - 1] } : focus };
+			if (key === "down")
+				return { focus: index < ids.length - 1 ? { stage: "list", selectedId: ids[index + 1] } : focus };
+			if (key === "open") return { focus: { stage: "details", selectedId: focus.selectedId } };
+			if (key === "stop") return { focus, effect: "stopSelected" };
+			if (key === "leave" || key === "left") return { focus: { stage: "chip" } };
+			if (key === "pageUp" || key === "pageDown") return { focus };
+			return { focus: undefined, effect: "passthrough" };
+		case "details":
+			if (key === "left") return { focus: { stage: "list", selectedId: focus.selectedId } };
+			if (key === "leave" || key === "open" || key === "space") return { focus: undefined };
+			if (key === "stop") return { focus, effect: "stopSelected" };
+			if (key === "up" || key === "down" || key === "pageUp" || key === "pageDown") return { focus };
+			return { focus: undefined, effect: "passthrough" };
+	}
+}
+
+export interface ShellSectionInput {
+	/** shellRows()-ordered. */
+	rows: BackgroundTask[];
+	runningCount: number;
+	focus: ShellFocus | undefined;
+	width: number;
+	now: number;
+}
+
+/**
+ * Whether the section renders at all (drives widget visibility and ↓ entry).
+ * Keyed on the ROW count, not the running count, so a finished shell's chip
+ * stays reachable for the linger window — otherwise its outcome would only be
+ * visible if the panel happened to be open when it finished.
+ */
+export function shellSectionVisible(rowCount: number, focus: ShellFocus | undefined): boolean {
+	return rowCount > 0 || focus !== undefined;
+}
+
+const STATUS_COLOR: Record<string, string> = { running: "accent", failed: "error", stopped: "dim" };
+
+/** The section's lines at the current stage. Caller checks visibility first. */
+export function renderShellSection(input: ShellSectionInput, paint: ShellPaint): string[] {
+	const width = Math.max(20, input.width);
+	const focus = input.focus;
+	// The label counts ROWS (running + lingering finished), matching what the
+	// panel actually shows — visibility keys on rows too, so a finished shell's
+	// chip must not read "0 shells" while it is still openable.
+	if (!focus) return [paint.fg("dim", cut(`${countNoun(input.rows.length, "shell")} · ↓ to manage`, width))];
+	if (focus.stage === "chip") {
+		// Cut the plain parts BEFORE painting — cutting painted text breaks escapes.
+		const label = cut(` ${countNoun(input.rows.length, "shell")} `, width);
+		const hint = cut("· Enter to view tasks", Math.max(0, width - label.length - 1));
+		return [`${paint.inverse(label)}${hint ? ` ${paint.fg("dim", hint)}` : ""}`];
+	}
+	if (focus.stage === "list") return renderShellList(input, focus.selectedId, paint, width);
+	return renderShellDetails(input, focus.selectedId, paint, width);
+}
+
+function renderShellList(input: ShellSectionInput, selectedId: string, paint: ShellPaint, width: number): string[] {
+	const out: string[] = [];
+	out.push(paint.fg("accent", paint.bold("Background")));
+	out.push(cut(countNoun(input.runningCount, "active shell"), width));
+	out.push("");
+	// A window of MAX_SHELL_LIST_ROWS slid to keep the selection visible, so a
+	// big shell fan-out cannot grow the panel past the terminal.
+	const selectedIndex = Math.max(0, input.rows.findIndex((t) => t.id === selectedId));
+	const start = Math.min(Math.max(0, selectedIndex - MAX_SHELL_LIST_ROWS + 1), Math.max(0, input.rows.length - MAX_SHELL_LIST_ROWS));
+	const shown = input.rows.slice(start, start + MAX_SHELL_LIST_ROWS);
+	if (start > 0) out.push(paint.fg("dim", `  +${start} more above`));
+	for (const task of shown) {
+		const marker = task.id === selectedId ? "❯ " : "  ";
+		const status = ` (${task.status})`;
+		const command = cut(task.command ?? task.description, Math.max(1, width - marker.length - status.length));
+		out.push(`${marker}${command}${paint.fg(STATUS_COLOR[task.status] ?? "dim", status)}`);
+	}
+	const below = input.rows.length - start - shown.length;
+	if (below > 0) out.push(paint.fg("dim", `  +${below} more below`));
+	if (!input.rows.length) out.push(paint.fg("dim", "  no shells"));
+	out.push("");
+	out.push(paint.fg("dim", cut("↑/↓ to select · Enter to view · x to stop · Esc to close", width)));
+	return out;
+}
+
+function renderShellDetails(input: ShellSectionInput, selectedId: string, paint: ShellPaint, width: number): string[] {
+	const task = input.rows.find((t) => t.id === selectedId);
+	const out: string[] = [];
+	out.push(paint.fg("accent", paint.bold("Shell details")));
+	out.push("");
+	if (!task) {
+		out.push(paint.fg("dim", "shell gone"));
+		return out;
+	}
+	const field = (label: string, value: string) => `${paint.bold(padPlainText(label, 9))} ${value}`;
+	out.push(field("Status:", paint.fg(STATUS_COLOR[task.status] ?? "dim", task.status)));
+	out.push(field("Runtime:", formatDuration(task.startedAt, task.finishedAt, input.now)));
+	out.push(field("Command:", cut(task.command ?? task.description, Math.max(1, width - 10))));
+	out.push("");
+	out.push(paint.bold("Output:"));
+
+	let output = "";
+	try {
+		output = task.output();
+	} catch {
+		output = "(output unavailable)";
+	}
+	// Bound the split to a tail slice — re-splitting a 200KB spool every ticker
+	// frame to keep 10 lines is O(buffer) work for nothing. A mid-line cut only
+	// matters when the tail holds fewer lines than the box, and those are
+	// width-cut anyway.
+	const tail = output.length > OUTPUT_TAIL_CHARS ? output.slice(-OUTPUT_TAIL_CHARS) : output;
+	const lines = tail ? tail.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n") : [];
+	const shown = lines.slice(-OUTPUT_BOX_ROWS);
+	const inner = Math.max(1, width - 4);
+	out.push(`┌${"─".repeat(Math.max(0, width - 2))}┐`);
+	for (let i = 0; i < OUTPUT_BOX_ROWS; i++) {
+		out.push(`│ ${padPlainText(cut(shown[i] ?? "", inner), inner)} │`);
+	}
+	out.push(`└${"─".repeat(Math.max(0, width - 2))}┘`);
+	out.push(paint.fg("dim", `Showing ${countNoun(shown.length, "line")}`));
+	out.push("");
+	out.push(paint.fg("dim", cut("← to go back · Esc/Enter/Space to close · x to stop", width)));
+	return out;
+}

package/extensions/subagents/usage.ts

@@ -1,9 +1,9 @@
 /**
- * Token/cost accounting for child-process subagent runs.
+ * Token/cost accounting for in-process subagent runs.
  *
- * A child run in `--mode json` emits one `message_end` per assistant message,
- * each carrying a pi-ai `Usage` for that API call; summing them gives the
- * run's totals (the in-process equivalent is `session.getSessionStats()`).
+ * A child session emits one `message_end` per assistant message, each carrying
+ * a pi-ai `Usage` for that API call (SessionTurnTracker feeds them in); summing
+ * them gives the run's totals, across every turn of a resident.
  */
 
 export interface UsageTotals {
@@ -19,6 +19,18 @@ export function emptyUsage(): UsageTotals {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, cost: 0 };
 }
 
+/** Field-wise sum of two totals (pure — neither input is mutated). */
+export function sumUsage(a: UsageTotals, b: UsageTotals): UsageTotals {
+	return {
+		input: a.input + b.input,
+		output: a.output + b.output,
+		cacheRead: a.cacheRead + b.cacheRead,
+		cacheWrite: a.cacheWrite + b.cacheWrite,
+		total: a.total + b.total,
+		cost: a.cost + b.cost,
+	};
+}
+
 /** Add one assistant message's `usage` (untrusted JSONL) into `totals`. */
 export function addUsage(totals: UsageTotals, usage: unknown): void {
 	if (!usage || typeof usage !== "object") return;

package/extensions/subagents/worktree.ts

@@ -11,6 +11,7 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
+import { registerWorktreeIsolation, releaseWorktreeIsolation } from "../lib/worktree-isolation.ts";
 
 const run = promisify(execFile);
 
@@ -39,6 +40,15 @@ export async function createWorktree(cwd: string, label: string): Promise<Worktr
 	const path = join(dir, "tree");
 	const branch = `cc-subagent/${safeLabel}-${Date.now().toString(36)}`;
 	await git(["worktree", "add", "-b", branch, path, "HEAD"], cwd);
+	// Register for the child permission gate's git-isolation guard. The shared
+	// checkout's ROOT, not cwd — the spawn may run from a subdirectory.
+	let sharedRoot = cwd;
+	try {
+		sharedRoot = await git(["rev-parse", "--show-toplevel"], cwd);
+	} catch {
+		// Keep cwd as the best available anchor.
+	}
+	registerWorktreeIsolation(path, sharedRoot);
 	return { path, branch };
 }
 
@@ -65,5 +75,8 @@ export async function cleanupWorktree(cwd: string, worktree: Worktree): Promise<
 		// Leave it behind rather than failing the run.
 		return false;
 	}
+	// Release only when the worktree is actually gone — a kept worktree can
+	// still host a resumed session (SendMessage), which must stay guarded.
+	releaseWorktreeIsolation(worktree.path);
 	return true;
 }

package/extensions/system-prompt/environment.ts

@@ -1,7 +1,11 @@
 /**
  * Environment facts for the system prompt's # Environment section.
  * Collected once per (cwd, model) and cached so the prompt stays byte-stable
- * across turns — required for provider prompt caching to pay off.
+ * across turns — required for provider prompt caching to pay off. Nothing
+ * time-valued belongs here: the date rides Claude Code's `# currentDate` line
+ * in the first-message reminder (claude-context), never the system prompt
+ * (Claude Code's own prompt has no date line; a cached one went stale at
+ * midnight — CACHE-REVIEW-2026-09-04 L2).
  */
 
 import os from "node:os";
@@ -14,7 +18,6 @@ export interface EnvironmentInfo {
 	platform: string;
 	osVersion: string;
 	shell: string;
-	date: string;
 	modelLine: string;
 	/** Per-project auto-memory directory; the memory extension guarantees it exists. */
 	memoryDir: string;
@@ -28,7 +31,6 @@ export function collectEnvironment(cwd: string, modelLine: string): EnvironmentI
 		platform: process.platform,
 		osVersion: `${os.type()} ${os.release()}`,
 		shell: process.env.SHELL ? (process.env.SHELL.split("/").pop() ?? "unknown") : "unknown",
-		date: new Date().toISOString().slice(0, 10),
 		modelLine,
 		memoryDir: projectMemoryDir(cwd, os.homedir()),
 	};

package/extensions/system-prompt/git-status.ts

@@ -0,0 +1,93 @@
+/**
+ * Claude Code's `gitStatus:` block — appended to the very end of the system
+ * prompt in a git repo, identical across model tiers, and a one-time snapshot:
+ * CC states it is "the git status at the start of the conversation" and "will not
+ * update during the conversation", so it is computed once per session and frozen.
+ *
+ * Format and commands reverse-engineered from real CC captures
+ * (git-cc-sonnet.json / git-cc-haiku.json): `git branch --show-current`, the main
+ * branch from `origin/HEAD` (falling back to a local main/master), `git config
+ * user.name`, `git status --porcelain`, and `git log -5 --format='%h %s'`. Both
+ * the status and the log are whole-output `.trim()`ed — which is why a leading
+ * `??`/` M` porcelain line renders flush-left in the capture.
+ *
+ * The module is pure apart from `defaultRunner`; `collectGitStatus` takes an
+ * injectable runner so the git commands can be faked in unit tests.
+ */
+
+import { execFileSync } from "node:child_process";
+
+export interface GitSnapshot {
+	branch: string;
+	mainBranch: string;
+	user: string;
+	/** `git status --porcelain`, trimmed. */
+	status: string;
+	/** `git log -5 --format='%h %s'`, trimmed. */
+	commits: string;
+}
+
+const HEADER =
+	"gitStatus: This is the git status at the start of the conversation. " +
+	"Note that this status is a snapshot in time, and will not update during the conversation.";
+
+/** Assemble CC's block from a snapshot. Pure; byte-exact against the captures. */
+export function formatGitStatus(s: GitSnapshot): string {
+	return [
+		HEADER,
+		"",
+		`Current branch: ${s.branch}`,
+		"",
+		`Main branch (you will usually use this for PRs): ${s.mainBranch}`,
+		"",
+		`Git user: ${s.user}`,
+		"",
+		"Status:",
+		s.status,
+		"",
+		"Recent commits:",
+		s.commits,
+	].join("\n");
+}
+
+/** Runs one git command in `cwd`, returning trimmed stdout or null on any failure. */
+export type GitRunner = (args: string[]) => string | null;
+
+function defaultRunner(cwd: string): GitRunner {
+	return (args) => {
+		try {
+			return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+		} catch {
+			return null;
+		}
+	};
+}
+
+/** The main branch: `origin/HEAD` if set, else a local `main`/`master`, else the current branch. */
+function resolveMainBranch(run: GitRunner, branch: string): string {
+	const originHead = run(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+	if (originHead) return originHead.replace(/^origin\//, "");
+	for (const candidate of ["main", "master"]) {
+		if (run(["rev-parse", "--verify", "--quiet", candidate])) return candidate;
+	}
+	return branch;
+}
+
+/**
+ * CC's `gitStatus:` block for `cwd`, or null when `cwd` is not inside a git work
+ * tree. Individual command failures degrade to empty fields rather than dropping
+ * the whole block, matching CC's per-field resilience.
+ */
+export function collectGitStatus(cwd: string, runner?: GitRunner): string | null {
+	const run = runner ?? defaultRunner(cwd);
+	if (run(["rev-parse", "--is-inside-work-tree"]) !== "true") return null;
+
+	const branch = run(["branch", "--show-current"]) ?? "";
+	return formatGitStatus({
+		branch,
+		mainBranch: resolveMainBranch(run, branch),
+		user: run(["config", "user.name"]) ?? "",
+		status: run(["status", "--porcelain"]) ?? "",
+		commits: run(["log", "-5", "--format=%h %s"]) ?? "",
+	});
+}