@visual-z/xeno 0.4.0 → 0.6.0

package/src/core/completion-review.ts

@@ -59,24 +59,33 @@ export function requestCompletion(state: RequestState, remainingRequests: number
 
   const gaps: string[] = [];
   const acceptance = options?.acceptance ?? state.acceptance;
+  const missingCommands = acceptance?.status === "needs_work" ? acceptance.criteria.flatMap(item =>
+    item.kind === "command" && item.status !== "pass" ? [{ id: item.id, command: item.command, status: item.status }] : []) : [];
   if (state.used_tools && text.length === 0) gaps.push("the final reply is empty");
   if (state.changed && !verifiedAfter && !acceptance) gaps.push("files were changed but no command has succeeded since the last edit");
   if (acceptance?.status === "needs_work") gaps.push(`declared acceptance criteria need evidence: ${[
-    ...acceptance.criteria.filter(item => item.kind === "command" && item.status !== "pass").map(item => `${item.id}=${item.status}`),
+    ...missingCommands.map(item => `${item.id}=${item.status}`),
     ...(acceptance.targets ?? []).filter(target => target.status !== "ready").map(target => `target ${target.id}=${target.status}`),
   ].join(", ")}`);
   if (text.length > 0 && looksLikeHandBack(text) && acceptance?.status !== "awaiting_human") gaps.push(options?.taskAware
     ? "the reply deferred the request; check whether authorized work remains or a specific blocker requires the user"
     : "the reply handed the task back instead of finishing it; no one will answer");
   if (gaps.length === 0) return finish;
+  // D11 / O.11: a declared command needs its exact receipt even when the
+  // request has no recorded edit. Compound shell success is not that receipt.
+  const next = missingCommands.length > 0
+    ? "Obtain a fresh successful receipt for each missing command. Run each command exactly as a separate invocation without adding other commands:\n" +
+      missingCommands.map(item => `- ${item.id}: ${JSON.stringify(item.command)}`).join("\n") +
+      "\nIf verification cannot run, report the specific blocker. "
+    : options?.taskAware && !state.changed
+      ? "Use original sources for research and full inputs for calculations; do not invent command evidence. Finish with the result or the specific blocker. "
+      : "Run the command that verifies the result, or finish with the specific blocker that prevents verification. ";
   return { action: "continue", guidance: {
     reason: "completion_review",
     sources: [state.request.event, final.source.event],
     text: `Harness completion check: ${gaps.join("; ")}. ` +
       `Re-read the original request (event ${state.request.event}) and check each requirement against evidence in this session. ` +
-      (options?.taskAware && !state.changed
-        ? "Use original sources for research and full inputs for calculations; do not invent command evidence. Required human acceptance remains pending. Finish with the result or the specific blocker. "
-        : "Run the command that verifies the result, or finish with the specific blocker that prevents verification. ") +
+      next + (acceptance?.criteria.some(item => item.kind === "human" && item.status !== "accepted") ? "Required human acceptance remains pending. " : "") +
       "This check runs once per request.",
   } };
 }

package/src/core/control-protocol.ts

