@visual-z/xeno 0.1.0

package/src/runtime/tools.ts

@@ -0,0 +1,1193 @@
+/**
+ * Built-in tools: read, write, edit, bash, plus grep / find / ls.
+ *
+ * Search is its own trio because bash defaults to ask: without a confined
+ * read-only search the model reaches for the shell for every "where is this
+ * symbol", and each of those costs a keypress. The schemas stay small; the
+ * walk lives in store/search.ts so ignore rules and the no-symlink cap stay
+ * one implementation.
+ *
+ * The load-bearing property here is that a tool's EFFECT is derived by this
+ * module from what actually happened, never from what the model said it was
+ * doing. A read records the digest of the bytes it returned; an edit records
+ * the digests either side of the write; a command records its exit code. That
+ * is what lets deriveHandoff verify a completion claim against evidence rather
+ * than believing it.
+ *
+ * `bash` can reach outside any path the model declared, which the tree design
+ * has to account for -- see appendix I. This module does not try to prevent
+ * that by making the shell less capable; it records what it can and leaves the
+ * workspace-snapshot cross-check to the layer above.
+ */
+
+import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, resolve, relative, isAbsolute, join, sep } from "node:path";
+import type { Effect, LineRange, ArtifactRef } from "../core/events.ts";
+import { archiveObservation, type ArchivedObservation } from "../store/observations.ts";
+import { commandHeader, headTailView } from "../core/observation-view.ts";
+import {
+  DEFAULT_YIELD_MS, MAX_YIELD_MS, MIN_YIELD_MS, findSession, runningSessions, startSession, takeOutput, waitSession,
+} from "./exec-sessions.ts";
+import { observeCommand } from "../store/command.ts";
+import { executionOutcome, type ExecutionOutcome } from "../core/outcome.ts";
+import { waitForAdmission } from "./execution-control.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import { classifyGate } from "../core/evidence.ts";
+import { readBounds } from "../core/read-bounds.ts";
+import { closestName, inputError, isJsonValue, type JsonValue, type ToolDiagnostic } from "../core/tool-contract.ts";
+import { planEdits, type EditSpec } from "../core/edit-plan.ts";
+import { toView } from "../core/text-normalize.ts";
+import { repairToolInput } from "../core/tool-input.ts";
+import { HISTORY_SECTIONS } from "../core/history.ts";
+import { parseDataQuery, queryData } from "../core/data-query.ts";
+import { readQuerySources } from "../store/query-source.ts";
+import {
+  askWithoutTtyMessage,
+  decide,
+  deniedMessage,
+  permissionRequest,
+  type PermissionRequest,
+  type PermissionRule,
+} from "../core/permissions.ts";
+import type { ToolSchema } from "./provider.ts";
+import { find as findFiles, grep, ls } from "../store/search.ts";
+import { scanWorkspace, workspaceVersion, DEFAULT_IGNORE } from "../store/workspace.ts";
+
+export interface ToolResult {
+  /** What the model sees. */
+  content: string;
+  ok: boolean;
+  /** Derived by the harness from the actual outcome. */
+  effect?: Effect;
+  content_ref?: ArtifactRef;
+  content_sha256?: string;
+  /** Observed bytes without presentation/version metadata, for D9 novelty. */
+  observation_sha256?: string;
+  outcome?: ExecutionOutcome;
+  data?: JsonValue;
+  diagnostic?: ToolDiagnostic;
+}
+
+export interface ToolContext {
+  /** O.1: per-execution copy; never mutate the session's shared tool context with a live signal. */
+  signal?: AbortSignal;
+  /** Absolute path. Every tool path is confined to this subtree. */
+  root: string;
+  /**
+   * Absolute path containing `root`: the boundary for model-supplied paths.
+   * Absent means `root`. Setting it wider lets file tools reach, say, /etc
+   * during an evaluation without making `root` -- the base for relative
+   * paths and the scope of every fingerprint and snapshot -- the whole disk.
+   */
+  pathRoot?: string;
+  /**
+   * Which tools this caller may run at all.
+   *
+   * Narrowing the schema tells a cooperative model what not to call; it is
+   * not a boundary, because a call that arrives anyway still executes. A
+   * read-only branch has to be unable to write even if it asks, so the
+   * allow-list lives on the context that runTool actually consults.
+   */
+  allow?: readonly string[];
+  /** Command names that count as verification gates, by leading token. */
+  gates: Record<string, string>;
+  /** Per-command wall-clock default. An unbounded wait is not allowed. */
+  timeoutMs: number;
+  /** Ceiling on a model-requested `timeout`; the schema maximum is advice, this is the bound. */
+  maxTimeoutMs?: number;
+  /** Tool output above this is truncated; the marker says how much was cut. */
+  maxOutputBytes: number;
+  outputStore?: string;
+  /**
+   * First-match permission rules. Absent means every call is allowed, which
+   * is what the existing tests rely on: they exercise the tool, not the gate.
+   * The CLI always supplies a list whose default is bash=ask.
+   */
+  rules?: readonly PermissionRule[];
+  /**
+   * Session-scoped remembers. Mutated in place, never written to disk: a
+   * persisted "always allow" would fire months later when nobody is watching.
+   */
+  sessionRules?: PermissionRule[];
+  /**
+   * Called when decide() returns ask. Tests set this directly. The CLI
+   * uses `askSlot` so the TUI can attach and detach without replacing
+   * the ToolContext object (sessionRules live on that object).
+   */
+  ask?: (request: PermissionRequest) => Promise<ApprovalChoice>;
+  /**
+   * Stable slot the TUI writes. A missing `current` is "no tty": the
+   * refusal then names `--allow-tools` rather than pretending someone
+   * said no.
+   */
+  askSlot?: { current?: (request: PermissionRequest) => Promise<ApprovalChoice> };
+}
+
+/**
+ * What the person picked at the approval prompt.
+ *
+ * `command` is only meaningful for bash, where the prompt shows the exact
+ * string. Other tools have no command to remember.
+ */
+export type ApprovalChoice = "once" | "command" | "tool" | "deny";
+
+export const DEFAULT_TOOL_CONTEXT: Omit<ToolContext, "root"> = {
+  // Runner prefixes are resolved in command position so `python3 -m pytest`
+  // works without letting `echo pytest` forge a gate (D11 / M.2).
+  gates: { pytest: "pytest", tsc: "typecheck", cargo: "cargo", jest: "test", vitest: "test" },
+  // Five minutes covers typical compiles and installs; longer work asks for
+  // its own `timeout` up to the hour ceiling (omp uses the same 300 / 3600).
+  // Approved change from 120s (2026-09-28): 120s hard-killed real builds.
+  timeoutMs: 300_000,
+  maxTimeoutMs: 3_600_000,
+  maxOutputBytes: 30_000,
+};
+
+const sha256 = (s: string | Uint8Array) => createHash("sha256").update(s).digest("hex");
+
+/**
+ * The configured gate a command counts as, if any.
+ *
+ * Matched in COMMAND POSITION only: the first token, or a token immediately
+ * after a runner prefix. The suite that proves something is frequently not
+ * the first word -- `python3 -m pytest`, `npx vitest run`, `uv run pytest` --
+ * so first-token matching misses real gates. But matching any token anywhere
+ * would let `echo pytest` count as a passing test suite, which is precisely
+ * the fake evidence the rest of this design exists to reject.
+ */
+export function matchGate(ctx: ToolContext, command: string): string | undefined {
+  return classifyGate(ctx.gates, command);
+}
+
+/**
+ * Confines a model-supplied path to the workspace root.
+ *
+ * Schema validation is not path validation: the model's `path` is untrusted
+ * output, and `../` in it would otherwise reach anywhere on the filesystem.
+ */
+function confine(ctx: ToolContext, path: string): string | { error: string } {
+  const abs = isAbsolute(path) ? resolve(path) : resolve(ctx.root, path);
+  const boundary = ctx.pathRoot ?? ctx.root;
+  if (!within(boundary, abs)) {
+    return { error: boundary === ctx.root ? `path escapes the workspace root: ${path}` : `path escapes the path root ${boundary}: ${path}` };
+  }
+  return abs;
+}
+
+function within(base: string, abs: string): boolean {
+  const rel = relative(base, abs);
+  return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
+}
+
+/** Search reports paths relative to, and applies ignores from, the root that holds the target. */
+const searchRoot = (ctx: ToolContext, abs: string) => within(ctx.root, abs) ? ctx.root : ctx.pathRoot ?? ctx.root;
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+export interface ToolDefinition extends ToolSchema {
+  access: "read" | "write" | "shell" | "state";
+  execution: "parallel" | "exclusive";
+  branch: "read" | "write" | "none";
+  /** Accepted by admission but not advertised to the model: harness and test switches. */
+  hiddenInputs?: readonly string[];
+  run?: (ctx: ToolContext, input: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export const TOOL_DEFINITIONS: ToolDefinition[] = [
+  {
+    name: "query",
+    access: "read", execution: "parallel", branch: "read", run: toolQuery,
+    description: "Compute over complete confined files (up to 32 MiB / 250000 records). Concatenates paths in order. CSV supports quoted records; JSON pointer selects nested data; JSONL parses each record; lines exposes line/text columns. Filter, group, aggregate and sort without shell or code execution. Returns full result with source hashes; large output has retrievable artifact pages. Numeric aggregates reject non-numeric values; empty/null values are excluded.",
+    input_schema: {
+      type: "object", required: ["paths", "format"], properties: {
+        paths: { type: "array", items: { type: "string" } },
+        format: { type: "string", enum: ["csv", "json", "jsonl", "lines"] },
+        pointer: { type: "string", description: "JSON pointer, e.g. /records" },
+        where: { type: "array", items: { type: "object", required: ["field", "op", "value"], properties: {
+          field: { type: "string" }, op: { type: "string", enum: ["eq", "ne", "contains", "gt", "gte", "lt", "lte"] }, value: {},
+        } } },
+        select: { type: "array", items: { type: "string" } },
+        group_by: { type: "array", items: { type: "string" } },
+        aggregate: { type: "array", items: { type: "object", required: ["op", "as"], properties: {
+          op: { type: "string", enum: ["count", "sum", "avg", "min", "max"] }, field: { type: "string" }, as: { type: "string" },
+        } } },
+        order_by: { type: "array", items: { type: "object", required: ["field"], properties: {
+          field: { type: "string" }, descending: { type: "boolean" },
+        } } },
+      },
+    },
+  },
+  {
+    name: "history",
+    access: "read", execution: "exclusive", branch: "read",
+    description: "Recover prior work: work_id and resource locate linked work and exact normalized paths; query adds literal AND keywords and shows up to 5 matching lines (hits) per result; recent lists activity. event reads original evidence; events reads 1..100 originals in request order and reports missing entries. Results keep version/replacement links and artifact pages. Also supports node/section handoff pages and artifact/offset. Active ancestry only.",
+    input_schema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        recent: { type: "boolean" },
+        event: { type: "string", description: "Exact source event id from query results" },
+        events: { type: "array", items: { type: "string" }, description: "1..100 exact event ids; preserves request order and identifies missing sources" },
+        resource: { type: "string", description: "Exact resource path, with ./ and repeated slashes normalized" },
+        work_id: { type: "string", description: "Canonical work ID returned by note" },
+        tool: { type: "string", description: "Optional tool name filter for query/recent" },
+        node: { type: "integer" },
+        artifact: { type: "string", description: "sha256 from a truncated tool observation; omit node and section" },
+        section: { type: "string", enum: [...HISTORY_SECTIONS] },
+        offset: { type: "integer", minimum: 0 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "read",
+    access: "read", execution: "parallel", branch: "read", run: toolRead,
+    description:
+      "Read a file. Returns the contents with 1-indexed line numbers. " +
+      "Optionally limit to an inclusive line range. Reports total lines and the next range; end beyond EOF is clamped. " +
+      "Reports sha256 for optional edit version checks. If the observation is truncated, recover its full artifact or smaller ranges before skipping ahead.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path relative to the workspace root" },
+        start: { type: "integer", minimum: 1, description: "First existing line, 1-indexed" },
+        end: { type: "integer", minimum: 1, description: "Last line, inclusive; capped at EOF" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "write",
+    access: "write", execution: "exclusive", branch: "write", run: toolWrite,
+    description: "Write a file, creating parent directories. Replaces existing content.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        content: { type: "string" },
+      },
+      required: ["path", "content"],
+    },
+  },
+  {
+    name: "edit",
+    access: "write", execution: "exclusive", branch: "write", run: toolEdit,
+    description:
+      "Replace exact text in a file. old_string must match once unless replace_all is set; copy it from read output, " +
+      "including indentation (line numbers are not part of the file). For several changes to one file pass edits[], " +
+      "each matched against the original; all apply or none do. If there is no exact match, a unique match that differs only in " +
+      "trailing whitespace, quote or dash style is applied and flagged fuzzy. A failure shows the closest text in the file. " +
+      "Pass expected_sha256 from read to reject stale edits.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        old_string: { type: "string", minLength: 1, description: "Exact text to replace, including indentation" },
+        new_string: { type: "string" },
+        replace_all: { type: "boolean" },
+        edits: { type: "array", minItems: 1, description: "Several replacements instead of old_string/new_string", items: {
+          type: "object", required: ["old_string", "new_string"], properties: {
+            old_string: { type: "string", minLength: 1 }, new_string: { type: "string" }, replace_all: { type: "boolean" },
+          } } },
+        expected_sha256: { type: "string", description: "Whole-file version returned by read; mismatch leaves the file unchanged" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    // The channel the handoff is built from. Without it every model-annotated
+    // field stays empty: no completion is ever recorded, so progress reads as
+    // zero and the stop-and-ask rule fires on a working session; and no next
+    // action survives a boundary, so the next node starts disoriented and
+    // spends a turn re-reading the workspace to find out where it was.
+    //
+    // One tool with a kind rather than six tools, because every tool schema is
+    // paid for in the prompt on every request.
+    name: "note",
+    access: "state", execution: "exclusive", branch: "read",
+    // Older spellings of proof that parseNote still reads; logs carry them.
+    hiddenInputs: ["gate", "command"],
+    description:
+      "Record something for the durable record that survives a context " +
+      "boundary. Use `done` the moment a command proves something works, and " +
+      "`next` before a long stretch of work so the next context knows where " +
+      "to resume. Also record decisions worth not relitigating and dead ends " +
+      "worth not retrying.",
+    input_schema: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "string",
+          enum: ["done", "next", "decision", "pitfall", "blocked", "question", "unblock", "reopen", "cancel", "pin"],
+          description:
+            "done: something is finished and a command proves it. " +
+            "next: work in progress plus its concrete next step. " +
+            "decision: a choice made, so it is not reargued. " +
+            "pitfall: something tried that failed, so it is not retried. " +
+            "blocked: work that cannot proceed. question: needs a human. " +
+            "unblock/reopen: reactivate identified work with a current next_action. cancel: abandon identified work. pin: associate an original tool event with existing work; this does not verify completion.",
+        },
+        what: { type: "string", description: "The thing, in one line" },
+        work_id: { type: "string", description: "Stable ID for next/blocked/done. Required for unblock/reopen/cancel; keep it when the title changes." },
+        event: { type: "string", description: "pin: original observation event ID returned by history" },
+        resource: { type: "string", description: "pin: optional source resource path" },
+        supersedes: { type: "string", description: "pin: explicitly replace an earlier pinned source event for the same work item" },
+        proof: {
+          type: "string",
+          description:
+            "done: the command you ran that proves it, exactly as you ran it. " +
+            "It is matched against the log, so it must have already run and " +
+            "exited zero in this session -- otherwise the claim is recorded " +
+            "as unverified.",
+        },
+        next_action: { type: "string", description: "next/unblock/reopen: the current concrete next step" },
+        why: { type: "string", description: "decision: why. pitfall: why it failed. blocked: why." },
+        rejected: {
+          type: "array", items: { type: "string" },
+          description: "decision: alternatives considered and not taken",
+        },
+      },
+      required: ["kind", "what"],
+    },
+  },
+  {
+    /**
+     * Read-only exploration in a separate node.
+     *
+     * The value is isolation: the branch's own tool calls stay in its node
+     * and only a summary comes back, so a search that reads twenty files
+     * costs the parent one paragraph. That is also the limit of when it pays
+     * -- each branch carries about 20k tokens of fixed overhead, and a
+     * measured fan-out ran 2.6x the tokens of the sequential path at roughly
+     * five times the cost, while being slower. Sequential is usually right.
+     */
+    name: "branch",
+    access: "state", execution: "exclusive", branch: "none",
+    description:
+      "Run a bounded subtask in a separate context and return its outcome and handoff reference. " +
+      "Read-only by default; writes=true uses an isolated git worktree. Include all required context in the prompt. " +
+      "Useful for independent exploration with much larger inputs than results; branch overhead can exceed doing small tasks directly. " +
+      "Adopt continues the selected branch and switches to its workspace; it does not merge edits into the original directory.",
+    input_schema: {
+      type: "object",
+      properties: {
+        purpose: { type: "string", description: "What this branch is for, in one line" },
+        prompt: {
+          type: "string",
+          description:
+            "The branch's entire instruction. It starts with no knowledge of " +
+            "this conversation, so include the file paths, error text and " +
+            "decisions it needs -- this string is the only channel.",
+        },
+        writes: {
+          type: "boolean",
+          description:
+            "Set only if the branch must change files. It then works in an " +
+            "isolated checkout; adopt switches to that checkout without merging into the parent. " +
+            "It requires a git repository. Leave it off " +
+            "for exploration, which is both cheaper and the common case.",
+        },
+      },
+      required: ["purpose", "prompt"],
+    },
+  },
+  {
+    name: "resolve",
+    access: "state", execution: "exclusive", branch: "none",
+    description:
+      "Adopt or discard a branch that has come back. Every branch must be " +
+      "resolved; an unresolved one stays an open question.",
+    input_schema: {
+      type: "object",
+      properties: {
+        node: { type: "number", description: "The branch's node number" },
+        resolution: { type: "string", enum: ["adopt", "discard"] },
+        why: { type: "string", description: "discard: why it was rejected" },
+      },
+      required: ["node", "resolution"],
+    },
+  },
+  {
+    name: "bash",
+    access: "shell", execution: "exclusive", branch: "write", run: toolBash,
+    description:
+      "Run a command with bash in a fresh non-interactive shell (no TTY; cwd, variables and `cd` do not persist between calls). " +
+      "Returns a header `exit N · wall time` with any timeout, then stdout and stderr interleaved; long output keeps its head and tail. " +
+      "Default timeout 300s; pass timeout for longer work. Start servers or watchers in the background with output redirected, " +
+      "e.g. `nohup cmd > server.log 2>&1 &`, then poll the log or port.",
+    input_schema: {
+      type: "object",
+      properties: {
+        command: { type: "string" },
+        timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the process group is killed; default 300" },
+        workdir: { type: "string", description: "Directory to run in, relative to the workspace root; default the root" },
+      },
+      required: ["command"],
+    },
+  },
+  {
+    name: "exec_command",
+    access: "shell", execution: "exclusive", branch: "write", run: toolExec,
+    description:
+      "Start a command that may keep running: a server, a REPL, a long build, or a program that asks for input. " +
+      "Waits up to yield_time_ms; if it has exited, returns `exit N · wall time` and its output like bash, otherwise " +
+      "`running · session <id>` with the output so far while the process keeps running. Continue with write_stdin. " +
+      "tty=true runs it in a terminal, for programs that need one (REPLs, prompts, curses). Prefer bash for commands that simply finish.",
+    input_schema: {
+      type: "object",
+      properties: {
+        cmd: { type: "string", description: "Shell command, run with bash -lc" },
+        workdir: { type: "string", description: "Directory to run in; default the workspace root" },
+        tty: { type: "boolean", description: "Run in a pseudo-terminal; default false" },
+        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "How long to wait before returning; default 10000" },
+        timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the session is killed; default 300" },
+      },
+      required: ["cmd"],
+    },
+  },
+  {
+    name: "write_stdin",
+    access: "shell", execution: "exclusive", branch: "write", run: toolWriteStdin,
+    description:
+      "Send characters to a running exec_command session and return the output since the last call. " +
+      "Empty chars polls. Include \\n to submit a line; \\u0003 is Ctrl-C, \\u0004 is Ctrl-D (end of input). " +
+      "When the process has exited, returns its exit code and the session closes.",
+    input_schema: {
+      type: "object",
+      properties: {
+        session_id: { type: "integer", minimum: 1 },
+        chars: { type: "string", description: "Characters to write; empty to poll" },
+        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "How long to wait for output; default 10000" },
+      },
+      required: ["session_id"],
+    },
+  },
+  {
+    name: "grep",
+    access: "read", execution: "parallel", branch: "read", run: toolGrep,
+    // Forces the TypeScript walk or ripgrep so both engines stay testable.
+    hiddenInputs: ["engine"],
+    description:
+      "Search file contents for a regex. Stays inside the workspace, does " +
+      "not follow symlinks, and skips .git, node_modules and .xeno. Uses " +
+      "ripgrep when it is already on PATH, otherwise a TypeScript walk. " +
+      "Truncates with a count of what was left out.",
+    input_schema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Regular expression to search for" },
+        path: { type: "string", description: "File or directory, relative to the workspace root" },
+        glob: { type: "string", description: "Only search files matching this glob" },
+        limit: { type: "number", description: "Maximum matches to return" },
+      },
+      required: ["pattern"],
+    },
+  },
+  {
+    name: "find",
+    access: "read", execution: "parallel", branch: "read", run: toolFind,
+    description:
+      "Find files by glob pattern. Stays inside the workspace, does not " +
+      "follow symlinks, and skips .git, node_modules and .xeno. Uses fd " +
+      "when it is already on PATH, otherwise a TypeScript walk.",
+    input_schema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Glob, e.g. '*.ts' or 'src/**/*.md'" },
+        path: { type: "string", description: "Directory, relative to the workspace root" },
+        limit: { type: "number", description: "Maximum paths to return" },
+      },
+      required: ["pattern"],
+    },
+  },
+  {
+    name: "ls",
+    access: "read", execution: "parallel", branch: "read", run: toolLs,
+    description:
+      "List a directory. Directories are marked with a trailing '/'. Stays " +
+      "inside the workspace, does not follow symlinks, and skips .git, " +
+      "node_modules and .xeno.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory, relative to the workspace root" },
+        limit: { type: "number", description: "Maximum entries to return" },
+      },
+      required: [],
+    },
+  },
+];
+
+/** Runtime policy metadata never leaks into provider-specific wire schemas. */
+export const TOOL_SCHEMAS: ToolSchema[] = TOOL_DEFINITIONS.map(({ name, description, input_schema }) => ({ name, description, input_schema }));
+
+export function toolDefinition(name: string): ToolDefinition | undefined {
+  return TOOL_DEFINITIONS.find(tool => tool.name === name);
+}
+
+// ---------------------------------------------------------------------------
+// Implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * Read limits. pi uses the same 2000 lines / 2000 characters: a page large
+ * enough that most source files arrive whole, small enough that a log file
+ * or a minified bundle cannot spend the observation budget on its own.
+ */
+const READ_DEFAULT_LINES = 2_000;
+const READ_MAX_LINE_CHARS = 2_000;
+
+function clipLine(line: string, number: number): string {
+  if (line.length <= READ_MAX_LINE_CHARS) return line;
+  return `${line.slice(0, READ_MAX_LINE_CHARS)} [line truncated: ${line.length} chars; see the rest with bash, e.g. \`sed -n '${number}p' FILE | cut -c${READ_MAX_LINE_CHARS + 1}-\`]`;
+}
+
+async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const path = String(input["path"] ?? "");
+  const abs = confine(ctx, path);
+  if (typeof abs !== "string") return { content: abs.error, ok: false };
+
+  let text: string;
+  let bytes: Uint8Array;
+  try {
+    bytes = await readFile(abs);
+    text = Buffer.from(bytes).toString("utf8");
+  } catch (err) {
+    return { content: `cannot read ${path}: ${(err as Error).message}`, ok: false };
+  }
+
+  if (bytes.subarray(0, 8_192).includes(0)) {
+    return { ok: false, content: `${path} looks binary (${bytes.length} bytes, contains NUL); inspect it with bash, e.g. \`file ${path}\` or \`xxd ${path} | head\`` };
+  }
+  const lines = toView(text).text.split("\n");
+  // Without an end, a read stops after READ_DEFAULT_LINES so one large file
+  // cannot take the whole observation budget; the notice names the next start.
+  const first = input["start"] ?? 1;
+  const end = input["end"] === undefined && Number.isSafeInteger(first) ? (first as number) + READ_DEFAULT_LINES - 1 : input["end"];
+  const selected = readBounds(lines.length, input["start"], end);
+  if (!selected.ok) return { ok: false, content: selected.message };
+  const { start } = selected;
+  const slice = lines.slice(start - 1, selected.end);
+  const numbered = slice.map((l, i) => `${start + i}\t${clipLine(l, start + i)}`).join("\n");
+
+  const ranges: LineRange[] = [[start, selected.end]];
+  return {
+    ...await presentObservation(ctx, `${selected.notice}\nsha256: ${sha256(bytes)}\n${numbered}`),
+    ok: true,
+    data: { path, sha256: sha256(bytes), start, end: selected.end, total_lines: lines.length, next_start: selected.end < lines.length ? selected.end + 1 : null },
+    observation_sha256: sha256(numbered),
+    // The digest is of the whole file, not the slice: it answers "has this
+    // file changed since the agent looked", which a partial read still bears on.
+    effect: { kind: "read", path, sha256: sha256(bytes), ranges },
+  };
+}
+
+async function toolWrite(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const path = String(input["path"] ?? "");
+  const content = String(input["content"] ?? "");
+  const abs = confine(ctx, path);
+  if (typeof abs !== "string") return { content: abs.error, ok: false };
+
+  let before: Uint8Array | null = null;
+  try {
+    before = await readFile(abs);
+  } catch (error) {
+    if ((error as { code?: string }).code !== "ENOENT") return { ok: false, content: `cannot fingerprint ${path}: ${String(error)}` };
+  }
+
+  try {
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, content, "utf8");
+  } catch (err) {
+    return { content: `cannot write ${path}: ${(err as Error).message}`, ok: false };
+  }
+
+  return {
+    content: `wrote ${new TextEncoder().encode(content).length} bytes to ${path}`,
+    ok: true,
+    data: { path, bytes: new TextEncoder().encode(content).length, sha256_before: before === null ? null : sha256(before), sha256_after: sha256(content) },
+    effect: {
+      kind: "edit",
+      path,
+      sha256_before: before === null ? null : sha256(before),
+      sha256_after: sha256(content),
+    },
+  };
+}
+
+async function toolEdit(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const path = String(input["path"] ?? "");
+  const edits: EditSpec[] = Array.isArray(input["edits"])
+    ? (input["edits"] as Record<string, unknown>[]).map((edit) => ({ old_string: String(edit["old_string"] ?? ""),
+      new_string: String(edit["new_string"] ?? ""), replace_all: edit["replace_all"] === true }))
+    : typeof input["old_string"] === "string"
+      ? [{ old_string: input["old_string"], new_string: String(input["new_string"] ?? ""), replace_all: input["replace_all"] === true }]
+      : [];
+  if (edits.length === 0) {
+    const message = "edit needs old_string and new_string, or edits[]";
+    return { ok: false, content: message, diagnostic: { code: "invalid_input", message } };
+  }
+
+  const abs = confine(ctx, path);
+  if (typeof abs !== "string") return { content: abs.error, ok: false };
+
+  let before: string;
+  try {
+    before = await readFile(abs, "utf8");
+  } catch (err) {
+    return { content: `cannot read ${path}: ${(err as Error).message}`, ok: false };
+  }
+
+  const version = sha256(before);
+  const recover = { tool: "read", input: { path } };
+  if (input["expected_sha256"] !== undefined && input["expected_sha256"] !== version) {
+    const message = `file version changed for ${path}; current sha256: ${version}. Read the current file before retrying.`;
+    return { ok: false, content: message, data: { path, sha256: version },
+      diagnostic: { code: "version_mismatch", message, recover } };
+  }
+  const plan = planEdits(before, edits);
+  if (!plan.ok) {
+    const closest = plan.closest === undefined ? "" :
+      `\nclosest match at lines ${plan.closest.startLine}-${plan.closest.endLine} (similarity ${plan.closest.score.toFixed(2)}); first difference:\n` +
+      `-${plan.closest.expected}\n+${plan.closest.actual}\n` +
+      `(- is your old_string, + is the file; retry with the file's text, or read lines ${plan.closest.startLine}-${plan.closest.endLine})`;
+    const message = `${plan.message} in ${path}`;
+    return { ok: false, content: `${message}${closest}\ncurrent sha256: ${version}`,
+      data: { path, sha256: version, occurrences: plan.occurrences, edit: plan.edit,
+        ...(plan.closest === undefined ? {} : { closest: { start_line: plan.closest.startLine, end_line: plan.closest.endLine, score: plan.closest.score } }) },
+      diagnostic: { code: plan.code, message, recover: plan.closest === undefined ? recover
+        : { tool: "read", input: { path, start: plan.closest.startLine, end: plan.closest.endLine } } } };
+  }
+  const { after } = plan;
+  try {
+    await writeFile(abs, after, "utf8");
+  } catch (err) {
+    return { content: `cannot write ${path}: ${(err as Error).message}`, ok: false };
+  }
+
+  const fuzzy = plan.fuzzy ? " (fuzzy: matched ignoring trailing whitespace, quote and dash style; check the diff)" : "";
+  return {
+    ...await presentObservation(ctx, `replaced ${plan.replacements} occurrence(s) in ${path}${fuzzy}\nsha256: ${sha256(after)}\n${plan.diff}`),
+    ok: true,
+    data: { path, replacements: plan.replacements, fuzzy: plan.fuzzy, first_changed_line: plan.firstLine, sha256_before: version, sha256_after: sha256(after) },
+    effect: {
+      kind: "edit",
+      path,
+      sha256_before: sha256(before),
+      sha256_after: sha256(after),
+    },
+  };
+}
+
+async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const command = String(input["command"] ?? "");
+  if (command.trim().length === 0) return { content: "empty command", ok: false };
+  const cwd = typeof input["workdir"] === "string" && input["workdir"].length > 0 ? confine(ctx, input["workdir"]) : ctx.root;
+  if (typeof cwd !== "string") return { content: cwd.error, ok: false };
+  const requestedMs = typeof input["timeout"] === "number" ? input["timeout"] * 1000 : undefined;
+  const timeoutMs = Math.min(requestedMs ?? ctx.timeoutMs, ctx.maxTimeoutMs ?? ctx.timeoutMs);
+
+  const captured = await observeCommand({ command, cwd,
+    outputStore: ctx.outputStore ?? join(ctx.root, ".xeno", "observations"),
+    maxOutputBytes: ctx.maxOutputBytes, timeoutMs,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
+  });
+
+  const gate = matchGate(ctx, command);
+  const exit = captured.exit;
+  const observed = await scanWorkspace(ctx.root, FINGERPRINT_IGNORE);
+  const header = commandHeader({ exit, wallMs: captured.wallMs, timeoutMs,
+    ...(requestedMs !== undefined ? { requestedMs } : {}),
+    ...(captured.stopped ? { stopped: captured.stopped } : {}) });
+
+  return {
+    // The artifact starts with `exit N\n`; the view replaces that line with
+    // the full header and pages the rest, so offsets stay artifact offsets.
+    content: header + "\n" + observationView(captured, ctx.maxOutputBytes - utf8Length(header) - 1, captured.prefixBytes),
+    content_ref: captured.ref,
+    ok: captured.stopped === undefined && exit === 0,
+    outcome: executionOutcome(captured.stopped ?? (exit === 0 ? "tool_completed" : "tool_failed")),
+    data: { exit, output: captured.ref },
+    effect: {
+      kind: "command",
+      cmd: command,
+      exit,
+      // Attached from configured patterns, never guessed from the text.
+      ...(gate !== undefined ? { gate } : {}),
+      ...(observed.ok ? { workspace_sha256: workspaceVersion(observed.files) } : {}),
+    },
+  };
+}
+
+/**
+ * Derived output a command's fingerprint leaves out.
+ *
+ * The fingerprint keys verification evidence to the source state it ran
+ * against; build products and caches change on every build without the
+ * sources changing, and walking them (a Rust `target/` or a virtualenv) costs
+ * seconds after every command. Snapshots and rewind keep DEFAULT_IGNORE --
+ * whether to restore derived files is their decision, not this one.
+ */
+const FINGERPRINT_IGNORE: readonly string[] = [...DEFAULT_IGNORE,
+  "target", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox",
+  ".gradle", ".next", ".turbo", ".cache"];
+
+const clampYield = (value: unknown) =>
+  Math.min(MAX_YIELD_MS, Math.max(MIN_YIELD_MS, typeof value === "number" && Number.isFinite(value) ? value : DEFAULT_YIELD_MS));
+
+async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const command = String(input["cmd"] ?? "");
+  if (command.trim().length === 0) return { content: "empty command", ok: false };
+  const cwd = typeof input["workdir"] === "string" && input["workdir"].length > 0 ? confine(ctx, input["workdir"]) : ctx.root;
+  if (typeof cwd !== "string") return { content: cwd.error, ok: false };
+  const requestedMs = typeof input["timeout"] === "number" ? input["timeout"] * 1000 : undefined;
+  const timeoutMs = Math.min(requestedMs ?? ctx.timeoutMs, ctx.maxTimeoutMs ?? ctx.timeoutMs);
+  const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
+  const session = await startSession({ command, cwd, tty: input["tty"] === true, timeoutMs, spoolDir: outputStore });
+  if ("error" in session) return { ok: false, content: session.error };
+  await waitSession(session, clampYield(input["yield_time_ms"]), ctx.signal);
+  return sessionResult(ctx, session.id, command, timeoutMs, await takeOutput(session, outputStore, ctx.maxOutputBytes));
+}
+
+async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const id = Number(input["session_id"]);
+  const session = findSession(id);
+  if (session === undefined) {
+    const running = runningSessions().map((s) => s.id).join(", ");
+    return { ok: false, content: `no running session ${id}` +
+      (running.length > 0 ? `; running sessions: ${running}` : "; sessions end when their process exits or xeno restarts") };
+  }
+  const chars = typeof input["chars"] === "string" ? input["chars"] : "";
+  if (chars.length > 0 && session.exit === null) session.write(chars);
+  await waitSession(session, clampYield(input["yield_time_ms"]), ctx.signal);
+  const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
+  return sessionResult(ctx, id, session.command, session.timeoutMs, await takeOutput(session, outputStore, ctx.maxOutputBytes));
+}
+
+/**
+ * One call's view of a session. A running session proves nothing yet, so it
+ * carries no effect; only an observed exit does, exactly as bash's would (D11).
+ */
+async function sessionResult(ctx: ToolContext, id: number, command: string, timeoutMs: number,
+  taken: Awaited<ReturnType<typeof takeOutput>>): Promise<ToolResult> {
+  const { stored, exit } = taken;
+  const header = exit === null
+    ? `running · session ${id} · ${(taken.wallMs / 1000).toFixed(1)}s elapsed; poll or send input with write_stdin(session_id=${id})`
+    : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed`;
+  const content = header + "\n" + observationView(stored, ctx.maxOutputBytes - utf8Length(header) - 1);
+  if (exit === null) {
+    return { ok: true, content, content_ref: stored.ref, data: { session_id: id, running: true, output: stored.ref } };
+  }
+  const gate = matchGate(ctx, command);
+  const observed = await scanWorkspace(ctx.root, FINGERPRINT_IGNORE);
+  return {
+    ok: exit === 0 && taken.stopped === undefined,
+    content, content_ref: stored.ref,
+    outcome: executionOutcome(taken.stopped ?? (exit === 0 ? "tool_completed" : "tool_failed")),
+    data: { session_id: id, running: false, exit, output: stored.ref },
+    effect: { kind: "command", cmd: command, exit, ...(gate !== undefined ? { gate } : {}),
+      ...(observed.ok ? { workspace_sha256: workspaceVersion(observed.files) } : {}) },
+  };
+}
+
+const utf8Length = (text: string) => new TextEncoder().encode(text).length;
+
+/**
+ * Head and tail of an archived observation, skipping its first `skip` bytes.
+ *
+ * The marker names the artifact and the byte offset where the gap starts, so
+ * the missing middle is one `history` call away rather than a rerun.
+ */
+function observationView(stored: ArchivedObservation, limit: number, skip = 0): string {
+  const { ref } = stored;
+  const marker = (omitted: number, offset: number) =>
+    `\n[truncated ${omitted} bytes at offset ${offset + skip}; full output: ${ref.path}; ` +
+    `history artifact=${ref.sha256} offset=${offset + skip}]\n`;
+  const total = ref.bytes - skip;
+  const tail = stored.tail.subarray(Math.max(0, stored.tail.length - total));
+  return headTailView(stored.head.subarray(skip), tail, total, Math.max(0, limit), marker);
+}
+
+export async function presentObservation(ctx: ToolContext, content: string): Promise<Pick<ToolResult, "content" | "content_ref" | "content_sha256">> {
+  const bytes = new TextEncoder().encode(content);
+  if (bytes.length <= ctx.maxOutputBytes) return { content, content_sha256: sha256(bytes) };
+  async function* source(): AsyncGenerator<Uint8Array> { yield bytes; }
+  const stored = await archiveObservation(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), source(), ctx.maxOutputBytes);
+  return { content: observationView(stored, ctx.maxOutputBytes), content_ref: stored.ref, content_sha256: stored.ref.sha256 };
+}
+
+function toolPath(ctx: ToolContext, input: Record<string, unknown>): string | { error: string } {
+  const path = typeof input["path"] === "string" && input["path"].length > 0 ? input["path"] : ".";
+  return confine(ctx, path);
+}
+
+function optionalLimit(input: Record<string, unknown>): number | undefined {
+  const n = input["limit"];
+  return typeof n === "number" && Number.isFinite(n) ? n : undefined;
+}
+
+function grepEngine(input: Record<string, unknown>): "auto" | "ripgrep" | "walk" {
+  const engine = input["engine"];
+  if (engine === "walk" || engine === "ripgrep") return engine;
+  return "auto";
+}
+
+async function toolGrep(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const abs = toolPath(ctx, input);
+  if (typeof abs !== "string") return { content: abs.error, ok: false };
+  const glob = typeof input["glob"] === "string" ? input["glob"] : undefined;
+  const limit = optionalLimit(input);
+  const result = await grep({
+    root: searchRoot(ctx, abs),
+    path: abs,
+    pattern: String(input["pattern"] ?? ""),
+    engine: grepEngine(input),
+    timeoutMs: ctx.timeoutMs,
+    ...(glob !== undefined ? { glob } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+  });
+  return { ...await presentObservation(ctx, result.content), ok: result.ok };
+}
+
+async function toolQuery(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const query = parseDataQuery(input);
+  const { text, sources } = await readQuerySources(ctx.root, input["paths"]);
+  const value = { sources, ...queryData(text, query) };
+  if (!isJsonValue(value)) throw new Error("query produced a non-JSON value");
+  const observation = await presentObservation(ctx, JSON.stringify(value));
+  return { ok: true, ...observation, data: observation.content_ref ? { artifact: observation.content_ref, format: "json" } : value };
+}
+
+async function toolFind(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const abs = toolPath(ctx, input);
+  if (typeof abs !== "string") return { content: abs.error, ok: false };
+  const limit = optionalLimit(input);
+  const result = await findFiles({
+    root: searchRoot(ctx, abs),
+    path: abs,
+    pattern: String(input["pattern"] ?? ""),
+    timeoutMs: ctx.timeoutMs,
+    ...(limit !== undefined ? { limit } : {}),
+  });
+  return { ...await presentObservation(ctx, result.content), ok: result.ok };
+}
+
+async function toolLs(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  const abs = toolPath(ctx, input);
+  if (typeof abs !== "string") return { content: abs.error, ok: false };
+  const limit = optionalLimit(input);
+  const result = await ls({
+    root: searchRoot(ctx, abs),
+    path: abs,
+    ...(limit !== undefined ? { limit } : {}),
+  });
+  return { ...await presentObservation(ctx, result.content), ok: result.ok };
+}
+
+/**
+ * Tools a read-only branch may use.
+ *
+ * Applied twice, deliberately. As a schema it tells the model what exists,
+ * which is what actually shapes behaviour. As `ToolContext.allow` it is
+ * enforced in runTool, because a narrowed schema is guidance and not a
+ * boundary -- a write call that arrives anyway would otherwise run.
+ */
+export const BRANCH_TOOL_NAMES = TOOL_DEFINITIONS.filter(tool => tool.branch === "read").map(tool => tool.name);
+
+/** Writing adds effects to the shared evidence tools; new readers cannot go missing. */
+export const WRITING_BRANCH_TOOL_NAMES = TOOL_DEFINITIONS.filter(tool => tool.branch !== "none").map(tool => tool.name);
+
+export function branchTools(writes = false): ToolSchema[] {
+  const allowed = new Set<string>(
+    writes ? WRITING_BRANCH_TOOL_NAMES : BRANCH_TOOL_NAMES,
+  );
+  return TOOL_SCHEMAS.filter((t) => allowed.has(t.name));
+}
+
+/**
+ * The door in front of every tool, including note/branch/resolve which
+ * the loop handles itself.
+ *
+ * A denial is a ToolResult, never an exception: an unanswered tool_use
+ * makes the next request unpairable. Same shape as a refused branch and
+ * an interrupt.
+ *
+ * Returns null when the call may proceed.
+ */
+export async function gateTool(
+  ctx: ToolContext,
+  name: string,
+  input: unknown,
+): Promise<ToolResult | null> {
+  if (ctx.signal?.aborted) return cancelledTool();
+  // Checked before decide, so a tool that left the schema cannot reach
+  // the approval prompt. The model should not have seen it; if a call
+  // arrives anyway it is answered, not executed.
+  if (ctx.allow && !ctx.allow.includes(name)) {
+    return {
+      content: `refused: ${name} is not available here (allowed: ${ctx.allow.join(", ")})`,
+      ok: false,
+    };
+  }
+  const definition = toolDefinition(name);
+  input = repairToolInput(name, input);
+  const invalid = definition ? inputError(definition.input_schema, input, "input", definition.hiddenInputs) : null;
+  if (invalid) return { ok: false, content: invalid, diagnostic: { code: "invalid_input", message: invalid } };
+  if (ctx.rules === undefined) return null;
+
+  const request = permissionRequest(name, input);
+  const rules = [...(ctx.sessionRules ?? []), ...ctx.rules];
+  const decision = decide(rules, request);
+  switch (decision) {
+    case "allow":
+      return null;
+    case "deny":
+      return { content: deniedMessage(request), ok: false };
+    case "ask": {
+      const ask = ctx.ask ?? ctx.askSlot?.current;
+      if (ask === undefined) {
+        return { content: askWithoutTtyMessage(request), ok: false };
+      }
+      const choice = await waitForAdmission(ask(request), ctx.signal);
+      if (choice === undefined || ctx.signal?.aborted) return cancelledTool();
+      switch (choice) {
+        case "once":
+          return null;
+        case "command": {
+          if (request.command !== undefined && ctx.sessionRules) {
+            ctx.sessionRules.unshift({
+              action: "allow",
+              tool: request.tool,
+              command: request.command,
+            });
+          }
+          return null;
+        }
+        case "tool": {
+          if (ctx.sessionRules) {
+            ctx.sessionRules.unshift({ action: "allow", tool: request.tool });
+          }
+          return null;
+        }
+        case "deny":
+          return { content: deniedMessage(request), ok: false };
+        default:
+          return assertNever(choice, "gateTool");
+      }
+    }
+    default:
+      return assertNever(decision, "gateTool");
+  }
+}
+
+export async function runTool(
+  ctx: ToolContext,
+  name: string,
+  input: unknown,
+): Promise<ToolResult> {
+  const prepared = await prepareTool(ctx, name, input);
+  return typeof prepared === "function" ? prepared() : prepared;
+}
+
+/** O.5: ordered admission returns a capability for this exact call, never a policy bypass flag. */
+export async function prepareTool(ctx: ToolContext, name: string, input: unknown): Promise<ToolResult | (() => Promise<ToolResult>)> {
+  const gated = await gateTool(ctx, name, input);
+  if (gated) return finishToolResult(gated);
+  return () => dispatchTool(ctx, name, input);
+}
+
+async function dispatchTool(ctx: ToolContext, name: string, input: unknown): Promise<ToolResult> {
+  if (ctx.signal?.aborted) return finishToolResult(cancelledTool());
+  const impl = toolDefinition(name)?.run;
+  if (!impl) {
+    const near = closestName(name, TOOL_DEFINITIONS.filter((tool) => tool.run !== undefined).map((tool) => tool.name));
+    return finishToolResult({ content: `unknown tool: ${name}` + (near === undefined ? "" : `; did you mean ${near}?`), ok: false });
+  }
+  if (typeof input !== "object" || input === null) {
+    return finishToolResult({ content: `tool ${name} needs an object input`, ok: false });
+  }
+  try {
+    const result = await impl(ctx, repairToolInput(name, input) as Record<string, unknown>);
+    return finishToolResult(result);
+  } catch (err) {
+    // A tool that throws must still produce a result: an unanswered tool_use
+    // makes the next request unpairable.
+    return finishToolResult({ content: `tool ${name} failed: ${(err as Error).message}`, ok: false });
+  }
+}
+
+/** One finalizer also covers session-owned tools; result text never determines success. */
+export function finishToolResult(result: ToolResult): ToolResult {
+  return { ...result, outcome: result.outcome ?? executionOutcome(result.ok ? "tool_completed" : "tool_failed"),
+    ...(!result.ok && !result.diagnostic ? { diagnostic: { code: "execution_failed" as const, message: result.content } } : {}) };
+}
+
+function cancelledTool(): ToolResult {
+  return { ok: false, content: "interrupted: cancelled before this tool started", outcome: executionOutcome("not_started") };
+}
+
+export async function workspaceRoot(path: string): Promise<string> {
+  const abs = resolve(path);
+  const s = await stat(abs);
+  if (!s.isDirectory()) throw new Error(`workspace root is not a directory: ${abs}`);
+  return abs;
+}
+
+// ---------------------------------------------------------------------------
+// Annotations
+// ---------------------------------------------------------------------------
+
+/**
+ * A `note` call, translated into the log event it records.
+ *
+ * Returned separately from ToolResult because these are not effects on the
+ * workspace: they are the model's own account of what it is doing, which the
+ * handoff carries across a boundary. They remain claims -- a `done` note is
+ * resolved against exit codes in the log, so one whose gate never passed
+ * surfaces as unverified rather than as completed.
+ */
+export type Annotation =
+  | {
+      t: "claim";
+      what: string;
+      evidence: { gate: string } | { command: string };
+      /** The raw citation, before the gate registry has had a say. */
+      proof?: string;
+      work_id?: string;
+    }
+  | { t: "next_action"; what: string; next_action: string; work_id?: string }
+  | { t: "decision"; chose: string; because: string; rejected?: readonly string[] }
+  | { t: "pitfall"; tried: string; failed_because: string }
+  | { t: "blocked"; what: string; reason: string; work_id?: string }
+  | { t: "work_status"; what: string; work_id: string; operation: "unblock" | "reopen" | "cancel"; next_action?: string; reason?: string }
+  | { t: "evidence_link"; what: string; work: string; source: string; resource?: string; supersedes?: string }
+  | { t: "question"; text: string };
+
+export interface NoteOutcome {
+  result: ToolResult;
+  annotation?: Annotation;
+}
+
+export function parseNote(input: unknown): NoteOutcome {
+  if (typeof input !== "object" || input === null) {
+    return { result: { content: "note needs an object input", ok: false } };
+  }
+  const o = input as Record<string, unknown>;
+  const kind = String(o["kind"] ?? "");
+  const what = String(o["what"] ?? "").trim();
+  const why = typeof o["why"] === "string" ? o["why"].trim() : "";
+  const id = o["work_id"];
+  if (id !== undefined && (typeof id !== "string" || !id.trim())) {
+    return { result: { ok: false, content: "work_id must be a non-empty string" } };
+  }
+  const identity = typeof id === "string" ? { work_id: id.trim() } : {};
+  if (id !== undefined && !["next", "done", "blocked", "unblock", "reopen", "cancel", "pin"].includes(kind)) {
+    return { result: { ok: false, content: "work_id applies to work lifecycle notes, not decisions, pitfalls or questions" } };
+  }
+
+  if (what.length === 0) {
+    return { result: { content: "note needs a non-empty `what`", ok: false } };
+  }
+
+  switch (kind) {
+    case "pin": {
+      const source = o["event"];
+      if (!identity.work_id || typeof source !== "string" || !source.trim()) return { result: { ok: false, content: "pin requires an existing work_id and original event id" } };
+      for (const key of ["resource", "supersedes"]) if (o[key] !== undefined && (typeof o[key] !== "string" || !o[key].trim())) return { result: { ok: false, content: `${key} must be a non-empty string` } };
+      return { result: { ok: true, content: "recorded evidence reference" }, annotation: { t: "evidence_link", what, work: identity.work_id, source,
+        ...(typeof o["resource"] === "string" ? { resource: o["resource"] } : {}),
+        ...(typeof o["supersedes"] === "string" ? { supersedes: o["supersedes"] } : {}) } };
+    }
+    case "done": {
+      // Accepts the older field names too: a model that writes `gate` or
+      // `command` meant the same thing, and refusing on the field name would
+      // lose a real claim over a schema detail.
+      const proof = ["proof", "gate", "command"]
+        .map((k) => (typeof o[k] === "string" ? String(o[k]).trim() : ""))
+        .find((v) => v.length > 0);
+      if (!proof) {
+        return {
+          result: {
+            content:
+              "a `done` note must cite the command that proves it; run the " +
+              "proving command first, then record it",
+            ok: false,
+          },
+        };
+      }
+      // Whether this is a gate name or a raw command is the harness's
+      // question, not the model's -- ctx decides, in the loop.
+      return {
+        result: { content: `recorded: done "${what}" (proof: ${proof})`, ok: true },
+        annotation: { t: "claim", what, evidence: { command: proof }, proof, ...identity },
+      };
+    }
+    case "next": {
+      const next = typeof o["next_action"] === "string" ? o["next_action"].trim() : "";
+      if (next.length === 0) {
+        return { result: { content: "a `next` note needs a concrete next_action", ok: false } };
+      }
+      return {
+        result: { content: `recorded: next "${what}" -> ${next}`, ok: true },
+        annotation: { t: "next_action", what, next_action: next, ...identity },
+      };
+    }
+    case "decision": {
+      if (why.length === 0) {
+        return { result: { content: "a `decision` note needs `why`", ok: false } };
+      }
+      const rejected = Array.isArray(o["rejected"])
+        ? (o["rejected"] as unknown[]).map(String)
+        : undefined;
+      return {
+        result: { content: `recorded: decision "${what}"`, ok: true },
+        annotation: {
+          t: "decision", chose: what, because: why,
+          ...(rejected && rejected.length > 0 ? { rejected } : {}),
+        },
+      };
+    }
+    case "pitfall": {
+      if (why.length === 0) {
+        return { result: { content: "a `pitfall` note needs `why` it failed", ok: false } };
+      }
+      return {
+        result: { content: `recorded: pitfall "${what}"`, ok: true },
+        annotation: { t: "pitfall", tried: what, failed_because: why },
+      };
+    }
+    case "blocked": {
+      return {
+        result: { content: `recorded: blocked "${what}"`, ok: true },
+        annotation: { t: "blocked", what, reason: why || "no reason given", ...identity },
+      };
+    }
+    case "unblock":
+    case "reopen":
+    case "cancel": {
+      if (identity.work_id === undefined) return { result: { ok: false, content: `${kind} requires an existing work_id` } };
+      const next = typeof o["next_action"] === "string" ? o["next_action"].trim() : "";
+      if (kind !== "cancel" && !next) return { result: { ok: false, content: `${kind} requires a current next_action` } };
+      return { result: { ok: true, content: `recorded: ${kind} ${identity.work_id}` },
+        annotation: { t: "work_status", work_id: identity.work_id, what, operation: kind,
+          ...(kind !== "cancel" ? { next_action: next } : {}), ...(why ? { reason: why } : {}) } };
+    }
+    case "question": {
+      return {
+        result: { content: `recorded: question "${what}"`, ok: true },
+        annotation: { t: "question", text: what },
+      };
+    }
+    default:
+      return {
+        result: {
+          content: `unknown note kind "${kind}"; use done, next, decision, pitfall, blocked, question, unblock, reopen or cancel`,
+          ok: false,
+        },
+      };
+  }
+}