@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/tools.ts

@@ -14,34 +14,43 @@
  * is what lets deriveHandoff verify a completion claim against evidence rather
  * than believing it.
  *
- * `bash` can reach outside any path the model declared, which the tree design
- * has to account for -- see appendix I. This module does not try to prevent
- * that by making the shell less capable; it records what it can and leaves the
- * workspace-snapshot cross-check to the layer above.
+ * 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, writeFile, mkdir, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import { dirname, resolve, relative, isAbsolute, join, sep } from "node:path";
+import { hostname } from "node:os";
+import { resolve, relative, isAbsolute, join, sep } from "node:path";
 import type { Effect, LineRange, ArtifactRef } from "../core/events.ts";
-import { archiveObservation, type ArchivedObservation } from "../store/observations.ts";
+import { archiveObservation, readObservation, type ArchivedObservation } from "../store/observations.ts";
 import { blobAddress } from "../store/blobs.ts";
 import { commandHeader, headTailView } from "../core/observation-view.ts";
 import {
-  DEFAULT_YIELD_MS, MAX_YIELD_MS, MIN_YIELD_MS, findSession, runningSessions, startSession, takeOutput, waitSession,
+  DEFAULT_YIELD_MS, MAX_YIELD_MS, MIN_YIELD_MS, findSession, closedSession, runningSessions, startSession, pollSession,
 } from "./exec-sessions.ts";
-import { observeCommand } from "../store/command.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 } from "../core/command-contract.ts";
+import { 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 } from "../core/read-bounds.ts";
-import { closestName, inputError, isJsonValue, type JsonValue, type ToolDiagnostic } from "../core/tool-contract.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 { repairToolInput } from "../core/tool-input.ts";
 import { HISTORY_SECTIONS } from "../core/history.ts";
-import { parseDataQuery, queryData } from "../core/data-query.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 {
   askWithoutTtyMessage,
@@ -52,14 +61,25 @@ import {
   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 } from "../store/search.ts";