@@ -9,12 +9,19 @@ const turn = { ...thread, turnId: identity };
 export const CONTROL_METHODS = {
   initialize: object({ clientInfo: object({ name: identity, version: identity }) }),
   initialized: object({}),
+  "thread/list": object({}),
+  "thread/new": object({ name: identity }, []),
+  "thread/resume": object({ session: text }),
+  "thread/fork": object({ ...thread, name: identity }, ["threadId"]),
+  "thread/close": object(thread),
+  "thread/mode": object({ ...thread, mode: { enum: ["build", "plan"] } }),
   "thread/read": object(thread),
   "thread/subscribe": object({ ...thread, after: object({ streamId: identity, sequence: { type: "integer", minimum: 0 } }) }, ["threadId"]),
   "turn/start": object({ ...thread, input: text }),
   "turn/steer": object({ ...turn, input: text }),
   "turn/interrupt": object(turn),
   "approval/respond": object({ ...turn, approvalId: identity, choice: { enum: ["once", "command", "tool", "deny"] } }),
+  "question/respond": object({ ...turn, requestId: text, reply: text }),
   "acceptance/accept": object({ ...thread, requestId: identity, criterionId: identity }),
   "context/read": object({ ...thread, focus: { enum: ["messages", "omitted", "history"] }, offset: { type: "integer", minimum: 0 },
     limit: { type: "integer", minimum: 1, maximum: 100 } }, ["threadId", "focus"]),
@@ -24,7 +31,7 @@ export const CONTROL_METHODS = {
 } as const;
 export const CONTROL_SCHEMA = { protocol: "xeno-control/0.1", experimental: true,
   transport: "JSONL; JSON-RPC envelopes with jsonrpc omitted", methods: CONTROL_METHODS,
-  notifications: ["turn/started", "turn/event", "item/completed", "turn/completed", "turn/error", "turn/steeringQueued", "approval/request", "approval/resolved", "thread/statusChanged"],
+  notifications: ["turn/started", "turn/event", "item/completed", "turn/completed", "turn/error", "turn/steeringQueued", "approval/request", "approval/resolved", "question/request", "question/resolved", "thread/statusChanged"],
   recovery: "subscribe first, then use the returned snapshot cursor; gaps or a new streamId require a snapshot and paginated item/list, never replaying commands",
   identity: "threadId hashes the resolved session directory path; turnId is the original user event ID; item identity is node plus event ID",
   limits: { frameBytes: 1048576, queuedRequests: 32, outputBytes: 2097152 } } as const;

package/src/core/file-precondition.ts

@@ -26,6 +26,12 @@ export const isFileDigest = (value: unknown): value is string => typeof value ==
 export function latestObservedFileVersion(events: readonly LogEvent[], resource: string, identify: (path: string) => string): string | undefined {
   for (let index = events.length - 1; index >= 0; index--) {
     const event = events[index]!;
+    // P.3: multi-file Patch and captured commands observe each actual resulting version.
+    if (event.t === "checkpoint" && event.phase === "applied") {
+      for (const [path, change] of Object.entries(event.changes))
+        if (identify(path) === resource) return change.after?.sha256;
+      continue;
+    }
     if (event.t !== "tool_result") continue;
     const effect = event.effect;
     if ((effect?.kind === "read" || effect?.kind === "edit") && identify(effect.path) === resource)

package/src/core/lsp-framing.ts

@@ -0,0 +1,34 @@
+/** LSP 3.17 uses byte-counted Content-Length, not line-delimited JSON. */
+export type LspFrame = { body: Uint8Array; consumed: number };
+// Operational ceiling for optional server output; this is not a context segment threshold.
+export const MAX_LSP_FRAME = 8 * 1024 * 1024;
+// An operational bound, independent of context-segment thresholds: reject unbounded headers.
+export const MAX_LSP_HEADER = 8192;
+export function nextLspFrame(bytes: Uint8Array): LspFrame | null {
+  let end = -1;
+  for (let i = 0; i + 3 < bytes.length; i++) if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) { end = i; break; }
+  if (end < 0) { if (bytes.length > MAX_LSP_HEADER) throw Error("LSP header exceeds 8 KiB"); return null; }
+  if (end > MAX_LSP_HEADER || bytes.subarray(0, end).some(byte => byte > 127)) throw Error("invalid LSP ASCII header");
+  const headers = new TextDecoder("ascii").decode(bytes.subarray(0, end)).split("\r\n");
+  if (headers.some(header => !/^[a-zA-Z0-9-]+:[\t\x20-\x7e]*$/.test(header))) throw Error("invalid LSP header field");
+  const lengths = headers.filter(header => /^content-length:/i.test(header));
+  if (lengths.length !== 1 || !/^content-length:\s*[0-9]+\s*$/i.test(lengths[0]!)) throw Error("invalid LSP Content-Length");
+  const types = headers.filter(header => /^content-type:/i.test(header));
+  if (types.length > 1) throw Error("ambiguous LSP Content-Type");
+  const charsets = types.flatMap(header => header.split(";").slice(1).filter(parameter => /^\s*charset\s*=/i.test(parameter)));
+  if (charsets.length > 1 || charsets.some(parameter => !/^\s*charset\s*=\s*(utf-?8|"utf-?8")\s*$/i.test(parameter))) throw Error("unsupported LSP charset");
+  const length = Number(lengths[0]!.split(":")[1]!.trim());
+  if (!Number.isSafeInteger(length) || length > MAX_LSP_FRAME) throw Error("LSP frame exceeds 8 MiB");
+  const consumed = end + 4 + length;
+  return bytes.length < consumed ? null : { body: bytes.slice(end + 4, consumed), consumed };
+}
+/** Unversioned server diagnostics cannot prove that they describe the current owned file. */
+export function diagnosticFreshness(observedVersion: number | undefined, currentVersion: number): "current" | "stale" | "unversioned" {
+  return observedVersion === undefined ? "unversioned" : observedVersion === currentVersion ? "current" : "stale";
+}
+export function encodeLspFrame(value: unknown): Uint8Array {
+  const body = new TextEncoder().encode(JSON.stringify(value));
+  if (body.length > MAX_LSP_FRAME) throw Error("LSP frame exceeds 8 MiB");
+  const header = new TextEncoder().encode(`Content-Length: ${body.length}\r\n\r\n`);
+  const frame = new Uint8Array(header.length + body.length); frame.set(header); frame.set(body, header.length); return frame;
+}

package/src/core/mcp-config.ts

@@ -0,0 +1,68 @@
+/** Explicit MCP configuration is authority; remote tool annotations never grant permissions (D11/D13). */
+import { webUrl } from "./web-content.ts";
+
+export interface McpOAuthConfig { clientId?: string; clientSecretEnv?: string; scope?: string; redirectUrl?: string }
+interface McpCommonConfig { enabled?: boolean; timeoutMs?: number }
+export type McpServerConfig = McpCommonConfig & ({ transport: "stdio"; command: string; args?: string[]; env?: Record<string, string> }
+  | { transport: "http"; url: string; bearerTokenEnv?: string; headers?: Record<string, string>; headersEnv?: Record<string, string>; oauth?: boolean | McpOAuthConfig });
+export type McpServers = Readonly<Record<string, McpServerConfig>>;
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error(`${label} must be an object`);
+  return value as Record<string, unknown>;
+}
+function strings(value: unknown, label: string, envNames = false): Record<string, string> {
+  const source = object(value, label), result: Record<string, string> = Object.create(null);
+  for (const [key, entry] of Object.entries(source)) {
+    if (typeof entry !== "string" || /[\r\n\u0000]/.test(entry) || /[\r\n\u0000]/.test(key)) throw Error(`${label} must contain single-line string values`);
+    if (envNames && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(entry)) throw Error(`${label} values must name environment variables`);
+    result[key] = entry;
+  }
+  return result;
+}
+function optionalString(source: Record<string, unknown>, key: string, envName = false): string | undefined {
+  const value = source[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value || /[\r\n\u0000]/.test(value) || envName && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) throw Error(`${key} must be a valid ${envName ? "environment variable name" : "single-line string"}`);
+  return value;
+}
+export function mcpCallbackUrl(value: string): string {
+  const parsed = new URL(webUrl(value));
+  if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1" || parsed.search || !parsed.port || !parsed.pathname.startsWith("/"))
+    throw Error("OAuth redirectUrl must be an HTTP 127.0.0.1 URL with an explicit port and no query");
+  return parsed.href;
+}
+function oauth(value: unknown): boolean | McpOAuthConfig {
+  if (typeof value === "boolean") return value;
+  const source = object(value, "oauth");
+  if (Object.keys(source).some(key => !["clientId", "clientSecretEnv", "scope", "redirectUrl"].includes(key))) throw Error("oauth has an unsupported field");
+  const clientId = optionalString(source, "clientId"), clientSecretEnv = optionalString(source, "clientSecretEnv", true), scope = optionalString(source, "scope"), redirectUrl = optionalString(source, "redirectUrl");
+  if (clientSecretEnv && !clientId) throw Error("oauth.clientSecretEnv requires oauth.clientId");
+  return { ...(clientId ? { clientId } : {}), ...(clientSecretEnv ? { clientSecretEnv } : {}), ...(scope ? { scope } : {}), ...(redirectUrl ? { redirectUrl: mcpCallbackUrl(redirectUrl) } : {}) };
+}
+export function parseMcpServers(value: unknown): McpServers {
+  if (value === undefined || value === null) return {};
+  const source = object(value, "mcpServers"), result: Record<string, McpServerConfig> = Object.create(null);
+  for (const [name, raw] of Object.entries(source)) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) throw Error("MCP server names must contain 1 to 64 letters, digits, underscores or hyphens");
+    const config = object(raw, `MCP server ${name}`), enabled = config["enabled"], timeout = config["timeoutMs"];
+    if (enabled !== undefined && typeof enabled !== "boolean") throw Error(`MCP server ${name}.enabled must be boolean`);
+    // Assumed cap protects startup and tool execution from a misconfigured peer, not an OS sandbox.
+    if (timeout !== undefined && (!Number.isSafeInteger(timeout) || Number(timeout) < 1 || Number(timeout) > 300_000)) throw Error("MCP timeoutMs must be an integer from 1 to 300000");
+    const common = { ...(typeof enabled === "boolean" ? { enabled } : {}), ...(typeof timeout === "number" ? { timeoutMs: timeout } : {}) };
+    if (config["transport"] === "stdio") {
+      if (Object.keys(config).some(key => !["transport", "command", "args", "env", "enabled", "timeoutMs"].includes(key))) throw Error(`MCP server ${name} has an unsupported stdio field`);
+      const command = optionalString(config, "command"), args = config["args"], env = config["env"];
+      if (!command) throw Error(`MCP server ${name}.command is required`);
+      if (args !== undefined && (!Array.isArray(args) || !args.every(arg => typeof arg === "string" && !arg.includes("\u0000")))) throw Error("MCP args must be strings without NUL");
+      result[name] = { transport: "stdio", command, ...common, ...(Array.isArray(args) ? { args: args.slice() as string[] } : {}), ...(env === undefined ? {} : { env: strings(env, "env") }) };
+    } else if (config["transport"] === "http") {
+      if (Object.keys(config).some(key => !["transport", "url", "bearerTokenEnv", "headers", "headersEnv", "oauth", "enabled", "timeoutMs"].includes(key))) throw Error(`MCP server ${name} has an unsupported HTTP field`);
+      const token = optionalString(config, "bearerTokenEnv", true), headers = config["headers"], headersEnv = config["headersEnv"];
+      if (config["oauth"] && token) throw Error("Use bearerTokenEnv or oauth for one MCP server, not both");
+      result[name] = { transport: "http", url: webUrl(config["url"]), ...common, ...(token ? { bearerTokenEnv: token } : {}),
+        ...(headers === undefined ? {} : { headers: strings(headers, "headers") }), ...(headersEnv === undefined ? {} : { headersEnv: strings(headersEnv, "headersEnv", true) }),
+        ...(config["oauth"] === undefined ? {} : { oauth: oauth(config["oauth"]) }) };
+    } else throw Error(`MCP server ${name}.transport must be stdio or http`);
+  }
+  return result;
+}

