one-code-extension 0.4.1 → 0.6.0

package/extensions/subagents/agent-description.ts

@@ -0,0 +1,132 @@
+/**
+ * The Agent tool's model-facing description: Claude Code's Agent text plus
+ * One Code's own paragraph (pure).
+ *
+ * The short form goes to frontier and workhorse models, the long form (the
+ * text Claude Code writes for its weakest models, with the fork guidance,
+ * the briefing section and worked examples) to cheap and tiny ones
+ * (lib/tool-variants.ts). Changes from Claude Code's text: a fork rejects a
+ * `model` override rather than ignoring it, agent definitions come from
+ * `.claude/agents/*.md` only, and tool names are One Code's. The closing
+ * paragraph describes what only One Code has: `task_output` and `task_stop`,
+ * the one-shot print session, run names and `action: "list"`.
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+export const AGENT_SHORT_DESCRIPTION = `Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types are listed in <system-reminder> messages in the conversation.
+
+When using the Agent tool, specify a subagent_type to select an agent: \`"fork"\` forks yourself (the fork inherits your full conversation context and always runs on your model — a \`model\` override is rejected); any other type — or omitting it — starts a fresh agent (general-purpose by default).
+
+## When to use
+
+Reach for this when the task matches an available agent type, when you have independent work to run in parallel, or when answering would mean reading across several files — delegate it and you keep the conclusion, not the file dumps. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you've delegated a search, don't also run it yourself — wait for the result.
+
+A fork runs in the background and keeps its tool output out of your context. If you are the fork, execute directly — don't re-delegate. Subagents run in the background; you'll be notified when one completes. Never fabricate or predict a pending agent's results — the notification is never something you write yourself; if the user asks before it arrives, say it's still running.
+
+- The agent's final report is not shown to the user — relay what matters.
+- Use SendMessage with the agent's ID or name to continue a previously spawned agent with its context intact; a new Agent call starts fresh (except subagent_type: "fork", which inherits your context).
+- Each agent type's model, reasoning effort, and tools come from its definition (\`.claude/agents/*.md\` frontmatter).
+- \`isolation: "worktree"\` gives the agent its own git worktree (auto-cleaned if unchanged).`;
+
+export const AGENT_LONG_DESCRIPTION = `Launch a new agent to handle complex, multi-step tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types are listed in <system-reminder> messages in the conversation.
+
+When using the Agent tool, specify a subagent_type to select an agent: \`"fork"\` forks yourself (the fork inherits your full conversation context and always runs on your model — a \`model\` override is rejected); any other type — or omitting it — starts a fresh agent (general-purpose by default).
+
+## Usage notes
+
+- Always include a short description summarizing what the agent will do
+- When the agent is done, its final report is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting the work as done.
+- To continue a previously spawned agent, use SendMessage with the agent's ID or name as the \`to\` field — that resumes it with full context. A new Agent call starts a fresh agent with no memory of prior runs (except subagent_type: "fork"), so the prompt must be self-contained.
+- Each agent type's model, reasoning effort, and tool access are set in its definition (\`.claude/agents/*.md\` frontmatter); the \`model\` parameter here overrides the definition for this one call.
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since a fresh agent is not aware of the user's intent
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first.
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
+- With \`isolation: "worktree"\`, the worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.
+
+## When to fork
+
+Fork yourself (pass \`subagent_type: "fork"\`) when the intermediate tool output isn't worth keeping in your context. The criterion is qualitative — "will I need this output again" — not task size. Fork open-ended questions. If research can be broken into independent questions, launch parallel forks in one message. A fork beats a fresh subagent for this — it inherits context and shares your cache.
+
+Forks are cheap because they share your prompt cache.
+
+**Don't peek.** The tool result includes an \`output_file\` path — do not read or tail it. You get a completion notification; trust it. Reading the transcript mid-flight pulls the fork's tool noise into your context, which defeats the point of forking.
+
+**Don't race.** After launching, you know nothing about what the fork found. Never fabricate or predict fork results in any format — not as prose, summary, or structured output. The notification arrives as a user-role message in a later turn; it is never something you write yourself. If the user asks a follow-up before the notification lands, tell them the fork is still running — give status, not a guess.
+
+**Writing a fork prompt.** Since the fork inherits your context, the prompt is a *directive* — what to do, not what the situation is. Be specific about scope: what's in, what's out, what another agent is handling. Don't re-explain background.
+
+
+## Writing the prompt
+
+Any agent other than a fork starts with zero context. Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so ("report in under 200 words").
+- Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+For fresh agents, terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
+
+Example usage:
+
+<example>
+user: "What's left on this branch before we can ship?"
+assistant: <thinking>Forking this — it's a survey question. I want the punch list, not the git output in my context.</thinking>
+Agent({
+  subagent_type: "fork",
+  name: "ship-audit",
+  description: "Branch ship-readiness audit",
+  prompt: "Audit what's left before this branch can ship. Check: uncommitted changes, commits ahead of main, whether tests exist, whether the GrowthBook gate is wired up, whether CI-relevant files changed. Report a punch list — done vs. missing. Under 200 words."
+})
+assistant: Ship-readiness audit running.
+<commentary>
+Turn ends here. The coordinator knows nothing about the findings yet. What follows is a SEPARATE turn — the notification arrives from outside, as a user-role message. It is not something the coordinator writes.
+</commentary>
+[later turn — notification arrives as user message]
+assistant: Audit's back. Three blockers: no tests for the new prompt path, GrowthBook gate wired but not in build_flags.yaml, and one uncommitted file.
+</example>
+
+<example>
+user: "so is the gate wired up or not"
+<commentary>
+User asks mid-wait. The audit fork was launched to answer exactly this, and it hasn't returned. The coordinator does not have this answer. Give status, not a fabricated result.
+</commentary>
+assistant: Still waiting on the audit — that's one of the things it's checking. Should land shortly.
+</example>
+
+<example>
+user: "Can you get a second opinion on whether this migration is safe?"
+assistant: <thinking>I'll ask the code-reviewer agent — it won't see my analysis, so it can give an independent read.</thinking>
+<commentary>
+A non-fork subagent_type is specified, so the agent starts fresh. It needs full context in the prompt. The briefing explains what to assess and why.
+</commentary>
+Agent({
+  name: "migration-review",
+  description: "Independent migration review",
+  subagent_type: "code-reviewer",
+  prompt: "Review migration 0042_user_schema.sql for safety. Context: we're adding a NOT NULL column to a 50M-row table. Existing rows get a backfill default. I want a second opinion on whether the backfill approach is safe under concurrent writes — I've checked locking behavior but want independent verification. Report: is this safe, and if not, what specifically breaks?"
+})
+</example>
+`;
+
+/** One Code's own part, after Claude Code's text in both forms. */
+export const AGENT_HOW_AGENTS_RUN = `## How agents run
+
+- Call task_output only if your next step cannot proceed without the result (block=true waits); stop a run with task_stop. Both are deferred — load them with tool_search first.
+- In a one-shot print session the call blocks and returns the report directly — no notification follows.
+- Give a complete, self-contained task: the agent cannot ask follow-up questions.
+- Each run gets a name — SendMessage reaches it live while it runs and continues it after it finishes. \`action: "list"\` re-prints the agent catalog.`;
+
+/** The Agent description for a form, naming the mode's agent folder (`.onecode` in independent mode, lib/config-mode.ts). */
+export function agentDescription(form: DescriptionForm, configDir = ".claude"): string {
+	const base = form === "long" ? AGENT_LONG_DESCRIPTION : AGENT_SHORT_DESCRIPTION;
+	return `${base.trimEnd()}\n\n${AGENT_HOW_AGENTS_RUN}`.replaceAll("`.claude/agents/*.md`", `\`${configDir}/agents/*.md\``);
+}