+import { find as findFiles, grep, ls, MAX_FILE_BYTES, MAX_SEARCH_CAPTURE_BYTES, type SearchResult } from "../store/search.ts";
 import { scanWorkspace, workspaceVersion, 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";
 
 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;
@@ -70,18 +90,50 @@ export interface ToolResult {
   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[];
 }
 
 export interface ToolContext {
+  /** 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[];
+  /** Historical fingerprint compatibility, never enabled by the normal CLI. */
+  legacyWorkspace?: boolean;
+  /** 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 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?: {
-    before(name: string, input: unknown, id: string | undefined): Promise<string | undefined>;
+    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;
@@ -97,6 +149,8 @@ export interface ToolContext {
    * 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.
    *
@@ -141,6 +195,8 @@ export interface ToolContext {
   askSlot?: { current?: (request: PermissionRequest) => Promise<ApprovalChoice> };
 }
 
+export interface NestedInvocationOptions { signal?: AbortSignal }
+
 /**
  * What the person picked at the approval prompt.
  *
@@ -152,7 +208,8 @@ export type ApprovalChoice = "once" | "command" | "tool" | "deny";
 export const DEFAULT_TOOL_CONTEXT: Omit<ToolContext, "root"> = {
   // Runner prefixes are resolved in command position so `python3 -m pytest`
   // works without letting `echo pytest` forge a gate (D11 / M.2).
-  gates: { pytest: "pytest", tsc: "typecheck", cargo: "cargo", jest: "test", vitest: "test", go: "go" },
+  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.
@@ -163,6 +220,16 @@ export const DEFAULT_TOOL_CONTEXT: Omit<ToolContext, "root"> = {
 
 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.
  *
@@ -205,6 +272,13 @@ const searchRoot = (ctx: ToolContext, abs: string) => within(ctx.root, abs) ? ct
 // ---------------------------------------------------------------------------
 
 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";
@@ -214,9 +288,20 @@ export interface ToolDefinition extends ToolSchema {
   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: {
@@ -224,6 +309,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
         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: {},
         } } },
@@ -238,8 +324,21 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       },
     },
   },
+  {
+    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", minimum: 100, maximum: 30000, description: "Milliseconds to wait for launch; default 10000, distinct from the hard timeout" },
+      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: {
@@ -250,11 +349,13 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
         event: { type: "string", description: "Exact source event id from query results" },
         events: { type: "array", items: { type: "string" }, description: "1..100 exact event ids; preserves request order and identifies missing sources" },
         resource: { type: "string", description: "Exact resource path, with ./ and repeated slashes normalized" },
-        work_id: { type: "string", description: "Canonical work ID returned by note" },
+        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 },
       },
@@ -263,11 +364,13 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   },
   {
     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. " +
-      "Reports sha256 for optional edit version checks. If the observation is truncated, recover its full artifact or smaller ranges before skipping ahead.",
+      "Returns read_handle and whole-file sha256 for version checks. 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: {
@@ -281,25 +384,30 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: "write",
     access: "write", execution: "exclusive", branch: "write", run: toolWrite,
-    description: "Write a file, creating parent directories. Replaces existing content.",
+    description: "Write a file, creating parent directories. Replaces existing content. Pass read_handle or expected_sha256 for an explicit version check; otherwise Session uses its last observed version. 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: "Descriptor SHA from an observation of this file, workspace and host" },
+        expected_sha256: { type: "string", description: "Expected whole-file raw-byte SHA-256" },
+        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 and a version receipt before an edit." }],
     access: "write", execution: "exclusive", branch: "write", run: toolEdit,
     description:
-      "Replace exact text in a file. old_string must match once unless replace_all is set; copy it from read output, " +
+      "Replace exact text in a file. 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. " +
-      "Pass expected_sha256 from read to reject stale edits.",
+      "Pass read_handle or expected_sha256 from a file observation to reject stale edits; when omitted, Session uses its last observed version. 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: {
@@ -311,7 +419,8 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
           type: "object", required: ["old_string", "new_string"], properties: {
             old_string: { type: "string", minLength: 1 }, new_string: { type: "string" }, replace_all: { type: "boolean" },
           } } },
-        expected_sha256: { type: "string", description: "Whole-file version returned by read; mismatch leaves the file unchanged" },
+        expected_sha256: { type: "string", description: "Observed whole-file version; mismatch leaves the file unchanged" },
+        read_handle: { type: "string", description: "Descriptor SHA from an observation of this file, workspace and host" },
       },
       required: ["path"],
     },
@@ -326,21 +435,21 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     // 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. Use `done` the moment a command proves something works, and " +
-      "`next` before a long stretch of work so the next context knows where " +
-      "to resume. Also record decisions worth not relitigating and dead ends " +
-      "worth not retrying.",
+      "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"],
+          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. " +
@@ -350,8 +459,9 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
             "unblock/reopen: reactivate identified work with a current next_action. cancel: abandon identified work. pin: associate an original tool event with existing work; this does not verify completion.",
         },
         what: { type: "string", description: "The thing, in one line" },
-        work_id: { type: "string", description: "Stable ID for next/blocked/done. Required for unblock/reopen/cancel; keep it when the title changes." },
-        event: { type: "string", description: "pin: original observation event ID returned by history" },
+        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: {
@@ -384,6 +494,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
      * 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. " +
@@ -394,6 +505,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       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:
@@ -417,13 +529,14 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     name: "resolve",
     access: "state", execution: "exclusive", branch: "none",
     description:
-      "Adopt or discard a branch that has come back. Every branch must be " +
+      "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"] },
+        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"],
@@ -431,37 +544,64 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   },
   {
     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 300s; pass timeout for longer work. Start servers or watchers in the background with output redirected, " +
-      "e.g. `nohup cmd > server.log 2>&1 &`, then poll the log or port.",
+      "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. " +
-      "Waits up to yield_time_ms; if it has exited, returns `exit N · wall time` and its output like bash, otherwise " +
-      "`running · session <id>` with the output so far while the process keeps running. Continue with write_stdin. " +
-      "tty=true runs it in a terminal, for programs that need one (REPLs, prompts, curses). Prefer bash for commands that simply finish.",
+      "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 -lc" },
+        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", minimum: 100, maximum: 30000, description: "How long to wait before returning; default 10000" },
+        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Milliseconds to wait before returning; default 10000" },
         timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the session is killed; default 300" },
       },
       required: ["cmd"],
@@ -469,17 +609,19 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   },
   {
     name: "write_stdin",
+    example: { session_id: 1, chars: "", yield_time_ms: 1000 },
     access: "shell", execution: "exclusive", branch: "write", run: toolWriteStdin,
     description:
-      "Send characters to a running exec_command session and return the output since the last call. " +
+      "Send characters to an owned running process handle and return the output since the last call. " +
       "Empty chars polls. Include \\n to submit a line; \\u0003 is Ctrl-C, \\u0004 is Ctrl-D (end of input). " +
-      "When the process has exited, returns its exit code and the session closes.",
+      "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", minimum: 100, maximum: 30000, description: "How long to wait for output; default 10000" },
+        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Milliseconds to wait for output; default 10000" },
       },
       required: ["session_id"],
     },
@@ -493,7 +635,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       "Search file contents for a regex. Stays inside the workspace, does " +
       "not follow symlinks, and skips .git, node_modules and .xeno. Uses " +
       "ripgrep when it is already on PATH, otherwise a TypeScript walk. " +
-      "Truncates with a count of what was left out.",
+      "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: {
@@ -511,7 +653,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     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.",
+      "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: {
@@ -528,7 +670,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     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.",
+      "node_modules and .xeno. Omitted entries remain in a history artifact with exact byte offsets.",
     input_schema: {
       type: "object",
       properties: {
@@ -541,12 +683,94 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
 ];
 
 /** Runtime policy metadata never leaks into provider-specific wire schemas. */
-export const TOOL_SCHEMAS: ToolSchema[] = TOOL_DEFINITIONS.map(({ name, description, input_schema }) => ({ name, description, input_schema }));
+export function 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)) &&
+    decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], { 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 &&
+          decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], 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
 // ---------------------------------------------------------------------------
