@visual-z/xeno 0.8.1 → 0.8.3

package/src/runtime/stream-idle.ts

@@ -0,0 +1,80 @@
+/**
+ * Abandons one attempt whose stream has gone silent.
+ *
+ * Without this a stream the network silently dropped waits until the user
+ * presses Escape (Horizyn 2026-10-12: a request sat 5m39s before the socket
+ * error surfaced). OpenAI's Codex CLI (`stream_idle_timeout_ms`, default
+ * 300000) and Claude Code (300s) both cut a stream that delivers nothing for
+ * five minutes against the same backends, so a live stream -- extended
+ * thinking included -- is not that quiet. The limit is theirs, not measured
+ * here (feat-stream-idle-watchdog).
+ *
+ * The clock starts when the request is sent, so it also bounds the wait for
+ * the first byte, and restarts on anything received: body bytes where the
+ * adapter owns fetch, stream events (pings included) where an SDK does.
+ */
+
+export const STREAM_IDLE_MS = 300_000;
+
+/** retry.ts recognises this by name, so it need not import an adapter. */
+export class StreamIdleError extends Error {
+  constructor(ms: number) {
+    super(`no data from the provider for ${Math.round(ms / 1000)}s; the stream was abandoned`);
+    this.name = "StreamIdleError";
+  }
+}
+
+export class IdleWatch {
+  /** Pass this, not the caller's, to the request: it also aborts on silence. */
+  readonly signal: AbortSignal;
+  private readonly controller = new AbortController();
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private expired = false;
+  private readonly outer: AbortSignal | undefined;
+  private readonly ms: number;
+
+  constructor(outer: AbortSignal | undefined, ms: number = STREAM_IDLE_MS) {
+    this.outer = outer; this.ms = ms;
+    this.signal = outer === undefined ? this.controller.signal : AbortSignal.any([outer, this.controller.signal]);
+    this.touch();
+  }
+
+  touch(): void {
+    if (this.expired) return;
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.expired = true;
+      this.controller.abort(new StreamIdleError(this.ms));
+    }, this.ms);
+  }
+
+  /** A body that restarts the clock on every chunk. */
+  body(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+    return stream.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
+      transform: (chunk, sink) => { this.touch(); sink.enqueue(chunk); },
+    }));
+  }
+
+  /** An event stream that restarts the clock on every event. */
+  async *events<T>(source: AsyncIterable<T>): AsyncGenerator<T> {
+    for await (const event of source) { this.touch(); yield event; }
+  }
+
+  /**
+   * Whatever the abort surfaced as -- AbortError, a closed body, the SDK's
+   * own wrapper -- silence becomes StreamIdleError. The caller's own abort
+   * stays an abort: Escape must not start another attempt.
+   */
+  rethrow(error: unknown): never {
+    if (this.expired && this.outer?.aborted !== true) throw new StreamIdleError(this.ms);
+    throw error;
+  }
+
+  dispose(): void { clearTimeout(this.timer); }
+}
+
+/** Runs one attempt under its own idle watch, cleared however it ends. */
+export async function watchIdle<T>(outer: AbortSignal | undefined, ms: number | undefined, run: (idle: IdleWatch) => Promise<T>): Promise<T> {
+  const idle = new IdleWatch(outer, ms);
+  try { return await run(idle); } catch (error) { return idle.rethrow(error); } finally { idle.dispose(); }
+}

package/src/runtime/tools.ts

