@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/tools.ts

@@ -1,1820 +0,0 @@
-/**
- * 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.
- *
- * P.3 separates shell execution facts from recoverable file changes. Commands
- * observe a bounded source scope for verification; optional file checkpoints
- * belong to the admitted execution boundary, not session startup or turn end.
- */
-
-import { readFile, stat } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { hostname } from "node:os";
-import { resolve, relative, isAbsolute, join, sep } from "node:path";
-import type { Effect, LineRange, ArtifactRef, ApprovalEvent } from "../core/events.ts";
-import { archiveObservation, readObservation, type ArchivedObservation } from "../store/observations.ts";
-import { blobAddress } from "../store/blobs.ts";
-import { commandHeader, foldCarriageReturns, headTailView } from "../core/observation-view.ts";
-import {
-  yieldWait, emptyYieldWait, findSession, closedSession, runningSessions, startSession, pollSession, isControlInput,
-} from "./exec-sessions.ts";
-import { recoverProcessReceipt, type ProcessReceipt, type latestProcessReceipt } from "../core/process-receipt.ts";
-import { observeCommand, observeArgvCommand } from "../store/command.ts";
-import { executionOutcome, type ExecutionOutcome } from "../core/outcome.ts";
-import { commandCompletion, commandTimeout, commandAnswer, outputBytesForTokens } from "../core/command-contract.ts";
-import { linesWithin, previewReadObservation, readObservationText, type ObservationReceipt } from "../core/read-observation.ts";
-import { checkFilePrecondition, isFileDigest, isFileReadDescriptor, type FileReadDescriptor, type FilePrecondition } from "../core/file-precondition.ts";
-import { previewSearchObservation, searchObservationText } from "../core/search-observation.ts";
-import { waitForAdmission } from "./execution-control.ts";
-import { assertNever } from "../core/exhaustive.ts";
-import { artifactRecovery, toolDescription, type ToolGuidance } from "../core/prompt-policy.ts";
-import { classifyGate } from "../core/evidence.ts";
-import { readBounds, readNotice } from "../core/read-bounds.ts";
-import { closestName, inputError, isJsonValue, minimalInput, type JsonValue, type ToolDiagnostic } from "../core/tool-contract.ts";
-import { failureDiagnostic, failureFromError, scopeFailureGuidance, NOT_STARTED, READ_ATTEMPTED, UNKNOWN_EFFECT, type FailureFacts } from "../core/tool-failure.ts";
-import { planEdits, type EditSpec } from "../core/edit-plan.ts";
-import { toView } from "../core/text-normalize.ts";
-import { nearestPaths } from "../core/path-suggestions.ts";
-import { buildFileIndex, MAX_INDEX_ENTRIES } from "../store/file-index.ts";
-import { repairToolInput } from "../core/tool-input.ts";
-import { HISTORY_SECTIONS } from "../core/history.ts";
-import { RECOVERY_SECTIONS } from "../core/recovery-sources.ts";
-import { queryData } from "../core/data-query.ts";
-import { parseQueryInput, MAX_SQL_CHARS, SQL_QUERY_HELP } from "../core/sql-query.ts";
-import { readQuerySources } from "../store/query-source.ts";
-import {
-  approvalNeeded,
-  askWithoutTtyMessage,
-  deniedMessage,
-  describeRule,
-  explainDecision,
-  permissionRequest,
-  type PermissionRequest,
-  type PermissionRule,
-} from "../core/permissions.ts";
-import type { ToolSchema } from "./provider.ts";
-import type { HistoryCache } from "./history-cache.ts";
-import type { ImageRef } from "../core/images.ts";
-import { imageDescription } from "../core/images.ts";
-import { attachImageBytes } from "./images.ts";
-import { detectSupportedImageMimeType } from "../vendor/pi-rich/mime.ts";
-import { find as findFiles, grep, ls, MAX_FILE_BYTES, MAX_SEARCH_CAPTURE_BYTES, type SearchResult } from "../store/search.ts";
-import { DEFAULT_IGNORE } from "../store/workspace.ts";
-import { observeWorkspace } from "../store/workspace-observation.ts";
-import { readEditableFile, replaceFile } from "../store/file-checkpoints.ts";
-import type { WorkspaceLifecycle } from "./workspace-lifecycle.ts";
-import { environmentProbeCommand } from "../core/environment.ts";
-import { observeEnvironment } from "./environment-tools.ts";
-import { beginCommandArtifacts, prepareArtifactArguments, commandArtifactSummary } from "./command-artifacts.ts";
-import { MAX_COMMAND_ARTIFACTS } from "../core/command-artifacts.ts";
-import { checkSourceCancellation } from "../store/source-cancellation.ts";
-import { canonicalPermissionRequest } from "../store/permission-paths.ts";
-import { permissionResourceAction, permissionResourceDecision } from "./permission-resources.ts";
-import { parsePatch, patchPaths } from "../core/patch.ts";
-import { decideWithSessionRules } from "../core/permissions.ts";
-
-export interface ToolResult {
-  /** Broker-owned identity, returned to a composer only after the original receipt commits. */
-  invocation?: { call_id: string; event: string };
-  images?: readonly ImageRef[];
-  /** 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;
-  observation?: ObservationReceipt;
-  outcome?: ExecutionOutcome;
-  data?: JsonValue;
-  diagnostic?: ToolDiagnostic;
-  warnings?: readonly ToolDiagnostic[];
-  /** Scoped instructions attached to a read-only call that ran (S.6 item 3). */
-  instructions?: { keys: readonly string[]; text: string };
-}
-
-/**
- * What target-scoped instruction discovery decided for one call: hold a change
- * back until the rules are read, or let a read-only call run and carry them.
- */
-export type InstructionCheck =
-  | { kind: "block"; result: ToolResult }
-  | { kind: "attach"; instructions: { keys: readonly string[]; text: string } };
-
-export interface ToolContext {
-  /** S.9: placeholders back to values, applied after admission and only to what the tool itself runs. */
-  expandSecrets?: (input: unknown) => unknown;
-  historyEvents?: () => Promise<import("../core/events.ts").LogEvent[]>;
-  checkpointBlobs?: string;
-  frozenSystem?: () => string;
-  instructionCheck?: (ctx: ToolContext, name: string, input: unknown) => Promise<InstructionCheck | null>;
-  workflowMode?: "build" | "plan";
-  /** What a Plan-mode refusal tells the model instead of the default "select Build". */
-  planHint?: string;
-  /** CLI owns its approval defaults; SDK callers retain their supplied host policy across reload. */
-  appOwnsPermissions?: true;
-  hostPermissionRules?: PermissionRule[];
-  questionSlot?: import("./question-tool.ts").QuestionSlot;
-  /** R10: model-visible names constrain new advice without granting tool admission. */
-  advice?: readonly string[];
-  /** Runtime adapter identity, never supplied by a model tool argument. */
-  hostId?: string;
-  /** R4: trusted Session projection over original log ancestry, never model input. */
-  observedFileVersion?: (absolute: string) => Promise<string | undefined>;
-  /** R7: original active ancestry, scoped by Session rather than a model-supplied log path. */
-  observedProcess?: (session: number) => Promise<ReturnType<typeof latestProcessReceipt>>;
-  /** P.3: admitted execution owns file recovery; extensions cannot supply model-authored effects. */
-  workspace?: WorkspaceLifecycle;
-  ownedStatePaths?: readonly string[];
-  /** O.15: optional disposable view; the reader still validates the original log. */
-  historyCache?: HistoryCache;
-  /** O.14: opaque process ownership is supplied by Session, never by model input. */
-  execOwner?: string;
-  /** Session-owned empty stdin waits; low-level/native callers retain bounded polling. */
-  processWait?: { wake(): AbortSignal };
-  onProcessWait?: (session: number, active: boolean) => void;
-  /** Session-owned registrations never mutate the built-in table (D13). */
-  extensions?: ReadonlyMap<string, ToolDefinition>;
-  /** R11: current locally selected optional schemas, never restored as authority from historical text. */
-  deferredTools?: readonly ToolSchema[];
-  callId?: string;
-  parentCallId?: string;
-  /** Pi A: a live composing scope supplied by Session, never model arguments. */
-  invoke?: (name: string, input: unknown, options?: NestedInvocationOptions) => Promise<ToolResult>;
-  /** Trusted extension host capability. Never exposed in ExtensionContext or a provider schema. */
-  invokeHost?: (input: NativeCommandInput, signal?: AbortSignal) => Promise<ToolResult>;
-  runOwnedCommand?: (execute: () => Promise<ToolResult>) => Promise<ToolResult>;
-  drainNested?: () => Promise<void>;
-  origin?: "extension";
-  readonlyBranch?: boolean;
-  extensionDepth?: number;
-  extensionHooks?: {
-    serial?(): boolean;
-    scope?<T>(ctx: ToolContext, action: () => T): T;
-    before(name: string, input: unknown, id: string | undefined, parentId?: string): Promise<string | undefined>;
-    event(type: string, fields: Record<string, unknown>): Promise<void>;
-  };
-  imageStore?: string;
-  imageAutoResize?: boolean;
-  /** 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;
-  /** O.12: exact frozen skill resources can be read without widening the path boundary. */
-  skillResources?: readonly { path: string; text: string; modelInvocable: boolean }[];
-  /**
-   * 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;
-  onOutput?: (chunk: Uint8Array) => void;
-  /**
-   * 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> };
-  /**
-   * Receives the gate's verdict for a call that needed one, and is awaited
-   * before the call may start (feat-approval-events). The session appends it
-   * as an `approval` event; absent, nothing is recorded.
-   */
-  onApproval?: (approval: ApprovalRecord) => Promise<void>;
-}
-
-/** The `approval` event without the identity the log assigns. */
-export type ApprovalRecord = Omit<ApprovalEvent, "t" | "id" | "at">;
-
-export interface NestedInvocationOptions { signal?: AbortSignal }
-
-/**
- * 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). make, just
-  // and task are not keys: their targets are matched against these keys
-  // (`make test check-shell`), because a bare `make` runs an unknown goal.
-  gates: { pytest: "pytest", tsc: "typecheck", cargo: "cargo", jest: "test", vitest: "test", go: "go",
-    test: "test", typecheck: "typecheck", check: "check", build: "build", lint: "lint", gate: "gate" },
-  // 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");
-
-function failure(code: ToolDiagnostic["code"], content: string, facts: FailureFacts = NOT_STARTED,
-  extra: Pick<ToolDiagnostic, "recover" | "example"> = {}): ToolResult {
-  return { ok: false, content, diagnostic: failureDiagnostic(code, content, facts, extra) };
-}
-
-function caughtFailure(error: unknown, facts: FailureFacts, prefix = ""): ToolResult {
-  const diagnostic = failureFromError(error, facts);
-  return { ok: false, content: prefix + diagnostic.message, diagnostic };
-}
-
-/**
- * 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. Each segment
- * of an `&&` chain is matched the same way; see classifyGate.
- */
-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;
-}
-
-/**
- * Assumed budget for listing the workspace after a failed lookup. The hint is
- * a convenience on a failure path: past this the failure is returned without
- * it rather than held up.
- */
-const PATH_SUGGESTION_DEADLINE_MS = 2_000;
-
-/** A not_found for a workspace path names the closest existing paths (missing-path-candidates card). */
-async function withPathSuggestions(ctx: ToolContext, path: string, result: ToolResult): Promise<ToolResult> {
-  if (result.ok || result.diagnostic?.code !== "not_found") return result;
-  const abs = isAbsolute(path) ? resolve(path) : resolve(ctx.root, path);
-  if (!within(ctx.root, abs)) return result;
-  let listed: readonly string[];
-  try {
-    listed = (await buildFileIndex(ctx.root, { maxEntries: MAX_INDEX_ENTRIES, deadline: performance.now() + PATH_SUGGESTION_DEADLINE_MS,
-      ...(ctx.signal ? { signal: ctx.signal } : {}) })).paths;
-  } catch { return result; } // No listing, no hint; the failure itself stands.
-  const near = nearestPaths(relative(ctx.root, abs).split(sep).join("/"), listed.map(item => item.split(sep).join("/")));
-  if (near.length === 0) return result;
-  const hint = "\nDid you mean one of these existing paths?\n" + near.map(item => `  ${item}`).join("\n");
-  return { ...result, content: result.content + hint, diagnostic: { ...result.diagnostic, message: result.diagnostic.message + hint } };
-}
-
-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 {
-  /** Q.18: opt-in builtins are absent from every default profile, including full. */
-  optional?: boolean;
-  /** Q.13: current adapter observation only; excluded from the frozen model schema. */
-  integrationHealth?: () => import("./integrations.ts").IntegrationObservation;
-  /** R10: optional companion advice is rendered only for the actual builtin capabilities. */
-  guidance?: readonly ToolGuidance[];
-  example?: { readonly [key: string]: JsonValue };
-  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[];
-  prepareArguments?: (input: unknown) => unknown;
-  /** Protocol adapters with complete schemas own validation, rather than the builtin vocabulary. */
-  validateInput?: (input: unknown) => void;
-  run?: (ctx: ToolContext, input: Record<string, unknown>) => Promise<ToolResult>;
-}
-
-const commandArtifactsSchema = {
-  type: "object", required: ["paths"], additionalProperties: false,
-  description: "Optionally observe up to 16 workspace-relative ordinary output files before/after this command (512 MiB per phase). Records digests and input scope, not proof of production or runtime acceptance. Missing/unstable files remain unknown; the command exit is retained.",
-  properties: {
-    paths: { type: "array", minItems: 1, maxItems: MAX_COMMAND_ARTIFACTS, items: { type: "string" } },
-    output_roots: { type: "array", minItems: 1, maxItems: MAX_COMMAND_ARTIFACTS, items: { type: "string" },
-      description: "Nonoverlapping output directories/files excluded from the input fingerprint, each covering requested files. Defaults to paths. Never exclude source inputs." },
-  },
-};
-
-export const TOOL_DEFINITIONS: ToolDefinition[] = [
-  {
-    name: "query",
-    example: { paths: ["data.csv"], format: "csv", aggregate: [{ op: "count", as: "rows" }] },
-    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" },
-        sql: { type: "string", maxLength: MAX_SQL_CHARS, description: SQL_QUERY_HELP + " Example: SELECT category, SUM(amount) AS total FROM source GROUP BY category ORDER BY total DESC. Mutually exclusive with JSON operators. Fields preserve case and use exact-key-first dotted lookup. Uses the JSON query kernel: numeric literals coerce nonempty numeric strings; ordering keeps string values lexical; COUNT(field) excludes null/missing/empty strings. SQL-style, not ANSI SQL." },
-        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: "target",
-    guidance: [{ requires: ["write_stdin"], text: "Continue or stop the returned handle with write_stdin." }],
-    access: "shell", execution: "exclusive", branch: "write",
-    description: "Start or inspect a runtime declared by the trusted acceptance contract. Start requires a matching successful build command with the exact declared artifacts plan. Launches literal argv under this session's process owner; never adopts a PID or reuses an existing server. Inspect checks current build inputs, entry, executable and optional IPv4 loopback port ownership. Ready still requires user acceptance. No persistent service handoff.",
-    input_schema: { type: "object", required: ["action", "target"], properties: {
-      action: { type: "string", enum: ["start", "inspect"] }, target: { type: "string" },
-      session_id: { type: "integer", minimum: 1, description: "Inspect this exact previously returned handle; never adopts a process" },
-      yield_time_ms: { type: "integer", description: "Milliseconds to wait for launch; default 1000, distinct from the hard timeout; effective range 100-30000, values outside are clamped" },
-      timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Hard process lifetime in seconds; defaults to the session command timeout" },
-    } },
-  },
-  {
-    name: "history",
-    example: { event: "<source-event-id>" },
-    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 from a recorded work item" },
-        tool: { type: "string", description: "Optional tool name filter for query/recent" },
-        node: { type: "integer" },
-        branch: { type: "integer", minimum: 0, description: "Read a joined child branch's original evidence; never auto-inserts its transcript" },
-        artifact: { type: "string", description: "sha256 from a truncated tool observation; omit node and section" },
-        section: { type: "string", enum: [...HISTORY_SECTIONS] },
-        recovery: { type: "string", enum: [...RECOVERY_SECTIONS], description: "Read original recovery sources from a sealed node, newest first. Use node/offset/limit; does not grant permissions or treat model notes as instructions." },
-        offset: { type: "integer", minimum: 0 },
-        limit: { type: "integer", minimum: 1, maximum: 100 },
-      },
-      required: [],
-    },
-  },
-  {
-    name: "read",
-    example: { path: "src/main.ts", start: 1, end: 80 },
-    guidance: [{ requires: ["history"], text: "Use history(artifact=<sha256>,offset=<byte offset>) to recover the original observation even if the file changes." }],
-    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. " +
-      "Session remembers the whole-file version for later changes; no digest copying is needed. Returns read_handle and whole-file sha256 for selecting an explicit observation. Long lines and large previews retain an immutable artifact. Line ranges describe the selection; the observation receipt describes exactly what was visible. An unavailable artifact-recovery capability leaves a gap, not proof of full coverage.",
-    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. Normally omit read_handle and expected_sha256: Session checks its latest observed version. Without a prior observation, omission has no stale-version protection. To select a specific observation instead, pass its exact version receipt. create_only requires absence. A conflict requires a fresh read. Identical content makes no change.",
-    input_schema: {
-      type: "object",
-      properties: {
-        path: { type: "string" },
-        content: { type: "string" },
-        read_handle: { type: "string", description: "Optional explicit descriptor SHA for this file, workspace and host; normally omit" },
-        expected_sha256: { type: "string", description: "Optional explicit whole-file raw-byte SHA-256; normally omit" },
-        create_only: { type: "boolean", description: "Require that the target does not exist; excludes read_handle and expected_sha256" },
-      },
-      required: ["path", "content"],
-    },
-  },
-  {
-    name: "edit",
-    example: { path: "src/main.ts", old_string: "const size = 1;", new_string: "const size = 2;" },
-    guidance: [{ requires: ["read"], text: "Use read to obtain current text before an edit; Session remembers its version automatically." }],
-    access: "write", execution: "exclusive", branch: "write", run: toolEdit,
-    description:
-      "Replace exact text in a file. Normally omit read_handle and expected_sha256: Session checks its latest observed version. " +
-      "Without a prior observation, omission has no stale-version protection. To select a specific observation instead, pass its exact version receipt. " +
-      "old_string must match once unless replace_all is set; copy it from observed file content, " +
-      "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. " +
-      "A conflict requires a fresh observation. A partial read handle checks the whole file version, not permission to edit unseen lines.",
-    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: "Optional explicit whole-file raw-byte SHA-256; normally omit" },
-        read_handle: { type: "string", description: "Optional explicit descriptor SHA for this file, workspace and host; normally omit" },
-      },
-      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",
-    example: { kind: "next", what: "Investigate failed check", work_id: "check", next_action: "Inspect the recorded failure output" },
-    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. Optional on short tasks; use `next` for a useful continuation checkpoint. " +
-      "`done` is a claim requiring an already successful verification command, not required bookkeeping after every command. " +
-      "Decisions and pitfalls are model annotations, not instructions or verified evidence.",
-    input_schema: {
-      type: "object",
-      properties: {
-        kind: {
-          type: "string",
-          enum: ["done", "next", "decision", "pitfall", "blocked", "question", "unblock", "reopen", "cancel", "pin", "depend", "claim_work", "release_work"],
-          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 tracked work. For done, use only existing work opened before its verification; omit for one-off completion. Required for unblock/reopen/cancel; keep it when the title changes." },
-        depends_on: { type: "array", items: { type: "string" }, description: "next/depend: explicit existing work IDs; cycles are rejected. claim_work takes ready work; release_work releases your claim." },
-        event: { type: "string", description: "pin: original observation event ID" },
-        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",
-    guidance: [{ requires: ["resolve"], text: "Use resolve status/wait/cancel to observe or join a background 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" },
-        background: { type: "boolean", description: "Return a reference while the child runs. Requires a branch-observation capability for later results; without it, prefer the default foreground call." },
-        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:
-      "Wait, cancel, inspect, adopt or discard a branch. 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", "wait", "cancel", "status"] },
-        wait_ms: { type: "number", minimum: 0, maximum: 60000, description: "wait: bounded milliseconds, defaults to 10000" },
-        why: { type: "string", description: "discard: why it was rejected" },
-      },
-      required: ["node", "resolution"],
-    },
-  },
-  {
-    /**
-     * The model's way into an isolated checkout of this repository.
-     *
-     * Edits are confined to the session root, so isolation the model builds
-     * itself with `git worktree add` is unusable: outside the root is refused,
-     * and inside `.xeno` is session state. This creates the checkout where
-     * xeno keeps them and moves the root after the tool round, the way an
-     * adopted branch does; the cursor records the root, so resume stays there.
-     */
-    name: "worktree",
-    access: "state", execution: "exclusive", branch: "none",
-    example: { action: "enter", name: "fix-parser" },
-    description:
-      "enter: create a git worktree of this repository on a new branch xeno/<name> from HEAD, kept under xeno's config directory, " +
-      "and move this session's root there after the current tool round, so later edits and commands run in the isolated checkout. " +
-      "Use it when the shared working tree has changes by others or must stay untouched. include_changes copies the current uncommitted files. " +
-      "exit: move the root back to the repository's main checkout. The worktree and its branch are kept; nothing is merged or deleted.",
-    input_schema: {
-      type: "object",
-      properties: {
-        action: { type: "string", enum: ["enter", "exit"] },
-        name: { type: "string", description: "enter: letters, digits, dot, dash or underscore; becomes the branch xeno/<name>" },
-        include_changes: { type: "boolean", description: "enter: start from the current uncommitted files instead of HEAD; default false" },
-      },
-      required: ["action"],
-    },
-  },
-  {
-    name: "bash",
-    example: { command: "bun test", workdir: ".", timeout: 300 },
-    guidance: [{ requires: ["exec_command", "write_stdin"], text: "For foreground servers or interactive input, use exec_command and observe the handle with write_stdin." }],
-    access: "shell", execution: "exclusive", branch: "write", run: toolBash,
-    prepareArguments: prepareArtifactArguments,
-    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 300 seconds; pass timeout for longer work. Timeout or cancellation cleans the process group. " +
-      "Normal shell exit can leave background children; this call exposes no handle for later control. Keep work in the foreground and do not start detached servers or watchers here.",
-    input_schema: {
-      type: "object",
-      properties: {
-        command: { type: "string" },
-        artifacts: commandArtifactsSchema,
-        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: "environment",
-    example: { program: "python3", probe: "python" },
-    access: "shell", execution: "exclusive", branch: "write", run: toolEnvironment,
-    description: "Probe one program in the same fresh login Bash as commands. Requires shell permission. Returns the resolved executable, reported version, source identity, observation time and raw output reference. probe=python uses isolated Python to inspect actual tarfile.extractall filter support. Every call probes again; old observations can expire or be invalidated. This describes this executor only, not an SSH target or another container. Functions and aliases require an exact executable path. Bounded to 5s and an output stop budget of 256 KiB; large or incomplete reports remain unconfirmed.",
-    hiddenInputs: ["command"],
-    prepareArguments(input) {
-      if (input === null || typeof input !== "object" || Array.isArray(input)) return input;
-      const args = input as Record<string, unknown>;
-      return { ...args, probe: args["probe"] ?? "version", command: environmentProbeCommand(args["program"], args["probe"] ?? "version") };
-    },
-    input_schema: { type: "object", required: ["program"], properties: {
-      program: { type: "string", description: "Executable name or literal path; never shell code. Prefer the exact interpreter used by the failing command." },
-      probe: { type: "string", enum: ["version", "python"], description: "version runs --version (default); python observes the actual interpreter API in isolated mode." },
-      workdir: { type: "string", description: "Directory to run in, relative to the workspace root; default the root" },
-    } },
-  },
-  {
-    name: "exec_command",
-    example: { cmd: "bun test", workdir: ".", yield_time_ms: 1000, timeout: 300 },
-    guidance: [{ requires: ["write_stdin"], text: "Continue the returned handle with write_stdin until exit; empty chars polls without replaying the command." }],
-    access: "shell", execution: "exclusive", branch: "write", run: toolExec,
-    prepareArguments: prepareArtifactArguments,
-    description:
-      "Start a command that may keep running: a server, a REPL, a long build, or a program that asks for input. " +
-      "Uses a fresh login shell; set workdir because cwd and variables do not persist. " +
-      "Waits up to yield_time_ms milliseconds; if it has exited, returns `exit N · wall time` and its output, otherwise " +
-      "`running · session <id>` with the output so far while the process keeps running. Running is not completion; if no handle-observation capability is available, report unfinished execution rather than rerunning it. " +
-      "tty=true runs it in a terminal for REPLs and prompts. Keep servers in the foreground: the owned group is cleaned when the command exits, times out, or its xeno session closes. " +
-      "A wait deadline only ends this call; timeout is the command's hard deadline. No persistent service handoff.",
-    input_schema: {
-      type: "object",
-      properties: {
-        cmd: { type: "string", description: "Shell command, run with bash -o pipefail -lc" },
-        artifacts: commandArtifactsSchema,
-        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", description: "Milliseconds to wait before returning; default 10000; effective range 100-30000, values outside are clamped" },
-        max_output_tokens: { type: "integer", minimum: 1, description: "Lower this call's inline output preview to about this many tokens; full output stays recoverable" },
-        timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the session is killed; default 300" },
-      },
-      required: ["cmd"],
-    },
-  },
-  {
-    name: "write_stdin",
-    example: { session_id: 1, chars: "", yield_time_ms: 1000 },
-    access: "shell", execution: "exclusive", branch: "write", run: toolWriteStdin,
-    description:
-      "Send characters to an owned running process handle and return the output since the last call. " +
-      "In an agent session, empty chars waits for new output, exit, hard timeout, cancellation or user steering without periodic model polling. Include \\n to submit a line; \\u0003 is Ctrl-C, \\u0004 is Ctrl-D (end of input). " +
-      "After exit, empty chars retrieves the last receipt without rerunning or producing fresh verification. Source and byte cursor are in data; full_output recovers all captured output. " +
-      "Lost handles cannot accept input; a last running observation is not an exit. Ctrl-C may interrupt a PTY foreground job while its REPL stays alive.",
-    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", description: "Bounded wait when sending input or using low-level polling, effective range 100-30000; an agent's empty wait returns at exit or at the end of a window with new output, window default 10000, effective range 5000-300000; values outside are clamped" },
-        max_output_tokens: { type: "integer", minimum: 1, description: "Lower this call's inline output preview to about this many tokens; full output stays recoverable" },
-      },
-      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 on PATH or in xeno's bin directory, otherwise a TypeScript walk. " +
-      "Reports scan completeness separately from preview truncation. Long matches and omitted results remain in an immutable history artifact; use its sha256 and byte offset to recover them. Unknown or partial coverage cannot prove absence.",
-    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. Omitted paths remain in a history artifact; scan completeness is reported separately.",
-    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. Omitted entries remain in a history artifact with exact byte offsets.",
-    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 function modelToolSchema(tool: ToolSchema & Pick<ToolDefinition, "guidance" | "example">, builtins: readonly string[]): ToolSchema {
-  const description = toolDescription(tool.description, tool.guidance ?? [], builtins);
-  return { name: tool.name, description: description + (tool.example ? ` Example input (paths and IDs are illustrative): ${JSON.stringify(tool.example)}` : ""), input_schema: tool.input_schema };
-}
-
-export const ALL_TOOL_SCHEMAS: ToolSchema[] = TOOL_DEFINITIONS.map(tool => modelToolSchema(tool, TOOL_DEFINITIONS.map(item => item.name)));
-export const TOOL_SCHEMAS: ToolSchema[] = TOOL_DEFINITIONS.filter(tool => !tool.optional).map(tool => modelToolSchema(tool, TOOL_DEFINITIONS.filter(item => !item.optional).map(item => item.name)));
-
-export function toolDefinition(name: string, ctx?: ToolContext): ToolDefinition | undefined {
-  return ctx?.extensions?.get(name) ?? TOOL_DEFINITIONS.find(tool => tool.name === name);
-}
-
-/** Visible builtin contracts only; a same-named extension does not implement that contract. */
-export function adviceTools(ctx: ToolContext): string[] {
-  return TOOL_DEFINITIONS.map(tool => tool.name).filter(name => !ctx.extensions?.has(name) &&
-    (ctx.advice === undefined || ctx.advice.includes(name)) &&
-    (ctx.allow === undefined || ctx.allow.includes(name)) &&
-    decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], { tool: name }) !== "deny");
-}
-
-/** A proposed recovery is data, not execution. Validate it against today's exact admission inputs. */
-function scopeToolAdvice(ctx: ToolContext, result: ToolResult): ToolResult {
-  const names = adviceTools(ctx);
-  const scope = (diagnostic: ToolDiagnostic): ToolDiagnostic => {
-    let allowed = false;
-    const recover = diagnostic.recover;
-    if (recover && names.includes(recover.tool)) {
-      try {
-        const input = normalizeToolInput(ctx, recover.tool, recover.input);
-        const definition = toolDefinition(recover.tool, ctx)!;
-        allowed = inputError(definition.input_schema, input, "input", definition.hiddenInputs) === null &&
-          decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], permissionRequest(recover.tool, input)) !== "deny";
-      } catch { /* Unavailable or invalid advice is omitted; the original failure remains. */ }
-    }
-    return scopeFailureGuidance(diagnostic, names, allowed);
-  };
-  return { ...result, ...(result.diagnostic ? { diagnostic: scope(result.diagnostic) } : {}),
-    ...(result.warnings ? { warnings: result.warnings.map(scope) } : {}) };
-}
-
-export const NATIVE_COMMAND_NAME = "$extension.exec";
-export interface NativeCommandInput { argv: string[]; cwd?: string; timeout?: number }
-export interface NativeCommandResult { stdout: string; stderr: string; code: number; killed: boolean }
-
-/** Pi A: host authority is installed by the broker, not selected by a model parameter. */
-export function nativeCommandContext(ctx: ToolContext, signal?: AbortSignal): ToolContext {
-  return { ...ctx, origin: "extension", allow: ctx.readonlyBranch ? [] : [NATIVE_COMMAND_NAME], rules: [], sessionRules: [],
-    extensions: new Map([[NATIVE_COMMAND_NAME, nativeCommandDefinition]]),
-    ...(signal ? { signal: ctx.signal ? AbortSignal.any([ctx.signal, signal]) : signal } : {}) };
-}
-
-const nativeCommandDefinition: ToolDefinition = {
-  name: NATIVE_COMMAND_NAME, description: "Trusted local extension command with literal argv and independent pipe artifacts.",
-  access: "write", execution: "exclusive", branch: "none",
-  input_schema: { type: "object", properties: { argv: { type: "array", minItems: 1, items: { type: "string" } },
-    cwd: { type: "string" }, timeout: { type: "number", exclusiveMinimum: 0 } }, required: ["argv"] },
-  run: async (ctx, input) => {
-    const argv = input["argv"] as string[];
-    const requested = input["timeout"] as number | undefined;
-    if (requested !== undefined && (!Number.isFinite(requested) || requested <= 0)) return failure("invalid_input", "native timeout must be positive milliseconds");
-    const timeoutMs = commandTimeout(requested === undefined ? undefined : requested / 1000, ctx.timeoutMs, ctx.maxTimeoutMs);
-    const captured = await observeArgvCommand({ argv, cwd: typeof input["cwd"] === "string" ? resolve(ctx.root, input["cwd"]) : ctx.root,
-      outputStore: ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), maxOutputBytes: ctx.maxOutputBytes, timeoutMs,
-      ...(ctx.signal ? { signal: ctx.signal } : {}), ...(ctx.onOutput ? { onOutput: ctx.onOutput } : {}) });
-    // A display representation only: execution above never reparses a command string.
-    const command = argv.map(arg => "'" + arg.replaceAll("'", "'\\''") + "'").join(" ");
-    const gate = matchGate(ctx, command);
-    const header = commandHeader({ exit: captured.exit, wallMs: captured.wallMs, timeoutMs,
-      ...(requested !== undefined ? { requestedMs: requested } : {}), ...(captured.stopped ? { stopped: captured.stopped } : {}) });
-    return { ...commandCompletion(captured.exit, captured.stopped, captured.cleanup),
-      content: header + "\n" + observationView(captured, ctx.maxOutputBytes - utf8Length(header) - 1, captured.prefixBytes, adviceTools(ctx)),
-      content_ref: captured.ref,
-      data: { code: captured.exit, killed: captured.stopped !== undefined, capture: captured.capture, stdout: captured.stdout, stderr: captured.stderr,
-        ...(captured.cleanup ? { cleanup: "unknown" } : {}) },
-      effect: { kind: "command", cmd: command, exit: captured.exit, ...(gate ? { gate } : {}), ...await commandFingerprint(ctx) } };
-  },
-};
-
-/** SDK strings are hydrated from integrity-checked artifacts after the independent receipt commits. */
-export async function nativeCommandResult(result: ToolResult, store: string): Promise<NativeCommandResult> {
-  if (result.effect?.kind !== "command" || typeof result.data !== "object" || !result.data || Array.isArray(result.data)) throw new Error(result.content);
-  const data = result.data as { code: number; killed: boolean; capture: string; stdout: ArtifactRef; stderr: ArtifactRef };
-  if ("cleanup" in data && data.cleanup === "unknown") throw new Error("native command exited but process-group cleanup is unconfirmed; inspect the retained receipt before retrying");
-  if (data.capture !== "complete") throw new Error("native command exited but pipe capture is partial; inspect the retained receipt before retrying");
-  const [stdout, stderr] = await Promise.all([data.stdout, data.stderr].map(ref => readObservation(store, ref.sha256, 0, Math.max(1, ref.bytes))));
-  return { stdout: stdout!.text, stderr: stderr!.text, code: data.code, killed: data.killed };
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-
-async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  const path = String(input["path"] ?? "");
-  const resource = ctx.skillResources?.find(item => item.path === resolve(ctx.root, path));
-  if (resource && !resource.modelInvocable) return failure("permission_denied", "this skill requires explicit user invocation");
-  const abs = resource ? resource.path : confine(ctx, path);
-  if (typeof abs !== "string") return failure("permission_denied", abs.error);
-
-  let text: string;
-  let bytes: Uint8Array;
-  try {
-    checkSourceCancellation(ctx.signal);
-    bytes = resource ? new TextEncoder().encode(resource.text) : await readFile(abs, ctx.signal ? { signal: ctx.signal } : {});
-    checkSourceCancellation(ctx.signal);
-    text = Buffer.from(bytes).toString("utf8");
-  } catch (err) {
-    return withPathSuggestions(ctx, path, caughtFailure(err, READ_ATTEMPTED, `cannot read ${path}: `));
-  }
-
-  if (ctx.imageStore && detectSupportedImageMimeType(bytes)) {
-    const image = await attachImageBytes(bytes, path, ctx.imageStore, ctx.imageAutoResize ?? true);
-    return { ok: true, content: imageDescription(image), images: [image], effect: { kind: "read", path, sha256: blobAddress(bytes) } };
-  }
-  if (bytes.subarray(0, 8_192).includes(0)) {
-    return failure("invalid_input", `${path} looks binary (${bytes.length} bytes, contains NUL); use a binary inspection tool such as xxd if permitted`, READ_ATTEMPTED);
-  }
-  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 bounds = readBounds(lines.length, input["start"], end);
-  if (!bounds.ok) return failure("invalid_input", bounds.message, READ_ATTEMPTED);
-  const { start } = bounds;
-  const version = sha256(bytes);
-  // The selection is what fits whole, so the receipt's range is the range shown.
-  const sized = (count: number, handle: string) =>
-    `${readNotice(start, start + count - 1, lines.length, count < bounds.end - start + 1 ? ctx.maxOutputBytes : undefined)}\nsha256: ${version}\nread_handle: ${handle}\n`;
-  const shown = linesWithin(count => sized(count, "0".repeat(64)), lines.slice(start - 1, bounds.end), start, ctx.maxOutputBytes, undefined, adviceTools(ctx));
-  const selected = { end: start + shown - 1 };
-  const slice = lines.slice(start - 1, selected.end);
-  const store = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  async function* one(value: Uint8Array): AsyncGenerator<Uint8Array> { yield value; }
-  // Archive actual bytes before either presentation cut. Re-reading the current file is not recovery.
-  const raw = await archiveObservation(store, one(bytes), 0);
-  const source = { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), resource: abs, sha256: version, raw: raw.ref };
-  const selection = { start, end: selected.end, total_lines: lines.length };
-  const descriptor: FileReadDescriptor = { kind: "file_read", version: 1, source, selection };
-  const handle = await archiveObservation(store, one(new TextEncoder().encode(JSON.stringify(descriptor))), 0);
-  const header = sized(shown, handle.ref.sha256);
-  const full = new TextEncoder().encode(readObservationText(header, slice, start));
-  const observation = await archiveObservation(store, one(full), 0);
-  const preview = previewReadObservation(header, slice, start, observation.ref.sha256, ctx.maxOutputBytes, undefined, adviceTools(ctx));
-
-  const ranges: LineRange[] = [[start, selected.end]];
-  return {
-    content: preview.text, content_ref: observation.ref, content_sha256: observation.ref.sha256,
-    observation: { version: 1, source, artifact: observation.ref, descriptor: handle.ref, selection, preview: preview.preview },
-    ok: true,
-    data: { path, sha256: version, read_handle: handle.ref.sha256, start, end: selected.end, total_lines: lines.length, next_start: selected.end < lines.length ? selected.end + 1 : null },
-    observation_sha256: sha256(preview.semantic),
-    // 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: version, ranges },
-  };
-}
-
-/** Read descriptors are CAS data, not executable state or an alternate permission path. */
-async function filePrecondition(ctx: ToolContext, input: Record<string, unknown>, absolute: string, current: string | null):
-  Promise<{ ok: true; precondition: FilePrecondition } | { ok: false; result: ToolResult }> {
-  const path = String(input["path"]), handle = input["read_handle"] as string | undefined;
-  const expected = input["expected_sha256"] as string | undefined, createOnly = input["create_only"] === true;
-  const recover = { tool: "read", input: { path } };
-  const reject = (code: ToolDiagnostic["code"], message: string): { ok: false; result: ToolResult } => ({ ok: false,
-    result: { ...failure(code, message, READ_ATTEMPTED, { recover }), data: { path, sha256: current } } });
-  let descriptor: FileReadDescriptor | undefined;
-  if (handle !== undefined) {
-    if (!isFileDigest(handle)) return reject("invalid_input", "read_handle must be a descriptor SHA-256 returned by read");
-    try {
-      // Assumed metadata budget: descriptors contain identity and range, never file text.
-      const page = await readObservation(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), handle, 0, 64 * 1024);
-      if (page.next !== null) return reject("invalid_input", "read_handle descriptor exceeds the 64 KiB metadata limit");
-      const value: unknown = JSON.parse(page.text);
-      if (!isFileReadDescriptor(value)) return reject("invalid_input", "read_handle does not name a file read descriptor");
-      descriptor = value;
-    } catch { return reject("not_found", "read_handle descriptor is missing, corrupt, or unreadable; read the file here again"); }
-  }
-  const observed = handle === undefined && expected === undefined && !createOnly ? await ctx.observedFileVersion?.(absolute) : undefined;
-  const decision = checkFilePrecondition({ host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), resource: absolute }, current, {
-    ...(descriptor === undefined ? {} : { descriptor }), ...(handle === undefined ? {} : { read_handle: handle }),
-    ...(expected === undefined ? {} : { expected_sha256: expected }), ...(observed === undefined ? {} : { observed }), create_only: createOnly,
-  });
-  if (decision.ok) return decision;
-  const rejected = reject(decision.code, `${decision.message} (${path})`);
-  if (decision.precondition) rejected.result.data = { path, sha256: current, precondition: { ...decision.precondition } };
-  return rejected;
-}
-
-async function fileCommitFailure(ctx: ToolContext, absolute: string, path: string, error: unknown): Promise<ToolResult> {
-  const result = caughtFailure(error, UNKNOWN_EFFECT, `cannot write ${path}: `);
-  if (result.diagnostic?.code !== "version_mismatch") return result;
-  try {
-    const current = await readEditableFile(ctx.pathRoot ?? ctx.root, absolute);
-    const version = current.bytes === null ? null : sha256(current.bytes);
-    return { ...result, content: `${result.content}\ncurrent sha256: ${version ?? "absent"}`, data: { path, sha256: version } };
-  } catch { return result; } // A failed follow-up observation cannot invent the current version.
-}
-
-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 failure("permission_denied", abs.error);
-
-  const saved = await readEditableFile(ctx.pathRoot ?? ctx.root, abs);
-  const before = saved.bytes;
-  const previous = before === null ? null : sha256(before), after = new TextEncoder().encode(content), version = sha256(after);
-  const checked = await filePrecondition(ctx, input, abs, previous);
-  if (!checked.ok) return checked.result;
-  const data = { path, bytes: after.length, sha256_before: previous, sha256_after: version, precondition: { ...checked.precondition } };
-  if (previous === version) return { ok: true, content: `no change to ${path}; sha256: ${version}`, data: { ...data, changed: false } };
-
-  try {
-    await commitEdit(ctx, abs, saved, after);
-  } catch (err) {
-    return fileCommitFailure(ctx, abs, path, err);
-  }
-
-  return {
-    content: `wrote ${new TextEncoder().encode(content).length} bytes to ${path}`,
-    ok: true,
-    data: { ...data, changed: true },
-    effect: {
-      kind: "edit",
-      path,
-      sha256_before: previous,
-      sha256_after: version,
-    },
-  };
-}
-
-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 failure("invalid_input", message);
-  }
-
-  const abs = confine(ctx, path);
-  if (typeof abs !== "string") return failure("permission_denied", abs.error);
-
-  const saved = await readEditableFile(ctx.pathRoot ?? ctx.root, abs);
-  const version = saved.bytes === null ? null : sha256(saved.bytes);
-  const checked = await filePrecondition(ctx, input, abs, version);
-  if (!checked.ok) return checked.result;
-  if (saved.bytes === null) return withPathSuggestions(ctx, path, failure("not_found", `cannot read ${path}: file does not exist`, READ_ATTEMPTED));
-  const recover = { tool: "read", input: { path } };
-  let before: string;
-  try { before = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(saved.bytes); }
-  catch { return failure("invalid_input", `cannot edit ${path}: invalid UTF-8; byte-preserving inspection is required`, READ_ATTEMPTED); }
-  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: failureDiagnostic(plan.code, message, READ_ATTEMPTED, { recover: plan.closest === undefined ? recover
-        : { tool: "read", input: { path, start: plan.closest.startLine, end: plan.closest.endLine } } }) };
-  }
-  const { after } = plan;
-  try {
-    await commitEdit(ctx, abs, saved, new TextEncoder().encode(after));
-  } catch (err) {
-    return fileCommitFailure(ctx, abs, path, err);
-  }
-
-  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, changed: true, precondition: { ...checked.precondition }, replacements: plan.replacements, fuzzy: plan.fuzzy, first_changed_line: plan.firstLine, sha256_before: version, sha256_after: sha256(after) },
-    effect: {
-      kind: "edit",
-      path,
-      sha256_before: version,
-      sha256_after: sha256(after),
-    },
-  };
-}
-
-async function toolEnvironment(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  const cwd = typeof input["workdir"] === "string" && input["workdir"].length > 0 ? confine(ctx, input["workdir"]) : ctx.root;
-  if (typeof cwd !== "string") return failure("permission_denied", cwd.error);
-  const result = await observeEnvironment(ctx, cwd, String(input["program"]), input["probe"] === "python" ? "python" : "version", String(input["command"]));
-  return result.effect?.kind === "command" ? { ...result, effect: { ...result.effect, ...await commandFingerprint(ctx) } } : result;
-}
-
-async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  const command = String(input["command"] ?? "");
-  if (command.trim().length === 0) return failure("invalid_input", "empty command");
-  const cwd = typeof input["workdir"] === "string" && input["workdir"].length > 0 ? confine(ctx, input["workdir"]) : ctx.root;
-  if (typeof cwd !== "string") return failure("permission_denied", cwd.error);
-  const requestedMs = typeof input["timeout"] === "number" ? input["timeout"] * 1000 : undefined;
-  const timeoutMs = commandTimeout(typeof input["timeout"] === "number" ? input["timeout"] : undefined, ctx.timeoutMs, ctx.maxTimeoutMs);
-
-  const observer = await beginCommandArtifacts(ctx, command, cwd, input["artifacts"]);
-  if (ctx.signal?.aborted) return cancelledTool();
-  const captured = await observeCommand({ command, cwd,
-    outputStore: ctx.outputStore ?? join(ctx.root, ".xeno", "observations"),
-    maxOutputBytes: ctx.maxOutputBytes, timeoutMs,
-    ...(ctx.signal ? { signal: ctx.signal } : {}),
-    ...(ctx.onOutput ? { onOutput: ctx.onOutput } : {}),
-  });
-
-  const gate = matchGate(ctx, command);
-  const exit = captured.exit;
-  const artifacts = await observer?.finish(captured);
-  const observation = await commandFingerprint(ctx);
-  const header = commandHeader({ exit, wallMs: captured.wallMs, timeoutMs,
-    ...(requestedMs !== undefined ? { requestedMs } : {}),
-    ...(captured.stopped ? { stopped: captured.stopped } : {}) }) + answerLabel(command, exit, captured.stopped);
-  const artifactSummary = commandArtifactSummary(artifacts);
-
-  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.
-    // Folding only shrinks the view; the artifact and its offsets keep every byte.
-    content: header + artifactSummary + "\n" + foldCarriageReturns(observationView(captured,
-      ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, captured.prefixBytes, adviceTools(ctx))),
-    content_ref: captured.ref,
-    ...commandCompletion(exit, captured.stopped, captured.cleanup, command),
-    data: { exit, output: captured.ref, ...(captured.cleanup ? { cleanup: "unknown" } : {}), ...(artifacts ? { artifacts } : {}) },
-    effect: {
-      kind: "command",
-      cmd: command,
-      exit,
-      // Attached from configured patterns, never guessed from the text.
-      ...(gate !== undefined ? { gate } : {}),
-      ...observation,
-      ...(artifacts ? { artifacts } : {}),
-    },
-  };
-}
-
-async function commitEdit(ctx: ToolContext, absolute: string, before: Awaited<ReturnType<typeof readEditableFile>>, after: Uint8Array): Promise<void> {
-  const path = relative(ctx.root, absolute);
-  if (ctx.workspace && path !== ".." && !path.startsWith(`..${sep}`)) await ctx.workspace.edit(path, before, after, ctx.signal);
-  else await replaceFile(ctx.pathRoot ?? ctx.root, absolute, before.version, after, before.version?.mode ?? (0o666 & ~process.umask()), ctx.signal);
-}
-
-async function commandFingerprint(ctx: ToolContext): Promise<{ workspace_sha256?: string; workspace_observed?: boolean; workspace_scope?: "source-v1" }> {
-  const observed = await observeWorkspace(ctx.root, ctx.signal, ctx.ownedStatePaths);
-  return observed.ok ? { workspace_sha256: observed.fingerprint, workspace_observed: true, workspace_scope: "source-v1" } : { workspace_observed: false, workspace_scope: "source-v1" };
-}
-
-
-async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  const command = String(input["cmd"] ?? "");
-  if (command.trim().length === 0) return failure("invalid_input", "empty command");
-  const cwd = typeof input["workdir"] === "string" && input["workdir"].length > 0 ? confine(ctx, input["workdir"]) : ctx.root;
-  if (typeof cwd !== "string") return failure("permission_denied", cwd.error);
-  const timeoutMs = commandTimeout(typeof input["timeout"] === "number" ? input["timeout"] : undefined, ctx.timeoutMs, ctx.maxTimeoutMs);
-  const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  const artifactObserver = await beginCommandArtifacts(ctx, command, cwd, input["artifacts"]);
-  if (ctx.signal?.aborted) return cancelledTool();
-  const session = await startSession({ command, cwd, tty: input["tty"] === true, timeoutMs, spoolDir: outputStore,
-    source: { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd, runtime: `bun/${Bun.version}` },
-    ...(artifactObserver ? { artifactObserver } : {}),
-    ...(ctx.execOwner === undefined ? {} : { owner: ctx.execOwner }) });
-  if ("error" in session) return failure("execution_failed", session.error);
-  const wait = yieldWait(input["yield_time_ms"]);
-  const view = { ...ctx, maxOutputBytes: outputBytesForTokens(input["max_output_tokens"], ctx.maxOutputBytes) };
-  return sessionResult(view, command, timeoutMs, await pollSession(session, outputStore, view.maxOutputBytes, wait.ms, "", ctx.signal), wait.note);
-}
-
-async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  const id = Number(input["session_id"]);
-  const chars = typeof input["chars"] === "string" ? input["chars"] : "";
-  const session = findSession(id, ctx.execOwner);
-  if (session === undefined) {
-    const closed = closedSession(id, ctx.execOwner);
-    // Ctrl-C / Ctrl-D to a closed handle asks for what its exit already did: answer as a poll.
-    const input = isControlInput(chars) ? "" : chars;
-    if (closed) return receiptResult(ctx, { ...closed.receipt, replayed: true }, input);
-    const original = await ctx.observedProcess?.(id);
-    if (original) return receiptResult(ctx, recoverProcessReceipt(original.receipt, original.origin), input);
-    const running = runningSessions(ctx.execOwner).map((s) => s.id).join(", ");
-    return { ...failure("unknown_effect", `no running session ${id}; no observation in this session's active history` +
-      (running.length > 0 ? `; running sessions: ${running}` : ""), UNKNOWN_EFFECT),
-      data: { kind: "process", version: 1, session_id: id, state: "unknown", capability: "unknown", source: null, running: null, exit: null, replayed: true } };
-  }
-  const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  const owner = chars.length === 0 ? ctx.processWait : undefined;
-  const wait = owner ? emptyYieldWait(input["yield_time_ms"]) : yieldWait(input["yield_time_ms"]);
-  const view = { ...ctx, maxOutputBytes: outputBytesForTokens(input["max_output_tokens"], ctx.maxOutputBytes) };
-  return sessionResult(view, session.command, session.timeoutMs, await pollSession(session, outputStore, view.maxOutputBytes, wait.ms, chars, ctx.signal,
-    owner ? { wake: owner.wake(), onWaiting: active => ctx.onProcessWait?.(id, active), windowMs: wait.ms } : undefined), wait.note);
-}
-
-/** A successful historical query proves only that the receipt was found, never a new command exit. */
-function receiptResult(ctx: ToolContext, receipt: ProcessReceipt, chars: string): ToolResult {
-  const location = receipt.origin ? `; original node ${receipt.origin.node} event ${receipt.origin.event}` : "";
-  const observed = receipt.running === false ? `last observed ${receipt.state}, exit ${receipt.exit}` : "last observed running; current process state unknown";
-  const artifact = receipt.full_output ?? receipt.output;
-  const content = `session ${receipt.session_id}: ${observed}; control ${receipt.capability}; historical receipt, no execution${location}` + commandArtifactSummary(receipt.artifacts) +
-    (artifact ? `\nCaptured output: ${artifactRecovery(artifact.sha256, 0, adviceTools(ctx))}` : "");
-  return { ...(chars.length > 0 ? failure("not_found", "no live handle; input was not sent", NOT_STARTED)
-    : receipt.running === false ? { ok: true } : failure("unknown_effect", "live handle lost; inspect existing state before replay", UNKNOWN_EFFECT)),
-    content: content + (chars.length > 0 ? "\nInput was not sent: no live handle." : ""), data: receipt,
-    ...(receipt.output ? { content_ref: receipt.output, content_sha256: receipt.output.sha256 } : {}) };
-}
-
-/**
- * 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).
- */
-export async function sessionResult(ctx: ToolContext, command: string, timeoutMs: number,
-  taken: Awaited<ReturnType<typeof pollSession>>, waitNote = ""): Promise<ToolResult> {
-  const { stored, exit } = taken;
-  const id = taken.receipt.session_id;
-  if (taken.receipt.replayed) return receiptResult(ctx, taken.receipt, "");
-  const shown = exit === null
-    ? `running · session ${id} · ${(taken.wallMs / 1000).toFixed(1)}s elapsed; ` + (adviceTools(ctx).includes("write_stdin")
-      ? `poll or send input with write_stdin(session_id=${id})`
-      : "process-control capability unavailable; execution remains unfinished; do not replay")
-    : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, managed: true, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed` + answerLabel(command, exit, taken.stopped);
-  const unsent = taken.unsent === undefined ? "" : " · input was not sent: the process had already exited";
-  const header = shown + waitNote + unsent;
-  const artifactSummary = commandArtifactSummary(taken.receipt.artifacts);
-  const content = header + artifactSummary + "\n" + foldCarriageReturns(observationView(stored, ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, 0, adviceTools(ctx)));
-  const warnings = taken.receipt.capture === "partial" ? [failureDiagnostic("unknown_effect", "output capture is partial; full_output contains only captured bytes", UNKNOWN_EFFECT)] : [];
-  if (exit === null) {
-    return { ok: true, content, content_ref: stored.ref, content_sha256: stored.ref.sha256, data: taken.receipt, ...(warnings.length ? { warnings } : {}) };
-  }
-  const gate = matchGate(ctx, command);
-  const observation = await commandFingerprint(ctx);
-  // Refused input fails this call, yet the exit it observed is still recorded:
-  // the next poll only replays, so withholding the effect would lose it (D11).
-  const completion = taken.unsent === "refused"
-    ? { ok: false, outcome: executionOutcome("tool_failed"),
-      diagnostic: failureDiagnostic("not_found", "process had already exited; input was not sent; its exit and unread output are in this result", NOT_STARTED) }
-    : commandCompletion(exit, taken.stopped, undefined, command);
-  return {
-    ...completion,
-    content, content_ref: stored.ref, content_sha256: stored.ref.sha256,
-    data: taken.receipt, ...(warnings.length ? { warnings } : {}),
-    effect: { kind: "command", cmd: command, exit, ...(gate !== undefined ? { gate } : {}),
-      ...observation, ...(taken.receipt.artifacts ? { artifacts: taken.receipt.artifacts } : {}) },
-  };
-}
-
-/** The program's own meaning of an answering exit (grep 1: no match; 141 after head), appended to the header; the exit itself stays. */
-function answerLabel(command: string, exit: number, stopped?: "cancelled" | "timeout"): string {
-  const meaning = stopped === undefined ? commandAnswer(command, exit) : null;
-  return meaning === null ? "" : ` · ${meaning}`;
-}
-
-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, tools?: readonly string[]): string {
-  const { ref } = stored;
-  const marker = (omitted: number, offset: number) =>
-    `\n[truncated ${omitted} bytes at offset ${offset + skip}; full output: ${ref.path}; ` +
-    `${artifactRecovery(ref.sha256, offset + skip, tools)}]\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, 0, adviceTools(ctx)), 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 failure("permission_denied", abs.error);
-  const glob = typeof input["glob"] === "string" ? input["glob"] : undefined;
-  const limit = optionalLimit(input);
-  const result = await grep({
-    root: searchRoot(ctx, abs),
-    ...(ctx.rules ? { canRead: async (path: string) => await permissionResourceAction(searchRoot(ctx, abs), path, ctx.rules ?? [], ctx.sessionRules ?? [], "grep") === "allow" } : {}),
-    path: abs,
-    pattern: String(input["pattern"] ?? ""),
-    engine: grepEngine(input),
-    timeoutMs: ctx.timeoutMs,
-    ...(ctx.signal ? { signal: ctx.signal } : {}),
-    ...(glob !== undefined ? { glob } : {}),
-    ...(limit !== undefined ? { limit } : {}),
-  });
-  return presentSearch(ctx, "grep", input, abs, result);
-}
-
-async function presentSearch(ctx: ToolContext, tool: string, input: Record<string, unknown>, resource: string, result: SearchResult): Promise<ToolResult> {
-  const observation = result.observation;
-  if (!observation) return { ok: result.ok, ...await presentObservation(ctx, result.content), ...(result.diagnostic ? { diagnostic: result.diagnostic } : {}) };
-  const store = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  const archive = async (bytes: Uint8Array) => {
-    async function* source() { yield bytes; }
-    return (await archiveObservation(store, source(), 0)).ref;
-  };
-  const full = await archive(new TextEncoder().encode(searchObservationText(observation.rows)));
-  const raw = observation.raw ? await archive(observation.raw) : undefined;
-  const rawErrors = observation.rawErrors?.length ? await archive(observation.rawErrors) : undefined;
-  const manifest = await archive(new TextEncoder().encode(JSON.stringify({ version: 1, tool, input, resource, engine: observation.engine,
-    scan: observation.scan, sources: observation.sources, scope: { ignored: DEFAULT_IGNORE, follows_symlinks: false,
-      max_file_bytes: tool === "grep" ? MAX_FILE_BYTES : null, execution_byte_budget: MAX_SEARCH_CAPTURE_BYTES },
-    matches: observation.rows.length, artifact: full, ...(raw ? { raw } : {}), ...(rawErrors ? { raw_errors: rawErrors } : {}) })));
-  const preview = previewSearchObservation(observation, full.sha256, ctx.maxOutputBytes, 500,
-    `[engine=${observation.engine}; scan=${observation.scan.status}; sources=${observation.scan.source_versions}; manifest=${manifest.sha256}]` +
-      (result.diagnostic ? `\n[${result.diagnostic.message}]` : ""), adviceTools(ctx));
-  const data = { kind: "search", version: 1, source: { host: ctx.hostId ?? hostname(), workspace: ctx.root, resource },
-    engine: observation.engine, scan: { status: observation.scan.status, reasons: [...new Set(observation.scan.reasons.map(reason => reason.code))],
-      examined_files: observation.scan.examined_files, source_versions: observation.scan.source_versions },
-    matches: observation.rows.length, artifact: full, manifest, ...(raw ? { raw } : {}), ...(rawErrors ? { raw_errors: rawErrors } : {}), preview: preview.preview };
-  if (!isJsonValue(data)) throw new Error("search produced a non-JSON receipt");
-  return { ok: result.ok, content: preview.text, content_ref: full, content_sha256: full.sha256,
-    observation_sha256: sha256(preview.semantic), data, ...(result.diagnostic ? { diagnostic: result.diagnostic,
-      ...(result.diagnostic.code === "cancelled" || result.diagnostic.code === "timeout" ? { outcome: executionOutcome(result.diagnostic.code) } : {}) } : {}) };
-}
-
-async function toolQuery(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  let query: ReturnType<typeof parseQueryInput>;
-  try { query = parseQueryInput(input); }
-  catch (error) { return failure("invalid_input", String(error)); }
-  const { text, sources } = await readQuerySources(ctx.root, input["paths"], ctx.signal);
-  checkSourceCancellation(ctx.signal);
-  let value: { sources: typeof sources } & ReturnType<typeof queryData>;
-  try { value = { sources, ...queryData(text, query) }; }
-  catch (error) { return failure("invalid_input", String(error), READ_ATTEMPTED); }
-  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 failure("permission_denied", abs.error);
-  const limit = optionalLimit(input);
-  const result = await findFiles({
-    root: searchRoot(ctx, abs),
-    ...(ctx.rules ? { canRead: async (path: string) => await permissionResourceAction(searchRoot(ctx, abs), path, ctx.rules ?? [], ctx.sessionRules ?? [], "find") === "allow" } : {}),
-    path: abs,
-    pattern: String(input["pattern"] ?? ""),
-    timeoutMs: ctx.timeoutMs,
-    ...(ctx.signal ? { signal: ctx.signal } : {}),
-    ...(limit !== undefined ? { limit } : {}),
-  });
-  return presentSearch(ctx, "find", input, abs, result);
-}
-
-async function toolLs(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
-  const abs = toolPath(ctx, input);
-  if (typeof abs !== "string") return failure("permission_denied", abs.error);
-  const limit = optionalLimit(input);
-  const result = await ls({
-    root: searchRoot(ctx, abs),
-    ...(ctx.rules ? { canRead: async (path: string) => await permissionResourceAction(searchRoot(ctx, abs), path, ctx.rules ?? [], ctx.sessionRules ?? [], "ls") === "allow" } : {}),
-    path: abs,
-    ...(ctx.signal ? { signal: ctx.signal } : {}),
-    ...(limit !== undefined ? { limit } : {}),
-  });
-  return presentSearch(ctx, "ls", input, abs, result);
-}
-
-/**
- * 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, only?: readonly string[]): ToolSchema[] {
-  const allowed = new Set<string>(
-    writes ? WRITING_BRANCH_TOOL_NAMES : BRANCH_TOOL_NAMES,
-  );
-  const definitions = TOOL_DEFINITIONS.filter(t => allowed.has(t.name) && (only === undefined || only.includes(t.name)));
-  return definitions.map(tool => modelToolSchema(tool, definitions.map(item => item.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 failure("permission_denied", `refused: ${name} is not available here (allowed: ${ctx.allow.join(", ")})`);
-  }
-  const definition = toolDefinition(name, ctx);
-  if (ctx.workflowMode === "plan" && definition && definition.access !== "read" &&
-    !(definition.access === "state" && (name === "note" || name === "question" && ctx.questionSlot)))
-    return failure("permission_denied", `${name} is unavailable in Plan mode; ${ctx.planHint ?? "select Build at an idle checkpoint."}`);
-  input = repairToolInput(name, input);
-  let invalid: string | null = null;
-  if (definition?.validateInput) {
-    try { definition.validateInput(input); } catch (error) { return caughtFailure(error, NOT_STARTED, "Invalid tool arguments: "); }
-  } else if (definition) invalid = inputError(definition.input_schema, input, "input", definition.hiddenInputs);
-  if (invalid) {
-    const example = minimalInput(definition!.input_schema);
-    return failure("invalid_input", invalid, NOT_STARTED, example !== null && typeof example === "object" && !Array.isArray(example) &&
-      inputError(definition!.input_schema, example) === null ? { example: example as { [key: string]: JsonValue } } : {});
-  }
-  if (ctx.rules === undefined) return null;
-
-  const permissionInput = name === "apply_patch" && input && typeof input === "object" && "patchText" in input ? { paths: patchPaths(parsePatch(String(input.patchText))) } : input;
-  const request = await canonicalPermissionRequest(ctx.root, name, permissionInput);
-  let explained = explainDecision(ctx.rules, ctx.sessionRules ?? [], request);
-  if (definition?.access === "read" && request.paths) for (const path of request.paths) {
-    const resource = await permissionResourceDecision(ctx.root, path, ctx.rules, ctx.sessionRules ?? [], name);
-    if (resource.action === "deny") { explained = resource; break; }
-    if (resource.action === "ask" && explained.action === "allow") explained = resource;
-  }
-  const decision = explained.action;
-  // feat-approval-events: the verdict is durable before the call can start, so
-  // the log answers "why was this allowed" -- including automatic allows.
-  const record = async (verdict: ApprovalRecord["decision"], source: ApprovalRecord["source"]) => {
-    if (!ctx.onApproval || ctx.callId === undefined || !approvalNeeded(request, decision)) return;
-    await ctx.onApproval({ call_id: ctx.callId, tool: request.tool, decision: verdict, source,
-      ...(request.command !== undefined ? { command: request.command } : {}),
-      ...(explained.rule ? { rule: describeRule(explained.rule) } : {}) });
-  };
-  switch (decision) {
-    case "allow":
-      // An empty rule list consulted no policy (tool tests, trusted host execution).
-      if (explained.source !== "none") await record("allow", explained.source);
-      return null;
-    case "deny":
-      await record("deny", "config");
-      return failure("permission_denied", deniedMessage(request));
-    case "ask": {
-      const ask = ctx.ask ?? ctx.askSlot?.current;
-      if (ask === undefined) {
-        await record("deny", "no_prompt");
-        return failure("permission_denied", askWithoutTtyMessage(request));
-      }
-      let choice: ApprovalChoice | undefined;
-      try { choice = await waitForAdmission(ask(request), ctx.signal); }
-      catch (error) { return caughtFailure(error, NOT_STARTED, "approval unavailable: "); }
-      // A withdrawn prompt is not a decision; the result already says cancelled.
-      if (choice === undefined || ctx.signal?.aborted) return cancelledTool();
-      await record(choice, "user");
-      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 failure("permission_denied", deniedMessage(request));
-        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>)> {
-  try { input = normalizeToolInput(ctx, name, input); }
-  catch (error) { return scopeToolAdvice(ctx, finishToolResult(failure("invalid_input", `Invalid ${name} arguments: ${String(error)}`))); }
-  return prepareNormalizedTool(ctx, name, input);
-}
-
-/** Shared with the broker so the durable invocation names the arguments actually admitted. */
-export function normalizeToolInput(ctx: ToolContext, name: string, input: unknown): unknown {
-  // Freeze the adapter's normalized arguments before admission and durable logging.
-  return repairToolInput(name, toolDefinition(name, ctx)?.prepareArguments?.(input) ?? input);
-}
-
-/** D11: notification observers receive values, never capabilities or mutable execution evidence. */
-function observerValue<T>(value: T): T {
-  return value === undefined ? value : JSON.parse(JSON.stringify(value)) as T;
-}
-
-/** Normalization is not admission: this entrance still enforces every permission and hook. */
-export async function prepareNormalizedTool(ctx: ToolContext, name: string, input: unknown,
-  prepareAction?: () => Promise<() => Promise<ToolResult>>): Promise<ToolResult | (() => Promise<ToolResult>)> {
-  const scoped = <T>(action: () => T): T => ctx.extensionHooks?.scope ? ctx.extensionHooks.scope(ctx, action) : action();
-  let attached: ToolResult["instructions"];
-  try {
-    const gated = await gateTool(ctx, name, input);
-    if (gated) return scopeToolAdvice(ctx, finishToolResult(gated));
-    const instructions = await ctx.instructionCheck?.(ctx, name, input);
-    if (instructions?.kind === "block") return scopeToolAdvice(ctx, finishToolResult(instructions.result));
-    if (instructions?.kind === "attach") attached = instructions.instructions;
-    const veto = await scoped(() => ctx.extensionHooks?.before(name, observerValue(input), ctx.callId, ctx.parentCallId));
-    await ctx.drainNested?.();
-    if (veto) return scopeToolAdvice(ctx, finishToolResult(failure("permission_denied", veto)));
-  } catch (error) { return scopeToolAdvice(ctx, finishToolResult(caughtFailure(error, UNKNOWN_EFFECT))); }
-  let owned: (() => Promise<ToolResult>) | undefined;
-  let begun = false;
-  const lifecycle = { toolName: name, toolCallId: ctx.callId, ...(ctx.parentCallId ? { parentToolCallId: ctx.parentCallId } : {}), ...(ctx.origin ? { origin: ctx.origin } : {}) };
-  if (prepareAction) {
-    // Branch spawn preparation is ordered after admission and before siblings
-    // begin, under the same lifecycle observers as ordinary workspace tools.
-    try {
-      begun = true;
-      await scoped(() => ctx.extensionHooks?.event("tool_execution_start", { ...lifecycle, args: observerValue(input) }));
-      await ctx.drainNested?.();
-      owned = ctx.signal?.aborted ? async () => cancelledTool() : await prepareAction();
-    } catch (error) { owned = async () => { throw error; }; }
-  }
-  return async () => {
-    let observed: ToolResult | undefined;
-    const warnings: ToolDiagnostic[] = [], updates = new Set<Promise<void>>();
-    try {
-      if (!begun) await scoped(() => ctx.extensionHooks?.event("tool_execution_start", { ...lifecycle, args: observerValue(input) }));
-      await ctx.drainNested?.();
-      // Admission, the durable invocation and every hook saw the placeholder; only the tool sees the value.
-      const runInput = ctx.expandSecrets ? ctx.expandSecrets(input) : input;
-      const execute = async () => {
-        const executionContext: ToolContext = { ...ctx, onOutput: chunk => {
-          ctx.onOutput?.(chunk);
-          const update = scoped(() => ctx.extensionHooks?.event("tool_execution_update", { ...lifecycle, partialResult: { content: [{ type: "text", text: new TextDecoder().decode(chunk) }] } }));
-          if (update) {
-            const pending = update.catch(error => { warnings.push(failureFromError(error, UNKNOWN_EFFECT)); }).finally(() => { updates.delete(pending); });
-            updates.add(pending);
-          }
-        } };
-        observed = owned ? finishToolResult(ctx.signal?.aborted ? cancelledTool() : await owned(),
-          toolDefinition(name, ctx)?.access === "read" ? READ_ATTEMPTED : UNKNOWN_EFFECT) : await dispatchTool(executionContext, name, runInput);
-        return observed;
-      };
-      const command = ["bash", "environment", "target", "exec_command", "write_stdin", NATIVE_COMMAND_NAME].includes(name);
-      const operation = () => ctx.workspace && command ? ctx.workspace.command(name, runInput, execute, ctx.signal) : execute();
-      // Progress handlers may enqueue native commands. They run only after this
-      // process drains, before the outer receipt; awaiting them inside it deadlocks.
-      observed = command && ctx.runOwnedCommand ? await ctx.runOwnedCommand(operation) : await operation();
-      await scoped(() => ctx.extensionHooks?.event("tool_result", { ...lifecycle, input: observerValue(input), content: [{ type: "text", text: observed!.content }], isError: !observed!.ok, details: observerValue(observed!.data) }));
-      await scoped(() => ctx.extensionHooks?.event("tool_execution_end", { ...lifecycle, result: observerValue(observed), isError: !observed!.ok }));
-    } catch (error) {
-      // Notification/checkpoint failures after an observed operation cannot erase its actual result.
-      if (observed) warnings.push(failureFromError(error, UNKNOWN_EFFECT));
-      else observed = finishToolResult(caughtFailure(error, UNKNOWN_EFFECT));
-    }
-    await Promise.all(updates);
-    const result = warnings.length ? { ...observed, warnings: [...(observed.warnings ?? []), ...warnings] } : observed;
-    return scopeToolAdvice(ctx, attached ? { ...result, instructions: attached } : result);
-  };
-}
-
-async function dispatchTool(ctx: ToolContext, name: string, input: unknown): Promise<ToolResult> {
-  if (ctx.signal?.aborted) return finishToolResult(cancelledTool());
-  const impl = toolDefinition(name, ctx)?.run;
-  if (!impl) {
-    const near = closestName(name, TOOL_DEFINITIONS.filter((tool) => tool.run !== undefined && (ctx.allow === undefined || ctx.allow.includes(tool.name))).map((tool) => tool.name));
-    return finishToolResult(failure("invalid_input", `unknown tool: ${name}` + (near === undefined ? "" : `; did you mean ${near}?`)));
-  }
-  if (typeof input !== "object" || input === null) {
-    return finishToolResult(failure("invalid_input", `tool ${name} needs an object input`));
-  }
-  try {
-    const result = await impl(ctx, repairToolInput(name, input) as Record<string, unknown>);
-    return finishToolResult(result, toolDefinition(name, ctx)?.access === "read" && !ctx.extensions?.has(name) ? READ_ATTEMPTED : UNKNOWN_EFFECT);
-  } catch (err) {
-    // A tool that throws must still produce a result: an unanswered tool_use
-    // makes the next request unpairable.
-    return finishToolResult(caughtFailure(err, toolDefinition(name, ctx)?.access === "read" && !ctx.extensions?.has(name) ? READ_ATTEMPTED : UNKNOWN_EFFECT, `tool ${name} failed: `));
-  }
-}
-
-/** One finalizer also covers session-owned tools; result text never determines success. */
-export function finishToolResult(result: ToolResult, facts = UNKNOWN_EFFECT): ToolResult {
-  if (result.ok) return { ...result, outcome: result.outcome ?? executionOutcome("tool_completed") };
-  const reason = result.outcome?.reason;
-  const actual = result.effect?.kind === "command" ? { execution: "started" as const, effects: "possible" as const } : facts;
-  const code = reason === "cancelled" || reason === "not_started" ? "cancelled" : reason === "timeout" ? "timeout"
-    : result.effect?.kind === "command" ? "command_failed" : actual.effects === "possible" ? "unknown_effect" : "execution_failed";
-  const diagnostic = result.diagnostic?.execution !== undefined ? result.diagnostic : failureDiagnostic(result.diagnostic?.code ?? code,
-    result.diagnostic?.message ?? result.content, actual, { ...(result.diagnostic?.recover ? { recover: result.diagnostic.recover } : {}) });
-  return { ...result, diagnostic, outcome: result.outcome ?? executionOutcome("tool_failed") };
-}
-
-function cancelledTool(): ToolResult {
-  return { ...failure("cancelled", "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; depends_on?: readonly string[] }
-  | { t: "work_dependencies"; what: string; work_id: string; depends_on: readonly string[] }
-  | { t: "work_owner"; what: string; work_id: string; operation: "claim" | "release" }
-  | { 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 {
-  const parsed = parseNoteInput(input);
-  return parsed.result.ok ? parsed : { ...parsed,
-    result: { ...failure("invalid_input", parsed.result.content), data: { recorded: false } } };
-}
-
-function parseNoteInput(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() } : {};
-  const deps = o["depends_on"];
-  if (deps !== undefined && (identity.work_id === undefined || !["next", "depend"].includes(kind) || !Array.isArray(deps) ||
-      deps.some(value => typeof value !== "string" || !value.trim()))) return { result: { ok: false, content: "depends_on requires next/depend with a work_id and explicit non-empty IDs" } };
-  if (id !== undefined && !["next", "done", "blocked", "unblock", "reopen", "cancel", "pin", "decision", "pitfall", "depend", "claim_work", "release_work"].includes(kind)) {
-    return { result: { ok: false, content: "work_id applies to work lifecycle, decisions, pitfalls and pins" } };
-  }
-
-  if (what.length === 0) {
-    return { result: { content: "note needs a non-empty `what`", ok: false } };
-  }
-
-  switch (kind) {
-    case "depend": {
-      if (!identity.work_id || !Array.isArray(deps)) return { result: { ok: false, content: "depend requires work_id and depends_on" } };
-      return { result: { ok: true, content: "recorded dependencies" }, annotation: { t: "work_dependencies", what, work_id: identity.work_id, depends_on: deps as string[] } };
-    }
-    case "claim_work": case "release_work": {
-      if (!identity.work_id) return { result: { ok: false, content: "work ownership requires a work_id" } };
-      return { result: { ok: true, content: "recorded work ownership" }, annotation: { t: "work_owner", what, work_id: identity.work_id, operation: kind === "claim_work" ? "claim" : "release" } };
-    }
-    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, ...(Array.isArray(deps) ? { depends_on: deps as string[] } : {}) },
-      };
-    }
-    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, ...identity,
-          ...(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, ...identity },
-      };
-    }
-    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,
-        },
-      };
-  }
-}