commandmate 0.21.5 → 0.22.0

package/dist/server/src/lib/detection/prompt-detect-multiple-choice.js

@@ -2,6 +2,7 @@
 /** Multiple choice prompt detection logic extracted from prompt-detector.ts (Issue #575). */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APPROVAL_TARGET_MAX_LOOKBACK = void 0;
+exports.findClaudeTaskPanelLines = findClaudeTaskPanelLines;
 exports.findApprovalContextStart = findApprovalContextStart;
 exports.joinApprovalTarget = joinApprovalTarget;
 exports.buildMultipleChoiceResult = buildMultipleChoiceResult;
@@ -52,6 +53,93 @@ const DEFAULT_OPTION_PATTERN = /^\s*[\u276F\u25CF\u203A][^\d]*(\d+)(?:\.(?!\d)|\
  * Layer 4 (2+ options), and Layer 5 (SEC-001 question line validation).
  */
 const NORMAL_OPTION_PATTERN = /^\s*[^\d]{0,3}(\d+)(?:\.(?!\d)|\s+)\s*(.+)$/;
+/**
+ * [Issue #1708] Header row of Claude Code's bottom-anchored task panel, e.g.
+ *   "  7 tasks (0 done, 1 in progress, 6 open)"
+ *
+ * The panel is an overlay pinned to the LAST rows of the pane, structurally
+ * unrelated to whatever the agent is currently blocked on. In a production pane
+ * (200x1000, alternate screen) a prompt dialog therefore renders near the top and
+ * the panel ~880 blank rows below it — rows `compactBlankRows` collapses to one,
+ * putting the panel squarely inside Pass 2's 50-line reverse-scan window.
+ *
+ * That is only harmless while something trims it away. #704/#807 trim at a
+ * footer, but the AskUserQuestion *confirmation* step ("Ready to submit your
+ * answers?") renders NEITHER footer, so nothing trims and the panel is the first
+ * thing the reverse scan meets. Measured on the live capture in
+ * fixtures/claude-live-1708/askuserquestion-submit-taskpanel.txt, two of its rows
+ * match NORMAL_OPTION_PATTERN independently:
+ *   - this header      → option 7,  label "tasks (2 done, 1 in progress, 4 open)"
+ *   - "… +2 completed" → option 2,  label "completed"
+ * Either one alone is enough to make isValidPrecedingOption() reject the real
+ * `❯ 1. Submit answers` / `2. Cancel` above it, so collectedOptions never reaches
+ * 2 and the frame is published as "no prompt" — Issue #1708's silent timeout.
+ *
+ * Anchored at line start and requires the literal `tasks (` + `<n> done`, which
+ * no option label produced by any supported CLI carries. ReDoS safe (S4-001):
+ * bounded repetition, no nesting.
+ */
+const CLAUDE_TASK_PANEL_HEADER_PATTERN = /^\s*\d{1,3}\s+tasks?\s+\(\d+\s+done\b/i;
+/**
+ * [Issue #1708] A single task row of the panel described above, e.g. "  ◼ Phase 3".
+ *
+ * Today these rows are inert — `isContinuationLine()` already absorbs them — but
+ * only because none of the observed titles begins with a digit. A title like
+ * "2. Fix the parser" would render as "  ◻ 2. Fix the parser" and be collected as
+ * option 2, reintroducing the same poisoning from a direction no single-line
+ * guard anticipates. Skipping the whole panel block closes that off structurally
+ * instead of one wording at a time.
+ *
+ * The glyph set is exactly the two forms measured on a live pane — ◼ (in
+ * progress) and ◻ (open) — and nothing else. Every extra glyph is a line this
+ * guard can delete from the frame, so the set is an allowlist of things seen,
+ * not a guess at what the family might contain:
+ *
+ *   - ❯ ● › are DEFAULT_OPTION_PATTERN's cursor indicators.
+ *   - ⏺ ⎿ ✔ ✗ are the transcript markers TURN_BOUNDARY_PATTERN reads.
+ *   - ☐ ☑ ☒ are the natural rendering of a MULTI-SELECT choice, and
+ *     AskUserQuestion has a multiSelect mode. Measured: with those in the set,
+ *     `☐ 1. Blue / ☑ 2. Green / ☐ 3. Red` under a panel header is claimed as
+ *     panel content and the prompt above it disappears entirely
+ *     (isPrompt=false, zero options) — Issue #1708's own failure, recreated by
+ *     its fix. See the regression test.
+ *
+ * A completed row never appears (the panel collapses those into `… +N
+ * completed`, which SUMMARY_LINE_PATTERN handles), so no done-marker is needed.
+ * An unmatched glyph simply ends the block, which is the safe direction: those
+ * rows go back to being handled exactly as they were before this guard existed.
+ *
+ * To widen this, capture a live pane that actually renders the new glyph and add
+ * it as a fixture. Do not widen it from the shape of the character.
+ */
+const CLAUDE_TASK_PANEL_ROW_PATTERN = /^\s*[◼◻]\s/;
+/**
+ * Line indices belonging to a Claude task panel within [start, end).
+ *
+ * Walks down from each header row for as long as rows keep looking like panel
+ * content (task rows or the collapsed `… +N …` summary). The first line that is
+ * neither ends the block, so a panel that abuts other content cannot swallow it.
+ *
+ * @param lines - Full frame, already ANSI/box stripped
+ * @param start - First index to consider (inclusive)
+ * @param end - Last index to consider (exclusive)
+ * @returns Indices Pass 2 must treat as metadata rather than options
+ */
+function findClaudeTaskPanelLines(lines, start, end) {
+    const panelLines = new Set();
+    for (let i = Math.max(0, start); i < Math.min(end, lines.length); i++) {
+        if (!CLAUDE_TASK_PANEL_HEADER_PATTERN.test(lines[i]))
+            continue;
+        panelLines.add(i);
+        for (let j = i + 1; j < Math.min(end, lines.length); j++) {
+            const row = lines[j];
+            if (!CLAUDE_TASK_PANEL_ROW_PATTERN.test(row) && !SUMMARY_LINE_PATTERN.test(row))
+                break;
+            panelLines.add(j);
+        }
+    }
+    return panelLines;
+}
 /**
  * Pattern for separator lines (horizontal rules).
  * Matches lines consisting only of dash (-) or em-dash (─) characters.
@@ -95,12 +183,17 @@ const COLLAPSED_OUTPUT_PATTERN = /^\s*\[[^\]]*\d+\s+lines?\]/i;
  *     `3. Show me more`) — those still flow through NORMAL_OPTION_PATTERN.
  *   - Optional leading ellipsis (… U+2026) and optional collapse direction
  *     marker (+ - ↑ ↓ ⏵ ⏷) accept the variants observed in the wild.
+ *   - [Issue #1708] `completed` joined `pending`/`more` after a live capture
+ *     (fixtures/claude-live-1708) showed the task panel collapsing FINISHED
+ *     rows as `… +2 completed`. That wording was outside the #704 guard, so it
+ *     reached Pass 2 and was collected as `option 2 / label='completed'` —
+ *     poisoning isValidPrecedingOption() exactly as `… +1 pending` used to.
  *   - The pattern deliberately omits any free `(.+)` capture — it must
  *     short-circuit, not extract data.
  *
  * Pattern shape: linear regex with no nested quantifiers — ReDoS safe (S4-001).
  */
-const SUMMARY_LINE_PATTERN = /^\s*[…]?\s*[+\-↑↓⏵⏷]?\s*\d+\s+(?:pending|more)\b/i;
+const SUMMARY_LINE_PATTERN = /^\s*[…]?\s*[+\-↑↓⏵⏷]?\s*\d+\s+(?:pending|more|completed)\b/i;
 /**
  * [Issue #704] Pattern for the Claude Code v2.1.142 prompt footer line.
  * Example: "  Esc to cancel · Tab to amend → · Herding…"
@@ -763,8 +856,19 @@ function detectMultipleChoicePrompt(output, options, truncateRawContentFn) {
     const collectedOptions = [];
     let questionEndIndex = -1;
     let continuationLineCount = 0;
+    // [Issue #1708] Claude's bottom-anchored task panel is an overlay, not part of
+    // the prompt frame. Resolved as a block up front because the reverse scan meets
+    // its rows before its header and so cannot recognise them one at a time.
+    const taskPanelLines = findClaudeTaskPanelLines(lines, scanStart, effectiveEnd);
     for (let i = effectiveEnd - 1; i >= scanStart; i--) {
         const line = lines[i].trim();
+        // [Issue #1708] Task-panel rows are metadata. Same handling as the
+        // COLLAPSED_OUTPUT / SUMMARY guards below: skip without ending the scan, so
+        // the options rendered ABOVE the panel are still reachable.
+        if (taskPanelLines.has(i)) {
+            continuationLineCount++;
+            continue;
+        }
         // Collapsed preview markers like "[… 12 lines] ctrl + a view all" are
         // metadata, not selectable options. Skip them before option parsing to
         // avoid misclassifying "12" as an option number.

package/dist/server/src/lib/detection/unclassified-frame-tracker.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Dwell tracking for interactive frames the detection layer could not classify
+ * (Issue #1708).
+ *
+ * `isUnclassifiedActive` is a per-poll observation: the frame looked interactive
+ * and nothing parsed it. A single true reading proves nothing — a capture taken
+ * mid-repaint produces one routinely — so the signal only becomes actionable
+ * once it has held for a while. This module owns that "for a while", and owns
+ * the once-per-run guard that keeps a stalled session from writing a history row
+ * on every poll.
+ *
+ * Deliberately free of I/O: the caller decides what to do with the verdict. The
+ * state is in-memory and per-process, matching the Auto-Yes prompt dedup it sits
+ * beside — a server restart re-arms the tracker, which costs at most one
+ * duplicate record and never a missed one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNCLASSIFIED_RECORD_DWELL_MS = void 0;
+exports.observeUnclassifiedFrame = observeUnclassifiedFrame;
+exports.resetUnclassifiedFrameTracking = resetUnclassifiedFrameTracking;
+exports.unclassifiedFrameRunCount = unclassifiedFrameRunCount;
+/**
+ * How long a frame must stay unclassified before it is worth recording.
+ *
+ * Matches UNCLASSIFIED_DWELL_MS in src/cli/commands/wait.ts on purpose: the row
+ * this produces is the audit trail for exactly the state `wait` reports as
+ * exit 10, and two different thresholds would leave one of them explaining a
+ * stall the other never saw.
+ */
+exports.UNCLASSIFIED_RECORD_DWELL_MS = 60_000;
+const runs = globalThis.__unclassifiedFrameRuns ??
+    (globalThis.__unclassifiedFrameRuns = new Map());
+/**
+ * How long an unobserved run survives before it is dropped.
+ *
+ * A run normally ends when its session reports a classified frame. It can also
+ * end by nobody ever asking again — the worktree was removed, the session was
+ * killed, the browser tab was closed. Nothing calls back to say so, so entries
+ * are aged out instead. Generous on purpose: it only has to be longer than any
+ * real polling gap, and an entry that is dropped early merely restarts the dwell
+ * for a session nobody is watching.
+ */
+const RUN_IDLE_TTL_MS = 60 * 60 * 1000;
+/** Drop runs nothing has reported on for {@link RUN_IDLE_TTL_MS}. */
+function pruneExpiredRuns(now) {
+    for (const [key, run] of runs) {
+        if (now - run.lastSeen > RUN_IDLE_TTL_MS)
+            runs.delete(key);
+    }
+}
+/**
+ * Fold one poll's `isUnclassifiedActive` reading into the run for `key`.
+ *
+ * @param key - Session identity; use the same composite key the pollers use
+ *   (worktree:cliTool:instance) so instances of one agent track separately
+ * @param isUnclassifiedActive - This poll's reading
+ * @param now - Epoch ms, injectable for tests
+ */
+function observeUnclassifiedFrame(key, isUnclassifiedActive, now = Date.now()) {
+    pruneExpiredRuns(now);
+    if (!isUnclassifiedActive) {
+        runs.delete(key);
+        return { dwellMs: 0, shouldRecord: false };
+    }
+    const run = runs.get(key);
+    if (!run) {
+        runs.set(key, { since: now, lastSeen: now, recorded: false });
+        return { dwellMs: 0, shouldRecord: false };
+    }
+    run.lastSeen = now;
+    // A clock that went backwards (NTP step) must not park the run at a dwell it
+    // can never work off; treat it as a fresh start instead.
+    const dwellMs = Math.max(0, now - run.since);
+    if (run.recorded || dwellMs < exports.UNCLASSIFIED_RECORD_DWELL_MS) {
+        return { dwellMs, shouldRecord: false };
+    }
+    run.recorded = true;
+    return { dwellMs, shouldRecord: true };
+}
+/**
+ * Forget tracking state.
+ *
+ * @param key - Session to forget; omit to clear every session (tests)
+ */
+function resetUnclassifiedFrameTracking(key) {
+    if (key === undefined) {
+        runs.clear();
+        return;
+    }
+    runs.delete(key);
+}
+/** Number of sessions currently being tracked. Test-only. @internal */
+function unclassifiedFrameRunCount() {
+    return runs.size;
+}

package/dist/server/src/lib/env.js

@@ -20,6 +20,7 @@ exports.getEnvByKey = getEnvByKey;
 exports.resetDatabasePathWarning = resetDatabasePathWarning;
 exports.getDatabasePathWithDeprecationWarning = getDatabasePathWithDeprecationWarning;
 exports.getLogConfig = getLogConfig;
+exports.getServerPort = getServerPort;
 exports.getEnv = getEnv;
 exports.validateEnv = validateEnv;
 const path_1 = __importDefault(require("path"));
@@ -141,6 +142,31 @@ function getLogConfig() {
         format: formatEnv === 'json' ? 'json' : 'text',
     };
 }
+/** Fallback port, shared by {@link getServerPort} and {@link getEnv}. */
+const DEFAULT_PORT = 3000;
+/**
+ * The port this server listens on, for callers that only need the port.
+ *
+ * Distinct from {@link getEnv} in two ways that matter to its users: it does no
+ * database-path resolution, and it never throws. Issue #1722 builds the hook
+ * endpoint URL baked into every injected Claude settings file from this, on the
+ * session-start path — where an unrelated `CM_DB_PATH` problem must not be able
+ * to prevent an agent from starting, and a nonsense `CM_PORT` should degrade to
+ * hooks pointing at the default port rather than to no session at all.
+ *
+ * @returns A port in [1, 65535]; {@link DEFAULT_PORT} when CM_PORT is unset or
+ *   unusable
+ */
+function getServerPort() {
+    const raw = getEnvByKey('CM_PORT');
+    if (!raw)
+        return DEFAULT_PORT;
+    const port = parseInt(raw, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        return DEFAULT_PORT;
+    }
+    return port;
+}
 /**
  * Get and validate environment variables (with fallback support)
  *
@@ -156,7 +182,7 @@ function getLogConfig() {
 function getEnv() {
     // Get raw values with defaults (using fallback support)
     const rootDir = getEnvByKey('CM_ROOT_DIR') || process.cwd();
-    const port = parseInt(getEnvByKey('CM_PORT') || '3000', 10);
+    const port = parseInt(getEnvByKey('CM_PORT') || String(DEFAULT_PORT), 10);
     const bind = getEnvByKey('CM_BIND') || '127.0.0.1';
     // Issue #135: DB path resolution with proper fallback chain
     // Priority: CM_DB_PATH > DATABASE_PATH (deprecated) > getDefaultDbPath()

package/dist/server/src/lib/hooks/agent-event-types.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * The vocabulary shared by the hook receiver, the injected settings generator
+ * and the in-memory session state (Issue #1722).
+ *
+ * Split out of `agent-event-service` so the pieces that only need the words —
+ * the settings generator, `lib/session/agent-event-state` — can have them
+ * without pulling in SQLite, the task state machine and the verification
+ * runner. `agent-event-service` re-exports everything here, so existing
+ * importers are unaffected.
+ *
+ * The mapping below is not derived from Claude Code's documentation. It is
+ * derived from the payloads in `tests/fixtures/hooks/claude/`, captured from a
+ * live v2.1.223 session in Issue #1721 and written up in
+ * `docs/design/agent-hooks-live-verification.md`. Where the two disagree, the
+ * fixtures win.
+ *
+ * @module lib/hooks/agent-event-types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_EVENT_DETAIL_LENGTH = exports.CLAUDE_HOOK_EVENT_NAMES = exports.AGENT_EVENT_TYPES = void 0;
+exports.isAgentEventType = isAgentEventType;
+exports.mapClaudeHookEventName = mapClaudeHookEventName;
+exports.extractClaudeEventDetail = extractClaudeEventDetail;
+/**
+ * Event kinds accepted by `POST /api/hooks/agent-event`.
+ *
+ * `stop` is the only one that moves anything. The rest are accepted, recorded
+ * and exposed for observation; wiring them into `sessionStatus` / `wait` /
+ * Auto-Yes is Issue #1723's job, deliberately kept separate so a change to the
+ * completion verdict is never a side effect of adding a receiver (#1549).
+ *
+ * `pre_tool_use` / `post_tool_use` (Issue #1726) are the two events received for
+ * a *specific* tool rather than for the session: the injected hooks carry
+ * `matcher: "AskUserQuestion"`, so they bracket the agent asking the human a
+ * question — the first carries the question and its options in `tool_input`, the
+ * second says the call is over. Both are observations; this receiver never
+ * answers either with a decision.
+ */
+exports.AGENT_EVENT_TYPES = [
+    'stop',
+    'notification',
+    'session_start',
+    'user_prompt_submit',
+    'session_end',
+    'pre_tool_use',
+    'post_tool_use',
+];
+function isAgentEventType(value) {
+    return typeof value === 'string' && exports.AGENT_EVENT_TYPES.includes(value);
+}
+/**
+ * Claude Code's own `hook_event_name` values, mapped onto the vocabulary above.
+ *
+ * An injected `type: "http"` hook posts Claude's payload verbatim — there is no
+ * way to shape the body — so the receiver has to read Claude's spelling. Only
+ * the events CommandMate injects are listed, and an unmapped name is refused
+ * rather than silently filed under something else.
+ *
+ * `PermissionRequest` is absent because it has its own receiver: its response
+ * body is a decision the agent obeys, which is the opposite contract to this
+ * fire-and-forget route (#1724).
+ *
+ * `PostToolUse` **is** mapped, on the strength of a measurement taken for Issue
+ * #1726 rather than of the #1721 spike, which recorded it as unobserved. Driving
+ * a live v2.1.223 session on 2026-08-06 with a `PostToolUse` hook registered:
+ *
+ * ```
+ * 15:36:04.112  PreToolUse   AskUserQuestion   (picker drawn)
+ * 15:36:10.127  Notification permission_prompt (picker still up)
+ * 15:36:28.643  PostToolUse  AskUserQuestion   (the human answered)
+ * 15:36:29.992  Stop
+ * ```
+ *
+ * It fires, and it is the precise signal — "this tool call is over" — where
+ * `Stop` is "the turn is over" and can be minutes later if the agent keeps
+ * working after the answer. Both are wired up; see `agent-event-state`.
+ */
+exports.CLAUDE_HOOK_EVENT_NAMES = {
+    Stop: 'stop',
+    SubagentStop: 'stop',
+    Notification: 'notification',
+    SessionStart: 'session_start',
+    SessionEnd: 'session_end',
+    UserPromptSubmit: 'user_prompt_submit',
+    // Issue #1726. Injected with matcher `AskUserQuestion`, so in practice these
+    // only ever arrive for that tool — but the receiver re-reads `tool_name`
+    // rather than trusting the matcher, because a user's own settings.json is
+    // concatenated with the injected one and may register a wider matcher.
+    PreToolUse: 'pre_tool_use',
+    PostToolUse: 'post_tool_use',
+};
+/** @returns The event this `hook_event_name` maps to, or null when unmapped. */
+function mapClaudeHookEventName(value) {
+    if (typeof value !== 'string')
+        return null;
+    return exports.CLAUDE_HOOK_EVENT_NAMES[value] ?? null;
+}
+/** Bound on the stored `detail`; every observed value is a short enum-ish word. */
+exports.MAX_EVENT_DETAIL_LENGTH = 128;
+/**
+ * The event's subtype, as a single short string, or null when it has none.
+ *
+ * Each event spells this differently and none of them share a field:
+ *
+ * - `Notification` → `notification_type` (`permission_prompt` / `idle_prompt`).
+ *   This is also what a `Notification` matcher is tested against — **not**
+ *   `message`, which is English prose for a human (D3).
+ * - `SessionEnd` → `reason` (`clear` / `prompt_input_exit` / …)
+ * - `SessionStart` → `source` (`startup` / `clear` / …)
+ * - `PreToolUse` / `PostToolUse` → `tool_name` (`AskUserQuestion`), Issue #1726
+ *
+ * `Stop` and `UserPromptSubmit` have no subtype, so they answer null.
+ */
+function extractClaudeEventDetail(event, payload) {
+    const field = event === 'notification'
+        ? 'notification_type'
+        : event === 'session_end'
+            ? 'reason'
+            : event === 'session_start'
+                ? 'source'
+                : event === 'pre_tool_use' || event === 'post_tool_use'
+                    ? 'tool_name'
+                    : null;
+    if (field === null)
+        return null;
+    const value = payload[field];
+    if (typeof value !== 'string' || value === '')
+        return null;
+    return value.slice(0, exports.MAX_EVENT_DETAIL_LENGTH);
+}

package/dist/server/src/lib/hooks/ask-user-question-payload.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Reading Claude Code's `AskUserQuestion` tool input (Issue #1726).
+ *
+ * The shape here is taken from the payloads the Issue #1721 spike captured from
+ * a live v2.1.223 session — `tests/fixtures/hooks/claude/`
+ * `pre-tool-use-ask-user-question.json` and
+ * `permission-request-ask-user-question.json` — not from documentation. Where
+ * the two disagree the fixtures win, and the fixtures are asserted against in
+ * `tests/unit/hooks/ask-user-question-payload.test.ts` so a Claude-side shape
+ * change fails a test instead of silently emptying the options.
+ *
+ * ```json
+ * { "hook_event_name": "PreToolUse", "tool_name": "AskUserQuestion",
+ *   "tool_input": { "questions": [
+ *     { "question": "…", "header": "Color", "multiSelect": false,
+ *       "options": [ { "label": "Blue", "description": "…" } ] } ] } }
+ * ```
+ *
+ * Two facts about the payload decide everything downstream:
+ *
+ *  - **`tool_use_id` is not a correlation key.** It is present on `PreToolUse`
+ *    and absent from `PermissionRequest` (D2), so nothing here reads it.
+ *    Correlation is (worktree, tool, instance) from the injected hook URL, which
+ *    is what every other structured state in this codebase is keyed by.
+ *  - **The payload describes the *questions*, not the *screen*.** The picker
+ *    renders these options and then appends its own ("Type something." / "Chat
+ *    about this"), and the final step replaces them entirely with "1. Submit
+ *    answers / 2. Cancel". Turning a payload into a set of answerable options is
+ *    therefore `lib/session/ask-user-question-prompt`'s job, not this module's.
+ *
+ * Parsing is strict, and every rejection degrades to the behaviour of a machine
+ * without this feature: `null` means "no structured options", which leaves the
+ * scraper's parsed prompt exactly as it was.
+ *
+ * @module lib/hooks/ask-user-question-payload
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ASK_USER_QUESTION_HEADER_LENGTH = exports.MAX_ASK_USER_QUESTION_DESCRIPTION_LENGTH = exports.MAX_ASK_USER_QUESTION_LABEL_LENGTH = exports.MAX_ASK_USER_QUESTION_TEXT_LENGTH = exports.MAX_ASK_USER_QUESTION_OPTIONS = exports.MAX_ASK_USER_QUESTIONS = void 0;
+exports.parseAskUserQuestionToolInput = parseAskUserQuestionToolInput;
+exports.parseAskUserQuestionPayload = parseAskUserQuestionPayload;
+const permission_request_payload_1 = require("./permission-request-payload");
+/** Cap on questions in one tool call. The observed payloads carry 1–3. */
+exports.MAX_ASK_USER_QUESTIONS = 20;
+/**
+ * Cap on options in one question.
+ *
+ * 20 is the same ceiling `prompt-detect-multiple-choice` puts on an option
+ * number, so a payload this module accepts can always be lined up against a
+ * screen the detector accepted.
+ */
+exports.MAX_ASK_USER_QUESTION_OPTIONS = 20;
+/** Bound on the question text; it is displayed and stored, never matched on. */
+exports.MAX_ASK_USER_QUESTION_TEXT_LENGTH = 1000;
+/** Bound on an option label. Labels are compared against screen text. */
+exports.MAX_ASK_USER_QUESTION_LABEL_LENGTH = 200;
+/** Bound on an option description — prose, shown under the label. */
+exports.MAX_ASK_USER_QUESTION_DESCRIPTION_LENGTH = 500;
+/** Bound on the tab header Claude renders for each question. */
+exports.MAX_ASK_USER_QUESTION_HEADER_LENGTH = 64;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readBoundedString(value, max) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    return trimmed.slice(0, max);
+}
+function parseChoice(value) {
+    if (!isPlainObject(value))
+        return null;
+    const label = readBoundedString(value.label, exports.MAX_ASK_USER_QUESTION_LABEL_LENGTH);
+    if (label === null)
+        return null;
+    return {
+        label,
+        description: readBoundedString(value.description, exports.MAX_ASK_USER_QUESTION_DESCRIPTION_LENGTH),
+    };
+}
+function parseEntry(value) {
+    if (!isPlainObject(value))
+        return null;
+    const question = readBoundedString(value.question, exports.MAX_ASK_USER_QUESTION_TEXT_LENGTH);
+    if (question === null)
+        return null;
+    if (!Array.isArray(value.options) || value.options.length === 0)
+        return null;
+    if (value.options.length > exports.MAX_ASK_USER_QUESTION_OPTIONS)
+        return null;
+    const choices = [];
+    for (const option of value.options) {
+        const choice = parseChoice(option);
+        // A question with an unreadable option is a question this server cannot
+        // line up against the screen by position, and position is the whole of the
+        // correspondence rule. Refuse the payload rather than shift the numbering.
+        if (choice === null)
+            return null;
+        choices.push(choice);
+    }
+    return {
+        question,
+        header: readBoundedString(value.header, exports.MAX_ASK_USER_QUESTION_HEADER_LENGTH),
+        multiSelect: value.multiSelect === true,
+        choices,
+    };
+}
+/**
+ * Parse the `questions` array out of an `AskUserQuestion` `tool_input`.
+ *
+ * @returns The questions, or null when the input is not one this server can
+ *   vouch for — which every caller must treat as "no structured options".
+ */
+function parseAskUserQuestionToolInput(toolInput) {
+    if (!isPlainObject(toolInput))
+        return null;
+    if (!Array.isArray(toolInput.questions) || toolInput.questions.length === 0)
+        return null;
+    if (toolInput.questions.length > exports.MAX_ASK_USER_QUESTIONS)
+        return null;
+    const questions = [];
+    for (const raw of toolInput.questions) {
+        const entry = parseEntry(raw);
+        if (entry === null)
+            return null;
+        questions.push(entry);
+    }
+    return questions;
+}
+/**
+ * Parse a hook body that may be an `AskUserQuestion` tool call.
+ *
+ * Accepts any `hook_event_name` — `PreToolUse` is what Issue #1726 injects, and
+ * `PermissionRequest` carries a byte-identical `tool_input` (§5.6), so both are
+ * usable evidence of the same call. What is checked is `tool_name`: a payload
+ * for any other tool answers null.
+ *
+ * @param body - Whatever was posted to a hook receiver
+ * @returns The spec, or null when this is not an `AskUserQuestion` call this
+ *   server can read.
+ */
+function parseAskUserQuestionPayload(body) {
+    if (!isPlainObject(body))
+        return null;
+    if (body.tool_name !== permission_request_payload_1.ASK_USER_QUESTION_TOOL)
+        return null;
+    const questions = parseAskUserQuestionToolInput(body.tool_input);
+    if (questions === null)
+        return null;
+    return {
+        questions,
+        promptId: readBoundedString(body.prompt_id, 256),
+    };
+}