@@ -23,17 +23,17 @@ import { readFile, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { hostname } from "node:os";
 import { resolve, relative, isAbsolute, join, sep } from "node:path";
-import type { Effect, LineRange, ArtifactRef } from "../core/events.ts";
+import type { Effect, LineRange, ArtifactRef, ApprovalEvent } from "../core/events.ts";
 import { archiveObservation, readObservation, type ArchivedObservation } from "../store/observations.ts";
 import { blobAddress } from "../store/blobs.ts";
-import { commandHeader, headTailView } from "../core/observation-view.ts";
+import { commandHeader, foldCarriageReturns, headTailView } from "../core/observation-view.ts";
 import {
-  yieldWait, findSession, closedSession, runningSessions, startSession, pollSession,
+  yieldWait, emptyYieldWait, findSession, closedSession, runningSessions, startSession, pollSession, isControlInput,
 } from "./exec-sessions.ts";
 import { recoverProcessReceipt, type ProcessReceipt, type latestProcessReceipt } from "../core/process-receipt.ts";
 import { observeCommand, observeArgvCommand } from "../store/command.ts";
 import { executionOutcome, type ExecutionOutcome } from "../core/outcome.ts";
-import { commandCompletion, commandTimeout } from "../core/command-contract.ts";
+import { commandCompletion, commandTimeout, commandAnswer, outputBytesForTokens } from "../core/command-contract.ts";
 import { linesWithin, previewReadObservation, readObservationText, type ObservationReceipt } from "../core/read-observation.ts";
 import { checkFilePrecondition, isFileDigest, isFileReadDescriptor, type FileReadDescriptor, type FilePrecondition } from "../core/file-precondition.ts";
 import { previewSearchObservation, searchObservationText } from "../core/search-observation.ts";
@@ -46,6 +46,8 @@ import { closestName, inputError, isJsonValue, minimalInput, type JsonValue, typ
 import { failureDiagnostic, failureFromError, scopeFailureGuidance, NOT_STARTED, READ_ATTEMPTED, UNKNOWN_EFFECT, type FailureFacts } from "../core/tool-failure.ts";
 import { planEdits, type EditSpec } from "../core/edit-plan.ts";
 import { toView } from "../core/text-normalize.ts";
+import { nearestPaths } from "../core/path-suggestions.ts";
+import { buildFileIndex, MAX_INDEX_ENTRIES } from "../store/file-index.ts";
 import { repairToolInput } from "../core/tool-input.ts";
 import { HISTORY_SECTIONS } from "../core/history.ts";
 import { RECOVERY_SECTIONS } from "../core/recovery-sources.ts";
@@ -53,8 +55,11 @@ import { queryData } from "../core/data-query.ts";
 import { parseQueryInput, MAX_SQL_CHARS, SQL_QUERY_HELP } from "../core/sql-query.ts";
 import { readQuerySources } from "../store/query-source.ts";
 import {
+  approvalNeeded,
   askWithoutTtyMessage,
   deniedMessage,
+  describeRule,
+  explainDecision,
   permissionRequest,
   type PermissionRequest,
   type PermissionRule,
@@ -76,7 +81,7 @@ import { beginCommandArtifacts, prepareArtifactArguments, commandArtifactSummary
 import { MAX_COMMAND_ARTIFACTS } from "../core/command-artifacts.ts";
 import { checkSourceCancellation } from "../store/source-cancellation.ts";
 import { canonicalPermissionRequest } from "../store/permission-paths.ts";
-import { permissionResourceAction } from "./permission-resources.ts";
+import { permissionResourceAction, permissionResourceDecision } from "./permission-resources.ts";
 import { parsePatch, patchPaths } from "../core/patch.ts";
 import { decideWithSessionRules } from "../core/permissions.ts";
 
@@ -111,6 +116,8 @@ export type InstructionCheck =
   | { kind: "attach"; instructions: { keys: readonly string[]; text: string } };
 
 export interface ToolContext {
+  /** S.9: placeholders back to values, applied after admission and only to what the tool itself runs. */
+  expandSecrets?: (input: unknown) => unknown;
   historyEvents?: () => Promise<import("../core/events.ts").LogEvent[]>;
   checkpointBlobs?: string;
   frozenSystem?: () => string;
@@ -218,8 +225,17 @@ export interface ToolContext {
    * said no.
    */
   askSlot?: { current?: (request: PermissionRequest) => Promise<ApprovalChoice> };
+  /**
+   * Receives the gate's verdict for a call that needed one, and is awaited
+   * before the call may start (feat-approval-events). The session appends it
+   * as an `approval` event; absent, nothing is recorded.
+   */
+  onApproval?: (approval: ApprovalRecord) => Promise<void>;
 }
 
+/** The `approval` event without the identity the log assigns. */
+export type ApprovalRecord = Omit<ApprovalEvent, "t" | "id" | "at">;
+
 export interface NestedInvocationOptions { signal?: AbortSignal }
 
 /**
@@ -232,7 +248,9 @@ 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).
+  // works without letting `echo pytest` forge a gate (D11 / M.2). make, just
+  // and task are not keys: their targets are matched against these keys
+  // (`make test check-shell`), because a bare `make` runs an unknown goal.
   gates: { pytest: "pytest", tsc: "typecheck", cargo: "cargo", jest: "test", vitest: "test", go: "go",
     test: "test", typecheck: "typecheck", check: "check", build: "build", lint: "lint", gate: "gate" },
   // Five minutes covers typical compiles and installs; longer work asks for
@@ -263,7 +281,8 @@ function caughtFailure(error: unknown, facts: FailureFacts, prefix = ""): ToolRe
  * the first word -- `python3 -m pytest`, `npx vitest run`, `uv run pytest` --
  * so first-token matching misses real gates. But matching any token anywhere
  * would let `echo pytest` count as a passing test suite, which is precisely
- * the fake evidence the rest of this design exists to reject.
+ * the fake evidence the rest of this design exists to reject. Each segment
+ * of an `&&` chain is matched the same way; see classifyGate.
  */
 export function matchGate(ctx: ToolContext, command: string): string | undefined {
   return classifyGate(ctx.gates, command);
@@ -284,6 +303,29 @@ function confine(ctx: ToolContext, path: string): string | { error: string } {
   return abs;
 }
 
+/**
+ * Assumed budget for listing the workspace after a failed lookup. The hint is
+ * a convenience on a failure path: past this the failure is returned without
+ * it rather than held up.
+ */
+const PATH_SUGGESTION_DEADLINE_MS = 2_000;
+
+/** A not_found for a workspace path names the closest existing paths (missing-path-candidates card). */
+async function withPathSuggestions(ctx: ToolContext, path: string, result: ToolResult): Promise<ToolResult> {
+  if (result.ok || result.diagnostic?.code !== "not_found") return result;
+  const abs = isAbsolute(path) ? resolve(path) : resolve(ctx.root, path);
+  if (!within(ctx.root, abs)) return result;
+  let listed: readonly string[];
+  try {
+    listed = (await buildFileIndex(ctx.root, { maxEntries: MAX_INDEX_ENTRIES, deadline: performance.now() + PATH_SUGGESTION_DEADLINE_MS,
+      ...(ctx.signal ? { signal: ctx.signal } : {}) })).paths;
+  } catch { return result; } // No listing, no hint; the failure itself stands.
+  const near = nearestPaths(relative(ctx.root, abs).split(sep).join("/"), listed.map(item => item.split(sep).join("/")));
+  if (near.length === 0) return result;
+  const hint = "\nDid you mean one of these existing paths?\n" + near.map(item => `  ${item}`).join("\n");
+  return { ...result, content: result.content + hint, diagnostic: { ...result.diagnostic, message: result.diagnostic.message + hint } };
+}
+
 function within(base: string, abs: string): boolean {
   const rel = relative(base, abs);
   return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
@@ -571,6 +613,34 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       required: ["node", "resolution"],
     },
   },
+  {
+    /**
+     * The model's way into an isolated checkout of this repository.
+     *
+     * Edits are confined to the session root, so isolation the model builds
+     * itself with `git worktree add` is unusable: outside the root is refused,
+     * and inside `.xeno` is session state. This creates the checkout where
+     * xeno keeps them and moves the root after the tool round, the way an
+     * adopted branch does; the cursor records the root, so resume stays there.
+     */
+    name: "worktree",
+    access: "state", execution: "exclusive", branch: "none",
+    example: { action: "enter", name: "fix-parser" },
+    description:
+      "enter: create a git worktree of this repository on a new branch xeno/<name> from HEAD, kept under xeno's config directory, " +
+      "and move this session's root there after the current tool round, so later edits and commands run in the isolated checkout. " +
+      "Use it when the shared working tree has changes by others or must stay untouched. include_changes copies the current uncommitted files. " +
+      "exit: move the root back to the repository's main checkout. The worktree and its branch are kept; nothing is merged or deleted.",
+    input_schema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["enter", "exit"] },
+        name: { type: "string", description: "enter: letters, digits, dot, dash or underscore; becomes the branch xeno/<name>" },
+        include_changes: { type: "boolean", description: "enter: start from the current uncommitted files instead of HEAD; default false" },
+      },
+      required: ["action"],
+    },
+  },
   {
     name: "bash",
     example: { command: "bun test", workdir: ".", timeout: 300 },
@@ -631,6 +701,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
         workdir: { type: "string", description: "Directory to run in; default the workspace root" },
         tty: { type: "boolean", description: "Run in a pseudo-terminal; default false" },
         yield_time_ms: { type: "integer", description: "Milliseconds to wait before returning; default 10000; effective range 100-30000, values outside are clamped" },
+        max_output_tokens: { type: "integer", minimum: 1, description: "Lower this call's inline output preview to about this many tokens; full output stays recoverable" },
         timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the session is killed; default 300" },
       },
       required: ["cmd"],
@@ -650,7 +721,8 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       properties: {
         session_id: { type: "integer", minimum: 1 },
         chars: { type: "string", description: "Characters to write; empty to poll" },
-        yield_time_ms: { type: "integer", description: "Bounded wait when sending input or using low-level polling; effective range 100-30000, values outside are clamped; agent empty waits are owned until an observation changes" },
+        yield_time_ms: { type: "integer", description: "Bounded wait when sending input or using low-level polling, effective range 100-30000; an agent's empty wait returns at exit or at the end of a window with new output, window default 10000, effective range 5000-300000; values outside are clamped" },
+        max_output_tokens: { type: "integer", minimum: 1, description: "Lower this call's inline output preview to about this many tokens; full output stays recoverable" },
       },
       required: ["session_id"],
     },
@@ -663,7 +735,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     description:
       "Search file contents for a regex. Stays inside the workspace, does " +
       "not follow symlinks, and skips .git, node_modules and .xeno. Uses " +
-      "ripgrep when it is already on PATH, otherwise a TypeScript walk. " +
+      "ripgrep when it is on PATH or in xeno's bin directory, otherwise a TypeScript walk. " +
       "Reports scan completeness separately from preview truncation. Long matches and omitted results remain in an immutable history artifact; use its sha256 and byte offset to recover them. Unknown or partial coverage cannot prove absence.",
     input_schema: {
       type: "object",
@@ -826,7 +898,7 @@ async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promi
     checkSourceCancellation(ctx.signal);
     text = Buffer.from(bytes).toString("utf8");
   } catch (err) {
-    return caughtFailure(err, READ_ATTEMPTED, `cannot read ${path}: `);
+    return withPathSuggestions(ctx, path, caughtFailure(err, READ_ATTEMPTED, `cannot read ${path}: `));
   }
 
   if (ctx.imageStore && detectSupportedImageMimeType(bytes)) {
@@ -971,7 +1043,7 @@ async function toolEdit(ctx: ToolContext, input: Record<string, unknown>): Promi
   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);
+  if (saved.bytes === null) return withPathSuggestions(ctx, path, failure("not_found", `cannot read ${path}: file does not exist`, READ_ATTEMPTED));
   const recover = { tool: "read", input: { path } };
   let before: string;
   try { before = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(saved.bytes); }
@@ -1040,16 +1112,17 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
   const observation = await commandFingerprint(ctx);
   const header = commandHeader({ exit, wallMs: captured.wallMs, timeoutMs,
     ...(requestedMs !== undefined ? { requestedMs } : {}),
-    ...(captured.stopped ? { stopped: captured.stopped } : {}) });
+    ...(captured.stopped ? { stopped: captured.stopped } : {}) }) + answerLabel(command, exit, captured.stopped);
   const artifactSummary = commandArtifactSummary(artifacts);
 
   return {
     // The artifact starts with `exit N\n`; the view replaces that line with
     // the full header and pages the rest, so offsets stay artifact offsets.
-    content: header + artifactSummary + "\n" + observationView(captured,
-      ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, captured.prefixBytes, adviceTools(ctx)),
+    // Folding only shrinks the view; the artifact and its offsets keep every byte.
+    content: header + artifactSummary + "\n" + foldCarriageReturns(observationView(captured,
+      ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, captured.prefixBytes, adviceTools(ctx))),
     content_ref: captured.ref,
-    ...commandCompletion(exit, captured.stopped, captured.cleanup),
+    ...commandCompletion(exit, captured.stopped, captured.cleanup, command),
     data: { exit, output: captured.ref, ...(captured.cleanup ? { cleanup: "unknown" } : {}), ...(artifacts ? { artifacts } : {}) },
     effect: {
       kind: "command",
@@ -1090,7 +1163,8 @@ async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promi
     ...(ctx.execOwner === undefined ? {} : { owner: ctx.execOwner }) });
   if ("error" in session) return failure("execution_failed", session.error);
   const wait = yieldWait(input["yield_time_ms"]);