package/extensions/subagents/agents.ts

@@ -14,10 +14,12 @@
  * Subdirectories are searched recursively.
  */
 
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
+import { readdirSync, readFileSync, type Stats, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
-import { claudeUserDir } from "../lib/paths.ts";
+import { projectConfigDir, userConfigDir } from "../lib/config-mode.ts";
+import { SUBAGENT_HANDBACK } from "../lib/subagent-handback.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
 
 export interface AgentDefinition {
@@ -40,50 +42,113 @@ export interface AgentDefinition {
 	source: string;
 }
 
-function collectMarkdownFiles(dir: string, out: string[] = []): string[] {
+/** Visit every `.md` file under `dir`, at any depth, with its stats. */
+function walkMarkdownFiles(dir: string, visit: (path: string, stats: Stats) => void): void {
 	let entries: string[];
 	try {
 		entries = readdirSync(dir);
 	} catch {
-		return out; // missing or unreadable directory: nothing to discover
+		return; // missing or unreadable directory: nothing to discover
 	}
 	for (const entry of entries) {
 		const full = join(dir, entry);
 		// A dangling symlink or an unreadable entry must not take the whole
 		// catalog (and every Agent call) down with it — skip it (review L1).
-		let isDirectory: boolean;
+		let stats: Stats;
 		try {
-			isDirectory = statSync(full).isDirectory();
+			stats = statSync(full);
 		} catch {
 			continue;
 		}
-		if (isDirectory) {
-			collectMarkdownFiles(full, out);
+		if (stats.isDirectory()) {
+			walkMarkdownFiles(full, visit);
 		} else if (entry.endsWith(".md")) {
-			out.push(full);
+			visit(full, stats);
 		}
 	}
+}
+
+function collectMarkdownFiles(dir: string): string[] {
+	const out: string[] = [];
+	walkMarkdownFiles(dir, (path) => out.push(path));
 	return out;
 }
 
+/**
+ * A stamp of the agent files `discoverAgents` would read from these sources:
+ * each source, then each file's path, times and size. It changes when a file
+ * is added, removed, renamed or written, so a catalog built from the sources
+ * can be reused while the stamp holds, without reading or parsing any file.
+ */
+export function agentSourcesStamp(sources: Array<string | AgentSource>): string {
+	const parts: string[] = [];
+	for (const source of sources) {
+		const { dir, namespace } = typeof source === "string" ? { dir: source, namespace: undefined } : source;
+		parts.push(`${namespace ?? ""}@${dir}`);
+		walkMarkdownFiles(dir, (path, stats) => parts.push(`${path}:${stats.mtimeMs}:${stats.ctimeMs}:${stats.size}`));
+	}
+	return parts.join("\n");
+}
+
+/**
+ * Split one frontmatter tool string the way Claude Code does: on commas and
+ * spaces, except inside a rule's parentheses, so `Bash(git push:*), Write` is
+ * two entries and `Agent(worker, researcher)` is one.
+ */
+function splitToolSpecs(text: string): string[] {
+	const specs: string[] = [];
+	let current = "";
+	let inParens = false;
+	for (const char of text) {
+		if (char === "(") inParens = true;
+		else if (char === ")") inParens = false;
+		else if ((char === "," || /\s/.test(char)) && !inParens) {
+			if (current.trim()) specs.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	if (current.trim()) specs.push(current.trim());
+	return specs;
+}
+
+/**
+ * The tool a spec names. A rule-shaped entry (`Bash(git push:*)`) names its
+ * whole tool: Claude Code grants or removes the entire tool for it in an agent
+ * file, never only the rule's commands, so `disallowedTools: Bash(git push:*)`
+ * removes `bash`. Anything that is not `Name(…)` is taken as a plain name.
+ */
+function specToolName(spec: string): string {
+	const open = spec.indexOf("(");
+	return open > 0 && spec.endsWith(")") ? spec.slice(0, open) : spec;
+}
+
 /**
  * A frontmatter tool list (comma string or YAML list) as pi tool names: Claude
  * Code spellings map through the alias table (`Glob` → `find`, `WebFetch` →
  * `web_fetch`, `Task` → `Agent`, …), pi names and `mcp__*` pass through,
- * duplicates collapse. Exported for tests.
+ * rule-shaped entries reduce to their tool, duplicates collapse. A list that
+ * contains `*` returns `["*"]`; `parseAgentFile` reads that as "all tools".
+ * Exported for tests.
  */
 export function parseToolList(raw: unknown): string[] | undefined {
-	const list =
-		typeof raw === "string"
-			? raw
-					.split(",")
-					.map((t) => t.trim())
-					.filter(Boolean)
-			: Array.isArray(raw)
-				? raw.filter((t): t is string => typeof t === "string").map((t) => t.trim()).filter(Boolean)
-				: undefined;
-	if (!list || list.length === 0) return undefined;
-	return [...new Set(list.map(normalizeToolName))];
+	const entries =
+		typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw.filter((t): t is string => typeof t === "string") : undefined;
+	const specs = entries?.flatMap(splitToolSpecs);
+	if (!specs || specs.length === 0) return undefined;
+	if (specs.includes("*")) return ["*"];
+	return [...new Set(specs.map((spec) => normalizeToolName(specToolName(spec))))];
+}
+
+/**
+ * An agent file's `tools` allowlist. Claude Code reads a list containing `*`
+ * as "all tools", the same as no list; kept as `["*"]` the allowlist matched
+ * no tool and every spawn failed.
+ */
+function parseAllowlist(raw: unknown): string[] | undefined {
+	const tools = parseToolList(raw);
+	return tools?.includes("*") ? undefined : tools;
 }
 
 export function parseAgentFile(path: string, content: string): AgentDefinition | undefined {
@@ -98,7 +163,7 @@ export function parseAgentFile(path: string, content: string): AgentDefinition |
 	return {
 		name,
 		description: typeof fm.description === "string" ? fm.description : "",
-		tools: parseToolList(fm.tools),
+		tools: parseAllowlist(fm.tools),
 		excludeTools: disallowed.length > 0 ? [...new Set(disallowed)] : undefined,
 		// "inherit" is Claude Code's way of saying "use the session model".
 		model: typeof fm.model === "string" && fm.model !== "inherit" ? fm.model : undefined,
@@ -109,11 +174,25 @@ export function parseAgentFile(path: string, content: string): AgentDefinition |
 
 /**
  * Lowest to highest precedence: the catalog bundled with this package, then the
- * user's `~/.claude/agents`, then the project's `.claude/agents`. A user or
- * project definition with the same name replaces a bundled one.
+ * user's `~/.claude/agents`, then the project's `.claude/agents` (`~/.onecode`
+ * and `.onecode` in independent mode, lib/config-mode.ts). A user or project
+ * definition with the same name replaces a bundled one.
  */
 export function agentDirs(cwd: string, home: string, bundled?: string): string[] {
-	return [...(bundled ? [bundled] : []), join(claudeUserDir(home), "agents"), join(cwd, ".claude", "agents")];
+	return [...(bundled ? [bundled] : []), join(userConfigDir(home), "agents"), join(projectConfigDir(cwd), "agents")];
+}
+
+/** The agent files the package ships (general-purpose, explore, plan, …). */
+export const BUNDLED_AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
+
+/**
+ * Every agent-file source in rank order, as the Agent tool loads them:
+ * bundled, then plugin agents, then the user and project folders. Workflows
+ * resolve `agentType` from the same list (the code-defined guide is the Agent
+ * tool's alone).
+ */
+export function agentFileSources(cwd: string, home: string, pluginAgentDirs: readonly (string | AgentSource)[]): Array<string | AgentSource> {
+	return [BUNDLED_AGENTS_DIR, ...pluginAgentDirs, ...agentDirs(cwd, home)];
 }
 
 /** A directory whose agents are exposed as `<namespace>:<name>` (plugins). */
@@ -122,10 +201,19 @@ export interface AgentSource {
 	namespace?: string;
 }
 
+/** Agents defined in code (`one-code-guide`), taken as they are: never copied, so a lazy prompt stays lazy. */
+export interface CodeAgents {
+	agents: readonly AgentDefinition[];
+}
+
 /** Later sources override earlier ones on name collisions. */
-export function discoverAgents(sources: Array<string | AgentSource>): AgentDefinition[] {
+export function discoverAgents(sources: Array<string | AgentSource | CodeAgents>): AgentDefinition[] {
 	const byName = new Map<string, AgentDefinition>();
 	for (const source of sources) {
+		if (typeof source !== "string" && "agents" in source) {
+			for (const agent of source.agents) byName.set(agent.name, agent);
+			continue;
+		}
 		const { dir, namespace } = typeof source === "string" ? { dir: source, namespace: undefined } : source;
 		for (const file of collectMarkdownFiles(dir)) {
 			try {
@@ -145,11 +233,12 @@ export function discoverAgents(sources: Array<string | AgentSource>): AgentDefin
  * Tools a child cannot function without, re-added when an agent file's `tools`
  * allowlist omits them: pi's allowlist filters built-ins, extension tools AND
  * injected custom tools by exact name, so a CC-style `tools: Read, Grep` would
- * otherwise also strip the child's report channel (`SendMessage` → main), its
- * deferred-tool loader and the runtime's `structured_output`. Claude Code's
- * allowlist never strips its own plumbing either.
+ * otherwise also strip the child's report channels (`SendMessage` → main and
+ * the final `SubagentHandback`), its deferred-tool loader and the runtime's
+ * `structured_output`. Claude Code's allowlist never strips its own plumbing
+ * either.
  */
-const ALLOWLIST_ESSENTIALS = ["SendMessage", "tool_search", "structured_output"];
+const ALLOWLIST_ESSENTIALS = ["SendMessage", SUBAGENT_HANDBACK, "tool_search", "structured_output"];
 
 /** Apply an agent's allowlist to pi's `tools` option, keeping the essentials. */
 export function childToolAllowlist(tools: string[] | undefined): string[] | undefined {
@@ -168,3 +257,29 @@ export function usableAllowlistedTools(registered: string[], allowlist: string[]
 	const available = new Set(registered);
 	return allowlist.filter((name) => available.has(name));
 }
+
+/**
+ * pi's session tool options for a named agent: its allowlist with the child's
+ * plumbing re-added, and its denylist. The one builder both runners use (the
+ * subagent runner and the workflow runner), so an agent file means the same
+ * thing wherever it runs; the workflow runner once passed the raw allowlist and
+ * no denylist, which stripped `structured_output` and ignored `disallowedTools`
+ * (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 H2, H3).
+ */
+export function agentToolOptions(agent: AgentDefinition | undefined): { tools?: string[]; excludeTools?: string[] } {
+	return { tools: childToolAllowlist(agent?.tools), excludeTools: agent?.excludeTools };
+}
+
+/**
+ * The fail-loud error for an agent whose `tools` allowlist matched no tool the
+ * session registered, or undefined when the agent is usable. pi drops unknown
+ * names silently, so without this the agent would run with no tools and
+ * "complete" with an excuse.
+ */
+export function unusableAllowlistError(agent: AgentDefinition | undefined, registered: string[]): string | undefined {
+	if (!agent?.tools || usableAllowlistedTools(registered, agent.tools).length > 0) return undefined;
+	return (
+		`Agent "${agent.name}" lists tools (${agent.tools.join(", ")}) that match no available tool. ` +
+		"Use Claude Code names (Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, NotebookEdit, Skill, Agent, SendMessage) or pi names (read, edit, write, bash, grep, find, ls, …) in the agent file's `tools` list."
+	);
+}

package/extensions/subagents/default-model.ts

@@ -10,15 +10,14 @@
  *   not read: both project files live in the repository, and a checked-in `env`
  *   block must not get to pick which provider receives subagent tasks — the
  *   same containment rule as `autoMode` config.
- * - `subagentModel` — One Code's own top-level setting, same shape as
- *   `autoMode.classifierModel`. Wins over the env var when both are set,
+ * - `subagentModel` — One Code's own top-level setting. Wins over the env var when both are set,
  *   because it is the more specific statement of intent. It is One Code's key,
  *   not Claude Code's: it is written to and read from `~/.onecode/settings.json`
  *   (+ managed settings), never from `~/.claude`, where an old One Code build may
  *   have left a stale value the current session cannot reach. Claude Code's own
  *   `CLAUDE_CODE_SUBAGENT_MODEL` env block is still honoured from `~/.claude`
  *   (that key *is* Claude Code's). See "Own state, borrowed config" in
- *   docs/decisions/memory-state.md.
+ *   working-docs/decisions/memory-state.md.
  *
  * The env var additionally applies only to Claude-family sessions (see
  * `applicableSubagentDefault`): it is Claude Code's knob, and its typical

package/extensions/subagents/delegation-steer.ts

@@ -16,8 +16,8 @@
  */
 
 export const DELEGATION_STEER = [
-	'Delegation policy: when a request requires reading or searching MANY files (a codebase overview, "find every place where…", a consistency audit, exploring unfamiliar code), do NOT sweep the files yourself.',
-	'Make ONE Agent tool call with subagent_type: "explore" and the complete question as the task. The agent searches in its own separate context and returns just the answer; reading file after file yourself fills your context and degrades your answer.',
-	"Search directly only for a single targeted lookup (one known file or symbol).",
-	"When the agent has answered, report its answer and move on — do not re-read the files it already covered.",
+	"Delegation policy: when a request requires reading MANY files (a codebase overview, how a feature works across modules, exploring unfamiliar code), do NOT sweep the files yourself.",
+	'Make one Agent tool call per independent question, with subagent_type: "explore" and the complete question as the task; for several independent questions, issue those calls together in one message. The agent searches in its own separate context and returns just the answer; reading file after file yourself fills your context and degrades your answer.',
+	"Search directly for a single targeted lookup: one known file or symbol, or a word one grep can find everywhere.",
+	"When the agent has answered, report its answer and move on — do not re-read the files it already covered, except one you are about to edit (an edit needs a read first).",
 ].join("\n");

package/extensions/subagents/fork-cache.ts

@@ -0,0 +1,82 @@
+/**
+ * The fork's side of reading the parent's prompt cache (decisions/caching.md,
+ * "A call that inherits the session's context reads the session's cache").
+ *
+ * A fork's own session builds its requests from its own system prompt, tools
+ * and reminder stack, so every fork re-read the parent's whole transcript
+ * uncached: on a parent near a 1M-token window, the whole window per fork.
+ * This inline extension, loaded last in a fork's session, sends the parent's
+ * last captured request instead, with the fork's own messages after it:
+ *
+ * - `context_with_system` (it runs after every `context` handler, so the
+ *   fork's reminder stack is already on the messages it drops) removes the
+ *   messages the capture carries, leaving pi to convert only the fork's tail;
+ * - `before_provider_request` (inline extensions load after the path ones, so
+ *   tool-search has already edited the body) replaces everything but the tail
+ *   with the captured body (`forkRequestPayload`);
+ * - `before_provider_headers` sends the parent's session-affinity headers, so a
+ *   gateway such as OpenRouter routes the fork to the host holding the cache.
+ *
+ * Both steps check the same thing first (the capture's model and its boundary
+ * message in this context); when either fails, or the tail leaves less than
+ * `MIN_REPLAY_OUTPUT_TOKENS` of the captured output room, the request goes out
+ * the ordinary way, whole, and uncached. That happens only for a fork that
+ * compacted its own history away, runs on another model, or has nearly
+ * filled the window.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFER_CHANNEL } from "../lib/deferred.ts";
+import { type AffinityModel, affinityHeaders, captureMatches, forkOutputRoom, forkRequestPayload, forkBaselineNames, MIN_REPLAY_OUTPUT_TOKENS, type RequestCapture, uncoveredMessages } from "../lib/request-replay.ts";
+
+type ModelRef = { api?: string; provider?: string; id?: string };
+
+/** The APIs whose fork splice (`forkRequestPayload`) handles the body's shape. */
+const SPLICED_FORK_APIS: ReadonlySet<string> = new Set(["anthropic-messages", "openai-completions", "openai-responses", "azure-openai-responses", "openai-codex-responses"]);
+
+export function forkCacheExtension(capture: RequestCapture) {
+	return (pi: ExtensionAPI) => {
+		// The fork advertises the parent's tools, where SendMessage is deferred
+		// (subagents/index.ts). Defer the fork's own SendMessage the same way, so a
+		// tool_search load reaches it: on a model without tool references the load
+		// appends it, and elsewhere the parent's compatible schema (to: "main")
+		// already declares it. Inline extensions load after tool-search.
+		pi.events.emit(DEFER_CHANNEL, { name: "SendMessage", keywords: ["message", "main", "report", "progress"] });
+		/** Set by the context step for the request it shaped; the payload step splices only then. */
+		let shaped = false;
+		/** The tool names of the fork's first request: anything added later was loaded during the run. */
+		let baseline: Set<string> | undefined;
+
+		pi.on("context_with_system", (event, ctx) => {
+			shaped = false;
+			const covers = capture.covers;
+			// Bedrock and Google nest their tools and need joined turns and the
+			// fork's own abort signal, which the fork splice does not handle: their
+			// forks go out whole instead.
+			if (!covers || !SPLICED_FORK_APIS.has(capture.api) || !captureMatches(capture, ctx.model as ModelRef | undefined)) return undefined;
+			const tail = uncoveredMessages(event.messages as { role: string; timestamp?: number }[], covers);
+			if (!tail) return undefined;
+			// Too little output room left after the prefix: send the fork whole
+			// (pi's overflow handling then compacts it) rather than a splice the
+			// window cannot hold. The messages' JSON overstates the wire tail.
+			const room = forkOutputRoom(capture, tail.filter((message) => message.role !== "system"));
+			if (room !== undefined && room < MIN_REPLAY_OUTPUT_TOKENS) return undefined;
+			shaped = true;
+			return { messages: tail as typeof event.messages };
+		});
+
+		// Route to the parent's host: a gateway picks it by the session-affinity
+		// headers, and the parent's cache lives there. Harmless on a whole request.
+		pi.on("before_provider_headers", (event, ctx) => {
+			if (!capture.sessionId || !captureMatches(capture, ctx.model as ModelRef | undefined)) return;
+			Object.assign(event.headers, affinityHeaders(ctx.model as AffinityModel, capture.sessionId));
+		});
+
+		pi.on("before_provider_request", (event, ctx) => {
+			if (!shaped || !captureMatches(capture, ctx.model as ModelRef | undefined)) return undefined;
+			shaped = false;
+			const payload = event.payload as Record<string, unknown>;
+			baseline ??= forkBaselineNames(payload, capture.api);
+			return forkRequestPayload(capture, payload, baseline);
+		});
+	};
+}