one-code-extension 0.1.4 → 0.3.0

package/extensions/hooks/protocol.ts

@@ -5,6 +5,19 @@
  * fail-closed choices are One Code's own (see docs/decisions.md).
  */
 
+import { isAppendedReminderText } from "../lib/reminders.ts";
+
+/** The contiguous run of reminder/countdown blocks at the tail of a tool result (review M3). */
+function trailingReminderBlocks<T extends { type: string }>(content: readonly T[]): T[] {
+	let start = content.length;
+	for (let i = content.length - 1; i >= 0; i--) {
+		const block = content[i] as { type: string; text?: unknown };
+		if (block.type === "text" && typeof block.text === "string" && isAppendedReminderText(block.text)) start = i;
+		else break;
+	}
+	return content.slice(start);
+}
+
 export type CcHookEvent =
 	| "PreToolUse"
 	| "PostToolUse"
@@ -39,7 +52,16 @@ export interface HookStdinPayload {
 	prompt?: string;
 	stop_hook_active?: boolean;
 	trigger?: "manual" | "auto";
+	/** PreCompact: the `/compact <instructions>` text, empty when none (Claude Code sends the string as is). */
+	custom_instructions?: string;
+	/** PostCompact: the summary that replaced the compacted span. */
+	compact_summary?: string;
 	source?: string;
+	/** SessionEnd: why the session ended — clear | logout | prompt_input_exit | other (Claude Code's values). */
+	reason?: string;
+	/** Set when the call is a subagent's (Claude Code: hooks tell a child's call from the main thread's by its presence). */
+	agent_id?: string;
+	agent_type?: string;
 }
 
 export interface HookEnvelope {
@@ -149,3 +171,39 @@ export function interpretHookResult(event: CcHookEvent, run: FinishedRun): HookO
 	if (envelope.systemMessage?.trim()) outcome.systemMessage = envelope.systemMessage.trim();
 	return outcome;
 }
+
+/** A text block as pi's tool results carry it; what PostToolUse assembly adds. */
+interface TextBlock {
+	type: "text";
+	text: string;
+}
+
+/**
+ * A tool result's content after PostToolUse hooks spoke, or undefined when no
+ * hook changed anything. Shared by the parent's `tool_result` handler and the
+ * child hook gate so a subagent's results are assembled exactly like the
+ * parent's: an `updatedToolResult` replaces the content (a non-string is
+ * JSON-encoded), a block's reason is put in front — the tool already ran, so
+ * the objection is delivered in the result the model reads, the error flag left
+ * as the tool set it (a successful write marked as an error invites a redo) —
+ * and `additionalContext` (already framed by the caller) goes behind.
+ */
+export function applyPostToolUseOutcome<T extends { type: string }>(
+	content: readonly T[],
+	outcome: Pick<HookOutcome, "block" | "updatedToolResult" | "additionalContext">,
+): Array<T | TextBlock> | undefined {
+	if (!outcome.block && outcome.updatedToolResult === undefined && !outcome.additionalContext) return undefined;
+	let result: Array<T | TextBlock> = [...content];
+	if (outcome.updatedToolResult !== undefined) {
+		const replacement = outcome.updatedToolResult;
+		// The reminder queue may already have appended one-shots and the
+		// `<total_tokens>` countdown onto this result (system-reminder runs its
+		// tool_result hook before ours). Replacing the content must not drop
+		// them, so keep the trailing run of reminder blocks (review M3).
+		const reminderTail = trailingReminderBlocks(content);
+		result = [{ type: "text", text: typeof replacement === "string" ? replacement : JSON.stringify(replacement) }, ...reminderTail];
+	}
+	if (outcome.block) result = [{ type: "text", text: `PostToolUse hook: ${outcome.block.reason}` }, ...result];
+	if (outcome.additionalContext) result = [...result, { type: "text", text: outcome.additionalContext }];
+	return result;
+}

package/extensions/hooks/subagent-bridge.ts