-  return sessionResult(ctx, command, timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, wait.ms, "", ctx.signal), wait.note);
+  const view = { ...ctx, maxOutputBytes: outputBytesForTokens(input["max_output_tokens"], ctx.maxOutputBytes) };
+  return sessionResult(view, command, timeoutMs, await pollSession(session, outputStore, view.maxOutputBytes, wait.ms, "", ctx.signal), wait.note);
 }
 
 async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
@@ -1099,18 +1173,22 @@ async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>):
   const session = findSession(id, ctx.execOwner);
   if (session === undefined) {
     const closed = closedSession(id, ctx.execOwner);
-    if (closed) return receiptResult(ctx, { ...closed.receipt, replayed: true }, chars);
+    // Ctrl-C / Ctrl-D to a closed handle asks for what its exit already did: answer as a poll.
+    const input = isControlInput(chars) ? "" : chars;
+    if (closed) return receiptResult(ctx, { ...closed.receipt, replayed: true }, input);
     const original = await ctx.observedProcess?.(id);
-    if (original) return receiptResult(ctx, recoverProcessReceipt(original.receipt, original.origin), chars);
+    if (original) return receiptResult(ctx, recoverProcessReceipt(original.receipt, original.origin), input);
     const running = runningSessions(ctx.execOwner).map((s) => s.id).join(", ");
     return { ...failure("unknown_effect", `no running session ${id}; no observation in this session's active history` +
       (running.length > 0 ? `; running sessions: ${running}` : ""), UNKNOWN_EFFECT),
       data: { kind: "process", version: 1, session_id: id, state: "unknown", capability: "unknown", source: null, running: null, exit: null, replayed: true } };
   }
   const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  const wait = yieldWait(input["yield_time_ms"]);
