@visual-z/xeno 0.8.2 → 0.8.4

package/src/runtime/secrets.ts

@@ -0,0 +1,79 @@
+/**
+ * The session's live view of its secret vault (S.9). Rules and the inverse
+ * live in core/secrets.ts; this owns the mutable entries, their durable
+ * append, and the walk over an event's fields.
+ *
+ * One keeper per session tree: a branch shares its parent's, because both
+ * write the same log and a placeholder number must mean one value in it.
+ */
+import { expandText, isSolicitedSecret, mapStrings, placeholder, redactText, type SecretEntry } from "../core/secrets.ts";
+import type { LogEvent } from "../core/events.ts";
+import { appendVault, readVault } from "../store/secrets.ts";
+
+// Fields whose bytes a provider or the store verifies: rewriting them breaks
+// replay (signed thinking, raw provider blocks) or identity, and none of them
+// carries text a person typed or a tool printed.
+const VERIFIED_FIELDS = new Set(["id", "at", "raw", "wire", "signature", "replay_key", "sha256", "call_id", "user_id", "parent_call_id"]);
+
+export class SecretKeeper {
+  private entries: SecretEntry[] = [];
+  private pending: Promise<void> = Promise.resolve();
+
+  private readonly dir: string;
+  private readonly candidates: readonly { value: string; rule: string }[];
+
+  constructor(dir: string, candidates: readonly { value: string; rule: string }[] = []) {
+    this.dir = dir; this.candidates = candidates;
+  }
+
+  async load(): Promise<void> {
+    const stored = await readVault(this.dir);
+    // Entries this keeper already assigned (none before start) stay; stored ones fill in.
+    for (const entry of stored) if (!this.entries.some(known => known.n === entry.n)) this.entries.push(entry);
+  }
+
+  /**
+   * Returns the event to write and whether this call added vault entries. The
+   * entries are in memory at once -- the next event numbers after them -- and
+   * durable before the returned promise resolves, so no written event ever
+   * holds a placeholder the vault cannot expand.
+   */
+  async redact(event: LogEvent, previousAssistantText: string | undefined): Promise<{ event: LogEvent; added: number }> {
+    const added: SecretEntry[] = [];
+    const redact = (text: string): string => {
+      const result = redactText(text, [...this.entries, ...added], this.candidates);
+      added.push(...result.added);
+      return result.text;
+    };
+    const skip = (key: string) => VERIFIED_FIELDS.has(key);
+    let next: LogEvent;
+    if (event.t === "checkpoint") next = event; // file fingerprints and paths, never projected
+    else if (event.t === "assistant") {
+      // Thinking is replayed under the provider's signature; a changed byte is a rejected request.
+      next = { ...event, blocks: event.blocks.map(block => block.type === "thinking" ? block : mapStrings(block, redact, skip) as typeof block) };
+    } else if (event.t === "user" && isSolicitedSecret(event.text, previousAssistantText)) {
+      // The whole message is the credential, however short: it was asked for.
+      const value = event.text.trim();
+      const entry = this.entries.find(known => known.value === value) ??
+        { n: this.entries.reduce((max, known) => Math.max(max, known.n), 0) + 1, value, rule: "solicited" };
+      if (!this.entries.includes(entry)) added.push(entry);
+      next = { ...mapStrings(event, redact, key => skip(key) || key === "text") as LogEvent & { t: "user" }, text: placeholder(entry.n) };
+    } else next = mapStrings(event, redact, skip) as LogEvent;
+    if (added.length > 0) {
+      this.entries.push(...added);
+      const write = this.pending.then(() => appendVault(this.dir, added));
+      this.pending = write.catch(() => {});
+      await write;
+    }
+    return { event: next, added: added.length };
+  }
+
+  /** Tool input as the tool should run it: placeholders become values. */
+  expand(input: unknown): unknown {
+    return this.entries.length === 0 ? input : mapStrings(input, text => expandText(text, this.entries));
+  }
+}
+
+export const SECRET_GUIDANCE = "Values written as [[xeno-secret-N]] are credentials xeno hid from you. " +
+  "Use the placeholder exactly as written in tool inputs; xeno substitutes the real value when the tool runs " +
+  "and hides it again in the output. Do not ask the user to repeat a hidden value.";