@@ -557,25 +781,23 @@ export function toolDefinition(name: string, ctx?: ToolContext): ToolDefinition
  * or a minified bundle cannot spend the observation budget on its own.
  */
 const READ_DEFAULT_LINES = 2_000;
-const READ_MAX_LINE_CHARS = 2_000;
-
-function clipLine(line: string, number: number): string {
-  if (line.length <= READ_MAX_LINE_CHARS) return line;
-  return `${line.slice(0, READ_MAX_LINE_CHARS)} [line truncated: ${line.length} chars; see the rest with bash, e.g. \`sed -n '${number}p' FILE | cut -c${READ_MAX_LINE_CHARS + 1}-\`]`;
-}
 
 async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
   const path = String(input["path"] ?? "");
-  const abs = confine(ctx, path);
-  if (typeof abs !== "string") return { content: abs.error, ok: false };
+  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 {
-    bytes = await readFile(abs);
+    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 { content: `cannot read ${path}: ${(err as Error).message}`, ok: false };
+    return caughtFailure(err, READ_ATTEMPTED, `cannot read ${path}: `);
   }
 
   if (ctx.imageStore && detectSupportedImageMimeType(bytes)) {
@@ -583,7 +805,7 @@ async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promi
     return { ok: true, content: imageDescription(image), images: [image], effect: { kind: "read", path, sha256: blobAddress(bytes) } };
   }
   if (bytes.subarray(0, 8_192).includes(0)) {
-    return { ok: false, content: `${path} looks binary (${bytes.length} bytes, contains NUL); inspect it with bash, e.g. \`file ${path}\` or \`xxd ${path} | head\`` };
+    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
@@ -591,52 +813,106 @@ async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promi
   const first = input["start"] ?? 1;
   const end = input["end"] === undefined && Number.isSafeInteger(first) ? (first as number) + READ_DEFAULT_LINES - 1 : input["end"];
   const selected = readBounds(lines.length, input["start"], end);
-  if (!selected.ok) return { ok: false, content: selected.message };
+  if (!selected.ok) return failure("invalid_input", selected.message, READ_ATTEMPTED);
   const { start } = selected;
   const slice = lines.slice(start - 1, selected.end);
-  const numbered = slice.map((l, i) => `${start + i}\t${clipLine(l, start + i)}`).join("\n");
+  const version = sha256(bytes);
+  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 = `${selected.notice}\nsha256: ${version}\nread_handle: ${handle.ref.sha256}\n`;
+  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 {
-    ...await presentObservation(ctx, `${selected.notice}\nsha256: ${sha256(bytes)}\n${numbered}`),
+    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: sha256(bytes), start, end: selected.end, total_lines: lines.length, next_start: selected.end < lines.length ? selected.end + 1 : null },
-    observation_sha256: sha256(numbered),
+    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: sha256(bytes), ranges },
+    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 { content: abs.error, ok: false };
+  if (typeof abs !== "string") return failure("permission_denied", abs.error);
 
