@visual-z/xeno 0.5.0 → 0.7.0

package/src/runtime/patch-tool.ts

@@ -0,0 +1,38 @@
+/** One durable mutation owner for multi-file Patch, independent of provider syntax. */
+import { changedPaths } from "../core/checkpoints.ts";
+import { NOT_STARTED, READ_ATTEMPTED, UNKNOWN_EFFECT, failureDiagnostic, failureFromError } from "../core/tool-failure.ts";
+import { preparePatch, applyPreparedPatch } from "../store/patch.ts";
+import { presentObservation, type ToolDefinition } from "./tools.ts";
+
+export function createPatchTool(): ToolDefinition {
+  return {
+    name: "apply_patch", access: "write", execution: "exclusive", branch: "write",
+    description: "Apply a Codex-style multi-file patch containing Add File, Update File, optional Move to, and Delete File. Existing sources require a prior session read or explicit expected_sha256. All targets and exact unique hunks are preflighted before changes; add/move destinations must be absent. Uses durable file checkpoints and compensates partial application without overwriting external changes. Preserves original BOM, line endings and modes. Return contains resulting file SHA-256 versions.",
+    input_schema: { type: "object", required: ["patchText"], properties: {
+      patchText: { type: "string", description: "Full *** Begin Patch ... *** End Patch text; update hunks start with @@ and lines use space/+/- prefixes." },
+      expected_sha256: { type: "object", additionalProperties: { type: "string", pattern: "^[a-f0-9]{64}$" }, description: "Optional source path to exact SHA-256 premise; otherwise use observed session versions." },
+    } },
+    run: async (ctx, input) => {
+      if (!ctx.workspace) return { ok: false, content: "Patch requires the session's durable workspace checkpoint owner.", diagnostic: failureDiagnostic("environment_missing", "Patch requires the session's durable workspace checkpoint owner.", NOT_STARTED) };
+      let admitted = false;
+      try {
+        const expected = input["expected_sha256"];
+        if (expected !== undefined && (expected === null || typeof expected !== "object" || Array.isArray(expected))) throw new Error("expected_sha256 must be an object of source digests");
+        const prepared = await preparePatch(ctx.root, ctx.workspace.blobs, String(input["patchText"]), {
+          ...(ctx.observedFileVersion === undefined ? {} : { observedFileVersion: ctx.observedFileVersion }),
+          ...(expected === undefined ? {} : { expectedSha256: expected as Record<string, string> }),
+          ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+        });
+        admitted = true;
+        await ctx.workspace.patch(prepared.changes, () => applyPreparedPatch(ctx.root, ctx.workspace!.blobs, prepared, ctx.signal), ctx.signal);
+        const paths = changedPaths(prepared.changes);
+        const summary = paths.map(path => `${path}: ${prepared.changes[path]!.after?.sha256 ?? "deleted"}`).join("\n");
+        const data = paths.map(path => ({ path, before: prepared.changes[path]!.before?.sha256 ?? null, after: prepared.changes[path]!.after?.sha256 ?? null }));
+        return { ...await presentObservation(ctx, `Applied patch to ${paths.length} file path(s).\n${summary}\n\n${prepared.diffs.map(diff => diff.diff).join("\n")}`), ok: true, data: { files: data } };
+      } catch (error) {
+        const diagnostic = failureFromError(error, admitted ? UNKNOWN_EFFECT : READ_ATTEMPTED);
+        return { ok: false, content: diagnostic.message, diagnostic };
+      }
+    },
+  };
+}

package/src/runtime/permission-resources.ts

@@ -0,0 +1,11 @@
+/** R13: an indirect content reader must retain the same read-resource policy. */
+import { decideWithSessionRules, type PermissionAction, type PermissionRule } from "../core/permissions.ts";
+import { permissionPaths } from "../store/permission-paths.ts";
+
+export async function permissionResourceAction(root: string, path: string, configured: readonly PermissionRule[],
+  remembered: readonly PermissionRule[] = [], tool = "read"): Promise<PermissionAction> {
+  const paths = await permissionPaths(root, [path]);
+  const read = decideWithSessionRules(configured, remembered, { tool: "read", paths });
+  const specific = decideWithSessionRules(configured, remembered, { tool, paths });
+  return read === "deny" || specific === "deny" ? "deny" : read === "ask" || specific === "ask" ? "ask" : "allow";
+}

