one-code-extension 0.1.0

package/docs/decisions.md

@@ -0,0 +1,148 @@
+# Decisions
+
+Why this package is shaped the way it is — the choices that aren't obvious from
+the code, and which community packages were adopted, rejected, or replaced and
+on what evidence. This file is the **index**: a one-liner per decision, grouped
+by area. Full rationale lives in `docs/decisions/`; follow the link on each
+entry. (Companion docs: [`findings.md`](findings.md) for how pi behaves,
+[`handoff.md`](handoff.md) for current state and what's left.)
+
+## Distribution & dependencies
+
+Full context: [`decisions/distribution.md`](decisions/distribution.md).
+
+- **[Two artifacts from one codebase: the app and the package](decisions/distribution.md#two-artifacts-from-one-codebase-the-app-and-the-package-2026-08-10-unreviewed)** *(unreviewed)* — npm `one-code` (bundled app: pinned pi, `~/.one-code` isolation via `PI_CODING_AGENT_DIR`, package-registration load shape, stdout rebranding, own update check) + npm `one-code-extension` (peer-dep pi package with a runtime tested-range warning); Homebrew tap delivers the app.
+- **[Distribution: pi package, not a wrapper binary](decisions/distribution.md#distribution-pi-package-not-a-wrapper-binary)** — *(partially superseded by the two-artifact model)* ship as an installable pi package because pi's rebranding resolves from pi's own `package.json`; a dependent can't rebrand it, and a package keeps upstream upgrades a version bump away.
+- **[Community packages: adopted where they work](decisions/distribution.md#community-packages-adopted-where-they-work)** — prefer ecosystem packages, but trial first: only `pi-ask-user` survived; `pi-subagents` was rejected (children SIGKILLed ~29 ms after spawn here).
+- **[Publish readiness (Phase 7)](decisions/distribution.md#publish-readiness-phase-7)** — what's done and what remains before `npm publish` (metadata, tarball, install-path verification).
+
+## Branding, themes & startup
+
+Full context: [`decisions/branding.md`](decisions/branding.md).
+
+- **[Branding without a fork](decisions/branding.md#branding-without-a-fork)** — the π banner, shortcut hints, and resource sections are extension output, not a patched pi; `CC_NO_BANNER=1` restores pi's header.
+- **[Themes: authored, not adopted](decisions/branding.md#themes-authored-not-adopted)** — `one-code`/`one-code-light` are hand-authored 51-token themes; no community theme fit.
+- **[Rebrand: pincer](decisions/branding.md#rebrand-pincer)** — (history) why the product was "pincer" / npm `pincer-agent`, and Claude Code stays descriptive ("compatible with…") never titular.
+- **[Rebrand: One Code](decisions/branding.md#rebrand-one-code)** — pincer → **One Code** / npm `one-code`: the stacked wordmark, the full rename surface (state dir, env, channels, repo), and what stays as history.
+- **[Startup listing: quietStartup + banner sections](decisions/branding.md#startup-listing-quietstartup-banner-sections)** — when pi's `quietStartup` is on, compact context/skills/workflows/themes sections replace pi's noisy resource listing.
+
+## System prompt
+
+Full context: [`decisions/system-prompt.md`](decisions/system-prompt.md).
+
+- **[Per-turn `before_agent_start`, not a static override](decisions/system-prompt.md#system-prompt-per-turn-before_agent_start-not-a-static-override)** — rebuilt each turn so it reflects the live tool set (plan mode, deferred loading change it); the environment block is cached per (cwd, model) to stay byte-stable for prompt caching.
+- **[Tiered by model capability](decisions/system-prompt.md#system-prompt-tiered-by-model-capability-2026-08-07)** — three prompt tiers selected by model capability, tuning prompt *text* only (decoding params are a separate future dial).
+
+## Tools
+
+Full context: [`decisions/tools.md`](decisions/tools.md).
+
+- **[Tool names stay pi-idiomatic (snake_case)](decisions/tools.md#tool-names-stay-pi-idiomatic-snake_case)** — register `todo_write`/`subagent`-style names; `matcher.ts` maps users' Claude Code PascalCase permission rules onto them.
+- **[Deferred tools (ToolSearch)](decisions/tools.md#deferred-tools-toolsearch)** — how tool schemas are kept out of the prompt until asked for, using the provider's native mechanism where available.
+- **[Web tools](decisions/tools.md#web-tools)** — `web_search` wraps the one community dep (`pi-web-search`); the rest is our own.
+- **[AskUserQuestion — our own](decisions/tools.md#askuserquestion-our-own)** — the multi-question schema, option lists, multi-select, and headless fallback.
+- **[web_fetch answers a `prompt` with a reader model](decisions/tools.md#web_fetch-answers-a-prompt-with-a-reader-model)** — fetch → readability → markdown, and an optional `prompt` answered by a small reader model with a loud raw-content fallback.
+- **[Tool errors fail loud, never soft-fallback](decisions/tools.md#tool-errors-fail-loud-never-soft-fallback)** — a malformed/ambiguous call returns `isError:true` with the fix named, never a plausible-but-wrong success (the `subagent`-catalog archetype); audit + the 13 fixes across 12 tools.
+- **[Harness discipline (divergences found by self-comparison)](decisions/tools.md#harness-discipline-divergences-found-by-self-comparison)** — Claude-Code-compatible behaviours found by self-comparison that aren't obvious from any single tool.
+- **[Tier-aware tool surface: search built-ins for mid/low only (unreviewed)](decisions/tools.md#tier-aware-tool-surface-search-built-ins-for-midlow-only-unreviewed)** — pi never activates `grep`/`find`/`ls`; mid/low tiers now get them (their prompts demand them), frontier stays lean like Claude Code's.
+- **[Subagent steering: injected catalog, fork hardening (unreviewed)](decisions/tools.md#subagent-steering-injected-catalog-fork-hardening-unreviewed)** — the agent catalog rides an every-turn reminder; a fork's task gets a do-only-this preamble; `model`/`thinking` on a fork fail loud.
+- **[Background bash: override the built-in, gate before detaching (unreviewed)](decisions/tools.md#background-bash-override-the-built-in-gate-before-detaching-unreviewed)** — `run_in_background` on a pi-executor-delegating `bash` override; task_output/task_stop work unchanged; never auto-allowed.
+- **[Deferral runs on all tiers; steering follows CC's channels](decisions/tools.md#deferral-runs-on-all-tiers-steering-follows-ccs-channels-2026-08-10)** — deferral applies on every tier (capture-confirmed CC defers on Haiku too; verified 35→15 tools on deepseek); notifications carry CC's anti-confabulation preamble; MCP server `instructions` are injected, not dropped.
+- **[CLAUDE.md, memory, and skills injected as the CC reminder stack](decisions/tools.md#claudemd-memory-and-skills-injected-as-the-cc-reminder-stack-2026-08-10)** — moved out of the system prompt into the byte-identical first-user-message `<system-reminder>` stack (`claude-context` + `lib/claude-context.ts`, placement/order/suffix on the reminder queue).
+
+## Auto mode
+
+Full context: [`decisions/auto-mode.md`](decisions/auto-mode.md).
+
+- **[A deterministic pre-gate in front of an LLM classifier](decisions/auto-mode.md#auto-mode-a-deterministic-pre-gate-in-front-of-an-llm-classifier)** — a shell pre-gate that may only ever conclude "safe" (a latency optimisation, never a deny path), backed by an LLM approval classifier.
+- **[Parity pass against published Claude Code behaviour](decisions/auto-mode.md#auto-mode-parity-pass-against-the-published-claude-code-behaviour)** — where our auto mode was aligned to the shipped Claude Code auto-approve behaviour.
+- **[Grounding the verdict: cite a rule, don't narrate one](decisions/auto-mode.md#grounding-the-classifiers-verdict-cite-a-rule-dont-narrate-one)** — nothing the classifier says is trusted unless checked: a block must cite a real rule id, the tier comes from that id, an intent-based allow must quote the user verbatim.
+- **[Choosing the classifier model without leaking the session](decisions/auto-mode.md#choosing-the-classifier-model-without-leaking-the-session-to-another-provider)** — the classifier never silently changes provider; models are picked by cost + a per-provider default table, not id substrings.
+- **[Three defects the real OpenRouter catalog exposed](decisions/auto-mode.md#three-defects-the-real-openrouter-catalog-exposed)** — what a live gateway catalog broke in model selection, and the fixes.
+- **[Prompt caching, input size, and vendor containment on gateways](decisions/auto-mode.md#prompt-caching-input-size-and-vendor-containment-on-gateways)** — the stable prefix lives in the system prompt to cache; untrusted CLAUDE.md stays in the user message; sizing for Haiku's 4096-token prefix.
+- **[Hardening: the pi-automode review, and what came of it](decisions/auto-mode.md#auto-mode-hardening-the-pi-automode-review-and-what-came-of-it)** — the fail-closed posture: candidate chain, released pin on mid-session model death, deterministic floor for writes to the gate's own config.
+
+## Code review
+
+Full context: [`decisions/code-review-remediation.md`](decisions/code-review-remediation.md).
+
+- **[Auto-mode gate hardening: four false "safe" verdicts closed](decisions/code-review-remediation.md#auto-mode-gate-hardening-four-false-safe-verdicts-closed-2026-08-10)** — bare redirects, read-only-command redirects, `git -C <outside>`, `sort -o`, and `Bash(sh -c *)` rules all reached "safe"/allow without their real effect being weighed; every fix converts a false "safe" into an escalation, keeping the pre-gate's never-deny contract.
+- **[Worktree vs. permission rules — preserve-original, not reorder](decisions/code-review-remediation.md#worktree-vs-permission-rules--preserve-original-not-reorder-2026-08-10)** — worktree's `cd`-wrapper defeated every Bash rule; the original command is preserved for rule-matching while the classifier keeps seeing the wrapped command. Reordering permissions ahead of worktree was rejected (it would move containment to the wrong dir).
+- **[Background subagents now get the holistic review](decisions/code-review-remediation.md#background-subagents-now-get-the-holistic-review-2026-08-10)** — the end-of-run "review the whole action sequence" checkpoint now fires for background/resident runs, delivered as a follow-up since there is no `tool_result` to attach to.
+
+## Modes & keybindings
+
+Full context: [`decisions/modes.md`](decisions/modes.md).
+
+- **[`/effort`, and ultracode as a standing mode](decisions/modes.md#effort-and-ultracode-as-a-standing-mode)** — one "effort" dial; its last stop is `ultracode` = xhigh plus workflows armed every turn.
+- **[Aligning `/effort` with shift+tab](decisions/modes.md#aligning-effort-with-shifttab)** — why the slider mirrors shift+tab's model-filtered stops and dims the rest (pi reserves that key).
+- **[Permission-mode cycling on ctrl+q](decisions/modes.md#permission-mode-cycling-on-ctrlq-not-shifttab-ctrlm-or-altm)** — why the mode cycle is ctrl+q, not shift+tab / ctrl+m / alt+m.
+- **[Plan mode is file-based, like current Claude Code](decisions/modes.md#plan-mode-is-file-based-like-current-claude-code)** — plan mode writes a plan file under `~/.one-code/plans`; the matcher allows writes to that one file.
+
+## Subagents & workflows
+
+Full context: [`decisions/subagents-workflows.md`](decisions/subagents-workflows.md).
+
+- **[Subagents: what matches Claude Code and what does not](decisions/subagents-workflows.md#subagents-what-matches-claude-code-and-what-does-not)** — the parity map for the subagent tool (fork, worktree isolation, background runs, two-way messaging).
+- **[Permission modes and subagents](decisions/subagents-workflows.md#permission-modes-and-subagents)** — how permission mode propagates into subagent sessions.
+- **[Subagent model selection, resolved in the parent](decisions/subagents-workflows.md#subagent-model-selection-resolved-in-the-parent-advertised-by-reminder)** — aliases stay in-provider, crossings are announced, defaults come from `CLAUDE_CODE_SUBAGENT_MODEL`/`subagentModel`, menu re-advertised every turn.
+- **[Workflow tool (ultracode orchestration)](decisions/subagents-workflows.md#workflow-tool-ultracode-orchestration)** — vm-sandboxed JS scripts fanning out to in-process subagents; background runs, journal resume, saved workflows.
+
+## Model policy
+
+Full context: [`decisions/model-policy.md`](decisions/model-policy.md).
+
+- **[Shared role profiles](decisions/model-policy.md#shared-role-profiles-smaller-classifiers-and-delegated-workers-by-default)** — one same-provider/family table gives classifiers, delegated workers, and reader models a smaller default.
+- **[Upward cost pressure](decisions/model-policy.md#upward-cost-pressure-an-informational-warning-and-a-per-call-gate)** — an informational warning plus a per-call gate when a delegated model costs more than the session's.
+
+## Memory & session state
+
+Full context: [`decisions/memory-state.md`](decisions/memory-state.md).
+
+- **[Memory: own file-based implementation](decisions/memory-state.md#memory-own-file-based-implementation)** — Claude Code's `~/.claude/projects/<slug>/memory/` layout keyed by git root; relevance-based mid-session recall is unreplicable client internals.
+- **[The memory dir is harness-designated working space](decisions/memory-state.md#the-memory-dir-is-harness-designated-working-space-like-the-plan-file)** — why writes there need no permission prompt, like the plan file.
+- **[Session scratchpad, Claude Code-style](decisions/memory-state.md#session-scratchpad-claude-code-style)** — a per-session temp dir: prompt section plus the allowed-writes rule.
+- **[Own state, borrowed config](decisions/memory-state.md#own-state-borrowed-config-claude-is-read-only-one-code-writes-to-one-code)** — `.claude` is read-only; One Code writes its own state to `~/.one-code` so the two never clobber each other.
+
+## Compaction
+
+Full context: [`decisions/compaction.md`](decisions/compaction.md).
+
+- **[Compaction runs Claude Code's prompt, via session_before_compact](decisions/compaction.md#compaction-runs-claude-codes-prompt-via-session_before_compact)** — Claude Code's compaction prompt, `<summary>` extraction, an economical model, and the `CC_COMPACTION=0` pi fallback.
+- **[The cache miss, and the two-part fix](decisions/compaction.md#the-cache-miss-and-the-two-part-fix-2026-08-07)** — why the compaction call missed the prompt cache and the capture-based replay + reasoning-mirror + Anthropic beta-replay that fixed it, live-verified on three providers.
+
+## MCP
+
+Full context: [`decisions/mcp.md`](decisions/mcp.md).
+
+- **[MCP — our own client on the official SDK](decisions/mcp.md#mcp-our-own-client-on-the-official-sdk)** — `.mcp.json` discovery, `mcp__server__tool` naming, resources.
+- **[MCP servers with unset credentials](decisions/mcp.md#mcp-servers-with-unset-credentials)** — how a server with missing credentials is handled rather than crashing discovery.
+- **[Background connect: session_start no longer blocks the prompt](decisions/mcp.md#background-connect-session_start-no-longer-blocks-the-prompt-2026-08-10)** — the awaited MCP handshake *was* the 4.9s startup (findings §15); now fire-and-forget in the interactive session (501ms measured), still awaited in one-shots and subagent children; SDK import lazified.
+
+## LSP
+
+Full context: [`decisions/lsp.md`](decisions/lsp.md).
+
+- **[LSP: our own client, not a package](decisions/lsp.md#lsp-our-own-client-not-a-package)** — a zero-dep LSP client for post-edit diagnostics and `lsp_diagnostics`.
+
+## Skills & plugins
+
+Full context: [`decisions/skills-plugins.md`](decisions/skills-plugins.md).
+
+- **[Skills and plugins](decisions/skills-plugins.md#skills-and-plugins)** — `~/.claude` + `.claude` skills/commands discovery, and Claude Code plugins contributing namespaced agents/skills/commands/MCP.
+
+## TUI
+
+Full context: [`decisions/tui.md`](decisions/tui.md).
+
+- **[Compact tool rendering — the Claude Code transcript look](decisions/tui.md#compact-tool-rendering-the-claude-code-transcript-look-unreviewed)** *(unreviewed)* — `●`/`⎿` call+result lines with ctrl+o collapse for every One Code tool, compact `✳` notification headlines, boxless theme, dimmer thinking text.
+- **[Thinking collapsed by default, expandable with ctrl+t](decisions/tui.md#thinking-collapsed-by-default-expandable-with-ctrlt-unreviewed)** *(unreviewed)* — pi's own `hideThinkingBlock` defaulted on (only when the user never chose), `✻ Thinking…` label via `setHiddenThinkingLabel`; the write lands next session (settings cached at startup).
+- **[Built-in tools joined the ● language; banner cut to four lines](decisions/tui.md#built-in-tools-joined-the--language-banner-cut-to-four-lines-unreviewed)** *(unreviewed)* — `tool-style` wraps pi's read/write/edit/grep/find/ls renderers (`● Label(arg)` + base result under a `⎿` elbow, edit's diff preview kept); one curated hint line, sections as counts, warnings point at /lsp & /mcp.
+- **[Fullscreen (alt-screen) for Claude Code's clean exit — a setting, not extension code](decisions/tui.md#fullscreen-alt-screen-for-claude-codes-clean-exit-a-setting-not-extension-code-unreviewed)** *(unreviewed)* — CC's clean exit is the terminal alt-screen buffer; pi has it as `tuiMode: "fullscreen"`, but the renderer is a pi-core startup choice with no extension hook, so One Code recommends the setting rather than owning it.
+- **[Render memoization: components cache by width](decisions/tui.md#render-memoization-components-cache-by-width-2026-08-10)** — pi-tui renders every mounted component every frame (findings §15), so `linesComponent` memoizes by width (safe: state changes mint fresh components; `invalidate()` clears); `truncateLine` got a raw-length fast path. Rule: every custom renderer component must memoize `render(width)`.
+
+## Hooks
+
+Full context: [`decisions/hooks.md`](decisions/hooks.md).
+
+- **[Hooks: own the mechanism, port the best of three references](decisions/hooks.md#hooks-own-the-mechanism-port-the-best-of-three-references)** — 8 events, the Claude Code stdin/envelope protocol, ask→block fail-closed, once-per-config consent, and running before worktree/permissions.

package/extensions/ask-user/index.ts

@@ -0,0 +1,124 @@
+/**
+ * ask-user extension — Claude Code's AskUserQuestion.
+ *
+ * Asks the user up to four multiple-choice questions, each optionally
+ * multi-select, always with a free-text escape hatch. Questions are presented
+ * one dialog at a time (pi's UI has no native multi-question widget), and the
+ * collected answers come back as one tool result.
+ *
+ * Replaces the community `pi-ask-user`, which asked one question per call and
+ * pulled in a second, conflicting TypeBox.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { ccToolRenderers } from "../lib/tui-render.ts";
+import {
+	type Answer,
+	buildChoices,
+	DONE_LABEL,
+	formatAnswers,
+	OTHER_LABEL,
+	type Question,
+	resolveSelection,
+	stripMark,
+} from "./questions.ts";
+
+const NON_INTERACTIVE =
+	"This session has no interactive UI, so the user cannot be shown a dialog. Ask your question in your reply instead and stop, or proceed under a stated assumption.";
+
+async function askOne(question: Question, ctx: ExtensionContext): Promise<Answer | undefined> {
+	const selected: string[] = [];
+	const title = `${question.header}\n\n${question.question}`;
+
+	// Multi-select loops until the user is done; single-select runs once.
+	for (let round = 0; round < question.options.length + 1; round++) {
+		const choice = await ctx.ui.select(title, buildChoices(question, selected));
+		if (choice === undefined) return undefined; // cancelled
+
+		if (choice === DONE_LABEL) break;
+
+		if (choice === OTHER_LABEL) {
+			const typed = await ctx.ui.input(question.question, "Type your answer");
+			if (typed === undefined) return undefined;
+			return { question: question.question, header: question.header, selected: [typed], freeform: true };
+		}
+
+		const label = resolveSelection(stripMark(choice), question.options);
+		if (!label) break;
+
+		if (!question.multiSelect) {
+			return { question: question.question, header: question.header, selected: [label], freeform: false };
+		}
+
+		const existing = selected.indexOf(label);
+		if (existing >= 0) selected.splice(existing, 1);
+		else selected.push(label);
+	}
+
+	return { question: question.question, header: question.header, selected, freeform: false };
+}
+
+export default function askUserExtension(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "ask_user_question",
+		label: "Ask User",
+		...ccToolRenderers<{ questions?: Array<{ question?: string }> }>("Ask User", {
+			title: (a) => a?.questions?.[0]?.question,
+		}),
+		description:
+			"Ask the user to choose between options when you are blocked on a decision that is genuinely theirs — one you cannot resolve from the request, the code, or a sensible default. Ask up to four questions in one call; each gets a free-text 'Other' choice automatically. Do not use it for choices with an obvious default or for facts you can verify yourself.",
+		promptSnippet: "Ask the user to decide between options when genuinely blocked",
+		parameters: Type.Object({
+			questions: Type.Array(
+				Type.Object({
+					question: Type.String({ description: "The question, ending in a question mark" }),
+					header: Type.String({ description: "Very short label for the question (a few words)" }),
+					multiSelect: Type.Optional(
+						Type.Boolean({ description: "Allow choosing several options (default false)" }),
+					),
+					options: Type.Array(
+						Type.Object({
+							label: Type.String({ description: "Short choice text" }),
+							description: Type.Optional(Type.String({ description: "What choosing this means" })),
+						}),
+						{ minItems: 2, maxItems: 4 },
+					),
+				}),
+				{ minItems: 1, maxItems: 4, description: "Questions to ask (1-4)" },
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!ctx.hasUI) {
+				return { content: [{ type: "text", text: NON_INTERACTIVE }], details: {}, isError: true };
+			}
+
+			const answers: Answer[] = [];
+			for (const question of params.questions as Question[]) {
+				const answer = await askOne(question, ctx);
+				if (!answer) {
+					// Cancelling one question cancels the batch: the remaining answers
+					// would be meaningless without it.
+					return {
+						content: [
+							{
+								type: "text",
+								text:
+									answers.length > 0
+										? `The user cancelled before finishing. Answers so far:\n\n${formatAnswers(answers)}`
+										: "The user cancelled without answering.",
+							},
+						],
+						details: { answers, cancelled: true },
+					};
+				}
+				answers.push(answer);
+			}
+
+			return {
+				content: [{ type: "text", text: formatAnswers(answers) }],
+				details: { answers },
+			};
+		},
+	});
+}

package/extensions/ask-user/questions.ts

@@ -0,0 +1,60 @@
+/**
+ * Question and answer shaping for ask_user_question (pure).
+ */
+
+export interface QuestionOption {
+	label: string;
+	description?: string;
+}
+
+export interface Question {
+	question: string;
+	header: string;
+	multiSelect?: boolean;
+	options: QuestionOption[];
+}
+
+export interface Answer {
+	question: string;
+	header: string;
+	selected: string[];
+	/** True when the user typed their own answer instead of picking. */
+	freeform: boolean;
+}
+
+export const OTHER_LABEL = "Other (type your own answer)";
+export const DONE_LABEL = "Done selecting";
+
+/** `label — description`, so the description is visible in a plain select list. */
+export function formatOptionLabel(option: QuestionOption): string {
+	return option.description ? `${option.label} — ${option.description}` : option.label;
+}
+
+/** Maps a chosen display string back to the option label it came from. */
+export function resolveSelection(display: string, options: QuestionOption[]): string | undefined {
+	return options.find((option) => formatOptionLabel(option) === display)?.label;
+}
+
+export function buildChoices(question: Question, alreadySelected: string[] = []): string[] {
+	const marked = question.options.map((option) => {
+		const label = formatOptionLabel(option);
+		return question.multiSelect && alreadySelected.includes(option.label) ? `✓ ${label}` : label;
+	});
+	const extras = question.multiSelect ? [DONE_LABEL, OTHER_LABEL] : [OTHER_LABEL];
+	return [...marked, ...extras];
+}
+
+/** Strips the multi-select tick so the choice can be matched against options. */
+export function stripMark(display: string): string {
+	return display.startsWith("✓ ") ? display.slice(2) : display;
+}
+
+export function formatAnswers(answers: Answer[]): string {
+	if (answers.length === 0) return "The user did not answer.";
+	return answers
+		.map((answer) => {
+			const value = answer.selected.length > 0 ? answer.selected.join(", ") : "(no answer)";
+			return `${answer.question}\n→ ${value}${answer.freeform ? " (typed by the user)" : ""}`;
+		})
+		.join("\n\n");
+}

package/extensions/auto-mode/actions.ts

@@ -0,0 +1,78 @@
+/**
+ * The child-action log auto mode reviews when a subagent finishes (pure).
+ *
+ * Claude Code classifies subagent work at three points: the task description
+ * before the child starts, each of the child's own actions, and the child's
+ * full action history when it returns. The first two fall out of the permission
+ * gate — the spawn is classified like any other tool call, and the child
+ * inherits auto mode so its actions are classified in its own session.
+ *
+ * The return check is different in kind: it looks at the *aggregate*. Each step
+ * of "read the deploy config, read a token, open a PR" can pass individually
+ * while the sequence is what matters. That is only visible once the child is
+ * done, which is what this records.
+ *
+ * The log deliberately holds names and short subjects rather than tool output:
+ * output is untrusted content, and feeding it to the classifier is the injection
+ * path auto mode exists to close.
+ */
+
+export const SUBAGENT_ACTIONS_CHANNEL = "one-code:subagent-actions";
+
+export interface ChildAction {
+	toolName: string;
+	/** Command or path, clipped. Never tool output. */
+	subject: string;
+}
+
+export interface SubagentActionsPayload {
+	/** The parent's tool call id, so a foreground review attaches to the right result. */
+	toolCallId: string;
+	actions: ChildAction[];
+	/**
+	 * True for a background/resident run: the spawning call has already returned, so
+	 * there is no pending tool_result to attach the holistic review to. The gate
+	 * reviews on receipt and surfaces any concern as its own notification instead.
+	 */
+	background?: boolean;
+	/** Agent name, used to label a background review. */
+	agentName?: string;
+}
+
+/** Per-action and total caps: a long-running child must not blow up the prompt. */
+const SUBJECT_LIMIT = 160;
+const MAX_ACTIONS = 60;
+
+export function recordAction(log: ChildAction[], toolName: string, input: unknown): void {
+	if (log.length >= MAX_ACTIONS) return;
+	const args = (input ?? {}) as Record<string, unknown>;
+	const raw = args.command ?? args.file_path ?? args.path ?? args.url ?? args.pattern ?? "";
+	const subject = typeof raw === "string" ? raw : JSON.stringify(raw);
+	log.push({ toolName, subject: subject.slice(0, SUBJECT_LIMIT) });
+}
+
+/** Render the log for the classifier, collapsing repeats so 40 reads read as one line. */
+export function renderActions(actions: ChildAction[]): string {
+	const lines: string[] = [];
+	let previous: string | undefined;
+	let repeats = 0;
+
+	const flush = () => {
+		if (previous === undefined) return;
+		lines.push(repeats > 1 ? `${previous} (×${repeats})` : previous);
+	};
+
+	for (const action of actions) {
+		const line = action.subject ? `${action.toolName}: ${action.subject}` : action.toolName;
+		if (line === previous) {
+			repeats++;
+			continue;
+		}
+		flush();
+		previous = line;
+		repeats = 1;
+	}
+	flush();
+
+	return lines.join("\n");
+}