-  let before: Uint8Array | null = null;
-  try {
-    before = await readFile(abs);
-  } catch (error) {
-    if ((error as { code?: string }).code !== "ENOENT") return { ok: false, content: `cannot fingerprint ${path}: ${String(error)}` };
-  }
+  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 mkdir(dirname(abs), { recursive: true });
-    await writeFile(abs, content, "utf8");
+    await commitEdit(ctx, abs, saved, after);
   } catch (err) {
-    return { content: `cannot write ${path}: ${(err as Error).message}`, ok: false };
+    return fileCommitFailure(ctx, abs, path, err);
   }
 
   return {
     content: `wrote ${new TextEncoder().encode(content).length} bytes to ${path}`,
     ok: true,
-    data: { path, bytes: new TextEncoder().encode(content).length, sha256_before: before === null ? null : sha256(before), sha256_after: sha256(content) },
+    data: { ...data, changed: true },
     effect: {
       kind: "edit",
       path,
-      sha256_before: before === null ? null : sha256(before),
-      sha256_after: sha256(content),
+      sha256_before: previous,
+      sha256_after: version,
     },
   };
 }
@@ -651,26 +927,21 @@ async function toolEdit(ctx: ToolContext, input: Record<string, unknown>): Promi
       : [];
   if (edits.length === 0) {
     const message = "edit needs old_string and new_string, or edits[]";
-    return { ok: false, content: message, diagnostic: { code: "invalid_input", message } };
+    return failure("invalid_input", message);
   }
 
   const abs = confine(ctx, path);
-  if (typeof abs !== "string") return { content: abs.error, ok: false };
-
-  let before: string;
-  try {
-    before = await readFile(abs, "utf8");
-  } catch (err) {
-    return { content: `cannot read ${path}: ${(err as Error).message}`, ok: false };
-  }
+  if (typeof abs !== "string") return failure("permission_denied", abs.error);
 
-  const version = sha256(before);
+  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 failure("not_found", `cannot read ${path}: file does not exist`, READ_ATTEMPTED);
   const recover = { tool: "read", input: { path } };
-  if (input["expected_sha256"] !== undefined && input["expected_sha256"] !== version) {
-    const message = `file version changed for ${path}; current sha256: ${version}. Read the current file before retrying.`;
-    return { ok: false, content: message, data: { path, sha256: version },
-      diagnostic: { code: "version_mismatch", message, recover } };
-  }
+  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 ? "" :
@@ -681,38 +952,47 @@ async function toolEdit(ctx: ToolContext, input: Record<string, unknown>): Promi
     return { ok: false, content: `${message}${closest}\ncurrent sha256: ${version}`,
       data: { path, sha256: version, occurrences: plan.occurrences, edit: plan.edit,
         ...(plan.closest === undefined ? {} : { closest: { start_line: plan.closest.startLine, end_line: plan.closest.endLine, score: plan.closest.score } }) },
-      diagnostic: { code: plan.code, message, recover: plan.closest === undefined ? recover
-        : { tool: "read", input: { path, start: plan.closest.startLine, end: plan.closest.endLine } } } };
+      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 writeFile(abs, after, "utf8");
+    await commitEdit(ctx, abs, saved, new TextEncoder().encode(after));
   } catch (err) {
-    return { content: `cannot write ${path}: ${(err as Error).message}`, ok: false };
+    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, replacements: plan.replacements, fuzzy: plan.fuzzy, first_changed_line: plan.firstLine, sha256_before: version, sha256_after: sha256(after) },
+    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: sha256(before),
+      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 { content: "empty command", ok: false };
+  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 { content: cwd.error, ok: false };
+  if (typeof cwd !== "string") return failure("permission_denied", cwd.error);
   const requestedMs = typeof input["timeout"] === "number" ? input["timeout"] * 1000 : undefined;