-  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, wait.ms, chars, ctx.signal,
-    ctx.processWait && chars.length === 0 ? { wake: ctx.processWait.wake(), onWaiting: active => ctx.onProcessWait?.(id, active) } : undefined), wait.note);
+  const owner = chars.length === 0 ? ctx.processWait : undefined;
+  const wait = owner ? emptyYieldWait(input["yield_time_ms"]) : yieldWait(input["yield_time_ms"]);
+  const view = { ...ctx, maxOutputBytes: outputBytesForTokens(input["max_output_tokens"], ctx.maxOutputBytes) };
+  return sessionResult(view, session.command, session.timeoutMs, await pollSession(session, outputStore, view.maxOutputBytes, wait.ms, chars, ctx.signal,
+    owner ? { wake: owner.wake(), onWaiting: active => ctx.onProcessWait?.(id, active), windowMs: wait.ms } : undefined), wait.note);
 }
 
 /** A successful historical query proves only that the receipt was found, never a new command exit. */
@@ -1139,18 +1217,25 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
     ? `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 header = shown + waitNote;
+    : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, managed: true, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed` + answerLabel(command, exit, taken.stopped);
+  const unsent = taken.unsent === undefined ? "" : " · input was not sent: the process had already exited";
+  const header = shown + waitNote + unsent;
   const artifactSummary = commandArtifactSummary(taken.receipt.artifacts);