package/src/runtime/session-control.ts

@@ -13,6 +13,8 @@ import type { Session, LoopEvent, RequestOptions } from "./loop.ts";
 import type { ApprovalChoice } from "./tools.ts";
 import { validateQuestionReply, type QuestionRequest, type QuestionReply } from "../core/question.ts";
 import type { QuestionSlot } from "./question-tool.ts";
+import { requestExternalEffects } from "./turn-effects.ts";
+import type { ExternalEffect } from "../core/external-effects.ts";
 
 export type ControlNotice = { method: string; params: { threadId: string; streamId: string; sequence: number; turnId?: string; [key: string]: unknown } };
 export type PendingApproval = { id: string; turnId: string; request: PermissionRequest };
@@ -41,6 +43,8 @@ export class SessionControl {
   private waiting: ControlSnapshot["waiting"] = null;
   private changing = false;
   private inputSource: ((phase: Phase) => Promise<UserInput | null>) | undefined;
+  /** What the last finished turn did outside the workspace, as sent with its turn/completed. */
+  lastExternalEffects: readonly ExternalEffect[] = [];
 
   constructor(session: Session) {
     this.session = session;
@@ -144,7 +148,11 @@ export class SessionControl {
           if (state?.request.event === active.id) outcome = state.execution;
         }
       } catch { /* unreadable storage stays unknown, never an invented completion */ }
-      this.emit("turn/completed", { ...(outcome ? { outcome } : {}), steeringUndelivered: active.queue.length });
+      // feat-external-effects-summary: a projection of this request's receipts, never a stored event.
+      let externalEffects: ExternalEffect[] = [];
+      try { externalEffects = requestExternalEffects(this.session); } catch { /* the list is advisory; a read failure shows none */ }
+      this.lastExternalEffects = externalEffects;
+      this.emit("turn/completed", { ...(outcome ? { outcome } : {}), steeringUndelivered: active.queue.length, externalEffects });
       this.active = null;
     }
   }

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, negativeAnswer, outputBytesForTokens } 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));
@@ -679,7 +721,7 @@ 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"],
@@ -856,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)) {
@@ -1001,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); }
@@ -1076,8 +1118,9 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
   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, command),
     data: { exit, output: captured.ref, ...(captured.cleanup ? { cleanup: "unknown" } : {}), ...(artifacts ? { artifacts } : {}) },
@@ -1130,19 +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"]);
+  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,
-    ctx.processWait && chars.length === 0 ? { wake: ctx.processWait.wake(), onWaiting: active => ctx.onProcessWait?.(id, active) } : undefined), wait.note);
+    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. */
@@ -1172,17 +1218,24 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
       ? `poll or send input with write_stdin(session_id=${id})`
       : "process-control capability unavailable; execution remains unfinished; do not replay")
     : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, managed: true, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed` + answerLabel(command, exit, taken.stopped);
-  const header = shown + waitNote;
+  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, undefined, command),
+    ...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 } : {}),
@@ -1190,9 +1243,9 @@ export async function sessionResult(ctx: ToolContext, command: string, timeoutMs
   };
 }
 
-/** The program's own meaning of exit 1 (grep: no match), appended to the header; the exit itself stays. */
+/** 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 ? negativeAnswer(command, exit) : null;
+  const meaning = stopped === undefined ? commandAnswer(command, exit) : null;
   return meaning === null ? "" : ` · ${meaning}`;
 }
 
@@ -1390,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;
@@ -1501,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);
@@ -1511,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/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

@@ -11,7 +11,7 @@ export async function editablePath(root: string, path: string): Promise<string>
   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", `unsafe file checkpoint path: ${path} is inside .git or .xeno, which edit tools never change`, NOT_STARTED, { next: STATE_PATH_GUIDANCE });
+    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)) {

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);
 }