-  const timeoutMs = Math.min(requestedMs ?? ctx.timeoutMs, ctx.maxTimeoutMs ?? ctx.timeoutMs);
+  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,
@@ -722,26 +1002,29 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
 
   const gate = matchGate(ctx, command);
   const exit = captured.exit;
-  const observed = await scanWorkspace(ctx.root, FINGERPRINT_IGNORE);
+  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 } : {}) });
+  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.
-    content: header + "\n" + observationView(captured, ctx.maxOutputBytes - utf8Length(header) - 1, captured.prefixBytes),
+    content: header + artifactSummary + "\n" + observationView(captured,
+      ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, captured.prefixBytes, adviceTools(ctx)),
     content_ref: captured.ref,
-    ok: captured.stopped === undefined && exit === 0,
-    outcome: executionOutcome(captured.stopped ?? (exit === 0 ? "tool_completed" : "tool_failed")),
-    data: { exit, output: captured.ref },
+    ...commandCompletion(exit, captured.stopped, captured.cleanup),
+    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 } : {}),
-      ...(observed.ok ? { workspace_sha256: workspaceVersion(observed.files) } : {}),
+      ...observation,
+      ...(artifacts ? { artifacts } : {}),
     },
   };
 }
@@ -759,61 +1042,100 @@ const FINGERPRINT_IGNORE: readonly string[] = [...DEFAULT_IGNORE,
   "target", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox",
   ".gradle", ".next", ".turbo", ".cache"];
 
+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" }> {
+  if (ctx.legacyWorkspace) {
+    const observed = await scanWorkspace(ctx.root, FINGERPRINT_IGNORE);
+    return observed.ok ? { workspace_sha256: workspaceVersion(observed.files) } : {};
+  }
+  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" };
+}
+
 const clampYield = (value: unknown) =>
   Math.min(MAX_YIELD_MS, Math.max(MIN_YIELD_MS, typeof value === "number" && Number.isFinite(value) ? value : DEFAULT_YIELD_MS));
 
 async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
   const command = String(input["cmd"] ?? "");
-  if (command.trim().length === 0) return { content: "empty command", ok: false };
+  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 { content: cwd.error, ok: false };
-  const requestedMs = typeof input["timeout"] === "number" ? input["timeout"] * 1000 : undefined;
-  const timeoutMs = Math.min(requestedMs ?? ctx.timeoutMs, ctx.maxTimeoutMs ?? ctx.timeoutMs);
+  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 session = await startSession({ command, cwd, tty: input["tty"] === true, timeoutMs, spoolDir: outputStore });
-  if ("error" in session) return { ok: false, content: session.error };
-  await waitSession(session, clampYield(input["yield_time_ms"]), ctx.signal);
-  return sessionResult(ctx, session.id, command, timeoutMs, await takeOutput(session, outputStore, ctx.maxOutputBytes));
+  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);
+  return sessionResult(ctx, command, timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, clampYield(input["yield_time_ms"]), "", ctx.signal));
 }
 
 async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
   const id = Number(input["session_id"]);
-  const session = findSession(id);
+  const chars = typeof input["chars"] === "string" ? input["chars"] : "";
+  const session = findSession(id, ctx.execOwner);
   if (session === undefined) {
-    const running = runningSessions().map((s) => s.id).join(", ");
-    return { ok: false, content: `no running session ${id}` +
-      (running.length > 0 ? `; running sessions: ${running}` : "; sessions end when their process exits or xeno restarts") };
+    const closed = closedSession(id, ctx.execOwner);
+    if (closed) return receiptResult(ctx, { ...closed.receipt, replayed: true }, chars);
+    const original = await ctx.observedProcess?.(id);
+    if (original) return receiptResult(ctx, recoverProcessReceipt(original.receipt, original.origin), chars);
+    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 chars = typeof input["chars"] === "string" ? input["chars"] : "";
-  if (chars.length > 0 && session.exit === null) session.write(chars);
-  await waitSession(session, clampYield(input["yield_time_ms"]), ctx.signal);
   const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  return sessionResult(ctx, id, session.command, session.timeoutMs, await takeOutput(session, outputStore, ctx.maxOutputBytes));
+  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, clampYield(input["yield_time_ms"]), chars, ctx.signal));
+}
+
+/** 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).
  */