-  const content = header + artifactSummary + "\n" + observationView(stored, ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, 0, adviceTools(ctx));
+  const content = header + artifactSummary + "\n" + foldCarriageReturns(observationView(stored, ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, 0, adviceTools(ctx)));
   const warnings = taken.receipt.capture === "partial" ? [failureDiagnostic("unknown_effect", "output capture is partial; full_output contains only captured bytes", UNKNOWN_EFFECT)] : [];
   if (exit === null) {
     return { ok: true, content, content_ref: stored.ref, content_sha256: stored.ref.sha256, data: taken.receipt, ...(warnings.length ? { warnings } : {}) };
   }
   const gate = matchGate(ctx, command);
   const observation = await commandFingerprint(ctx);
+  // Refused input fails this call, yet the exit it observed is still recorded:
+  // the next poll only replays, so withholding the effect would lose it (D11).
+  const completion = taken.unsent === "refused"
+    ? { ok: false, outcome: executionOutcome("tool_failed"),
+      diagnostic: failureDiagnostic("not_found", "process had already exited; input was not sent; its exit and unread output are in this result", NOT_STARTED) }
+    : commandCompletion(exit, taken.stopped, undefined, command);
   return {
-    ...commandCompletion(exit, taken.stopped),
+    ...completion,
     content, content_ref: stored.ref, content_sha256: stored.ref.sha256,
     data: taken.receipt, ...(warnings.length ? { warnings } : {}),
     effect: { kind: "command", cmd: command, exit, ...(gate !== undefined ? { gate } : {}),
@@ -1158,6 +1243,12 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
   };
 }
 