package/src/core/model-preferences.ts

@@ -0,0 +1,28 @@
+/** User selections become startup preferences; restored session state stays in the log (D8/Q.25). */
+import { recordRecent } from "./model-picker.ts";
+import { modelKey } from "./session-position.ts";
+import { settingsToWrite, type Settings } from "./settings.ts";
+import type { ThinkingLevel } from "./thinking.ts";
+
+interface ModelIdentity { readonly provider: string; readonly id: string }
+
+/** Keep the effective effort with its model, without changing another model's saved effort. */
+export function modelPreferencePatch(model: ModelIdentity, recent: readonly string[], effort: ThinkingLevel): Settings {
+  return { defaultProvider: model.provider, defaultModel: model.id, recentModels: recordRecent(recent, modelKey(model)),
+    modelThinkingLevels: { [modelKey(model)]: effort } };
+}
+
+export function thinkingPreferencePatch(model: ModelIdentity, effort: ThinkingLevel): Settings {
+  return { defaultThinking: effort, modelThinkingLevels: { [modelKey(model)]: effort } };
+}
+
+/** Patch only known preferences; retain future keys and nested fields not owned by this selection. */
+export function mergePreferenceJson(previous: Readonly<Record<string, unknown>>, patch: Settings): Record<string, unknown> {
+  const next = { ...previous, ...settingsToWrite(patch) };
+  for (const key of ["terminal", "images", "markdown", "modelThinkingLevels"] as const) {
+    if (patch[key] === undefined) continue;
+    const old = previous[key];
+    next[key] = { ...(old !== null && typeof old === "object" && !Array.isArray(old) ? old : {}), ...patch[key] };
+  }
+  return next;
+}