@@ -0,0 +1,77 @@
+/**
+ * The parent→child hook bridge.
+ *
+ * In-process subagent sessions get a `noExtensions` loader, so the `hooks`
+ * extension never loads inside them, and until 2026-09-05 a user's
+ * PreToolUse/PostToolUse hooks — the Claude Code-compatible way to block a
+ * command class, rewrite inputs, run a formatter, inject context — applied to
+ * the main model's tool calls and to nothing a child did
+ * (STEERING-REVIEW-2026-09-05 M4). Claude Code runs hooks inside subagents
+ * (`tools/AgentTool/runAgent.ts` passes the same `canUseTool` pipeline; hook
+ * payloads carry `agent_id`/`agent_type`).
+ *
+ * Same transport as the permission bridge (`permissions/subagent-gate.ts`):
+ * the parent's `hooks` extension publishes a closure pair on this channel, the
+ * spawning extension captures it and threads it into the child loader, whose
+ * `hook-gate` inline extension calls it from the child's `tool_call` and
+ * `tool_result` handlers. Dispatch happens parent-side — the hook settings,
+ * project-hook consent, debug logging and the trust store stay in one place —
+ * with the payload naming the child (its session id as `agent_id`, the agent
+ * type, its cwd). Only the tool hooks are bridged: UserPromptSubmit, Stop,
+ * SessionStart/End and the compaction hooks are main-conversation events
+ * (Claude Code fires SubagentStop for a child's end, which One Code does not
+ * implement yet).
+ */
+
+import { type BridgeWatchApi, watchBridge } from "../lib/bridge-watch.ts";
+
+export const SUBAGENT_HOOK_CHANNEL = "one-code:subagent-hook-bridge";
+
+/** One child tool call, as the child's `tool_call` handler sees it. */
+export interface ChildHookCall {
+	toolName: string;
+	input: Record<string, unknown>;
+	/** The child's runtime cwd (a worktree, if isolated). */
+	cwd: string;
+	/** The child session's id — becomes the payload's `session_id` and `agent_id`. */
+	sessionId?: string;
+	/** The child's session file, if persisted (payload `transcript_path`). */
+	transcriptPath?: string;
+	/** The agent type (`explore`, `general-purpose`, …), set by the runner; undefined for a fork. */
+	agentType?: string;
+}
+
+/** The child's tool result, for PostToolUse. */
+export interface ChildHookResult extends ChildHookCall {
+	content: unknown;
+	isError: boolean;
+}
+
+/** What the parent's PreToolUse hooks decided; fields absent when no hook spoke. */
+export interface ChildPreToolUseOutcome {
+	block?: { reason: string };
+	/** Already translated back to the tool's native parameter names. */
+	updatedInput?: Record<string, unknown>;
+	additionalContext?: string;
+}
+
+/** What the parent's PostToolUse hooks decided. */
+export interface ChildPostToolUseOutcome {
+	block?: { reason: string };
+	updatedToolResult?: unknown;
+	additionalContext?: string;
+}
+
+export interface HookBridge {
+	preToolUse(call: ChildHookCall): Promise<ChildPreToolUseOutcome>;
+	postToolUse(result: ChildHookResult): Promise<ChildPostToolUseOutcome>;
+}
+
+export interface SubagentHookPayload {
+	bridge: HookBridge;
+}
+
+/** A lazy getter for the latest published hook bridge (`lib/bridge-watch.ts`); undefined until the hooks extension publishes. */
+export function watchHookBridge(pi: BridgeWatchApi): () => HookBridge | undefined {
+	return watchBridge(pi, SUBAGENT_HOOK_CHANNEL, (data) => (data as SubagentHookPayload | undefined)?.bridge);
+}

package/extensions/hooks/trust.ts

@@ -2,7 +2,7 @@
  * Project-hook consent. Hooks in a repo's `.claude/settings.json` are
  * arbitrary code execution the moment the repo is opened, so they run only
  * after the user approves them — once per configuration: approval is keyed to
- * a hash of the project+local hook config and persisted under `~/.one-code`, so
+ * a hash of the project+local hook config and persisted under `~/.onecode`, so
  * it survives restarts but any change to the hooks re-prompts (Claude Code's
  * own hooks-review behaviour). User, managed, and plugin hooks never prompt
  * (installing a plugin was the consent).
@@ -18,6 +18,7 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { boundConsentItems } from "../lib/consent-preview.ts";
 import { oneCodeStateDir } from "../lib/paths.ts";
 import type { HooksSource } from "./settings.ts";
 
@@ -84,9 +85,12 @@ export function describeProjectHooks(projectSources: HooksSource[]): string {
 			}
 		}
 	}