+/** The program's own meaning of an answering exit (grep 1: no match; 141 after head), appended to the header; the exit itself stays. */
+function answerLabel(command: string, exit: number, stopped?: "cancelled" | "timeout"): string {
+  const meaning = stopped === undefined ? commandAnswer(command, exit) : null;
+  return meaning === null ? "" : ` · ${meaning}`;
+}
+
 const utf8Length = (text: string) => new TextEncoder().encode(text).length;
 
 /**
@@ -1352,26 +1443,41 @@ export async function gateTool(
 
   const permissionInput = name === "apply_patch" && input && typeof input === "object" && "patchText" in input ? { paths: patchPaths(parsePatch(String(input.patchText))) } : input;
   const request = await canonicalPermissionRequest(ctx.root, name, permissionInput);
-  let decision = decideWithSessionRules(ctx.rules, ctx.sessionRules ?? [], request);
+  let explained = explainDecision(ctx.rules, ctx.sessionRules ?? [], request);
   if (definition?.access === "read" && request.paths) for (const path of request.paths) {
-    const resource = await permissionResourceAction(ctx.root, path, ctx.rules, ctx.sessionRules ?? [], name);
-    if (resource === "deny") { decision = "deny"; break; }
-    if (resource === "ask" && decision === "allow") decision = "ask";
+    const resource = await permissionResourceDecision(ctx.root, path, ctx.rules, ctx.sessionRules ?? [], name);
+    if (resource.action === "deny") { explained = resource; break; }
+    if (resource.action === "ask" && explained.action === "allow") explained = resource;
   }
+  const decision = explained.action;
+  // feat-approval-events: the verdict is durable before the call can start, so
+  // the log answers "why was this allowed" -- including automatic allows.
+  const record = async (verdict: ApprovalRecord["decision"], source: ApprovalRecord["source"]) => {
+    if (!ctx.onApproval || ctx.callId === undefined || !approvalNeeded(request, decision)) return;
+    await ctx.onApproval({ call_id: ctx.callId, tool: request.tool, decision: verdict, source,
+      ...(request.command !== undefined ? { command: request.command } : {}),
+      ...(explained.rule ? { rule: describeRule(explained.rule) } : {}) });
+  };
   switch (decision) {
     case "allow":
+      // An empty rule list consulted no policy (tool tests, trusted host execution).
+      if (explained.source !== "none") await record("allow", explained.source);
       return null;
     case "deny":
+      await record("deny", "config");
       return failure("permission_denied", deniedMessage(request));
     case "ask": {
       const ask = ctx.ask ?? ctx.askSlot?.current;
       if (ask === undefined) {
+        await record("deny", "no_prompt");
         return failure("permission_denied", askWithoutTtyMessage(request));
       }
       let choice: ApprovalChoice | undefined;
       try { choice = await waitForAdmission(ask(request), ctx.signal); }
       catch (error) { return caughtFailure(error, NOT_STARTED, "approval unavailable: "); }
+      // A withdrawn prompt is not a decision; the result already says cancelled.
       if (choice === undefined || ctx.signal?.aborted) return cancelledTool();
+      await record(choice, "user");
       switch (choice) {
         case "once":
           return null;
@@ -1463,6 +1569,8 @@ export async function prepareNormalizedTool(ctx: ToolContext, name: string, inpu
     try {
       if (!begun) await scoped(() => ctx.extensionHooks?.event("tool_execution_start", { ...lifecycle, args: observerValue(input) }));
       await ctx.drainNested?.();
+      // Admission, the durable invocation and every hook saw the placeholder; only the tool sees the value.
+      const runInput = ctx.expandSecrets ? ctx.expandSecrets(input) : input;
       const execute = async () => {
         const executionContext: ToolContext = { ...ctx, onOutput: chunk => {
           ctx.onOutput?.(chunk);
@@ -1473,11 +1581,11 @@ export async function prepareNormalizedTool(ctx: ToolContext, name: string, inpu
           }
         } };
         observed = owned ? finishToolResult(ctx.signal?.aborted ? cancelledTool() : await owned(),
-          toolDefinition(name, ctx)?.access === "read" ? READ_ATTEMPTED : UNKNOWN_EFFECT) : await dispatchTool(executionContext, name, input);
+          toolDefinition(name, ctx)?.access === "read" ? READ_ATTEMPTED : UNKNOWN_EFFECT) : await dispatchTool(executionContext, name, runInput);
         return observed;
       };
       const command = ["bash", "environment", "target", "exec_command", "write_stdin", NATIVE_COMMAND_NAME].includes(name);
-      const operation = () => ctx.workspace && command ? ctx.workspace.command(name, input, execute, ctx.signal) : execute();
+      const operation = () => ctx.workspace && command ? ctx.workspace.command(name, runInput, execute, ctx.signal) : execute();
       // Progress handlers may enqueue native commands. They run only after this
       // process drains, before the outer receipt; awaiting them inside it deadlocks.
       observed = command && ctx.runOwnedCommand ? await ctx.runOwnedCommand(operation) : await operation();

package/src/runtime/turn-effects.ts

@@ -0,0 +1,31 @@
+/**
+ * The current request's operations outside the workspace, read from the log
+ * when a request ends (feat-external-effects-summary). The derivation is the
+ * pure core function; this file only supplies what core may not read: the
+ * home directory and the platform's temporary directory.
+ * Nothing is recorded -- the list is a projection and is recomputed on demand.
+ */
+import { realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { externalEffects, type ExternalEffect, type ExternalOptions } from "../core/external-effects.ts";
+import { currentRequestEvents } from "../core/request-state.ts";
+import type { Session } from "./loop.ts";
+
+/** macOS reports /var/folders/... while processes see /private/var/folders/...; both are temporary. */
+export function hostExternalOptions(): ExternalOptions {
+  const temp = tmpdir();
+  let real = temp;
+  try { real = realpathSync(temp); } catch { /* an unreadable temp root is still the reported one */ }
+  return { home: homedir(), temp: [...new Set([temp, real])] };
+}
+
+/**
+ * Synchronous on purpose: SessionControl computes this between the turn's last
+ * event and releasing the turn, and an await there lets a disposal observe a
+ * turn that has already ended. The cost is one known gap: a request that
+ * crossed a segment boundary lists only what ran after the last cut (D8 keeps
+ * the earlier part in the sealed segment, not in memory). Silence, not a guess.
+ */
+export function requestExternalEffects(session: Session, options: ExternalOptions = hostExternalOptions()): ExternalEffect[] {
+  return externalEffects(currentRequestEvents(session.state.events), session.config.tools.root, options);
+}

package/src/store/command.ts

@@ -1,5 +1,7 @@
 /** O.1: own the process group, preserve partial observations, and drain before returning. */
 import { captureCommandObservation } from "./observations.ts";
+import { configDir } from "./config.ts";
+import { xenoBinDir } from "./tool-binaries.ts";
 import { commandArgv, commandEnvironment, COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
 import { ToolFault, NOT_STARTED, failureDiagnostic } from "../core/tool-failure.ts";
 
@@ -44,7 +46,7 @@ async function executeCaptured(input: CommandCaptureInput, argv: string[], nativ
       cwd: input.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe", detached: true,
       // Preserve the trusted native API's inherited environment; shell tools
       // retain their explicit noninteractive policy and login-shell startup.
-      env: native ? process.env : commandEnvironment(process.env),
+      env: native ? process.env : commandEnvironment(process.env, xenoBinDir(configDir())),
     }); } catch (error) {
       const os = (error as { code?: string }).code;
       throw new ToolFault(os === "ENOENT" || os === "ENOTDIR" ? "environment_missing" : os === "EACCES" || os === "EPERM" ? "permission_denied" : "execution_failed", String(error), NOT_STARTED);

package/src/store/context-files.ts

@@ -390,7 +390,11 @@ export async function discoverTargetInstructions(options: TargetInstructionOptio
   const root = resolve(options.workspace), directories = new Set<string>();
   for (const path of options.paths) {
     const absolute = resolve(root, path);
-    if (!isInside(absolute, root)) throw new Error(`instruction target escapes workspace: ${path}`);
+    // No workspace scope applies outside it, and another project's AGENTS.md
+    // is not this workspace's authority. Whether the target may be touched at
+    // all is the path rules' decision; throwing here pre-empted it with an
+    // internal step's name (outside-path-instructions card).
+    if (!isInside(absolute, root)) continue;
     for (const directory of projectDirectories(root, dirname(absolute))) directories.add(directory);
   }
   const ordered = [...directories].sort((a, b) => a.split(sep).length - b.split(sep).length || a.localeCompare(b));

package/src/store/file-checkpoints.ts

@@ -4,12 +4,15 @@ import { resolve, relative, dirname, join, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { blobAddress, putBlob, getBlobBytes, verifyBlob } from "./blobs.ts";
 import { sameVersion, changedPaths, type FileVersion, type FileChanges } from "../core/checkpoints.ts";
-import { ToolFault, NOT_STARTED, READ_ATTEMPTED, failureFromError } from "../core/tool-failure.ts";
+import { ToolFault, NOT_STARTED, READ_ATTEMPTED, STATE_PATH_GUIDANCE, failureFromError } from "../core/tool-failure.ts";
 
 export async function editablePath(root: string, path: string): Promise<string> {
   const base = resolve(root), absolute = resolve(base, path), rel = relative(base, absolute);
-  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || resolve(rel) === rel ||
-      rel.split(sep).some(part => part === ".git" || part === ".xeno")) throw new ToolFault("permission_denied", `unsafe file checkpoint path: ${path}`, NOT_STARTED);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || resolve(rel) === rel) throw new ToolFault("permission_denied", `unsafe file checkpoint path: ${path}`, NOT_STARTED);
+  // Session logs and blobs are the evidence; an edit there could rewrite it.
+  if (rel.split(sep).some(part => part === ".git" || part === ".xeno")) {
+    throw new ToolFault("permission_denied", `${path} is inside .git or .xeno, which edit tools never change; this is not a permission problem and no approval will allow it`, NOT_STARTED, { next: STATE_PATH_GUIDANCE });
+  }
   let current = base;
   for (const part of rel.split(sep)) {
     current = join(current, part);

package/src/store/log.ts

@@ -125,6 +125,11 @@ export interface Cursor {
   workspace?: string;
   /** Content-addressed frozen context; credentials and approvals are excluded. */
   context_ref?: string;
+  /**
+   * The xeno release that wrote this cursor. Every start writes one, so the
+   * append-only metadata journal is a timeline of the versions a session ran under.
+   */
+  xeno_version?: string;
   /**
    * A human name. Optional because most sessions never get one, and a log
    * written before names existed has none. Absent rather than empty: an
@@ -554,6 +559,21 @@ export async function readCursorAt(dir: string, node: number, atEvent?: string):
   return stateAtPosition(states, node, events.map(event => event.id), atEvent);
 }
 
+/**
+ * When this session was forked, or null for an original (fix-fork-start-time).
+ * copyAncestryTo keeps the parent's nodes and their timestamps, then writes
+ * the fork cursor and, right after it, the parent_session record; that
+ * cursor's updated_at is the fork moment. The last parent_session record is
+ * this session's own: a copied parent that was itself a fork brings its
+ * record along in the copied journal.
+ */
+export async function forkedAt(dir: string): Promise<string | null> {
+  const records = await readMetadata(dir) ?? [];
+  const own = records.findLastIndex(record => record.kind === "parent_session");
+  const cursor = records.slice(0, Math.max(0, own)).findLast(record => record.kind === "cursor");
+  return own >= 0 && cursor?.kind === "cursor" ? cursor.cursor.updated_at : null;
+}
+
 /** D3: the replaceable manifest is a projection of committed metadata events. */
 export async function readManifest(dir: string): Promise<Manifest> {
   return serialized(dir, () => readManifestUnlocked(dir));

package/src/store/replay.ts

@@ -7,7 +7,7 @@
 import { deriveHandoff } from "../core/derive.ts";
 import type { Handoff } from "../core/handoff.ts";
 import type { CutEvent, LogEvent } from "../core/events.ts";
-import { boundHandoff, boundRecoveryHandoff } from "../core/history.ts";
+import { boundHandoff, boundRecoveryHandoff, boundRecoveryHandoffV3 } from "../core/history.ts";
 import { retainedContext } from "../core/context-window.ts";
 import { digestNode, nodePath, readAncestry, readManifest, type Manifest } from "./log.ts";
 import { readNodeHistory } from "./restore.ts";
@@ -27,10 +27,11 @@ export interface ReplayedContext {
 export async function carriedHandoff(dir: string, node: number, full: Handoff,
   policy: Pick<CutEvent, "handoff_tokens" | "working_set_version" | "guidance_tools">, manifest?: Manifest): Promise<Handoff> {
   if (policy.handoff_tokens === undefined) return full;
-  if (policy.working_set_version === 2) {
+  // The recorded version selects the algorithm; a new default never reinterprets an old cut.
+  if (policy.working_set_version === 2 || policy.working_set_version === 3) {
     const history = await readNodeHistory(dir, node, manifest, "context");
     if (!history.ok) throw new Error(history.error);
-    return boundRecoveryHandoff(full, history.nodes, policy.handoff_tokens, policy.guidance_tools);
+    return (policy.working_set_version === 3 ? boundRecoveryHandoffV3 : boundRecoveryHandoff)(full, history.nodes, policy.handoff_tokens, policy.guidance_tools);
   }
   return boundHandoff(full, policy.handoff_tokens);
 }