package/src/core/patch.ts

@@ -0,0 +1,130 @@
+/** Codex patch grammar with exact, unambiguous matching (D9 / R4). No I/O. */
+import { assertNever } from "./exhaustive.ts";
+
+// Assumed resource ceilings, not measured: reject oversized plans before retaining hunks.
+export const MAX_PATCH_CHARS = 2 * 1024 * 1024;
+export const MAX_PATCH_FILES = 100;
+export interface PatchChunk {
+  oldLines: readonly string[];
+  newLines: readonly string[];
+  anchor?: string;
+  endOfFile: boolean;
+}
+export type PatchOperation =
+  | { kind: "add"; path: string; content: string }
+  | { kind: "delete"; path: string }
+  | { kind: "update"; path: string; movePath?: string; chunks: readonly PatchChunk[] };
+export class PatchError extends Error {
+  readonly code: "invalid_input" | "not_found" | "ambiguous_edit";
+  constructor(code: PatchError["code"], message: string) { super(message); this.code = code; }
+}
+const invalid = (message: string): never => { throw new PatchError("invalid_input", message); };
+const pathValue = (text: string): string => {
+  if (!text.trim() || text.includes("\0")) return invalid("patch paths must be nonempty and contain no NUL");
+  return text;
+};
+const fileHeader = (line: string) => /^\*\*\* (?:Add|Delete|Update) File: /.test(line);
+
+/** Parse all operations before the store resolves any target or changes a byte. */
+export function parsePatch(text: string): PatchOperation[] {
+  if (text.length > MAX_PATCH_CHARS) return invalid("patch exceeds the character budget");
+  const lines = text.replaceAll("\r\n", "\n").trim().split("\n");
+  if (lines[0] !== "*** Begin Patch" || lines.at(-1) !== "*** End Patch")
+    return invalid("patch must begin with *** Begin Patch and end with *** End Patch");
+  const operations: PatchOperation[] = [];
+  let index = 1;
+  while (index < lines.length - 1) {
+    if (operations.length >= MAX_PATCH_FILES) return invalid("patch exceeds the file budget");
+    const header = lines[index++]!;
+    if (header.startsWith("*** Add File: ")) {
+      const path = pathValue(header.slice("*** Add File: ".length));
+      const added: string[] = [];
+      while (index < lines.length - 1 && !fileHeader(lines[index]!)) {
+        const line = lines[index++]!;
+        if (!line.startsWith("+")) return invalid(`added lines must start with +: ${path}`);
+        added.push(line.slice(1));
+      }
+      operations.push({ kind: "add", path, content: added.length ? added.join("\n") + "\n" : "" });
+      continue;
+    }
+    if (header.startsWith("*** Delete File: ")) {
+      operations.push({ kind: "delete", path: pathValue(header.slice("*** Delete File: ".length)) });
+      continue;
+    }
+    if (!header.startsWith("*** Update File: ")) return invalid(`unexpected patch line ${index}: ${header}`);
+    const path = pathValue(header.slice("*** Update File: ".length));
+    const moveLine = lines[index];
+    const movePath = moveLine?.startsWith("*** Move to: ") ? pathValue(moveLine.slice("*** Move to: ".length)) : undefined;
+    if (movePath !== undefined) index++;
+    const chunks: PatchChunk[] = [];
+    while (index < lines.length - 1 && !fileHeader(lines[index]!)) {
+      const marker = lines[index++]!;
+      if (marker !== "@@" && !marker.startsWith("@@ ")) return invalid(`update hunks must start with @@: ${path}`);
+      const oldLines: string[] = [], newLines: string[] = [];
+      let endOfFile = false, changed = false;
+      while (index < lines.length - 1 && !fileHeader(lines[index]!) && !lines[index]!.startsWith("@@")) {
+        const line = lines[index++]!;
+        if (line === "*** End of File") { endOfFile = true; break; }
+        const prefix = line[0];
+        if (prefix !== " " && prefix !== "+" && prefix !== "-") return invalid(`invalid update line: ${path}`);
+        if (prefix !== "+") oldLines.push(line.slice(1));
+        if (prefix !== "-") newLines.push(line.slice(1));
+        if (prefix !== " ") changed = true;
+      }
+      if (!changed) return invalid(`update hunk makes no change: ${path}`);
+      chunks.push({ oldLines, newLines, endOfFile, ...(marker === "@@" ? {} : { anchor: marker.slice(3) }) });
+      if (endOfFile && index < lines.length - 1 && !fileHeader(lines[index]!)) return invalid(`End of File must finish the update: ${path}`);
+    }
+    if (!chunks.length && movePath === undefined) return invalid(`update has no hunks: ${path}`);
+    operations.push({ kind: "update", path, chunks, ...(movePath === undefined ? {} : { movePath }) });
+  }
+  if (!operations.length) return invalid("patch is empty");
+  return operations;
+}
+
+/** Keep BOM, line endings and final-newline status; ambiguous contexts require a reread. */
+export function applyPatchChunks(before: string, chunks: readonly PatchChunk[]): string {
+  const bom = before.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const body = before.slice(bom.length);
+  const ending = body.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = body.replaceAll("\r\n", "\n");
+  if (normalized.includes("\r")) return invalid("patch updates do not support bare CR line endings");
+  if (ending === "\r\n" && body.replaceAll("\r\n", "").includes("\n"))
+    return invalid("patch updates require a consistent line ending; mixed LF/CRLF bytes were preserved");
+  const finalNewline = normalized.endsWith("\n");
+  const lines = normalized ? normalized.split("\n") : [];
+  if (finalNewline) lines.pop();
+  let cursor = 0;
+  for (const chunk of chunks) {
+    let start = cursor;
+    if (chunk.anchor !== undefined) {
+      const anchors = lines.flatMap((line, at) => at >= cursor && line === chunk.anchor ? [at] : []);
+      if (anchors.length !== 1) throw new PatchError(anchors.length ? "ambiguous_edit" : "not_found", "patch anchor must match exactly once after the preceding hunk");
+      start = anchors[0]! + 1;
+    }
+    const matches: number[] = [];
+    for (let at = start; at <= lines.length - chunk.oldLines.length; at++) {
+      if (chunk.endOfFile && at + chunk.oldLines.length !== lines.length) continue;
+      if (chunk.oldLines.every((line, offset) => lines[at + offset] === line)) matches.push(at);
+    }
+    if (!chunk.oldLines.length && !chunk.endOfFile) {
+      if (chunk.anchor !== undefined || lines.length === 0) matches.splice(0, matches.length, start);
+      else throw new PatchError("ambiguous_edit", "insertion needs an anchor, End of File, or an empty source");
+    }
+    if (matches.length !== 1) throw new PatchError(matches.length ? "ambiguous_edit" : "not_found", "patch context must match exactly once; read current content and add context");
+    const at = matches[0]!;
+    lines.splice(at, chunk.oldLines.length, ...chunk.newLines);
+    cursor = at + chunk.newLines.length;
+  }
+  return bom + lines.join(ending) + (finalNewline && lines.length ? ending : "");
+}
+
+export function patchPaths(operations: readonly PatchOperation[]): string[] {
+  return operations.flatMap(operation => {
+    switch (operation.kind) {
+      case "add": case "delete": return [operation.path];
+      case "update": return operation.movePath === undefined ? [operation.path] : [operation.path, operation.movePath];
+      default: return assertNever(operation, "patchPaths");
+    }
+  });
+}