-	const shown = commands.slice(0, 5).map((cmd) => (cmd.length > 80 ? `${cmd.slice(0, 80)}…` : cmd));
-	const more = commands.length > shown.length ? `\n… and ${commands.length - shown.length} more` : "";
-	return `${commands.length} command hook(s):\n${shown.join("\n")}${more}`;
+	// Every command in full: a truncated command hides its tail, which is exactly
+	// where a padded `echo ok …; curl … | sh` would put the malicious part
+	// (review M5). But bound the total so a repo with hundreds of hooks (or one
+	// megabyte-long command) cannot flood the modal — past the budget the user is
+	// pointed at the file itself.
+	return `${commands.length} command hook(s):\n${boundConsentItems(commands, "review .claude/settings.json before approving")}`;
 }
 
 export interface TrustDecisionDeps {
@@ -94,6 +98,12 @@ export interface TrustDecisionDeps {
 	confirm: (title: string, message: string) => Promise<boolean | undefined>;
 	notify: (message: string) => void;
 	storePath?: string;
+	/**
+	 * Answer from the remembered/stored approval only: neither prompt nor record
+	 * a decision. For a dispatch at session shutdown — recording "declined" there
+	 * would silence the consent prompt in the session that replaces it.
+	 */
+	noPrompt?: boolean;
 }
 
 /** Process-lifetime memory of declined/approved hashes per project, so a dispatch storm asks once. */
@@ -120,6 +130,7 @@ export async function projectHooksApproved(
 		sessionDecisions.set(key, true);
 		return true;
 	}
+	if (deps.noPrompt) return false;
 	if (!deps.hasUI) {
 		sessionDecisions.set(key, false);
 		deps.notify("Project hooks skipped: not yet approved and no UI to ask (user/managed hooks still run).");

package/extensions/init/index.ts

@@ -0,0 +1,26 @@
+/**
+ * init extension — Claude Code's `/init`.
+ *
+ * `/init` scans the repo and writes a concise CLAUDE.md for future sessions. It
+ * is a prompt template, not procedural code: the handler submits INIT_PROMPT as
+ * a user turn (pi.sendUserMessage) and the model does the work with the ordinary
+ * tool set — subagent survey, ask_user_question, write. This mirrors how Claude
+ * Code's `/init` is just a canned prompt.
+ *
+ * pi has no built-in `/init`, so a Claude Code user typing it would otherwise
+ * have the word go to the model as a chat message.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { INIT_PROMPT } from "./prompt.ts";
+
+export default function initExtension(pi: ExtensionAPI) {
+	pi.registerCommand("init", {
+		description: "Analyze the codebase and set up a CLAUDE.md for future sessions",
+		// sendUserMessage always triggers a turn and returns void; the async
+		// handler satisfies RegisteredCommand's Promise<void> contract.
+		handler: async () => {
+			pi.sendUserMessage(INIT_PROMPT, { deliverAs: "followUp" });
+		},
+	});
+}

package/extensions/init/prompt.ts

@@ -0,0 +1,40 @@
+/**
+ * The `/init` prompt — adapted from Claude Code's `/init`, kept provider-neutral
+ * (One Code writes a CLAUDE.md that any Claude Code-compatible agent reads) and
+ * self-contained (no dependency on CC-internal skills like `update-config`).
+ *
+ * Submitted verbatim as a user turn by extensions/init/index.ts; the model does
+ * the work with the normal tool set (subagent survey, ask_user_question, write).
+ */
+export const INIT_PROMPT = `Analyze this codebase and set up a concise CLAUDE.md at the repository root, to be loaded into every future session working here. Keep it minimal — every line must earn its place: include only what an agent would get wrong or waste time rediscovering without it.
+
+## 1. Survey the codebase
+Launch an Explore subagent (or read directly if the repo is small) to gather:
+- Build, test, and lint commands — especially non-standard scripts, flags, or how to run a *single* test.
+- Languages, frameworks, package manager, and whether this is a monorepo/multi-module or single project.
+- High-level architecture that requires reading several files to grasp (the "big picture", not a file listing).
+- Non-obvious gotchas, required env vars, or workflow quirks.
+- Existing AI-tool config to fold in: an existing CLAUDE.md, AGENTS.md, .cursor/rules or .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules — and the important parts of README.md.
+
+## 2. Fill the gaps
+Use ask_user_question only for things the code cannot answer — branch/PR conventions, required setup, testing quirks, communication preferences. Skip anything already obvious from manifests or the README. Do not mark options as "recommended": this is how their team works, not best practices.
+
+## 3. Write CLAUDE.md
+Prefix the file with:
+
+\`\`\`
+# CLAUDE.md
+
+This file gives guidance to AI coding agents (Claude Code and compatible tools) working in this repository.
+\`\`\`
+
+Include: build/test/lint commands an agent can't guess; code-style rules that DIFFER from language defaults; testing instructions and quirks; repo etiquette (branch naming, PR/commit conventions); required env vars or setup; non-obvious gotchas and architectural decisions; the important parts of any existing AI-tool config.
+
+Exclude: file-by-file structure or component lists (discoverable by reading); standard language conventions; generic advice ("write clean code", "handle errors"); long references or API docs (link them with \`@path/to/file\` import syntax instead of inlining); anything that changes frequently (reference the source with \`@path\`).
+
+Be specific — "Use 2-space indentation in TypeScript" beats "format code properly." Do not repeat yourself and do not invent sections like "Common Development Tasks" — only include what you actually found.
+
+If a CLAUDE.md already exists: read it, propose concrete improvements as diffs, and explain each. Do NOT silently overwrite. For projects with distinct subdirectories (monorepos), mention that per-directory CLAUDE.md files are loaded automatically when working in those directories, and offer to create them.
+
+## 4. Recap
+Summarize which file(s) you wrote and the key points in each. Remind the user this is a starting point to review and tweak, and that they can run \`/init\` again anytime to re-scan.`;

package/extensions/interrupted/index.ts

@@ -0,0 +1,35 @@
+/**
+ * interrupted extension — Claude Code's "Interrupted · What should One Code do
+ * instead?" line, shown when the user aborts a turn (Esc).
+ *
+ * On agent_end, if the turn's last assistant message was aborted by the user
+ * (findings: pi marks it `stopReason: "aborted"`, or `"error"` on a run whose
+ * signal is aborted when the abort reached the provider call —
+ * `lib/interrupt.ts`), a display-only session entry
+ * is appended (`appendEntry` — not part of the LLM context, so the model never
+ * sees the note about its own interruption), rendered dim to match CC's
+ * InterruptedByUser component. The paired turn-duration line suppresses itself
+ * on the same signal, so an interrupted turn shows this note in place of the
+ * "Cooked for …" line — CC's behaviour (its turn-duration render is gated on
+ * `!aborted`).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { wasInterrupted } from "../lib/interrupt.ts";
+import { linesComponent, safeThemePaint } from "../lib/tui-render.ts";
+import { INTERRUPTED_TEXT } from "./line.ts";
+
+const ENTRY_TYPE = "one-code:interrupted";
+
+export default function interruptedExtension(pi: ExtensionAPI) {
+	pi.registerEntryRenderer(ENTRY_TYPE, (_entry, _options, theme) => {
+		const paint = safeThemePaint(theme);
+		return linesComponent(() => [paint("dim", INTERRUPTED_TEXT)]);
+	});
+
+	pi.on("agent_end", (event, ctx) => {
+		if (!ctx.hasUI) return;
+		if (!wasInterrupted(event.messages, ctx.signal?.aborted)) return;
+		pi.appendEntry(ENTRY_TYPE);
+	});
+}

package/extensions/interrupted/line.ts

@@ -0,0 +1,9 @@
+/**
+ * Pure pieces of Claude Code's InterruptedByUser line — the dim
+ * "Interrupted · What should Claude do instead?" note CC drops in place of the
+ * aborted assistant message when the user hits Esc. Rebranded to One Code; no
+ * leading mark, matching CC (its InterruptedByUser renders bare dim text).
+ */
+
+/** The dim interrupted note, One Code's wording of CC's InterruptedByUser. */
+export const INTERRUPTED_TEXT = "Interrupted · What should One Code do instead?";

package/extensions/lib/abort.ts

@@ -0,0 +1,15 @@
+/**
+ * Run `onAbort` when `signal` aborts — at once if it already has — and return
+ * the remover to call once the awaited work is over, so the listener does not
+ * outlive it. The idiom (check `aborted` first, `{ once: true }`, remove in
+ * `finally`) was hand-rolled at every tool that awaits something abortable.
+ */
+export function whenAborted(signal: AbortSignal | undefined, onAbort: () => void): () => void {
+	if (!signal) return () => {};
+	if (signal.aborted) {
+		onAbort();
+		return () => {};
+	}
+	signal.addEventListener("abort", onAbort, { once: true });
+	return () => signal.removeEventListener("abort", onAbort);
+}

package/extensions/lib/agent-loader.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared in-process agent wiring: the one place that builds a pi
+ * `ModelRuntime` and a `DefaultResourceLoader` for an agent session that runs
+ * inside this process. Used by both the workflow runner
+ * (`extensions/workflow/agent-session.ts`) and the subagent runner.
+ *
+ * Loaders are built with `noExtensions: true` so a child never auto-discovers
+ * the whole One Code package (which would recurse into the subagent/workflow
+ * tools and re-init UI/MCP/LSP). Fidelity is added back deliberately:
+ * `permissionGateFactory` is always attached (a child has no permission
+ * extension otherwise); callers pass `extraFactories` (e.g. claude-context,
+ * file-tracker) and `extraExtensionPaths` (curated stateless tool providers)
+ * for what they need. `extensionFactories` and `additionalExtensionPaths` are
+ * both loaded even under `noExtensions`.
+ */
+
+import os from "node:os";
+import { join } from "node:path";
+import {
+	type AgentSession,
+	type CreateAgentSessionOptions,
+	createAgentSession,
+	DefaultResourceLoader,
+	type ExtensionError,
+	type InlineExtension,
+	ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { HookBridge } from "../hooks/subagent-bridge.ts";
+import type { PermissionBridge } from "../permissions/subagent-gate.ts";
+import { withShortCacheRetention } from "./cache-retention.ts";
+import { hookGateFactory } from "./hook-gate.ts";
+import { permissionGateFactory } from "./permission-gate.ts";
+import { worktreeGuardFactory } from "./worktree-isolation.ts";
+
+/** The last assistant message's text (the value an agent run returns). */
+export function finalAssistantText(messages: AgentMessage[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i];
+		if (message.role !== "assistant") continue;
+		const content = (message as { content: unknown }).content;
+		if (typeof content === "string") return content;
+		if (Array.isArray(content)) {
+			const text = content
+				.filter((b): b is { type: "text"; text: string } => (b as { type?: string }).type === "text")
+				.map((b) => b.text)
+				.join("");
+			if (text.trim()) return text;
+		}
+	}
+	return "";
+}
+
+/**
+ * The canonical model/auth runtime, shared across all agents in a run (building
+ * one per agent is expensive). Children are tight loops, so it answers every
+ * auth with the provider's 5-minute cache TTL rather than the main session's
+ * 1-hour one (lib/cache-retention.ts).
+ */
+export async function createSharedModelRuntime(agentDir: string): Promise<ModelRuntime> {
+	const runtime = await ModelRuntime.create({
+		authPath: join(agentDir, "auth.json"),
+		modelsPath: join(agentDir, "models.json"),
+	});
+	return withShortCacheRetention(runtime);
+}
+
+export interface AgentLoaderOptions {
+	cwd: string;
+	agentDir: string;
+	/** Per-agent system prompt (an agent's own prompt, or a fork's inherited one). */
+	systemPrompt?: string;
+	/** Inline factories to attach alongside the permission gate (claude-context, file-tracker, injected tools). */
+	extraFactories?: InlineExtension[];
+	/** CLI-style extension entrypoints to load (curated stateless tool providers). Loaded even under noExtensions. */
+	extraExtensionPaths?: string[];
+	/** Tool names the permission gate must never gate (runtime-injected tools). */
+	neverGate?: Set<string>;
+	/**
+	 * The parent permissions extension's decision closure. When present, the child's
+	 * permission gate routes every tool call through it (mode inheritance, classifier,
+	 * prompts bubbled to the user); when absent (headless runs with no publishing
+	 * parent), the gate uses its fail-closed local fallback. A getter so it can be
+	 * read lazily — the bridge may not be published yet when the loader is built.
+	 */
+	getPermissionBridge?: () => PermissionBridge | undefined;
+	/**
+	 * The parent hooks extension's bridge (hooks/subagent-bridge.ts). When present,
+	 * the user's PreToolUse/PostToolUse hooks run for the child's tool calls, before
+	 * the guards and the permission gate (Claude Code runs hooks inside subagents).
+	 * A getter, read per call, like the permission bridge.
+	 */
+	getHookBridge?: () => HookBridge | undefined;
+	/** Resolves a child session id to its agent type, for the hook payload's `agent_type`. */
+	agentTypeOf?: (sessionId: string | undefined) => string | undefined;
+	/**
+	 * Stop pi from appending CLAUDE.md/AGENTS.md to the child's system prompt. Set
+	 * by a caller whose child session loads the `claude-context` extension, which
+	 * injects the `# claudeMd` reminder itself — otherwise the child carried the
+	 * project instructions twice (review S10).
+	 */
+	noContextFiles?: boolean;
+}
+
+/**
+ * Build and `reload()` a resource loader for an in-process agent session.
+ *
+ * ONE LOADER PER SESSION — never cache one across sessions. `AgentSession.dispose()`
+ * invalidates the loader's shared extension runtime, not just the session's
+ * runner: from then on every `pi.*` call from those extension instances throws
+ * the stale-ctx error and their `pi.events.on` subscriptions are gone, silently
+ * (pi's handler wrappers catch the throw, and an SDK session has no error
+ * listener). A cached loader therefore broke the second child of the same
+ * agent type, every SendMessage resume, every workflow agent after the first,
+ * and any sibling still running when one was disposed
+ * (LIFECYCLE-REVIEW-2026-09-06 H3, measured). A build costs ~3 ms once the
+ * extension modules are in jiti's cache, so there is nothing to save.
+ */
+export async function buildAgentLoader(options: AgentLoaderOptions): Promise<DefaultResourceLoader> {
+	const loader = new DefaultResourceLoader({
+		cwd: options.cwd,
+		agentDir: options.agentDir,
+		noExtensions: true,
+		...(options.noContextFiles ? { noContextFiles: true } : {}),
+		extensionFactories: [
+			// Order is load-bearing, mirroring the main session's extension order:
+			// hooks first (a hook's updatedInput must be what every guard judges),
+			// then the worktree git-isolation guard, then the permission gate.
+			...(options.getHookBridge ? [hookGateFactory(options.getHookBridge, { agentTypeOf: options.agentTypeOf, neverGate: options.neverGate })] : []),
+			worktreeGuardFactory(options.cwd),
+			permissionGateFactory(options.cwd, os.homedir(), options.neverGate, options.getPermissionBridge),
+			...(options.extraFactories ?? []),
+		],
+		...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),
+		...(options.extraExtensionPaths ? { additionalExtensionPaths: options.extraExtensionPaths } : {}),
+	});
+	await loader.reload();
+	return loader;
+}
+
+export interface OpenChildSessionOptions {
+	/**
+	 * The loader for this one session: options to build it, or one already built
+	 * by `buildAgentLoader` and never used by a session (see buildAgentLoader:
+	 * a disposed session leaves its loader dead).
+	 */
+	loader: AgentLoaderOptions | DefaultResourceLoader;
+	/** Everything else `createAgentSession` takes: cwd, model, tools, customTools, sessionManager, … */
+	session: Omit<CreateAgentSessionOptions, "resourceLoader" | "sessionStartEvent">;
+	/**
+	 * Why the child starts — a fresh run, a resume of a persisted child session,
+	 * or a fork of the parent transcript. Handlers read it the way they read pi's
+	 * own (file-tracker reconstructs its read state on `resume`/`fork`).
+	 */
+	startReason?: "startup" | "resume" | "fork";
+	/**
+	 * Where a child extension's handler errors go. An SDK session has no listener
+	 * of its own, so without this a throwing child handler leaves no trace.
+	 */
+	onError?: (error: ExtensionError) => void;
+}
+
+/**
+ * Build a fresh loader, create the session on it, and START it: `createAgentSession`
+ * never emits `session_start` — pi emits it only from `bindExtensions`, which the
+ * CLI modes call and an SDK caller must call itself (measured, LIFECYCLE-REVIEW
+ * H2; identical in 0.84.1 and 0.85.0). Until this helper existed no child ever
+ * saw the event, so every child ran without `# claudeMd` (claude-context), with
+ * its deferred tools eager and unlisted (tool-search), without its tier's search
+ * tools (search-tools) and without read-state reconstruction on a resume
+ * (file-tracker). Binding also runs the child's `resources_discover` pass, the
+ * way pi's own modes do.
+ */
+export async function openChildSession(options: OpenChildSessionOptions): Promise<AgentSession> {
+	const loader = options.loader instanceof DefaultResourceLoader ? options.loader : await buildAgentLoader(options.loader);
+	const { session } = await createAgentSession({
+		...options.session,
+		resourceLoader: loader,
+		sessionStartEvent: { type: "session_start", reason: options.startReason ?? "startup" },
+	});
+	await session.bindExtensions({ onError: options.onError });
+	return session;
+}

package/extensions/lib/anthropic-payload.ts

@@ -0,0 +1,15 @@
+/**
+ * Recognising an Anthropic Messages request body inside a `before_provider_request`
+ * payload (pure). Shared by context-management (clear_thinking), compaction
+ * (its replayed request) and tool-search (deferred tool definitions).
+ */
+
+/** Anthropic Messages API shape: `messages` + `max_tokens`, and not an OpenAI `input`. */
+export function looksLikeAnthropicRequest(payload: unknown): boolean {
+	if (!payload || typeof payload !== "object") return false;
+	const record = payload as Record<string, unknown>;
+	if (!Array.isArray(record.messages)) return false;
+	if ("input" in record) return false;
+	const model = typeof record.model === "string" ? record.model : "";
+	return model.includes("claude") || typeof record.max_tokens === "number";
+}

package/extensions/lib/atomic-write.ts

@@ -0,0 +1,56 @@
+/**
+ * Atomic JSON file writes (pure fs, no pi imports).
+ *
+ * Write to a temp sibling, then rename over the target — a reader never sees a
+ * partially written file, and a crash mid-write leaves the target untouched.
+ * Read-modify-write callers must spread over the parsed existing object so
+ * unknown fields round-trip (the files also belong to future versions and to
+ * users who hand-edit them).
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+let sequence = 0;
+
+export function writeJsonAtomic(path: string, data: unknown, options: { mode?: number } = {}): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp-${process.pid}-${++sequence}`;
+	writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, options.mode !== undefined ? { mode: options.mode } : undefined);
+	renameSync(tmp, path);
+}
+
+/** Parse a JSON file, or `undefined` when missing/unreadable/malformed. */
+export function readJsonFile<T>(path: string): T | undefined {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return undefined;
+	}
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * A `{key: boolean}` store file (the shape both override stores use): read
+ * drops non-boolean values, write is an atomic read-modify-write that
+ * round-trips unknown values.
+ */
+export function readBooleanMap(path: string): Record<string, boolean> {
+	const parsed = readJsonFile<Record<string, unknown>>(path);
+	if (!parsed || typeof parsed !== "object") return {};
+	const map: Record<string, boolean> = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (typeof value === "boolean") map[key] = value;
+	}
+	return map;
+}
+
+export function setBooleanMapEntry(path: string, key: string, value: boolean): void {
+	const existing = readJsonFile<Record<string, unknown>>(path) ?? {};
+	writeJsonAtomic(path, { ...existing, [key]: value });
+}

package/extensions/lib/bridge-watch.ts

@@ -0,0 +1,20 @@
+/**
+ * Subscribe to a bus channel on which a parent extension publishes a bridge
+ * (a closure pair a child session calls back into), and return a lazy getter
+ * for the latest one. The permission bridge and the hook bridge share this
+ * shape: the getter is threaded into child runners and yields `undefined` until
+ * the owning extension publishes at session start. Call once from an extension
+ * entry point — only they hold a `pi`.
+ */
+
+export interface BridgeWatchApi {
+	events: { on(channel: string, handler: (data: unknown) => void): void };
+}
+
+export function watchBridge<T>(pi: BridgeWatchApi, channel: string, pick: (data: unknown) => T | undefined): () => T | undefined {
+	let bridge: T | undefined;
+	pi.events.on(channel, (data) => {
+		bridge = pick(data);
+	});
+	return () => bridge;
+}