@lucascouts/claude-agent-tui 0.6.0 → 0.7.0

package/dist/model-catalog.js

@@ -41,7 +41,8 @@ export const MODEL_CATALOG = [
     {
         value: "default",
         displayName: "Default (recommended)",
-        description: "Use the model the claude TUI is configured with (safe fallback); supports reasoning effort.",
+        // Story 069 (R3): `default` resolves to the recommended Opus, so it carries the Opus description.
+        description: "Best for everyday, complex tasks",
         supportsEffort: true,
         supportedEffortLevels: REASONING_EFFORT_LEVELS,
         supportsAutoMode: true,
@@ -49,7 +50,7 @@ export const MODEL_CATALOG = [
     {
         value: "opus",
         displayName: "Opus",
-        description: "Claude Opus — highest capability; supports reasoning effort.",
+        description: "Best for everyday, complex tasks",
         supportsEffort: true,
         supportedEffortLevels: REASONING_EFFORT_LEVELS,
         supportsAutoMode: true,
@@ -57,7 +58,7 @@ export const MODEL_CATALOG = [
     {
         value: "sonnet",
         displayName: "Sonnet",
-        description: "Claude Sonnet — balanced speed and capability; supports reasoning effort.",
+        description: "Efficient for routine tasks",
         supportsEffort: true,
         supportedEffortLevels: REASONING_EFFORT_LEVELS,
         supportsAutoMode: true,
@@ -65,7 +66,8 @@ export const MODEL_CATALOG = [
     {
         value: "sonnet[1m]",
         displayName: "Sonnet (1M context)",
-        description: "Claude Sonnet with a 1M-token context window; draws from usage credits; supports reasoning effort.",
+        // Story 069 (R3): fork-only 1M variant — the Sonnet description plus its 1M-window note.
+        description: "Efficient for routine tasks, with a 1M-token context window",
         supportsEffort: true,
         supportedEffortLevels: REASONING_EFFORT_LEVELS,
         supportsAutoMode: true,
@@ -73,13 +75,81 @@ export const MODEL_CATALOG = [
     {
         value: "haiku",
         displayName: "Haiku",
-        description: "Claude Haiku — fastest and most economical; no reasoning effort levels.",
+        description: "Fastest for quick answers",
     },
     {
         value: "opusplan",
-        displayName: "Opus Plan",
-        description: "Opus while planning, Sonnet for execution (plan-mode workflow; fork extra).",
+        displayName: "Opus Plan Mode",
+        description: "Use Opus in plan mode, Sonnet otherwise",
     },
 ];
+/**
+ * Story 068 (R1, R1.1, R2) — the REAL per-alias context window, keyed by the EXACT {@link MODEL_CATALOG}
+ * `value`. These windows are NOT uniform: `opus` is natively 1M, `sonnet`/`haiku` are 200K, and
+ * `sonnet[1m]` is the explicit 1M variant. This map is the single source of truth that
+ * `inferContextWindowFromModel` (acp-agent.ts) consults BEFORE the `\b1m\b` regex fallback — the bug it
+ * fixes is `opus` having wrongly reported 200K (the regex only ever matched the literal `1m` token).
+ *
+ * Story 069 (R2): `default` and `opusplan` seed to 1M — `default` is the recommended Opus (the claude TUI's
+ * `/model default` resolves to `claude-opus-4-8[1m]`, a 1M model) and `opusplan` plans with Opus. This is
+ * only the PRE-FIRST-TURN seed: once a turn arrives, `inferContextWindowFromModelId` (story 069)
+ * AUTHORITATIVELY refines the window from the transcript's real `model`. Keys MIRROR `MODEL_CATALOG`
+ * `value`s; the drift guard lives in the test (068 anti-drift: every catalog value has an explicit entry).
+ */
+export const MODEL_CONTEXT_WINDOWS = {
+    default: 1_000_000,
+    opus: 1_000_000,
+    sonnet: 200_000,
+    "sonnet[1m]": 1_000_000,
+    haiku: 200_000,
+    opusplan: 1_000_000,
+};
+/**
+ * Story 069 (R1.1) — the REAL context window per concrete model ID, mirroring the claude CLI's
+ * `context:{window}` table. Used to AUTHORITATIVELY refine the window from a turn's actual `model`
+ * (the JSONL `model` field), correcting the alias seed. Opus is NOT uniform: 4.6 = 200K, 4.7+ = 1M.
+ * Dated snapshots / future versions are covered by the family+version heuristic in
+ * `inferContextWindowFromModelId`; this table is the exact-ID source of truth for today's gateway IDs.
+ */
+export const MODEL_ID_CONTEXT_WINDOWS = {
+    "claude-opus-4-8": 1_000_000,
+    "claude-opus-4-7": 1_000_000,
+    "claude-opus-4-6": 200_000,
+    "claude-fable-5": 1_000_000,
+    "claude-sonnet-5": 1_000_000,
+    "claude-sonnet-4-6": 200_000,
+    "claude-sonnet-4-5-20250929": 200_000,
+    "claude-sonnet-4-20250514": 200_000,
+    "claude-haiku-4-5": 200_000,
+};
+/**
+ * Story 072 — the version/context PREFIX the claude `/model` picker now shows before the static tagline
+ * (e.g. "Opus 4.8 with 1M context · Best for everyday, complex tasks"). Keyed by catalog `value`.
+ *
+ * CURATED + DRIFT-PRONE, exactly like MODEL_CATALOG membership: the fork holds only aliases pre-turn and
+ * cannot derive the concrete version (the SDK `supportedModels()` was cut), so these MIRROR the LIVE
+ * picker and MUST be re-verified on each model launch (source: the user's live `/model` output). The
+ * static tagline stays on `ModelInfo.description` (069 R3 untouched); this only prepends "<version> · ".
+ * `opusplan` is intentionally absent — its tagline ("Use Opus in plan mode, Sonnet otherwise") already
+ * names the models, so it renders bare.
+ */
+export const MODEL_VERSION_LABELS = {
+    default: "Opus 4.8 with 1M context",
+    opus: "Opus 4.8 with 1M context",
+    sonnet: "Sonnet 5",
+    "sonnet[1m]": "Sonnet 5 with 1M context",
+    haiku: "Haiku 4.5",
+};
+/**
+ * Story 072 — compose the Zed selector description: "<version label> · <tagline>", or the bare tagline
+ * when no label exists (e.g. `opusplan`). PURE + TOTAL: never throws on a missing label or tagline.
+ */
+export function modelSelectorDescription(info) {
+    const label = MODEL_VERSION_LABELS[info.value];
+    const tagline = info.description ?? "";
+    if (!label)
+        return tagline;
+    return tagline ? `${label} · ${tagline}` : label;
+}
 /** The safe fallback entry, kept as a named export so callers can seed/anchor on it without a lookup. */
 export const DEFAULT_MODEL_INFO = MODEL_CATALOG[0];

package/dist/permissions/allow-inject.d.ts

@@ -64,4 +64,3 @@ export interface ClearNativePromptOptions {
  * @returns an {@link InjectResult}: `'suppressed'` | `'cleared'` | `'stuck'`.
  */
 export declare function clearNativePrompt(opts: ClearNativePromptOptions): Promise<InjectResult>;
-//# sourceMappingURL=allow-inject.d.ts.map

package/dist/permissions/deny.d.ts

@@ -44,6 +44,18 @@ export declare function denyDecision(toolCall: DenyToolCall, reason?: string): H
  * @returns `{ hookSpecificOutput: { hookEventName:'PreToolUse', permissionDecision:'allow', … } }`.
  */
 export declare function allowDecision(toolCall: DenyToolCall, reason?: string): HookResponse;
+/** Story 064 — the interactive tool the gate denies fail-closed over the Zed bridge (R1). */
+export declare const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+/** True iff `toolName` is the AskUserQuestion interactive picker tool (exact, case-sensitive). */
+export declare function isAskUserQuestionTool(toolName: string): boolean;
+/**
+ * Story 064 (R1.1) — the deny reason for AskUserQuestion over the Zed bridge. AskUserQuestion renders
+ * an interactive multiple-choice picker bound to the hidden PTY's stdin; the Zed user can neither see
+ * nor answer it, so allowing it would stall the turn until the watchdog fires. Deny it fail-closed with
+ * this reason so the model proceeds without it (interim until story 065 relays it via ACP elicitation).
+ * MUST name the tool and cite the bridge limitation (the body matches `/AskUserQuestion/` and `/bridge/i`).
+ */
+export declare function askUserQuestionDenyReason(): string;
 /**
  * Matcher-scoped deny predicate (R2.3 NUANCE): does this deny matcher target the given tool?
  *
@@ -57,4 +69,3 @@ export declare function allowDecision(toolCall: DenyToolCall, reason?: string):
  * @returns true iff the matcher scopes the deny to this tool.
  */
 export declare function denyMatchesTool(matcher: string, toolName: string): boolean;
-//# sourceMappingURL=deny.d.ts.map

package/dist/permissions/deny.js

@@ -64,6 +64,24 @@ export function allowDecision(toolCall, reason) {
         },
     };
 }
+/** Story 064 — the interactive tool the gate denies fail-closed over the Zed bridge (R1). */
+export const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+/** True iff `toolName` is the AskUserQuestion interactive picker tool (exact, case-sensitive). */
+export function isAskUserQuestionTool(toolName) {
+    return toolName === ASK_USER_QUESTION_TOOL;
+}
+/**
+ * Story 064 (R1.1) — the deny reason for AskUserQuestion over the Zed bridge. AskUserQuestion renders
+ * an interactive multiple-choice picker bound to the hidden PTY's stdin; the Zed user can neither see
+ * nor answer it, so allowing it would stall the turn until the watchdog fires. Deny it fail-closed with
+ * this reason so the model proceeds without it (interim until story 065 relays it via ACP elicitation).
+ * MUST name the tool and cite the bridge limitation (the body matches `/AskUserQuestion/` and `/bridge/i`).
+ */
+export function askUserQuestionDenyReason() {
+    return (`${ASK_USER_QUESTION_TOOL} is not supported over the Zed bridge: its interactive multiple-choice ` +
+        `picker renders in a hidden PTY the user cannot see or answer, so the turn would stall. Denying it ` +
+        `fail-closed — continue without asking an interactive question.`);
+}
 /**
  * Matcher-scoped deny predicate (R2.3 NUANCE): does this deny matcher target the given tool?
  *

package/dist/permissions/elicitation-bridge.d.ts

@@ -0,0 +1,71 @@
+import type { CreateElicitationRequest, CreateElicitationResponse } from "@agentclientprotocol/sdk";
+/**
+ * The gate decision this bridge yields. Mirrors hook-server's `DenyWithReason`: AskUserQuestion is
+ * ALWAYS denied at the wire, and the user's selection (or the dismissal note) is carried in `reason`.
+ */
+export interface ElicitationDecision {
+    decision: "deny";
+    reason: string;
+}
+/** The `AskUserQuestion` tool_input subset the bridge projects into a form elicitation. */
+export interface AskUserQuestionInput {
+    questions: Array<{
+        /** The human-readable question text — becomes the property `title`. */
+        question: string;
+        /** The short key — becomes the property name AND a `required` entry. */
+        header: string;
+        /** Whether multiple options may be selected (currently projected as a single string-enum). */
+        multiSelect?: boolean;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+    }>;
+}
+/**
+ * The minimal ACP client surface the bridge needs — structurally satisfied by the kept
+ * `AgentSideConnection` (`client.unstable_createElicitation(params)`). Injected so a unit test drives
+ * the bridge with a fake client OFFLINE (no AgentSideConnection, no Zed).
+ */
+export interface ElicitationClient {
+    unstable_createElicitation(params: CreateElicitationRequest): Promise<CreateElicitationResponse>;
+}
+/**
+ * Project an `AskUserQuestion` tool_input into an ACP form `CreateElicitationRequest`, scoped to the
+ * session and tied to the originating tool call by `tool_use.id` (R1.1, R1.2).
+ *
+ * Each question becomes one string-enum property keyed by its `header`: `{ type: "string", title:
+ * <question>, enum: <option labels, in order> }`, and every header is marked `required` (one entry per
+ * question, in order). The returned literal is shaped to satisfy the pinned SDK `zCreateElicitationRequest`.
+ */
+export declare function buildElicitationRequest(toolUseId: string, sessionId: string, toolInput: AskUserQuestionInput): CreateElicitationRequest;
+/**
+ * Map an elicitation outcome back to a gate decision (R2). EVERY branch returns a `deny`: the gate
+ * always denies AskUserQuestion at the wire and surfaces the result through `reason` (the R2.1 seam — a
+ * PreToolUse hook cannot synthesize a native tool_result).
+ *
+ *   - `accept`: the reason embeds EVERY selected answer (e.g. `Env=prod, Cache=yes`) so the model can
+ *     read the choice from the deny reason. `content` null/undefined is handled defensively (still deny).
+ *   - `decline`/`cancel`/any unrecognized-or-missing action: the reason reads as a user DISMISSAL, not
+ *     an answer (default-deny defensively for unknown actions).
+ */
+export declare function mapOutcomeToDecision(resp: CreateElicitationResponse): ElicitationDecision;
+/** Options for {@link requestElicitation}. */
+export interface RequestElicitationOptions {
+    /** The hard upper bound (ms) on the round-trip; a slower client fails closed to a cancel. */
+    timeoutMs: number;
+    /** Optional sink for the fail-closed diagnostics (defaults to no-op; production wires the logger). */
+    onWarn?: (message: string) => void;
+}
+/**
+ * Perform the bounded, fail-closed elicitation round-trip (R4). NEVER throws and NEVER hangs past
+ * ~`timeoutMs`.
+ *
+ *   - Happy path (a well-formed response, action ∈ {accept,decline,cancel}) → returned UNCHANGED.
+ *   - Timeout → `onWarn` (naming the timeout) and resolve `{ action: "cancel" }`.
+ *   - Client throws → `onWarn` (including the underlying error text) and resolve `{ action: "cancel" }`.
+ *   - Malformed response (action not accept|decline|cancel) → normalized to `{ action: "cancel" }`.
+ *
+ * The timer is always cleared on settle so no live handle keeps the event loop open.
+ */
+export declare function requestElicitation(client: ElicitationClient, req: CreateElicitationRequest, opts: RequestElicitationOptions): Promise<CreateElicitationResponse>;

package/dist/permissions/elicitation-bridge.js

@@ -0,0 +1,146 @@
+/**
+ * Project an `AskUserQuestion` tool_input into an ACP form `CreateElicitationRequest`, scoped to the
+ * session and tied to the originating tool call by `tool_use.id` (R1.1, R1.2).
+ *
+ * Each question becomes one string-enum property keyed by its `header`: `{ type: "string", title:
+ * <question>, enum: <option labels, in order> }`, and every header is marked `required` (one entry per
+ * question, in order). The returned literal is shaped to satisfy the pinned SDK `zCreateElicitationRequest`.
+ */
+export function buildElicitationRequest(toolUseId, sessionId, toolInput) {
+    const properties = {};
+    const required = [];
+    for (const q of toolInput.questions) {
+        properties[q.header] = {
+            type: "string",
+            title: q.question,
+            enum: q.options.map((o) => o.label),
+        };
+        required.push(q.header);
+    }
+    const message = toolInput.questions.length === 1
+        ? `Please answer: ${toolInput.questions[0]?.question ?? "the question below"}`
+        : `Please answer the following ${toolInput.questions.length} question(s).`;
+    // The SDK `CreateElicitationRequest` is an awkward mode/scope intersection; this well-formed form
+    // literal parses against `zCreateElicitationRequest` (verified by the C1 test), so a single localized
+    // cast is used rather than scattering `any` across the object.
+    return {
+        mode: "form",
+        message,
+        sessionId,
+        toolCallId: toolUseId,
+        requestedSchema: {
+            type: "object",
+            properties,
+            required,
+        },
+    };
+}
+/** The wire actions the bridge recognizes as a well-formed elicitation response. */
+const KNOWN_ACTIONS = new Set(["accept", "decline", "cancel"]);
+/**
+ * True iff `resp` is a structurally well-formed `CreateElicitationResponse` — i.e. an object whose
+ * `action` is one of accept|decline|cancel. Used to fail closed on a malformed wire response WITHOUT
+ * importing the zod validators (blocked by the package `exports` map).
+ */
+function hasKnownAction(resp) {
+    return (typeof resp === "object" &&
+        resp !== null &&
+        "action" in resp &&
+        typeof resp.action === "string" &&
+        KNOWN_ACTIONS.has(resp.action));
+}
+/**
+ * Map an elicitation outcome back to a gate decision (R2). EVERY branch returns a `deny`: the gate
+ * always denies AskUserQuestion at the wire and surfaces the result through `reason` (the R2.1 seam — a
+ * PreToolUse hook cannot synthesize a native tool_result).
+ *
+ *   - `accept`: the reason embeds EVERY selected answer (e.g. `Env=prod, Cache=yes`) so the model can
+ *     read the choice from the deny reason. `content` null/undefined is handled defensively (still deny).
+ *   - `decline`/`cancel`/any unrecognized-or-missing action: the reason reads as a user DISMISSAL, not
+ *     an answer (default-deny defensively for unknown actions).
+ */
+export function mapOutcomeToDecision(resp) {
+    // `resp` is a typed union, but we read `action`/`content` defensively (a synthetic fail-closed
+    // cancel or a malformed upstream value may reach here) via a single localized view.
+    const view = resp;
+    if (view?.action === "accept") {
+        const content = view.content;
+        const answers = content !== undefined && content !== null
+            ? Object.entries(content)
+                .map(([key, value]) => `${key}=${String(value)}`)
+                .join(", ")
+            : "";
+        const reason = answers.length > 0
+            ? `AskUserQuestion answered by the user: ${answers}. (The tool is always denied at the ` +
+                `gate; this selection is returned to you via this reason.)`
+            : `AskUserQuestion was accepted but returned no selection. (The tool is always denied at ` +
+                `the gate; treat this as no usable answer.)`;
+        return { decision: "deny", reason };
+    }
+    // decline, cancel, or any unrecognized/missing action → a dismissal, never an answer.
+    return {
+        decision: "deny",
+        reason: `The user dismissed the AskUserQuestion prompt without providing an answer (no answer was ` +
+            `selected). (The tool is always denied at the gate.)`,
+    };
+}
+/** A synthetic fail-closed outcome — a cancel is a dismissal, mapped to a deny at the gate. */
+function failClosedCancel() {
+    // `{ action: "cancel" }` satisfies the SDK response union; a localized cast avoids widening the API.
+    return { action: "cancel" };
+}
+/**
+ * Perform the bounded, fail-closed elicitation round-trip (R4). NEVER throws and NEVER hangs past
+ * ~`timeoutMs`.
+ *
+ *   - Happy path (a well-formed response, action ∈ {accept,decline,cancel}) → returned UNCHANGED.
+ *   - Timeout → `onWarn` (naming the timeout) and resolve `{ action: "cancel" }`.
+ *   - Client throws → `onWarn` (including the underlying error text) and resolve `{ action: "cancel" }`.
+ *   - Malformed response (action not accept|decline|cancel) → normalized to `{ action: "cancel" }`.
+ *
+ * The timer is always cleared on settle so no live handle keeps the event loop open.
+ */
+export async function requestElicitation(client, req, opts) {
+    const { timeoutMs, onWarn } = opts;
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ __timedOut: true }), timeoutMs);
+    });
+    try {
+        const settled = await Promise.race([
+            // DEFER the client call through a resolved microtask so a SYNCHRONOUS throw (the method is
+            // `undefined` — capability advertised but absent — or it throws before returning a promise)
+            // becomes a REJECTION the inline handler below catches, instead of escaping at argument-
+            // evaluation time (this `try` has only a `finally`, so an eager throw would re-throw out of
+            // requestElicitation, violating "never throws"). Async rejections still take the same path.
+            Promise.resolve()
+                .then(() => client.unstable_createElicitation(req))
+                .then((resp) => ({ ok: true, resp }), (err) => ({ ok: false, err })),
+            timeout,
+        ]);
+        // Timeout won the race — fail closed to a cancel.
+        if ("__timedOut" in settled) {
+            onWarn?.(`[gate elicitation] FAIL CLOSED: AskUserQuestion elicitation timed out after ${timeoutMs}ms ` +
+                `— resolving as a cancel (dismissal), never an accept.`);
+            return failClosedCancel();
+        }
+        // The client threw — fail closed to a cancel, surfacing the underlying error text.
+        if (!settled.ok) {
+            const err = settled.err;
+            onWarn?.(`[gate elicitation] FAIL CLOSED: AskUserQuestion elicitation transport error ` +
+                `(${err instanceof Error ? err.message : String(err)}) — resolving as a cancel.`);
+            return failClosedCancel();
+        }
+        // A well-formed response is returned unchanged; a malformed one is normalized to a cancel.
+        if (hasKnownAction(settled.resp)) {
+            return settled.resp;
+        }
+        onWarn?.(`[gate elicitation] FAIL CLOSED: malformed elicitation response (action not accept|decline|` +
+            `cancel) — resolving as a cancel.`);
+        return failClosedCancel();
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/permissions/gate-wiring.d.ts

@@ -1,4 +1,5 @@
 import { ToolUseCorrelator, type PermissionClient } from "./request-permission.js";
+import { type ElicitationClient } from "./elicitation-bridge.js";
 import { type PtyWriter, type Schedule } from "./allow-inject.js";
 /**
  * Substrings that evidence the native TUI permission prompt (the bordered "Do you want to
@@ -62,12 +63,32 @@ export interface GatePty extends PtyWriter {
         dispose(): void;
     };
 }
+/**
+ * Story 065 — the default hard upper bound (ms) on the AskUserQuestion elicitation round-trip. Generous
+ * (a human may take minutes to answer) but DELIBERATELY BELOW the hook-server
+ * {@link import("./hook-server.js").DEFAULT_DECIDER_TIMEOUT_MS} (600_000), so the bridge times out FIRST
+ * with a legible fail-closed reason rather than the decider being killed out from under it. Injectable
+ * via {@link SessionGateOptions.elicitationTimeoutMs} so offline tests use a small value.
+ */
+export declare const DEFAULT_ELICITATION_TIMEOUT_MS = 300000;
 /** Options for {@link setupSessionGate}. Timing knobs are injectable for offline tests. */
 export interface SessionGateOptions {
-    /** The ACP client surface (`AgentSideConnection` satisfies it: `requestPermission(params)`). */
-    client: PermissionClient;
+    /** The ACP client surface. `AgentSideConnection` satisfies BOTH `requestPermission(params)`
+     *  (the story-033 relay) AND `unstable_createElicitation(params)` (the story-065 elicitation
+     *  bridge), so the field carries both capabilities. */
+    client: PermissionClient & ElicitationClient;
     /** Diagnostics sink for every fail-closed / stuck-prompt warning (production: logger.error). */
     onWarn?: (message: string) => void;
+    /**
+     * Story 065 (R1/R3) — whether the connected ACP client negotiated the elicitation `form` capability
+     * (`clientCapabilities.elicitation.form`). When true, AskUserQuestion is driven through a real ACP
+     * form elicitation ({@link SessionGateImpl.decideElicitation}); when false/omitted it DEGRADES to the
+     * story-064 fail-closed deny-guard. Defaults to false when read, so an existing gate/064 test that
+     * omits it keeps the degrade behavior (load-bearing — do NOT make required). */
+    clientSupportsElicitationForm?: boolean;
+    /** Story 065 — hard upper bound (ms) on the AskUserQuestion elicitation round-trip; default
+     *  {@link DEFAULT_ELICITATION_TIMEOUT_MS}. Injectable so offline tests use a small value. */
+    elicitationTimeoutMs?: number;
     /** Injectable timer seam (same discipline as allow-inject/end-of-turn). Default: setTimeout. */
     schedule?: Schedule;
     /** Directory for the per-session scratch settings file. Default: `os.tmpdir()`. */
@@ -155,4 +176,3 @@ export interface SessionGate {
  * an ungated claude that LOOKS gated (the blocker-b hazard). `FORK_GATE=off` is the escape hatch.
  */
 export declare function setupSessionGate(opts: SessionGateOptions): Promise<SessionGate>;
-//# sourceMappingURL=gate-wiring.d.ts.map

package/dist/permissions/gate-wiring.js

@@ -33,8 +33,10 @@ import * as path from "node:path";
 import { randomBytes, randomUUID } from "node:crypto";
 import { findFreePort } from "../gate/port.js";
 import { injectHook, restore } from "../gate/settings-writer.js";
-import { startHookServer } from "./hook-server.js";
+import { startHookServer, } from "./hook-server.js";
+import { askUserQuestionDenyReason, isAskUserQuestionTool } from "./deny.js";
 import { requestPermission, ToolUseCorrelator, } from "./request-permission.js";
+import { buildElicitationRequest, mapOutcomeToDecision, requestElicitation, } from "./elicitation-bridge.js";
 import { clearNativePrompt } from "./allow-inject.js";
 /**
  * Substrings that evidence the native TUI permission prompt (the bordered "Do you want to
@@ -111,9 +113,53 @@ export const SCRATCH_SETTINGS_PREFIX = "fork-acp-gate-settings-";
 /** Story 046 (R3) — the file-edit tools that `acceptEdits` auto-allows, mirroring claude's native
  *  acceptEdits semantics (edits proceed without prompting; every other tool still asks). */
 const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+/**
+ * Story 065 — the default hard upper bound (ms) on the AskUserQuestion elicitation round-trip. Generous
+ * (a human may take minutes to answer) but DELIBERATELY BELOW the hook-server
+ * {@link import("./hook-server.js").DEFAULT_DECIDER_TIMEOUT_MS} (600_000), so the bridge times out FIRST
+ * with a legible fail-closed reason rather than the decider being killed out from under it. Injectable
+ * via {@link SessionGateOptions.elicitationTimeoutMs} so offline tests use a small value.
+ */
+export const DEFAULT_ELICITATION_TIMEOUT_MS = 300_000;
 const defaultSchedule = (fn, ms) => {
     setTimeout(fn, ms);
 };
+/**
+ * Story 065 — STRUCTURAL guard that a hook payload's `tool_input` is a usable {@link AskUserQuestionInput}:
+ * an object carrying a NON-EMPTY `questions` array, EACH question being an object with a `header` string
+ * and a NON-EMPTY `options` array of `{ label: string }`. The runtime zod validators are not importable
+ * across the SDK package `exports` map, and the hook payload's `tool_input` is `unknown`, so this narrows
+ * before the bridge builder projects it into a form (an empty/garbage form would otherwise reach the
+ * client, and a per-question shape the builder walks — `q.options.map(...)`, `q.header` — would otherwise
+ * throw).
+ *
+ * Story 065 / task 4.1 (R4) — the per-question `options`/`header` validation is a BELT-AND-SUSPENDERS
+ * addition: {@link SessionGateImpl.decideElicitation} now also wraps the build in a try/catch (the
+ * mandatory total-function guarantee), so this guard's job is only to fail closed to the story-064 deny
+ * EARLY (with a "malformed tool_input" reason) rather than relying on the catch. Both together mean a
+ * malformed per-question input is a legible dismissal, never a crash and never an approve.
+ */
+function isAskUserQuestionInput(input) {
+    if (typeof input !== "object" ||
+        input === null ||
+        !("questions" in input) ||
+        !Array.isArray(input.questions)) {
+        return false;
+    }
+    const questions = input.questions;
+    if (questions.length === 0)
+        return false;
+    return questions.every((q) => {
+        if (typeof q !== "object" || q === null)
+            return false;
+        const question = q;
+        if (typeof question.header !== "string")
+            return false;
+        if (!Array.isArray(question.options) || question.options.length === 0)
+            return false;
+        return question.options.every((o) => typeof o === "object" && o !== null && typeof o.label === "string");
+    });
+}
 /** Internal mutable state of one session's gate. */
 class SessionGateImpl {
     constructor(opts) {
@@ -239,6 +285,22 @@ class SessionGateImpl {
     async decide(call) {
         if (this.torndown)
             return "deny"; // a hook racing teardown is never approved
+        // === Story 064/065 — AskUserQuestion handling, BEFORE any mode auto-allow or ACP relay. =========
+        // AskUserQuestion renders an interactive multiple-choice picker bound to the hidden PTY's stdin.
+        // Over the bridge the Zed user can't see or answer it, so an allow (including the bypass/acceptEdits
+        // auto-allow below) would stall the turn until the watchdog fires. This branch stays FIRST (after the
+        // torndown check) so AskUserQuestion is always intercepted regardless of permission mode.
+        //
+        // Story 065 (R1): when the client negotiated the elicitation `form` capability, drive a REAL ACP form
+        // elicitation and carry the answer back in a deny reason (a PreToolUse hook cannot synthesize a native
+        // tool_result — the tool is ALWAYS denied at the wire). Story 065 (R3): otherwise DEGRADE to the
+        // story-064 fail-closed deny-guard so the model proceeds without stalling.
+        if (isAskUserQuestionTool(call.toolName)) {
+            if (this.opts.clientSupportsElicitationForm) {
+                return await this.decideElicitation(call);
+            }
+            return { decision: "deny", reason: askUserQuestionDenyReason() }; // R3 degrade
+        }
         // === Story 046 (R3) — honor the live permission mode BEFORE relaying to Zed. =================
         // The hook payload carries the current mode (probe-d confirmed `permission_mode` matches the
         // selected mode in acceptEdits/bypassPermissions). Without this branch the gate raises
@@ -339,6 +401,66 @@ class SessionGateImpl {
             }
         });
     }
+    /**
+     * Story 065 (R1, R2.1, R2.2) — drive an AskUserQuestion via a REAL ACP form elicitation and map the
+     * user's outcome back to a gate decision. ALWAYS returns a `deny`+reason (a PreToolUse hook cannot
+     * synthesize a native tool_result): on accept the reason CARRIES the answer (R2.1); on
+     * decline/cancel/timeout/transport-error the reason reads as a dismissal (R2.2). Reached ONLY when the
+     * client negotiated the elicitation `form` capability (guarded in {@link decide}).
+     *
+     * FAIL CLOSED (mirrors the whole gate's posture): an elicitation is SESSION-SCOPED, so with no bound
+     * ACP session id (nor a payload fallback) we CANNOT raise one → fall back to the story-064 deny. A
+     * structurally malformed `tool_input` (not an object with a non-empty `questions` array) likewise falls
+     * back — the bridge builder would otherwise project an empty/garbage form. Both are dismissals, never
+     * an accept.
+     *
+     * The turn is BLOCKED awaiting the user exactly like the requestPermission relay, so the end-of-turn
+     * watchdog is re-armed via {@link startPermissionHeartbeat} for as long as the elicitation is open
+     * (always cleared in `finally`). The round-trip itself is bounded + fail-closed inside
+     * {@link requestElicitation} (it never throws and never hangs past the timeout).
+     */
+    async decideElicitation(call) {
+        const sessionId = this.sessionId ?? call.sessionId;
+        if (!sessionId) {
+            this.warn(`[gate elicitation] FAIL CLOSED: AskUserQuestion for tool_use ${call.toolUseId} arrived before ` +
+                `the gate was bound to an ACP session — cannot raise a session-scoped elicitation; denying ` +
+                `(story-064 fallback).`);
+            return { decision: "deny", reason: askUserQuestionDenyReason() };
+        }
+        if (!isAskUserQuestionInput(call.toolInput)) {
+            this.warn(`[gate elicitation] FAIL CLOSED: AskUserQuestion tool_use ${call.toolUseId} carried a malformed ` +
+                `tool_input (expected an object with a non-empty "questions" array) — cannot build a form ` +
+                `elicitation; denying (story-064 fallback).`);
+            return { decision: "deny", reason: askUserQuestionDenyReason() };
+        }
+        // The claude is blocked on this response with the JSONL silent, so re-arm the end-of-turn watchdog
+        // for as long as the elicitation is open (a slow human decision is NOT a dead turn). Mirror the
+        // requestPermission relay's heartbeat; always cleared in `finally`, on success or throw.
+        const stopHeartbeat = this.startPermissionHeartbeat();
+        try {
+            // TOTAL by construction (R4): build + round-trip are wrapped so ANY throw degrades to the
+            // story-064 deny with a legible diagnostic, never escaping decideElicitation. buildElicitationRequest
+            // itself can throw on a per-question input the structural guard did not catch (e.g. a question with
+            // no `options` array → `q.options.map(...)` throws); requestElicitation is fail-closed internally,
+            // but this catch is the mandatory total-function guarantee (the hook-server's decideWithTimeout is
+            // only the generic defense-in-depth net). A throw here is a dismissal, never an accept.
+            const req = buildElicitationRequest(call.toolUseId, sessionId, call.toolInput);
+            const resp = await requestElicitation(this.opts.client, req, {
+                timeoutMs: this.opts.elicitationTimeoutMs ?? DEFAULT_ELICITATION_TIMEOUT_MS,
+                onWarn: (m) => this.warn(m),
+            });
+            return mapOutcomeToDecision(resp);
+        }
+        catch (err) {
+            this.warn(`[gate elicitation] FAIL CLOSED: AskUserQuestion tool_use ${call.toolUseId} could not be ` +
+                `elicited (${err instanceof Error ? err.message : String(err)}) — denying (story-064 ` +
+                `fallback); the tool is intercepted, never approved.`);
+            return { decision: "deny", reason: askUserQuestionDenyReason() };
+        }
+        finally {
+            stopHeartbeat();
+        }
+    }
     /** Bounded poll until the pump has registered `toolUseId` as a clean single JSONL match. On
      *  expiry, resolve anyway — `requestPermission` then fails closed on the missing correlation.
      *

package/dist/permissions/hook-server.d.ts

@@ -27,8 +27,17 @@ export interface ForwardedToolCall {
      *  for a main-chain tool. There is NO parent tool_use.id in the payload (grouping is best-effort). */
     agentType?: string;
 }
-/** The decider the server forwards each tool call to; returns the enforced `'allow'`/`'deny'`. */
-export type ToolCallDecider = (call: ForwardedToolCall) => Promise<"allow" | "deny"> | "allow" | "deny";
+/** Story 064 — a deny that carries a custom `permissionDecisionReason` (e.g. the AskUserQuestion
+ *  anti-stall reason) instead of the {@link defaultDenyReason}. */
+export interface DenyWithReason {
+    decision: "deny";
+    reason: string;
+}
+/** The enforced outcome a decider returns: a plain allow/deny, or a deny carrying a custom reason.
+ *  Plain `"deny"` and {@link DenyWithReason} both intercept the tool; the latter just names a reason. */
+export type ToolDecision = "allow" | "deny" | DenyWithReason;
+/** The decider the server forwards each tool call to; returns the enforced {@link ToolDecision}. */
+export type ToolCallDecider = (call: ForwardedToolCall) => Promise<ToolDecision> | ToolDecision;
 /** The running hook server handle. */
 export interface HookServer {
     /** The loopback port the server bound (feeds the story-032 hook URL). */
@@ -84,4 +93,3 @@ export declare function parsePayload(raw: string): ForwardedToolCall | null;
  *   fails fast rather than spawning claude with an ungated hook URL).
  */
 export declare function startHookServer(opts: StartHookServerOptions): Promise<HookServer>;
-//# sourceMappingURL=hook-server.d.ts.map

package/dist/permissions/hook-server.js

@@ -42,6 +42,15 @@ function writeDecision(res, decision) {
     res.writeHead(200, { "content-type": "application/json" });
     res.end(json);
 }
+/** Map a decider's {@link ToolDecision} to the §9 hook body, honoring a {@link DenyWithReason}'s custom
+ *  reason (story 064). A plain allow/deny uses the default allow/deny body. */
+function toHookResponse(decision, call) {
+    if (decision === "allow")
+        return allowDecision(call);
+    if (decision === "deny")
+        return denyDecision(call);
+    return denyDecision(call, decision.reason);
+}
 /**
  * Parse a PreToolUse payload from raw JSON, normalizing to {@link ForwardedToolCall}. Returns null when
  * the body is unparseable OR lacks a `tool_use_id`/`tool_name` — the caller fails closed on null (a
@@ -161,7 +170,7 @@ export function startHookServer(opts) {
                     return;
                 }
                 const decision = await decideWithTimeout(decider, call, deciderTimeoutMs, onWarn);
-                writeDecision(res, decision === "allow" ? allowDecision(call) : denyDecision(call));
+                writeDecision(res, toHookResponse(decision, call));
             }
             catch (err) {
                 // Any unexpected handler error (body read failure, write failure) → fail closed.