package/src/core/permissions.ts

@@ -3,8 +3,8 @@
  * call is allow / ask / deny.
  *
  * Approval is the last look at what is about to run, not a boundary.
- * Path tools are already confined to the workspace root; bash is not,
- * which is why bash defaults to ask and everything else to allow.
+ * Path tools are already confined to the workspace root; host commands
+ * are not, which is why shell entry points default to ask.
  *
  * This module must stay free of I/O, clocks, and randomness. The CLI
  * compiles flags and session memory into a rule list; this file only
@@ -19,6 +19,8 @@ export interface PermissionRequest {
   readonly tool: string;
   /** Exact command string for bash; omitted for tools that have none. */
   readonly command?: string;
+  /** Normalized workspace-relative or external absolute file resources. */
+  readonly paths?: readonly string[];
 }
 
 export interface PermissionRule {
@@ -27,6 +29,11 @@ export interface PermissionRule {
   readonly tool?: string;
   /** Absent matches every command. When set, matches only this exact string. */
   readonly command?: string;
+  /** Literal argv prefix, matched only for a single command without expansion. */
+  readonly commandPrefix?: readonly string[];
+  readonly path?: string;
+  /** Portable path glob: *, ?, and **; no brace or character-class expansion. */
+  readonly pathGlob?: string;
 }
 
 /**
@@ -39,6 +46,8 @@ export type ToolSource = "builtin" | "extension";
 /** Task capabilities are frozen once at session creation (O.7); not permissions. */
 export const TOOL_PROFILES = {
   coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note"],
+  // An explicit preset preserves the measured legacy ten-tool coding contract.
+  foundation: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "question", "apply_patch", "diff", "webfetch", "websearch", "format", "lsp"],
   readonly: ["read", "grep", "find", "history", "note"],
   research: ["read", "grep", "find", "history", "note", "branch", "resolve"],
   data: ["read", "grep", "find", "history", "note", "query"],
@@ -75,11 +84,16 @@ export interface ToolSelection {
 export const ALLOW_TOOLS_FLAG = "--allow-tools";
 
 /**
- * Product default. bash asks because it is not confined to the workspace
- * root; every other built-in is allow because the path tools are.
+ * Product default. Shell entry points ask because their effects are not
+ * confined to the workspace root; path tools keep their own confinement.
  */
 export function defaultRules(): readonly PermissionRule[] {
   return [
+    // Templates are ordinary source; actual environment values deserve the
+    // same last look as commands. Indirect readers also check read resources.
+    { action: "allow", tool: "read", pathGlob: "**/.env.example" },
+    { action: "ask", tool: "read", pathGlob: "**/.env" },
+    { action: "ask", tool: "read", pathGlob: "**/.env.*" },
     { action: "ask", tool: "bash" },
     // Same reach as bash. write_stdin needs no rule of its own: it can only
     // address a session exec_command already started, under this approval.
@@ -91,9 +105,15 @@ export function defaultRules(): readonly PermissionRule[] {
 }
 
 /**
- * `--allow-tools` compiled to rules, in front of the defaults so they win.
+ * CLI opt-ins compiled to one process-scoped rule list. YOLO permits every
+ * tool; capability admission and path confinement still apply (D13).
+ * Neither this flag nor remembered approvals become a persisted policy.
  */
-export function rulesWithAllowTools(allowTools: readonly string[]): PermissionRule[] {
+export function rulesWithAllowTools(
+  allowTools: readonly string[],
+  options: { readonly yolo?: boolean } = {},
+): PermissionRule[] {
+  if (options.yolo === true) return [{ action: "allow" }];
   return [
     ...allowTools.map((tool) => ({ action: "allow" as const, tool })),
     ...defaultRules(),
@@ -103,24 +123,146 @@ export function rulesWithAllowTools(allowTools: readonly string[]): PermissionRu
 export function ruleMatches(rule: PermissionRule, request: PermissionRequest): boolean {
   if (rule.tool !== undefined && rule.tool !== request.tool) return false;
   if (rule.command !== undefined && rule.command !== request.command) return false;
+  if (rule.commandPrefix !== undefined) {
+    const words = request.command === undefined ? null : literalCommandWords(request.command);
+    if (!words || rule.commandPrefix.length === 0 || rule.commandPrefix.some((word, i) => words[i] !== word)) return false;
+  }
+  if (rule.path !== undefined && !request.paths?.some(path => normalizePermissionPath(path) === normalizePermissionPath(rule.path!))) return false;
+  if (rule.pathGlob !== undefined && !request.paths?.some(path => permissionPathMatches(rule.pathGlob!, path))) return false;
   return true;
 }
 
 /**
  * First matching rule wins. An empty list allows: the tool tests pass no
  * rules because they are testing the tool, not the gate. The CLI always
- * supplies defaultRules().
+ * supplies the current process's compiled policy.
  */
 export function decide(
   rules: readonly PermissionRule[],
   request: PermissionRequest,
 ): PermissionAction {
+  // A multi-file call needs every resource admitted. A broad allow for its
+  // first path must not conceal a denial on a later file (D13 / R13).
+  if (request.paths && request.paths.length > 1) {
+    const actions = request.paths.map(path => decide(rules, { ...request, paths: [path] }));
+    return actions.includes("deny") ? "deny" : actions.includes("ask") ? "ask" : "allow";
+  }
   for (const rule of rules) {
     if (ruleMatches(rule, request)) return rule.action;
   }
   return "allow";
 }
 
+/** Configured denial is a ceiling; in-memory approval can only resolve asks. */
+export function decideWithSessionRules(
+  configured: readonly PermissionRule[], remembered: readonly PermissionRule[], request: PermissionRequest,
+): PermissionAction {
+  if (decide(configured, request) === "deny") return "deny";
+  return decide([...remembered, ...configured], request);
+}
+
+/** Lexical normalization is pure; the store adds canonical symlink resources. */
+export function normalizePermissionPath(path: string): string {
+  const absolute = path.startsWith("/");
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop();
+    else if (part === ".." && absolute) continue;
+    else parts.push(part);
+  }
+  return (absolute ? "/" : "") + parts.join("/") || ".";
+}
+
+/** Dynamic programming avoids exponential regexp backtracking on model input. */
+export function permissionPathMatches(pattern: string, path: string): boolean {
+  const glob = normalizePermissionPath(pattern), value = normalizePermissionPath(path);
+  let row = Array<boolean>(value.length + 1).fill(false); row[0] = true;
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i]!;
+    const next = Array<boolean>(value.length + 1).fill(false);
+    if (char === "*") {
+      const deep = glob[i + 1] === "*";
+      if (deep) i++;
+      // **/ also matches zero directories, as in **/.env at the root.
+      const directories = deep && glob[i + 1] === "/";
+      if (directories) i++;
+      next[0] = row[0]!;
+      for (let j = 1; j <= value.length; j++) {
+        next[j] = row[j]! || ((deep || value[j - 1] !== "/") && next[j - 1]!);
+        if (directories && value[j - 1] !== "/") next[j] = row[j]!;
+      }
+      // A globstar followed by slash may consume complete directories only.
+      if (directories) {
+        let reachable = row[0]!;
+        for (let j = 1; j <= value.length; j++) {
+          reachable = reachable || row[j]!;
+          next[j] = row[j]! || (value[j - 1] === "/" && reachable);
+        }
+      }
+    } else {
+      for (let j = 1; j <= value.length; j++) next[j] = row[j - 1]! &&
+        (char === "?" ? value[j - 1] !== "/" : char === value[j - 1]);
+    }
+    row = next;
+  }
+  return row[value.length]!;
+}
+
+/**
+ * This is a prefix matcher, never a command-danger classifier. Unknown shell
+ * syntax fails to match and therefore retains the full-command ask (D13).
+ */
+export function literalCommandWords(command: string): string[] | null {
+  const words: string[] = [];
+  let word = "", started = false, quote: "'" | '"' | null = null;
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i]!;
+    if (char === "\n" || char === "\r" || char === "\0") return null;
+    if (quote === "'") {
+      if (char === "'") quote = null; else word += char;
+      continue;
+    }
+    if (char === "\\") {
+      const escaped = command[++i];
+      if (escaped === undefined || escaped === "\n" || escaped === "\r") return null;
+      // Bash double quotes retain backslash before ordinary characters.
+      word += quote === '"' && !['$', '`', '"', "\\"].includes(escaped) ? `\\${escaped}` : escaped;
+      started = true; continue;
+    }
+    if (quote === '"') {
+      if (char === '"') quote = null;
+      else if (char === "$" || char === "`") return null;
+      else word += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; started = true; continue; }
+    if (char === " " || char === "\t") { if (started) words.push(word); word = ""; started = false; continue; }
+    if (";|&<>($`*?[]{}~#".includes(char)) return null;
+    word += char; started = true;
+  }
+  if (quote !== null) return null;
+  if (started) words.push(word);
+  return words.length ? words : null;
+}
+
+/** Unknown config keys are errors: a typo must not silently weaken a policy. */
+export function parsePermissionRule(value: unknown): PermissionRule {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("permission rule must be an object");
+  const rule = value as Record<string, unknown>;
+  if (Object.keys(rule).some(key => !["action", "tool", "command", "commandPrefix", "path", "pathGlob"].includes(key))) throw Error("unknown permission rule field");
+  if (!["allow", "ask", "deny"].includes(String(rule["action"]))) throw Error("permission rule action must be allow, ask or deny");
+  for (const key of ["tool", "command", "path", "pathGlob"]) {
+    if (rule[key] !== undefined && (typeof rule[key] !== "string" || !String(rule[key]).trim() || String(rule[key]).includes("\0"))) throw Error(`permission ${key} must be a nonempty string`);
+  }
+  if (rule["path"] !== undefined && rule["pathGlob"] !== undefined) throw Error("permission path and pathGlob are mutually exclusive");
+  if (typeof rule["pathGlob"] === "string" && /[\[\]{}]/.test(rule["pathGlob"])) throw Error("permission pathGlob supports only *, ? and **");
+  const prefix = rule["commandPrefix"];
+  if (prefix !== undefined && (!Array.isArray(prefix) || prefix.length === 0 || prefix.some(word => typeof word !== "string" || !word || /[\r\n\0]/.test(word)))) throw Error("permission commandPrefix must contain literal argv tokens");
+  if (prefix !== undefined && rule["command"] !== undefined) throw Error("permission command and commandPrefix are mutually exclusive");
+  return structuredClone(value) as PermissionRule;
+}
+
 /**
  * Comma-separated flag values. Empty tokens are dropped so `--tools a,,b`
  * does not invent a blank name.
@@ -180,12 +322,15 @@ export function selectTools<T extends { name: string; source?: ToolSource }>(
 }
 
 export function permissionRequest(name: string, input: unknown): PermissionRequest {
-  if (!["bash", "exec_command", "environment"].includes(name) || typeof input !== "object" || input === null) {
+  if (typeof input !== "object" || input === null) {
     return { tool: name };
   }
-  const command = (input as { readonly [k: string]: unknown })[name === "exec_command" ? "cmd" : "command"];
-  if (typeof command !== "string") return { tool: name };
-  return { tool: name, command };
+  const fields = input as { readonly [k: string]: unknown };
+  const command = ["bash", "exec_command", "environment"].includes(name) ? fields[name === "exec_command" ? "cmd" : "command"] : undefined;
+  const paths = typeof fields["path"] === "string" ? [fields["path"]]
+    : Array.isArray(fields["paths"]) && fields["paths"].every(path => typeof path === "string") ? fields["paths"] as string[] : undefined;
+  return { tool: name, ...(typeof command === "string" ? { command } : {}),
+    ...(paths ? { paths: paths.map(normalizePermissionPath) } : {}) };
 }
 
 /**