one-code-extension 0.4.1 → 0.5.0

package/extensions/{system-prompt → lib}/git-status.ts

@@ -1,6 +1,7 @@
 /**
- * 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:
+ * Claude Code's `# gitStatus` section — part of the context reminder on the
+ * first user message (lib/claude-context.ts buildContextBlock) 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.
  *
@@ -11,11 +12,18 @@
  * the status and the log are whole-output `.trim()`ed — which is why a leading
  * `??`/` M` porcelain line renders flush-left in the capture.
  *
+ * Bounded the way Claude Code bounds it: the status is clipped at 2,000
+ * characters with Claude Code's note, a clean tree reads `(clean)`, an empty
+ * user name drops the `Git user:` line, and a `git status` that fails or hangs
+ * past the timeout drops the whole block, as Claude Code does on a failed
+ * snapshot.
+ *
  * 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";
+import { HARNESS_GIT_CONFIG } from "./git.ts";
 
 export interface GitSnapshot {
 	branch: string;
@@ -28,9 +36,27 @@ export interface GitSnapshot {
 }
 
 const HEADER =
-	"gitStatus: This is the git status at the start of the conversation. " +
+	"# gitStatus\nThis 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.";
 
+/** The main session's system-prompt extension claims the snapshot on this channel; a child session never does. */
+export const GIT_SNAPSHOT_OWNER_CHANNEL = "one-code:git-snapshot-owner";
+
+/** Claude Code's limit on the status inside the block, in characters. */
+export const GIT_STATUS_MAX_CHARS = 2000;
+
+/** Each git command's time limit: a hung `git status` (a network filesystem) must not block the first turn. */
+export const GIT_TIMEOUT_MS = 10_000;
+
+/**
+ * The status as the block carries it: cut at 2,000 characters with Claude
+ * Code's note, which names the shell tool the model has.
+ */
+export function clipGitStatus(status: string, shellTool = "bash"): string {
+	if (status.length <= GIT_STATUS_MAX_CHARS) return status;
+	return `${status.substring(0, GIT_STATUS_MAX_CHARS)}\n... (truncated because it exceeds 2k characters. If you need more information, run "git status" using ${shellTool})`;
+}
+
 /** Assemble CC's block from a snapshot. Pure; byte-exact against the captures. */
 export function formatGitStatus(s: GitSnapshot): string {
 	return [
@@ -40,10 +66,9 @@ export function formatGitStatus(s: GitSnapshot): string {
 		"",
 		`Main branch (you will usually use this for PRs): ${s.mainBranch}`,
 		"",
-		`Git user: ${s.user}`,
-		"",
+		...(s.user ? [`Git user: ${s.user}`, ""] : []),
 		"Status:",
-		s.status,
+		s.status || "(clean)",
 		"",
 		"Recent commits:",
 		s.commits,
@@ -56,7 +81,14 @@ 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();
+			return execFileSync("git", [...HARNESS_GIT_CONFIG, ...args], {
+				cwd,
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: GIT_TIMEOUT_MS,
+				// A status over the 1 MiB default would fail instead of being clipped.
+				maxBuffer: 64 * 1024 * 1024,
+			}).trim();
 		} catch {
 			return null;
 		}
@@ -75,19 +107,25 @@ function resolveMainBranch(run: GitRunner, branch: string): string {
 
 /**
  * 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.
+ * tree or `git status` fails (or times out): an empty status would claim a
+ * clean tree. Other command failures degrade to empty fields rather than
+ * dropping the whole block. `shellTool` is the tool the clip note tells the
+ * model to run `git status` with.
  */
-export function collectGitStatus(cwd: string, runner?: GitRunner): string | null {
+export function collectGitStatus(cwd: string, runner?: GitRunner, shellTool = "bash"): string | null {
 	const run = runner ?? defaultRunner(cwd);
 	if (run(["rev-parse", "--is-inside-work-tree"]) !== "true") return null;
 
 	const branch = run(["branch", "--show-current"]) ?? "";
+	const mainBranch = resolveMainBranch(run, branch);
+	const user = run(["config", "user.name"]) ?? "";
+	const status = run(["status", "--porcelain"]);
+	if (status === null) return null;
 	return formatGitStatus({
 		branch,
-		mainBranch: resolveMainBranch(run, branch),
-		user: run(["config", "user.name"]) ?? "",
-		status: run(["status", "--porcelain"]) ?? "",
+		mainBranch,
+		user,
+		status: clipGitStatus(status, shellTool),
 		commits: run(["log", "-5", "--format=%h %s"]) ?? "",
 	});
 }

package/extensions/lib/git.ts

@@ -1,24 +1,56 @@
 /** Shared git helpers — pure functions only (safe to import across extensions). */
 
+/**
+ * Global options for every git command the harness runs on its own (startup
+ * git status, the classifier's git status line, consent checks, worktree
+ * bookkeeping). git honours the checkout's own `.git/config`, and
+ * `core.fsmonitor` there names a
+ * program that `status` and other index reads run — so a directory whose
+ * `.git` came from an archive or a copied tree would run it the moment One
+ * Code starts in it, before any prompt (SECURITY-REVIEW-2026-09-23 M5).
+ * `--no-optional-locks` stops `status` rewriting the index, which would run the
+ * checkout's `post-index-change` hook. The model's own git commands are judged
+ * by the permission gate instead (auto-mode/git-checkout-programs.ts).
+ */
+export const HARNESS_GIT_CONFIG: readonly string[] = ["-c", "core.fsmonitor=false", "--no-optional-locks"];
+
 import { execFile } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { devNull } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { comparablePath, tryRealpath } from "./paths.ts";
+
+/** Harness worktree bookkeeping must not execute repository hooks before the tool permission gate. */
+export const HARNESS_GIT_NO_HOOKS: readonly string[] = ["-c", `core.hooksPath=${devNull}`];
 
 /**
- * Whether the checkout at `cwd` has no uncommitted or untracked changes, or
- * undefined when git could not say (not a repo, git missing). One short
- * `git status --porcelain`, asynchronous so the tool_call hook it runs from
- * does not stall the event loop; used for the classifier transcript's
- * ground-truth line after a `git status` call (permissions/index.ts).
+ * `git status` output for `cwd` with the given arguments, or undefined when
+ * git could not say (not a repo, git missing, timeout). Asynchronous so the
+ * tool_call hook it runs from does not stall the event loop; used for the
+ * classifier transcript's gitStatus line (auto-mode/git-status-meta.ts).
  */
-export function gitStatusClean(cwd: string): Promise<boolean | undefined> {
+export function gitStatusOutput(cwd: string, args: readonly string[]): Promise<string | undefined> {
 	return new Promise((resolvePromise) => {
-		execFile("git", ["status", "--porcelain"], { cwd, encoding: "utf8", timeout: 5_000, windowsHide: true }, (error, stdout) => {
-			resolvePromise(error ? undefined : stdout.trim().length === 0);
+		execFile("git", [...HARNESS_GIT_CONFIG, ...args], { cwd, encoding: "utf8", timeout: 5_000, windowsHide: true }, (error, stdout) => {
+			resolvePromise(error ? undefined : stdout);
 		});
 	});
 }
 
+/**
+ * Every worktree of the repository `cwd` belongs to (`git worktree list`),
+ * main checkout included, in native resolved form; undefined when git could
+ * not list them. The worktree guards refuse git aimed at any of them.
+ */
+export async function repositoryWorktrees(cwd: string): Promise<string[] | undefined> {
+	const out = await gitStatusOutput(cwd, ["worktree", "list", "--porcelain"]);
+	if (out === undefined) return undefined;
+	return out
+		.split("\n")
+		.filter((line) => line.startsWith("worktree "))
+		.map((line) => resolve(line.slice("worktree ".length)));
+}
+
 /**
  * The nearest checkout root at or above `startDir`: the directory holding a
  * `.git` entry (a directory for a main checkout, a file for a linked worktree
@@ -50,23 +82,53 @@ export function findProjectRoot(startDir: string): string | undefined {
 	return linkedWorktreeMainRoot(root) ?? root;
 }
 
-/** For a linked worktree root, the main checkout it belongs to; undefined otherwise. Exported for tests. */
-export function linkedWorktreeMainRoot(root: string): string | undefined {
+/**
+ * The git dir a checkout root's `.git` FILE points at (a linked worktree or a
+ * submodule: `gitdir: <path>`), absolute; undefined when `.git` is a directory,
+ * missing, or unreadable.
+ */
+export function gitdirFileTarget(root: string): string | undefined {
 	const dotGit = join(root, ".git");
-	let gitdir: string;
 	try {
 		if (!statSync(dotGit).isFile()) return undefined;
 		const match = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGit, "utf-8"));
 		if (!match) return undefined;
-		gitdir = match[1];
+		// resolve in both cases: git writes `C:/…` on Windows, and callers compare native paths.
+		return isAbsolute(match[1]) ? resolve(match[1]) : resolve(root, match[1]);
 	} catch {
 		return undefined;
 	}
-	const absolute = isAbsolute(gitdir) ? gitdir : resolve(root, gitdir);
+}
+
+/**
+ * For a linked worktree root, the main checkout it belongs to; undefined
+ * otherwise. Exported for tests. The `.git` file alone proves nothing: an
+ * archive or copied tree can carry `gitdir: /trusted/.git/worktrees/x` and so
+ * borrow that repository's identity (its settings and remembered consent). git
+ * records the way back in `<gitdir>/gitdir`, so only a worktree that record
+ * names is inherited.
+ */
+export function linkedWorktreeMainRoot(root: string): string | undefined {
+	const absolute = gitdirFileTarget(root);
+	if (!absolute) return undefined;
 	// <main>/.git/worktrees/<name> → <main>. A submodule's gitdir points into
 	// <super>/.git/modules/<name> and is left alone.
 	const worktrees = dirname(absolute);
 	const mainDotGit = dirname(worktrees);
 	if (basename(worktrees) !== "worktrees" || basename(mainDotGit) !== ".git") return undefined;
+	if (!pointsBack(absolute, root)) return undefined;
 	return dirname(mainDotGit);
 }
+
+/** Whether the worktree record `gitdir` names `<root>/.git` (absolute, or relative to the record with `worktree.useRelativePaths`). */
+function pointsBack(gitdir: string, root: string): boolean {
+	try {
+		const recorded = readFileSync(join(gitdir, "gitdir"), "utf-8").trim();
+		if (!recorded) return false;
+		const target = isAbsolute(recorded) ? resolve(recorded) : resolve(gitdir, recorded);
+		const dotGit = join(root, ".git");
+		return comparablePath(tryRealpath(target) ?? target) === comparablePath(tryRealpath(dotGit) ?? dotGit);
+	} catch {
+		return false;
+	}
+}

package/extensions/lib/grammars/LICENSE-tree-sitter-bash

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Max Brunsfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/lib/grammars/README.md

@@ -0,0 +1,2 @@
+tree-sitter-bash 0.25.1 release WASM (https://github.com/tree-sitter/tree-sitter-bash), unmodified.
+Loaded by ../bash-parser.ts with web-tree-sitter; bump both together (the grammar ABI must be one the runtime supports).

package/extensions/lib/guide-docs.ts

@@ -0,0 +1,45 @@
+/**
+ * Where the documentation the `one-code-guide` agent reads lives on this
+ * machine: One Code's own user guide (`docs/guide/`, shipped in the npm
+ * package next to `extensions/`) and the running pi's `docs/` and `examples/`
+ * (pi's `getDocsPath()`/`getExamplesPath()`, which name the host pi's copies in
+ * both install shapes; findings §6).
+ *
+ * The permissions extension makes these directories readable without a prompt
+ * (never writable), so the guide agent can read them on any model tier.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getDocsPath, getExamplesPath } from "@earendil-works/pi-coding-agent";
+
+/** One Code's user guide, `<package>/docs/guide`; its `README.md` is the index. */
+export const ONE_CODE_GUIDE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs", "guide");
+
+export interface GuideDocs {
+	/** One Code's user guide. */
+	guide: string;
+	/** The running pi's docs (extensions, packages, settings, …); undefined when not found. */
+	piDocs?: string;
+	/** The running pi's examples (extensions among them); undefined when not found. */
+	piExamples?: string;
+}
+
+function existing(read: () => string): string | undefined {
+	try {
+		const dir = read();
+		return existsSync(dir) ? dir : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function guideDocs(): GuideDocs {
+	return { guide: ONE_CODE_GUIDE_DIR, piDocs: existing(getDocsPath), piExamples: existing(getExamplesPath) };
+}
+
+/** The directories that exist, for the permission gate's read-only roots. */
+export function guideDocsDirs(docs: GuideDocs = guideDocs()): string[] {
+	return [existsSync(docs.guide) ? docs.guide : undefined, docs.piDocs, docs.piExamples].filter((dir): dir is string => !!dir);
+}

package/extensions/lib/headless-output.ts

@@ -0,0 +1,46 @@
+/**
+ * Output from a command in a one-shot run (`-p`, `--mode json`), where
+ * `ctx.ui.notify` is a no-op: pi wires no UI context there, so a message sent
+ * through it vanishes and the command exits silently.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/**
+ * A user-facing notice: a TUI/RPC toast where there is UI, otherwise stderr.
+ * `console.error` never corrupts the `--mode json` event stream on stdout.
+ */
+export function notifyOrPrint(ctx: Pick<ExtensionContext, "hasUI" | "ui">, message: string, level: "info" | "warning" | "error"): void {
+	if (ctx.hasUI) ctx.ui.notify(message, level);
+	else console.error(message);
+}
+
+/**
+ * Whether the session can show a custom TUI component: a panel opened through
+ * `ctx.ui.custom`, or a component widget. RPC has UI but forwards only dialogs,
+ * notices and string-array widgets: its `custom()` resolves undefined and a
+ * component factory vanishes, so a command falls back to text there.
+ */
+export function canShowCustomUi(ctx: Pick<ExtensionContext, "hasUI" | "mode">): boolean {
+	return ctx.hasUI && ctx.mode !== "rpc";
+}
+
+/** The line saying a command whose panel cannot open in RPC shows a read-only listing instead. */
+export function rpcReadOnlyText(command: string, manage: string): string {
+	return `${command} in RPC is read-only; use the TUI to ${manage}.`;
+}
+
+/** In RPC, say that a command whose panel cannot open shows a read-only listing instead. */
+export function notifyRpcReadOnly(ctx: Pick<ExtensionContext, "mode" | "ui">, command: string, manage: string): string | undefined {
+	if (ctx.mode !== "rpc") return undefined;
+	const text = rpcReadOnlyText(command, manage);
+	ctx.ui.notify(text, "info");
+	// Returned so a command reporting its result can include it.
+	return text;
+}
+
+/** A command's answer in a one-shot run: stdout in print mode, stderr in json mode (stdout is the event stream there). */
+export function printAnswer(ctx: Pick<ExtensionContext, "mode">, text: string): void {
+	if (ctx.mode === "print") console.log(text);
+	else console.error(text);
+}

package/extensions/lib/hook-gate.ts

@@ -22,28 +22,28 @@ import type { InlineExtension } from "@earendil-works/pi-coding-agent";
 import { applyPostToolUseOutcome } from "../hooks/protocol.ts";
 import type { ChildHookCall, HookBridge } from "../hooks/subagent-bridge.ts";
 import { REMINDER_CHANNEL } from "./reminders.ts";
+import { SUBAGENT_HANDBACK } from "./subagent-handback.ts";
 
 /** Tools the runtime itself injects; never run hooks for them. */
-const DEFAULT_INTERNAL_TOOLS = new Set(["structured_output"]);
+const DEFAULT_INTERNAL_TOOLS = new Set(["structured_output", SUBAGENT_HANDBACK]);
 
 export interface HookGateOptions {
 	/** The child's agent type for the payload's `agent_type`, resolved per session id by the runner. */
 	agentTypeOf?: (sessionId: string | undefined) => string | undefined;
-	neverGate?: Set<string>;
 }
 
 export function hookGateFactory(getBridge: () => HookBridge | undefined, options: HookGateOptions = {}): InlineExtension {
-	const neverGate = options.neverGate ?? DEFAULT_INTERNAL_TOOLS;
 	return {
 		name: "agent-hook-gate",
 		hidden: true,
 		factory: (pi) => {
-			const describe = (toolName: string, input: unknown, ctx: { cwd?: string; sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } } | undefined, fallbackCwd: string): ChildHookCall => {
+			const describe = (toolName: string, input: unknown, ctx: { cwd?: string; signal?: AbortSignal; sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } } | undefined, fallbackCwd: string): ChildHookCall => {
 				const sessionId = ctx?.sessionManager?.getSessionId?.();
 				return {
 					toolName,
 					input: (input ?? {}) as Record<string, unknown>,
 					cwd: ctx?.cwd ?? fallbackCwd,
+					signal: ctx?.signal,
 					sessionId,
 					transcriptPath: ctx?.sessionManager?.getSessionFile?.() ?? undefined,
 					agentType: options.agentTypeOf?.(sessionId),
@@ -51,7 +51,7 @@ export function hookGateFactory(getBridge: () => HookBridge | undefined, options
 			};
 
 			pi.on("tool_call", async (event, ctx) => {
-				if (neverGate.has(event.toolName)) return undefined;
+				if (DEFAULT_INTERNAL_TOOLS.has(event.toolName)) return undefined;
 				try {
 					const bridge = getBridge();
 					if (!bridge) return undefined;
@@ -67,7 +67,7 @@ export function hookGateFactory(getBridge: () => HookBridge | undefined, options
 			});
 
 			pi.on("tool_result", async (event, ctx) => {
-				if (neverGate.has(event.toolName)) return undefined;
+				if (DEFAULT_INTERNAL_TOOLS.has(event.toolName)) return undefined;
 				try {
 					const bridge = getBridge();
 					if (!bridge) return undefined;
@@ -78,7 +78,7 @@ export function hookGateFactory(getBridge: () => HookBridge | undefined, options
 					});
 					// Same assembly as the parent's tool_result handler; the parent already
 					// framed additionalContext as a <system-reminder>.
-					const content = applyPostToolUseOutcome(event.content, outcome);
+					const content = applyPostToolUseOutcome(event.content, outcome, event.toolName);
 					if (!content) return undefined;
 					return { content, isError: event.isError };
 				} catch {

package/extensions/lib/interrupt.ts

@@ -16,7 +16,7 @@
  * message with EMPTY content, `stopReason: "error"` and `errorMessage: "This
  * operation was aborted"` — the fetch layer's AbortError, not pi's "aborted"
  * label (measured over RPC on pi 0.85.0, STEERING-REVIEW-2026-09-05 L1;
- * upstream ask docs/upstream_prs.md #18). The run's abort signal is still the
+ * upstream ask working-docs/upstream_prs.md #18). The run's abort signal is still the
  * ground truth, and `ctx.signal` at `agent_end` is that signal (pi's
  * `activeRun` outlives the event), so callers pass `ctx.signal?.aborted` and
  * an `error` stop on an aborted run reads as "aborted": the user stopped the
@@ -34,6 +34,19 @@
  * carry the outcome over from the runs' `agent_end`. Findings §3.
  */
 
+/** A one-shot command failed before its user turn could settle (no agent_end to classify). */
+export const ONE_SHOT_COMMAND_FAILED_CHANNEL = "one-code:one-shot-command-failed";
+
+/**
+ * The harness stopped the current turn as a failure (a broken provider stream,
+ * a classifier that cannot judge). Emit it before `ctx.abort()`: the run then
+ * ends `aborted`, which alone reads as a user cancel and exits 0.
+ */
+export const TURN_FAILED_CHANNEL = "one-code:turn-failed";
+export interface TurnFailedEvent {
+	reason: string;
+}
+
 /** How the last assistant message of a run ended. */
 export type RunOutcome = "ok" | "aborted" | "error";
 
@@ -48,7 +61,10 @@ export interface RunMessage {
  * "ok". `signalAborted` is the run's abort signal at `agent_end`
  * (`ctx.signal?.aborted`): it turns an `error` stop into "aborted" (see the
  * header) and leaves a completed stop alone — a signal aborted after the final
- * message landed did not interrupt anything.
+ * message landed did not interrupt anything. A run ends on a tool call only
+ * when its batch terminates the loop; with the signal aborted that is a turn
+ * the user stopped before the model replied (a rejection without a reason,
+ * permissions/index.ts), so it is "aborted" too.
  */
 export function runOutcome(messages: ReadonlyArray<RunMessage> | undefined, signalAborted = false): RunOutcome {
 	if (!messages) return "ok";
@@ -56,8 +72,8 @@ export function runOutcome(messages: ReadonlyArray<RunMessage> | undefined, sign
 		const message = messages[i];
 		if (message.role !== "assistant") continue;
 		if (message.stopReason === "aborted") return "aborted";
-		if (message.stopReason === "error") return signalAborted ? "aborted" : "error";
-		return "ok";
+		if (signalAborted && (message.stopReason === "error" || message.stopReason === "toolUse")) return "aborted";
+		return message.stopReason === "error" ? "error" : "ok";
 	}
 	return "ok";
 }