package/src/runtime/pi-provider.ts

@@ -23,6 +23,7 @@ import { FailedResponseError, type OnDelta, type Provider, type ProviderConfig,
 import { DEFAULT_RETRY, withRetry, type RetryPolicy } from "./retry.ts";
 import { HttpError, StreamError } from "./openai.ts";
 import type { UsageSample } from "./usage.ts";
+import { disablePayloadTools, type ProviderSendOptions } from "./provider-tool-policy.ts";
 
 const APIS: Record<Api, ProviderStreams> = {
   "anthropic-messages": anthropicMessagesApi(), "openai-completions": openAICompletionsApi(),
@@ -305,14 +306,14 @@ export class PiProvider implements Provider {
     this.config = config; this.apiKey = apiKey; this.options = options;
   }
 
-  send(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta): Promise<Turn> {
+  send(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta, policy?: ProviderSendOptions): Promise<Turn> {
     // Bedrock's Pi adapter leaves retry ownership with the AWS SDK; never multiply that loop.
     const retry = this.options.retry ?? (this.config.spec.api === "bedrock-converse-stream" ? { ...DEFAULT_RETRY, maxRetries: 0 } : DEFAULT_RETRY);
-    return withRetry(() => this.attempt(frozen, messages, node, signal, onDelta), retry, undefined,
+    return withRetry(() => this.attempt(frozen, messages, node, signal, onDelta, policy), retry, undefined,
       (attempt, delayMs, error) => { onDelta?.({ kind: "discard" }); onDelta?.({ kind: "retry", attempt, delayMs }); this.options.onRetry?.(attempt, delayMs, error); }, signal);
   }
 
-  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta): Promise<Turn> {
+  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta, policy?: ProviderSendOptions): Promise<Turn> {
     signal?.throwIfAborted();
     const started = Date.now();
     const request = providerRequest(this.config.spec, this.apiKey, this.options.effects, this.options.fetch, this.options.oauth);
@@ -342,7 +343,7 @@ export class PiProvider implements Provider {
         const next = mergePayload(payload, request.body);
         // Stateless Responses is required by D8: never replace the recomputable projection with server state.
         if (model.api.includes("responses")) { next["store"] = false; delete next["previous_response_id"]; }
-        return next;
+        return policy?.toolUse === "disabled" ? disablePayloadTools(model.api, next) : next;
       } };
     let completed: AssistantMessage | undefined;
     // Pi emits fragments; xeno's progress contract replaces the displayed argument buffer.

package/src/runtime/provider-tool-policy.ts

@@ -0,0 +1,33 @@
+/** D6: native request controls may change; frozen system and tool declarations may not. */
+import { assertNever } from "../core/exhaustive.ts";
+import type { Api } from "./model.ts";
+
+export interface ProviderSendOptions { toolUse: "disabled" }
+
+export function supportsToolDisabling(api: Api): boolean {
+  // Bedrock's SDK implements none by deleting toolConfig. It cannot preserve D6.
+  switch (api) {
+    case "anthropic-messages": case "openai-completions": case "openai-responses": case "azure-openai-responses": case "openai-codex-responses":
+    case "google-generative-ai": case "google-vertex": case "mistral-conversations": case "pi-messages": return true;
+    case "bedrock-converse-stream": return false;
+    default: return assertNever(api, "tool disabling capability");
+  }
+}
+const object = (value: unknown): Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+
+/** Called after provider body overrides, at the last native payload boundary. */
+export function disablePayloadTools(api: Api, payload: Record<string, unknown>): Record<string, unknown> {
+  switch (api) {
+    case "anthropic-messages": return { ...payload, tool_choice: { type: "none" } };
+    case "openai-completions": case "openai-responses": case "azure-openai-responses": case "openai-codex-responses":
+      return { ...payload, tool_choice: "none" };
+    case "google-generative-ai": case "google-vertex": {
+      const config = object(payload["config"]), toolConfig = object(config["toolConfig"]);
+      return { ...payload, config: { ...config, toolConfig: { ...toolConfig, functionCallingConfig: { mode: "NONE" } } } };
+    }
+    case "mistral-conversations": return { ...payload, toolChoice: "none" };
+    case "pi-messages": return { ...payload, options: { ...object(payload["options"]), toolChoice: "none" } };
+    case "bedrock-converse-stream": throw new Error("Bedrock cannot disable tools while preserving frozen definitions");
+    default: return assertNever(api, "tool disabling protocol");
+  }
+}

package/src/runtime/provider.ts

@@ -39,11 +39,14 @@ import type { UsageSample } from "./usage.ts";
 import { type Effort, type ModelSpec, CLAUDE_OPUS_5 } from "./model.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
 import { anthropicOAuthHeaders } from "./oauth.ts";
+import type { ProviderSendOptions } from "./provider-tool-policy.ts";
 
 export interface ToolSchema {
   name: string;
   description: string;
   input_schema: {
+    /** Standard JSON Schema keywords from MCP must survive the frozen declaration. */
+    [keyword: string]: unknown;
     type: "object";
     properties: Record<string, unknown>;
     required: string[];
@@ -104,6 +107,7 @@ export interface Provider {
     node: number,
     signal?: AbortSignal,
     onDelta?: OnDelta,
+    options?: ProviderSendOptions,
   ): Promise<Turn>;
 }
 
@@ -233,9 +237,10 @@ export class AnthropicProvider implements Provider {
     node: number,
     signal?: AbortSignal,
     onDelta?: OnDelta,
+    options?: ProviderSendOptions,
   ): Promise<Turn> {
     return withRetry(
-      () => this.attempt(frozen, messages, node, signal, onDelta),
+      () => this.attempt(frozen, messages, node, signal, onDelta, options),
       this.retry,
       undefined,
       (attempt, delayMs, error) => {
@@ -255,6 +260,7 @@ export class AnthropicProvider implements Provider {
     node: number,
     signal?: AbortSignal,
     onDelta?: OnDelta,
+    options?: ProviderSendOptions,
   ): Promise<Turn> {
     const started = Date.now();
 
@@ -275,6 +281,7 @@ export class AnthropicProvider implements Provider {
         // Auto-caching walks the breakpoint forward over the growing tail.
         cache_control: { type: "ephemeral" },
         tools: frozen.tools as Anthropic.Tool[],
+        ...(options?.toolUse === "disabled" ? { tool_choice: { type: "none" as const } } : {}),
         // Only a reasoning model understands these. An older Claude, or an
         // Anthropic-compatible endpoint serving some other model, answers
         // them with a 400 or silently ignores them.

package/src/runtime/question-tool.ts

@@ -0,0 +1,62 @@
+/** R13: UI and protocol clients share one active-turn question adapter. */
+import { parseQuestions, questionRequest, validateQuestionReply, MAX_QUESTIONS, MAX_QUESTION_CHOICES,
+  type QuestionRequest, type QuestionReply } from "../core/question.ts";
+import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
+import { executionOutcome } from "../core/outcome.ts";
+import type { JsonValue, ToolDiagnostic } from "../core/tool-contract.ts";
+import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
+
+export type QuestionAdapter = (request: QuestionRequest, signal: AbortSignal) => Promise<unknown | undefined>;
+export interface QuestionSlot {
+  /** The Session/app owner changes this at user-turn boundaries, never model input. */
+  activeTurn?: string;
+  current?: QuestionAdapter;
+}
+function failure(code: ToolDiagnostic["code"], message: string): ToolResult {
+  return { ok: false, content: message, diagnostic: failureDiagnostic(code, message, NOT_STARTED),
+    outcome: executionOutcome(code === "cancelled" ? "cancelled" : "tool_failed") };
+}
+function plainReply(reply: QuestionReply): JsonValue {
+  return { request_id: reply.request_id, turn_id: reply.turn_id,
+    answers: reply.answers.map(answer => ({ id: answer.id, choices: [...answer.choices], ...(answer.text !== undefined ? { text: answer.text } : {}) })) };
+}
+async function ask(slot: QuestionSlot, ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
+  let questions;
+  try { questions = parseQuestions(input); }
+  catch (error) { return failure("invalid_input", error instanceof Error ? error.message : "Invalid question"); }
+  const turn = slot.activeTurn, call = ctx.callId, adapter = slot.current;
+  if (!turn || !call) return failure("permission_denied", "question requires an active turn and tool invocation");
+  if (!adapter) return failure("environment_missing", "question requires an interactive terminal or a connected client that can answer questions");
+  const signal = ctx.signal ?? new AbortController().signal;
+  if (signal.aborted) return failure("cancelled", "Question cancelled");
+  const request = questionRequest(turn, call, questions);
+  let stop = () => {};
+  const cancelled = new Promise<undefined>(resolve => { stop = () => resolve(undefined); signal.addEventListener("abort", stop, { once: true }); });
+  try {
+    // Late adapter rejection is observed by race; an adapter ignoring its
+    // signal cannot keep the original tool exchange unpaired (D5).
+    const answer = await Promise.race([Promise.resolve().then(() => adapter(structuredClone(request), signal)), cancelled]);
+    if (signal.aborted || answer === undefined || slot.activeTurn !== turn) return failure("cancelled", "Question cancelled or its turn is no longer active");
+    let reply;
+    try { reply = validateQuestionReply(request, answer); }
+    catch { return failure("invalid_input", "Question client returned an invalid answer or stale invocation identity"); }
+    const data = plainReply(reply);
+    return { ok: true, content: JSON.stringify(data), data, outcome: executionOutcome("tool_completed") };
+  } catch { return failure("execution_failed", "Question client failed before returning a validated answer"); }
+  finally { signal.removeEventListener("abort", stop); }
+}
+
+export function createQuestionTool(slot: QuestionSlot): ToolDefinition {
+  return { name: "question", access: "state", execution: "exclusive", branch: "none",
+    description: "Ask 1..3 concise questions for missing requirements or material decisions; await the user's answer in this turn. Use stable question and option ids. Set multiple=true for multiple choices; custom text is enabled by default. An absent/cancelled answer is not approval. This tool does not approve tool execution or change workflow mode.",
+    input_schema: { type: "object", required: ["questions"], properties: {
+      questions: { type: "array", minItems: 1, maxItems: MAX_QUESTIONS, items: { type: "object", additionalProperties: false,
+        required: ["id", "header", "question"], properties: {
+          id: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,63}$" }, header: { type: "string", minLength: 1, maxLength: 40 },
+          question: { type: "string", minLength: 1, maxLength: 2000 }, multiple: { type: "boolean" }, custom: { type: "boolean" },
+          options: { type: "array", maxItems: MAX_QUESTION_CHOICES, items: { type: "object", additionalProperties: false,
+            required: ["id", "label"], properties: { id: { type: "string", pattern: "^[a-z][a-z0-9_-]{0,63}$" },
+              label: { type: "string", minLength: 1, maxLength: 120 }, description: { type: "string", minLength: 1, maxLength: 600 } } } },
+        } } },
+    } }, run: (ctx, input) => ask(slot, ctx, input) };
+}

package/src/runtime/review-tool.ts

@@ -0,0 +1,48 @@
+/** Shared diff preparation for model tools and user review commands; no provider calls. */
+import type { FileChanges } from "../core/checkpoints.ts";
+import type { ReviewScope } from "../core/review.ts";
+import { failureFromError, READ_ATTEMPTED } from "../core/tool-failure.ts";
+import { readReview, readCheckpointReview } from "../store/review.ts";
+import { presentObservation, type ToolContext, type ToolDefinition } from "./tools.ts";
+
+export interface LastTurnReview { blobs: string; changes: FileChanges; limitations: string[] }
+export interface DiffToolOptions {
+  lastTurn?: (context: ToolContext) => Promise<LastTurnReview>;
+  /** Current resource policy must be checked before diff bytes enter an artifact or model output. */
+  canRead?: (context: ToolContext, path: string) => Promise<boolean>;
+}
+export function parseReviewScope(input: Record<string, unknown>): ReviewScope {
+  const kind = input["scope"] ?? "working";
+  if (kind === "working" || kind === "last-turn") {
+    if (input["base"] !== undefined || input["commit"] !== undefined) throw new Error(`${kind} scope accepts no revision`);
+    return { kind };
+  }
+  if (kind === "branch" && typeof input["base"] === "string" && input["base"].trim() && input["commit"] === undefined) return { kind, base: input["base"] };
+  if (kind === "commit" && typeof input["commit"] === "string" && input["commit"].trim() && input["base"] === undefined) return { kind, commit: input["commit"] };
+  throw new Error("review scope must be working, branch with base, commit with commit, or last-turn");
+}
+
+export function createDiffTool(options: DiffToolOptions = {}): ToolDefinition {
+  return {
+    name: "diff", access: "read", execution: "parallel", branch: "read",
+    description: "Read a unified diff for current staged/unstaged/untracked changes, a branch merge base, a selected commit, or durable checkpoints in the last user turn. Fixed Git argv disables external diff/textconv drivers and confines paths to the workspace. Reports uncaptured or unavailable data explicitly. This observes changes; it does not change files or run a model review.",
+    input_schema: { type: "object", required: [], properties: { scope: { type: "string", enum: ["working", "branch", "commit", "last-turn"] }, base: { type: "string" }, commit: { type: "string" } } },
+    run: async (ctx, input) => {
+      try {
+        const scope = parseReviewScope(input);
+        const canRead = options.canRead === undefined ? undefined : (path: string) => options.canRead!(ctx, path);
+        const snapshot = scope.kind === "last-turn" ? await (async () => {
+          if (!options.lastTurn) throw new Error("last-turn diff requires original session checkpoint history");
+          const original = await options.lastTurn(ctx);
+          return readCheckpointReview(original.blobs, original.changes, original.limitations, canRead);
+        })() : await readReview(ctx.root, scope, ctx.signal, canRead);
+        const notices = snapshot.limitations.length ? "\nLimitations:\n" + snapshot.limitations.map(line => "- " + line).join("\n") : "";
+        return { ...await presentObservation(ctx, `${snapshot.label}\n${snapshot.diff || "(no captured changes)"}${notices}`), ok: true,
+          data: { scope: scope.kind, paths: snapshot.paths, limitations: snapshot.limitations, ...(snapshot.base === undefined ? {} : { base: snapshot.base }) } };
+      } catch (error) {
+        const diagnostic = failureFromError(error, READ_ATTEMPTED);
+        return { ok: false, content: diagnostic.message, diagnostic };
+      }
+    },
+  };
+}

package/src/runtime/session-control.ts

@@ -11,16 +11,25 @@ import type { LogEvent } from "../core/events.ts";
 import { readNodeHistory } from "../store/restore.ts";
 import type { Session, LoopEvent } 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";
 
 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 };
 export type ControlSnapshot = {
   version: "xeno-control/0.1"; threadId: string; streamId: string; sequence: number; node: number;
   activeTurnId: string | null; goal: GoalView | null; context: ContextLens;
-  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[];
+  workflowMode: "build" | "plan";
+  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[]; questions: QuestionRequest[];
 };
 
 export class SessionControl {
+  /** App-owned configuration switches resources at an idle checkpoint; observers cannot mutate it. */
+  configureWorkflow?: (mode: "build" | "plan") => Promise<void>;
+  readonly questionSlot: QuestionSlot;
+  private questionClients = 0;
+  private readonly questionAdapter: NonNullable<QuestionSlot["current"]> = (request, signal) => this.askQuestion(request, signal);
+  private readonly questions = new Map<string, { request: QuestionRequest; resolve(reply: QuestionReply | undefined): void }>();
   readonly session: Session;
   readonly threadId: string;
   readonly streamId = randomUUID();
@@ -35,6 +44,7 @@ export class SessionControl {
 
   constructor(session: Session) {
     this.session = session;
+    this.questionSlot = session.config.tools.questionSlot ?? {};
     // Same identity rule as provider affinity; no new durable identity store (D8).
     this.threadId = createHash("sha256").update(resolve(session.config.logDir)).digest("hex");
     session.subscribeRecords(item => this.emit("item/completed", { item }));
@@ -42,6 +52,14 @@ export class SessionControl {
   get activeTurnId(): string | null { return this.active?.id ?? null; }
   get busy(): boolean { return this.changing || this.active !== null || this.session.running; }
 
+  /** One owner excludes turn admission across asynchronous checkpoint/configuration work. */
+  async withIdleChange<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.busy) throw Error("configuration changes require an idle session");
+    this.changing = true;
+    try { const result = await operation(); this.emit("thread/statusChanged"); return result; }
+    finally { this.changing = false; }
+  }
+
   subscribe(listener: (event: ControlNotice) => void): () => void {
     this.listeners.add(listener); return () => { this.listeners.delete(listener); };
   }
@@ -72,8 +90,9 @@ export class SessionControl {
     const projectedGoal = goalView(parts);
     const goal = this.active && projectedGoal?.state.request.event !== this.active.id ? null : projectedGoal;
     return { version: "xeno-control/0.1", threadId: this.threadId, streamId: this.streamId, sequence: this.sequence, node,
-      activeTurnId: this.activeTurnId, goal, waiting: this.waiting,
+      activeTurnId: this.activeTurnId, goal, waiting: this.waiting, workflowMode: s.config.tools.workflowMode ?? "build",
       approvals: structuredClone([...this.approvals.values()].map(item => item.data)),
+      questions: structuredClone([...this.questions.values()].map(item => item.request)),
       context: contextLens({ ...s.contextInput(), anchor: s.state.anchor, policy: s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
         contextWindow: s.provider.config.spec.contextWindow, outputReserve: s.provider.config.maxTokens,
         ...(s.config.counter ? { counter: s.config.counter } : {}), ...(s.config.boundary ? { boundary: s.config.boundary } : {}) }) };
@@ -92,6 +111,7 @@ export class SessionControl {
     if (this.busy) throw Error("a turn is already running");
     const active = { id: this.session.clock.nextId(), abort: new AbortController(), queue: [] as UserInput[] };
     this.active = active;
+    this.questionSlot.activeTurn = active.id;
     const signals = signal ? AbortSignal.any([signal, active.abort.signal]) : active.abort.signal;
     let outcome: ExecutionOutcome | undefined;
     try {
@@ -114,6 +134,8 @@ export class SessionControl {
       throw error;
     } finally {
       for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+      for (const question of [...this.questions.values()]) question.resolve(undefined);
+      delete this.questionSlot.activeTurn;
       this.waiting = null;
       // A thrown provider error also appends an outcome. Clients must be able to discover it.
       try {
@@ -142,11 +164,13 @@ export class SessionControl {
     // Assumed ingress bound, not an execution policy. Keep a client from queuing unbounded work.
     if (turn.queue.length >= 32) throw Error("steering queue is full");
     turn.queue.push(structuredClone(input));
+    this.session.wakeProcessWaits();
     this.emit("turn/steeringQueued", { count: turn.queue.length });
   }
   interrupt(turnId: string): void {
     this.current(turnId).abort.abort();
     for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+    for (const question of [...this.questions.values()]) question.resolve(undefined);
     this.session.cancel();
   }
   setWaiting(kind: ControlSnapshot["waiting"]): void {
@@ -178,6 +202,41 @@ export class SessionControl {
     approval.resolve(choice);
   }
   denyApprovals(): void { for (const approval of [...this.approvals.values()]) approval.resolve("deny"); }
+  attachQuestionClient(): () => void {
+    this.questionClients++;
+    if (!this.questionSlot.current) this.questionSlot.current = this.questionAdapter;
+    let closed = false;
+    return () => {
+      if (closed) return; closed = true;
+      if (--this.questionClients === 0) {
+        if (this.questionSlot.current === this.questionAdapter) delete this.questionSlot.current;
+        for (const question of [...this.questions.values()]) question.resolve(undefined);
+      }
+    };
+  }
+  askQuestion(request: QuestionRequest, signal: AbortSignal, present?: (request: QuestionRequest) => Promise<unknown>): Promise<QuestionReply | undefined> {
+    if (!this.active || request.turn_id !== this.active.id || signal.aborted || !present && this.questionClients === 0) return Promise.resolve(undefined);
+    if (this.questions.has(request.request_id)) return Promise.reject(Error("duplicate question invocation"));
+    return new Promise(resolve => {
+      const finish = (reply: QuestionReply | undefined) => {
+        if (!this.questions.delete(request.request_id)) return;
+        signal.removeEventListener("abort", aborted); this.setWaiting(this.questions.size ? "question" : null);
+        this.emit("question/resolved", { requestId: request.request_id }); resolve(reply);
+      };
+      const aborted = () => finish(undefined);
+      this.questions.set(request.request_id, { request: structuredClone(request), resolve: finish });
+      signal.addEventListener("abort", aborted, { once: true }); this.setWaiting("question");
+      this.emit("question/request", { question: structuredClone(request) });
+      if (present) void present(structuredClone(request)).then(value => {
+        if (value === undefined) finish(undefined); else try { finish(validateQuestionReply(request, value)); } catch { finish(undefined); }
+      }).catch(() => finish(undefined));
+    });
+  }
+  respondQuestion(turnId: string, requestId: string, reply: unknown): void {
+    this.current(turnId); const question = this.questions.get(requestId);
+    if (!question || question.request.turn_id !== turnId) throw Error("stale or unknown question requestId");
+    question.resolve(validateQuestionReply(question.request, reply));
+  }
   async accept(requestId: string, criterion: string): Promise<void> {
     if (this.busy) throw Error("acceptance requires an idle session");
     this.changing = true;

package/src/runtime/session-hub.ts

@@ -0,0 +1,85 @@
+/** A hub owns live sessions, not transcript mirrors. Durable listing stays a store projection. */
+import type { SessionControl } from "./session-control.ts";
+import { basename } from "node:path";
+
+// Assumed live-owner bound includes admitted opens, so concurrent requests cannot exceed it.
+export const MAX_LIVE_SESSIONS = 32;
+
+export interface SessionHubHost {
+  list(): Promise<unknown>;
+  open(kind: "new" | "resume" | "fork", params: Record<string, unknown>): Promise<SessionControl>;
+  dispose(control: SessionControl): Promise<void>;
+}
+export class SessionHub {
+  private readonly controls = new Map<string, SessionControl>();
+  private readonly opening = new Set<Promise<SessionControl>>();
+  private readonly resuming = new Map<string, Promise<SessionControl>>();
+  private readonly closing = new Map<string, Promise<void>>();
+  private reserved = 0;
+  private closed = false;
+  private disposal: Promise<void> | undefined;
+  private readonly host: SessionHubHost;
+  readonly initial: SessionControl;
+  constructor(initial: SessionControl, host: SessionHubHost) {
+    this.initial = initial; this.host = host; this.controls.set(initial.threadId, initial);
+  }
+  get(threadId: string): SessionControl {
+    if (this.closed || this.closing.has(threadId)) throw Error("session hub or thread is closing");
+    const control = this.controls.get(threadId);
+    if (!control) throw Error("unknown or closed threadId; resume the session first");
+    return control;
+  }
+  async list(): Promise<unknown> { if (this.closed) throw Error("session hub is closing"); return this.host.list(); }
+  open(kind: "new" | "resume" | "fork", params: Record<string, unknown>): Promise<SessionControl> {
+    if (this.closed) return Promise.reject(Error("session hub is closing; no new session was admitted"));
+    const captured = structuredClone(params);
+    // Coalesce resume only. Two explicit new/fork requests create two distinct sessions.
+    const key = kind === "resume" ? JSON.stringify(captured) : "";
+    const pending = key ? this.resuming.get(key) : undefined;
+    if (pending) return pending;
+    const requested = captured["session"];
+    const known = kind === "resume" && [...this.controls.values()].some(control => !this.closing.has(control.threadId)
+      && [control.threadId, control.session.config.logDir, basename(control.session.config.logDir)].includes(String(requested)));
+    if (!known && this.controls.size + this.reserved >= MAX_LIVE_SESSIONS) return Promise.reject(Error("live session limit reached; close a session first"));
+    if (!known) this.reserved++;
+    const operation = (async () => {
+      try {
+        const control = await this.host.open(kind, captured), existing = this.controls.get(control.threadId);
+        if (this.closing.has(control.threadId) || !existing && this.controls.size >= MAX_LIVE_SESSIONS) {
+          if (existing !== control) await this.host.dispose(control);
+          throw Error("thread is closing or the live session limit was reached");
+        }
+        if (existing && existing !== control) { await this.host.dispose(control); if (this.closed) throw Error("session hub closed during opening"); return existing; }
+        this.controls.set(control.threadId, control);
+        if (this.closed) throw Error("session hub closed during opening; the admitted owner will be drained");
+        return control;
+      } finally { if (!known) this.reserved--; }
+    })();
+    this.opening.add(operation); if (key) this.resuming.set(key, operation);
+    // Observe rejected opens without changing the caller's promise or leaking unhandled cleanup rejections.
+    void operation.finally(() => { this.opening.delete(operation); if (key) this.resuming.delete(key); }).catch(() => {});
+    return operation;
+  }
+  close(threadId: string): Promise<void> {
+    const pending = this.closing.get(threadId); if (pending) return pending;
+    const control = this.controls.get(threadId); if (!control) return Promise.reject(Error("unknown or closed threadId"));
+    const operation = (async () => {
+      if (control.activeTurnId) control.interrupt(control.activeTurnId);
+      await control.whenIdle().catch(() => {});
+      await this.host.dispose(control); this.controls.delete(threadId);
+    })();
+    this.closing.set(threadId, operation);
+    void operation.then(() => { if (this.closing.get(threadId) === operation) this.closing.delete(threadId); }, () => {});
+    return operation;
+  }
+  dispose(): Promise<void> {
+    if (this.disposal) return this.disposal;
+    this.closed = true;
+    return this.disposal = (async () => {
+      // Every kind is tracked; late publication belongs to this same draining generation.
+      await Promise.allSettled([...this.opening]);
+      const results = await Promise.allSettled([...this.controls.keys()].map(id => this.close(id)));
+      if (results.some(result => result.status === "rejected")) throw Error("session cleanup could not be confirmed");
+    })();
+  }
+}

package/src/runtime/tool-discovery.ts

@@ -1,7 +1,7 @@
 /** R11: a harness-owned discovery entry shares normal Session admission and result persistence. */
 import { createHash } from "node:crypto";
 import { discoverTools, MAX_DISCOVERY_QUERY, MAX_DISCOVERY_RESULTS, type DeclarationRequest } from "../core/tool-discovery.ts";
-import { decide } from "../core/permissions.ts";
+import { decideWithSessionRules } from "../core/permissions.ts";
 import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
 import type { ToolSchema } from "./provider.ts";
 import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
@@ -14,7 +14,7 @@ export const DISCOVERY_TOOL: ToolDefinition = {
     query: { type: "string", minLength: 1, maxLength: MAX_DISCOVERY_QUERY },
     limit: { type: "integer", minimum: 1, maximum: MAX_DISCOVERY_RESULTS, description: "Maximum matches to request; defaults to 5." },
   }, required: ["query"] },
-  access: "state", execution: "exclusive", branch: "none",
+  access: "read", execution: "exclusive", branch: "none",
   run: async () => ({ ok: false, content: "Tool discovery requires a live Session checkpoint." }),
 };
 
@@ -23,7 +23,8 @@ export function discoveryFingerprint(tool: ToolSchema): string {
   return createHash("sha256").update(JSON.stringify({ name: tool.name, description: tool.description, input_schema: tool.input_schema })).digest("hex");
 }
 export function discoveryPermitted(ctx: ToolContext, name: string): boolean {
-  return decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], { tool: name }) !== "deny";
+  if (ctx.workflowMode === "plan" && ctx.extensions?.get(name)?.access !== "read") return false;
+  return decideWithSessionRules(ctx.rules ?? [], ctx.sessionRules ?? [], { tool: name }) !== "deny";
 }
 /** A directory entry without its matching live implementation is unavailable, regardless of history. */
 export function currentDeferredTools(ctx: ToolContext): readonly ToolSchema[] {