-async function sessionResult(ctx: ToolContext, id: number, command: string, timeoutMs: number,
-  taken: Awaited<ReturnType<typeof takeOutput>>): Promise<ToolResult> {
+export async function sessionResult(ctx: ToolContext, command: string, timeoutMs: number,
+  taken: Awaited<ReturnType<typeof pollSession>>): Promise<ToolResult> {
   const { stored, exit } = taken;
+  const id = taken.receipt.session_id;
+  if (taken.receipt.replayed) return receiptResult(ctx, taken.receipt, "");
   const header = exit === null
-    ? `running · session ${id} · ${(taken.wallMs / 1000).toFixed(1)}s elapsed; poll or send input with write_stdin(session_id=${id})`
-    : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed`;
-  const content = header + "\n" + observationView(stored, ctx.maxOutputBytes - utf8Length(header) - 1);
+    ? `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`;
+  const artifactSummary = commandArtifactSummary(taken.receipt.artifacts);
+  const content = header + artifactSummary + "\n" + 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, data: { session_id: id, running: true, output: stored.ref } };
+    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 observed = await scanWorkspace(ctx.root, FINGERPRINT_IGNORE);
+  const observation = await commandFingerprint(ctx);
   return {
-    ok: exit === 0 && taken.stopped === undefined,
-    content, content_ref: stored.ref,
-    outcome: executionOutcome(taken.stopped ?? (exit === 0 ? "tool_completed" : "tool_failed")),
-    data: { session_id: id, running: false, exit, output: stored.ref },
+    ...commandCompletion(exit, taken.stopped),
+    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 } : {}),
-      ...(observed.ok ? { workspace_sha256: workspaceVersion(observed.files) } : {}) },
+      ...observation, ...(taken.receipt.artifacts ? { artifacts: taken.receipt.artifacts } : {}) },
   };
 }
 
@@ -825,11 +1147,11 @@ const utf8Length = (text: string) => new TextEncoder().encode(text).length;
  * The marker names the artifact and the byte offset where the gap starts, so
  * the missing middle is one `history` call away rather than a rerun.
  */
-function observationView(stored: ArchivedObservation, limit: number, skip = 0): string {
+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}; ` +
-    `history artifact=${ref.sha256} offset=${offset + skip}]\n`;
+    `${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);
@@ -840,7 +1162,7 @@ export async function presentObservation(ctx: ToolContext, content: string): Pro
   if (bytes.length <= ctx.maxOutputBytes) return { content, content_sha256: sha256(bytes) };
   async function* source(): AsyncGenerator<Uint8Array> { yield bytes; }
   const stored = await archiveObservation(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), source(), ctx.maxOutputBytes);
-  return { content: observationView(stored, ctx.maxOutputBytes), content_ref: stored.ref, content_sha256: stored.ref.sha256 };
+  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 } {
@@ -861,7 +1183,7 @@ function grepEngine(input: Record<string, unknown>): "auto" | "ripgrep" | "walk"
 
 async function toolGrep(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
   const abs = toolPath(ctx, input);
-  if (typeof abs !== "string") return { content: abs.error, ok: false };
+  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({
@@ -870,16 +1192,50 @@ async function toolGrep(ctx: ToolContext, input: Record<string, unknown>): Promi
     pattern: String(input["pattern"] ?? ""),
     engine: grepEngine(input),
     timeoutMs: ctx.timeoutMs,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
     ...(glob !== undefined ? { glob } : {}),
     ...(limit !== undefined ? { limit } : {}),
   });
-  return { ...await presentObservation(ctx, result.content), ok: result.ok };
+  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> {
-  const query = parseDataQuery(input);
-  const { text, sources } = await readQuerySources(ctx.root, input["paths"]);
-  const value = { sources, ...queryData(text, query) };
+  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 };
@@ -887,28 +1243,30 @@ async function toolQuery(ctx: ToolContext, input: Record<string, unknown>): Prom
 
 async function toolFind(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
   const abs = toolPath(ctx, input);
-  if (typeof abs !== "string") return { content: abs.error, ok: false };
+  if (typeof abs !== "string") return failure("permission_denied", abs.error);
   const limit = optionalLimit(input);
   const result = await findFiles({
     root: searchRoot(ctx, abs),
     path: abs,
     pattern: String(input["pattern"] ?? ""),
     timeoutMs: ctx.timeoutMs,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
     ...(limit !== undefined ? { limit } : {}),
   });
-  return { ...await presentObservation(ctx, result.content), ok: result.ok };
+  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 { content: abs.error, ok: false };
+  if (typeof abs !== "string") return failure("permission_denied", abs.error);
   const limit = optionalLimit(input);
   const result = await ls({
     root: searchRoot(ctx, abs),
     path: abs,
+    ...(ctx.signal ? { signal: ctx.signal } : {}),
     ...(limit !== undefined ? { limit } : {}),
   });
-  return { ...await presentObservation(ctx, result.content), ok: result.ok };
+  return presentSearch(ctx, "ls", input, abs, result);
 }
 
 /**
@@ -924,11 +1282,12 @@ export const BRANCH_TOOL_NAMES = TOOL_DEFINITIONS.filter(tool => tool.branch ===
 /** Writing adds effects to the shared evidence tools; new readers cannot go missing. */
 export const WRITING_BRANCH_TOOL_NAMES = TOOL_DEFINITIONS.filter(tool => tool.branch !== "none").map(tool => tool.name);
 
-export function branchTools(writes = false): ToolSchema[] {
+export function branchTools(writes = false, only?: readonly string[]): ToolSchema[] {
   const allowed = new Set<string>(
     writes ? WRITING_BRANCH_TOOL_NAMES : BRANCH_TOOL_NAMES,
   );
-  return TOOL_SCHEMAS.filter((t) => allowed.has(t.name));
+  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)));
 }
 
 /**
@@ -951,15 +1310,16 @@ export async function gateTool(
   // the approval prompt. The model should not have seen it; if a call
   // arrives anyway it is answered, not executed.
   if (ctx.allow && !ctx.allow.includes(name)) {
-    return {
-      content: `refused: ${name} is not available here (allowed: ${ctx.allow.join(", ")})`,
-      ok: false,
-    };
+    return failure("permission_denied", `refused: ${name} is not available here (allowed: ${ctx.allow.join(", ")})`);
   }
   const definition = toolDefinition(name, ctx);
   input = repairToolInput(name, input);
   const invalid = definition ? inputError(definition.input_schema, input, "input", definition.hiddenInputs) : null;
-  if (invalid) return { ok: false, content: invalid, diagnostic: { code: "invalid_input", message: invalid } };
+  if (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 request = permissionRequest(name, input);
@@ -969,13 +1329,15 @@ export async function gateTool(
     case "allow":
       return null;
     case "deny":
-      return { content: deniedMessage(request), ok: false };
+      return failure("permission_denied", deniedMessage(request));
     case "ask": {
       const ask = ctx.ask ?? ctx.askSlot?.current;
       if (ask === undefined) {
-        return { content: askWithoutTtyMessage(request), ok: false };
+        return failure("permission_denied", askWithoutTtyMessage(request));
       }
-      const choice = await waitForAdmission(ask(request), ctx.signal);
+      let choice: ApprovalChoice | undefined;
+      try { choice = await waitForAdmission(ask(request), ctx.signal); }
+      catch (error) { return caughtFailure(error, NOT_STARTED, "approval unavailable: "); }
       if (choice === undefined || ctx.signal?.aborted) return cancelledTool();
       switch (choice) {
         case "once":
@@ -997,7 +1359,7 @@ export async function gateTool(
           return null;
         }
         case "deny":
-          return { content: deniedMessage(request), ok: false };
+          return failure("permission_denied", deniedMessage(request));
         default:
           return assertNever(choice, "gateTool");
       }
@@ -1018,21 +1380,79 @@ export async function runTool(
 
 /** 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 = toolDefinition(name, ctx)?.prepareArguments?.(input) ?? input; }
-  catch (error) { return finishToolResult({ ok: false, content: `Invalid ${name} arguments: ${String(error)}` }); }
-  const gated = await gateTool(ctx, name, input);
-  if (gated) return finishToolResult(gated);
-  const veto = await ctx.extensionHooks?.before(name, input, ctx.callId);
-  if (veto) return finishToolResult({ ok: false, content: veto });
+  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();
+  try {
+    const gated = await gateTool(ctx, name, input);
+    if (gated) return scopeToolAdvice(ctx, finishToolResult(gated));
+    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 () => {
-    await ctx.extensionHooks?.event("tool_execution_start", { toolName: name, toolCallId: ctx.callId, args: input });
-    const result = await dispatchTool({ ...ctx, onOutput: chunk => {
-      ctx.onOutput?.(chunk);
-      void ctx.extensionHooks?.event("tool_execution_update", { toolName: name, toolCallId: ctx.callId, partialResult: { content: [{ type: "text", text: new TextDecoder().decode(chunk) }] } });
-    } }, name, input);
-    await ctx.extensionHooks?.event("tool_result", { toolName: name, toolCallId: ctx.callId, input, content: [{ type: "text", text: result.content }], isError: !result.ok, details: result.data });
-    await ctx.extensionHooks?.event("tool_execution_end", { toolName: name, toolCallId: ctx.callId, result, isError: !result.ok });
-    return result;
+    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?.();
+      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, input);
+        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, input, 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);
+    return scopeToolAdvice(ctx, warnings.length ? { ...observed, warnings: [...(observed.warnings ?? []), ...warnings] } : observed);
   };
 }
 
@@ -1040,30 +1460,36 @@ async function dispatchTool(ctx: ToolContext, name: string, input: unknown): Pro
   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).map((tool) => tool.name));
-    return finishToolResult({ content: `unknown tool: ${name}` + (near === undefined ? "" : `; did you mean ${near}?`), ok: false });
+    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({ content: `tool ${name} needs an object input`, ok: false });
+    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);
+    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({ content: `tool ${name} failed: ${(err as Error).message}`, ok: false });
+    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): ToolResult {
-  return { ...result, outcome: result.outcome ?? executionOutcome(result.ok ? "tool_completed" : "tool_failed"),
-    ...(!result.ok && !result.diagnostic ? { diagnostic: { code: "execution_failed" as const, message: result.content } } : {}) };
+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 { ok: false, content: "interrupted: cancelled before this tool started", outcome: executionOutcome("not_started") };
+  return { ...failure("cancelled", "interrupted: cancelled before this tool started"), outcome: executionOutcome("not_started") };
 }
 
 export async function workspaceRoot(path: string): Promise<string> {
@@ -1095,7 +1521,9 @@ export type Annotation =
       proof?: string;
       work_id?: string;
     }
-  | { t: "next_action"; what: string; next_action: 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 }
@@ -1109,6 +1537,12 @@ export interface NoteOutcome {
 }
 
 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 } };
   }
@@ -1121,8 +1555,11 @@ export function parseNote(input: unknown): NoteOutcome {
     return { result: { ok: false, content: "work_id must be a non-empty string" } };
   }
   const identity = typeof id === "string" ? { work_id: id.trim() } : {};
-  if (id !== undefined && !["next", "done", "blocked", "unblock", "reopen", "cancel", "pin"].includes(kind)) {
-    return { result: { ok: false, content: "work_id applies to work lifecycle notes, not decisions, pitfalls or questions" } };
+  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) {
@@ -1130,6 +1567,14 @@ export function parseNote(input: unknown): NoteOutcome {
   }
 
   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" } };
@@ -1169,7 +1614,7 @@ export function parseNote(input: unknown): NoteOutcome {
       }
       return {
         result: { content: `recorded: next "${what}" -> ${next}`, ok: true },
-        annotation: { t: "next_action", what, next_action: next, ...identity },
+        annotation: { t: "next_action", what, next_action: next, ...identity, ...(Array.isArray(deps) ? { depends_on: deps as string[] } : {}) },
       };
     }
     case "decision": {
@@ -1182,7 +1627,7 @@ export function parseNote(input: unknown): NoteOutcome {
       return {
         result: { content: `recorded: decision "${what}"`, ok: true },
         annotation: {
-          t: "decision", chose: what, because: why,
+          t: "decision", chose: what, because: why, ...identity,
           ...(rejected && rejected.length > 0 ? { rejected } : {}),
         },
       };
@@ -1193,7 +1638,7 @@ export function parseNote(input: unknown): NoteOutcome {
       }
       return {
         result: { content: `recorded: pitfall "${what}"`, ok: true },
-        annotation: { t: "pitfall", tried: what, failed_because: why },
+        annotation: { t: "pitfall", tried: what, failed_because: why, ...identity },
       };
     }
     case "blocked": {