commandmate 0.21.5 → 0.22.0

package/dist/server/src/lib/session/prompt-waiting-guard.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * "Is this session blocked on a prompt right now?" — the guard `send` consults
+ * before typing into a session (Issue #1708).
+ *
+ * A Claude/Codex prompt dialog does not forward keystrokes to the agent: text
+ * typed while one is open lands in the composer and sits there. Issue #1708's
+ * dispatch runner did exactly that — it read "no progress", sent a nudge, and
+ * left the session with a half-typed message queued underneath the dialog. The
+ * next `respond` then had to answer a prompt whose input line already contained
+ * someone else's text, which is how an "answer" can be delivered as a message.
+ *
+ * Refusing the send is the only thing that keeps `respond` well defined.
+ *
+ * Consulted from {@link sendUserMessage}, which is the choke point for every
+ * path that types a message at an agent — the send API and the timer manager.
+ * Putting it in the route instead would have left scheduled timer sends firing
+ * into open dialogs. The answer paths (`respond`, `special-keys`,
+ * `prompt-response`) do not go through that function, which is what keeps them
+ * open by construction rather than by remembering to exempt them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT_WAITING_CODE = void 0;
+exports.isPromptWaiting = isPromptWaiting;
+exports.promptWaitingMessage = promptWaitingMessage;
+const manager_1 = require("../../lib/cli-tools/manager");
+const cli_session_1 = require("../../lib/session/cli-session");
+const status_detector_1 = require("../../lib/detection/status-detector");
+const status_capture_config_1 = require("../../config/status-capture-config");
+const logger_1 = require("../../lib/logger");
+const prompt_waiting_composition_1 = require("../../lib/session/prompt-waiting-composition");
+const logger = (0, logger_1.createLogger)('prompt-waiting-guard');
+/** Stable machine-readable code for the refusal (HTTP body + CLI branching). */
+exports.PROMPT_WAITING_CODE = 'PROMPT_WAITING';
+/**
+ * Whether a send to this session would land in a prompt dialog's input line.
+ *
+ * Both layers are consulted, through the shared composition (Issue #1737). This
+ * function used to call `detectSessionStatus` and answer from it alone, which
+ * meant the OR rule #1725 established in `buildCurrentOutput` did not apply
+ * here: a dialog only the agent's own events could see — the #1708 shape
+ * exactly — was published as `isPromptWaiting: true` and still accepted sends.
+ * The composition now lives in one module and both callers read it, so there is
+ * no second answer to drift.
+ *
+ * The scraper's half is keyed off `hasActivePrompt` alone — the same signal the
+ * UI uses to render PromptPanel and `wait` uses to raise exit 10 — and
+ * deliberately NOT off `isSelectionListActive`. Arrow-key menus swallow text
+ * too, but they are also what Codex's pager and `/model` overlay look like, and
+ * refusing sends for those would block a legitimate message far more often than
+ * it would prevent a lost one. The asymmetry is the point: this guard only
+ * fires where the system already knows there is something to answer.
+ *
+ * Fail-open, in three places now rather than one. A capture that throws must
+ * not make the session unwritable — the cost of a missed guard is the pre-#1708
+ * behaviour, while the cost of a false refusal is a session nobody can talk to
+ * — and the structured layer is held to the same standard: its veto expires
+ * ({@link STRUCTURED_SEND_BLOCK_MAX_AGE_MS}), can be switched off for the server
+ * ({@link STRUCTURED_SEND_GUARD_ENV}), and can be waived for one send
+ * ({@link PromptWaitingOptions.ignoreStructured}). Note this makes the guard a
+ * best-effort narrowing, not a barrier: it is not, and must not be relied on as,
+ * a correctness guarantee that no text ever reaches an open dialog.
+ *
+ * @param worktreeId - Worktree whose session is being written to
+ * @param cliToolId - CLI tool driving that session
+ * @param instanceId - Agent instance, when not the primary one
+ * @param options - Per-call overrides; see {@link PromptWaitingOptions}
+ */
+async function isPromptWaiting(worktreeId, cliToolId, instanceId, options) {
+    try {
+        const cliTool = manager_1.CLIToolManager.getInstance().getTool(cliToolId);
+        if (!(await cliTool.isRunning(worktreeId, instanceId))) {
+            return { waiting: false };
+        }
+        const output = await (0, cli_session_1.captureSessionOutput)(worktreeId, cliToolId, status_capture_config_1.STATUS_CAPTURE_LINES, instanceId);
+        const status = (0, status_detector_1.detectSessionStatus)(output, cliToolId);
+        const resolution = (0, prompt_waiting_composition_1.resolvePromptWaiting)({
+            worktreeId,
+            cliToolId,
+            instanceId,
+            scraper: {
+                status: status.status,
+                reason: status.reason,
+                hasActivePrompt: status.hasActivePrompt,
+            },
+            ignoreStructured: options?.ignoreStructured,
+        });
+        if (!resolution.blocksSend) {
+            // A record that saw a dialog and was not allowed to act on it is the
+            // fail-open path this Issue added, so it says so out loud. Silence here
+            // would make "the guard did not fire" indistinguishable from "there was
+            // nothing to fire on", which is the pair an operator needs to tell apart.
+            if (resolution.structuredSendBlockSuppressed !== null) {
+                logger.info('structured-send-guard-not-applied', {
+                    worktreeId,
+                    cliToolId,
+                    instanceId,
+                    suppressed: resolution.structuredSendBlockSuppressed,
+                    promptWaitingSince: resolution.structured?.at ?? null,
+                });
+            }
+            return { waiting: false };
+        }
+        return {
+            waiting: true,
+            reason: resolution.blockReason ?? undefined,
+            blockedBy: resolution.blockedBy ?? undefined,
+        };
+    }
+    catch (error) {
+        logger.warn('prompt-waiting-check-failed', {
+            worktreeId,
+            cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { waiting: false };
+    }
+}
+/**
+ * The refusal message. Shared so the HTTP body and the CLI's stderr say the same
+ * thing — an operator who hits this in one surface should recognise it in the other.
+ *
+ * A structured-only refusal gets an extra sentence (Issue #1737), because the
+ * two refusals put the operator in different places. When the scraper saw the
+ * dialog, it is on screen and `respond` answers it. When only the agent's
+ * events saw it, the pane may look perfectly ordinary — and the instruction
+ * "answer the prompt" is then advice about a prompt the operator cannot find.
+ * That is precisely the state where a guard turns into an outage, so the message
+ * has to name the way past it and how long it lasts if they do nothing.
+ *
+ * @param blockedBy - Which layer refused; omitted callers get the plain message
+ */
+function promptWaitingMessage(worktreeId, blockedBy) {
+    const base = `${worktreeId} is waiting on a prompt. Sending now would type into the ` +
+        `prompt's input line instead of reaching the agent, and would leave that ` +
+        `text in place for the next answer. Answer the prompt first: ` +
+        `\`commandmate respond ${worktreeId} <answer>\`.`;
+    if (blockedBy !== 'structured')
+        return base;
+    const ttlMinutes = Math.round(prompt_waiting_composition_1.STRUCTURED_SEND_BLOCK_MAX_AGE_MS / 60_000);
+    return (`${base} This dialog was reported by the agent's own hooks and is not ` +
+        `visible to the terminal scraper, so if the pane looks idle the record has ` +
+        `outlived its dialog: it stops blocking sends ${ttlMinutes} minutes after ` +
+        `it was reported, or immediately with ` +
+        `\`commandmate send ${worktreeId} <message> --ignore-structured-prompt\` ` +
+        `(server-wide: ${prompt_waiting_composition_1.STRUCTURED_SEND_GUARD_ENV}=off).`);
+}

package/dist/server/src/lib/session/send-user-message.js

@@ -33,6 +33,7 @@ const assistant_response_saver_1 = require("../../lib/assistant-response-saver")
 const tmux_1 = require("../../lib/tmux/tmux");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
 const logger_1 = require("../../lib/logger");
+const prompt_waiting_guard_1 = require("../../lib/session/prompt-waiting-guard");
 const copilot_constants_1 = require("../../config/copilot-constants");
 const logger = (0, logger_1.createLogger)('session/send-user-message');
 function getErrorMessage(error) {
@@ -49,6 +50,40 @@ async function sendUserMessage(db, params) {
     const { worktreeId, content, cliToolId, instanceId, absoluteImagePath, copilotModel } = params;
     const messageType = params.messageType ?? 'normal';
     const cliTool = manager_1.CLIToolManager.getInstance().getTool(cliToolId);
+    // Issue #1708: refuse before the first side effect. A prompt dialog does not
+    // forward keystrokes to the agent — they accumulate in its own input line — so
+    // the message is lost AND the next `respond` has to answer a prompt whose
+    // input already holds someone else's text, which is how an answer gets
+    // delivered as a message.
+    //
+    // The guard lives HERE rather than in the send route because this function is
+    // the choke point for every path that types a message at an agent: the route
+    // and the timer manager (src/lib/timer-manager.ts, which calls it directly and
+    // would otherwise fire straight into an open dialog on schedule). The answer
+    // paths — `respond`, `special-keys`, `prompt-response` — do not go through
+    // here at all, which is what keeps them open; they are the only way out of
+    // this state and blocking them would strand the session.
+    //
+    // Issue #1737: the check consults the structured layer as well, through the
+    // same composition the current-output payload publishes. Before that it asked
+    // the scraper alone, so a dialog only the agent's hooks could see — the exact
+    // gap #1725 closed for the payload — was still sent into.
+    const promptGuard = await (0, prompt_waiting_guard_1.isPromptWaiting)(worktreeId, cliToolId, instanceId, {
+        ignoreStructured: params.ignoreStructuredPromptGuard,
+    });
+    if (promptGuard.waiting) {
+        logger.info('send-refused-prompt-waiting', {
+            worktreeId,
+            cliToolId,
+            reason: promptGuard.reason,
+            blockedBy: promptGuard.blockedBy,
+        });
+        return {
+            ok: false,
+            stage: 'prompt_waiting',
+            error: (0, prompt_waiting_guard_1.promptWaitingMessage)(worktreeId, promptGuard.blockedBy),
+        };
+    }
     // Generate the user-message timestamp BEFORE saving the pending response so
     // ordering holds: assistantResponse < userMessage.
     const userMessageTimestamp = new Date();

package/dist/server/src/lib/session/status-mapping.js

@@ -10,6 +10,7 @@
  * | `BranchStatus`      | `types/sidebar.ts`                  | idle / ready / running / waiting / generating |
  * | boolean triple      | `lib/session/worktree-status-helper.ts` | isRunning / isWaitingForResponse / isProcessing |
  * | `UIPhase`           | `types/ui-state.ts`                 | idle / waiting / receiving / prompt / complete |
+ * | `AgentEventType`    | `lib/hooks/agent-event-types.ts`    | stop / notification / session_start / …   |
  *
  * This module is the single place where those vocabularies are converted into
  * one another, so the correspondence cannot drift between call sites. It is a
@@ -21,6 +22,8 @@
  *   terminal output
  *     -> detectSessionStatus()                  (status-detector, NOT touched here)
  *     -> SessionStatus
+ *     -> [merged with agentEventToSessionStatus() in current-output-builder]
+ *
  *     -> sessionStatusToActivityFlags()         (this module)
  *     -> boolean triple (+ isRunning from tmux session existence)
  *     -> deriveCliStatus()                      (this module)
@@ -41,10 +44,128 @@
  * with no second call site, so the reducer stays the single owner.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_STATUS_REASON = void 0;
+exports.agentEventToSessionStatus = agentEventToSessionStatus;
 exports.sessionStatusToActivityFlags = sessionStatusToActivityFlags;
 exports.deriveCliStatus = deriveCliStatus;
 exports.deriveSessionStatus = deriveSessionStatus;
 exports.deriveBranchStatus = deriveBranchStatus;
+/**
+ * `sessionStatusReason` values produced by the structured-event layer
+ * (Issue #1723), as opposed to `STATUS_REASON` which is the scraper's.
+ *
+ * They are deliberately prefixed: a reader of a payload, a log line or a
+ * `commandmate capture --json` must be able to tell at a glance which of the two
+ * detection layers decided, because the whole point of the two-layer split is
+ * being able to measure how often they disagree.
+ */
+exports.HOOK_STATUS_REASON = {
+    /** The agent reported it began a turn (`UserPromptSubmit`). */
+    PROMPT_SUBMIT: 'hook_prompt_submit',
+    /** The agent reported the turn ended (`Stop` / `SubagentStop`). */
+    STOP: 'hook_stop',
+    /** `Notification(permission_prompt)` — the agent says a dialog is on screen. */
+    PERMISSION_PROMPT: 'hook_permission_prompt',
+    /**
+     * A `PermissionRequest` this server declined to decide (Issue #1725).
+     *
+     * Distinct from {@link PERMISSION_PROMPT} because the two are different kinds
+     * of evidence, and an operator reading a payload or a log has to be able to
+     * tell them apart: the notification is proof a dialog exists, this one is the
+     * prediction that one is about to. Only the prediction expires unaided.
+     */
+    PERMISSION_REQUEST: 'hook_permission_request',
+    /** `Notification(idle_prompt)` — the agent says it is sitting at the composer. */
+    IDLE_PROMPT: 'hook_idle_prompt',
+    /**
+     * `PreToolUse` — the agent reported it is invoking a tool (Issue #1726).
+     *
+     * A turn in progress, and nothing more. It is deliberately NOT `waiting` even
+     * though the only matcher injected for it is `AskUserQuestion`: whether that
+     * picker is on screen is the scraper's question (§5.6 measured that Claude
+     * emits nothing at all while it is up), and asserting `waiting` from a
+     * pre-invocation event would keep asserting it long after a human answered in
+     * the terminal, because no event marks that.
+     */
+    PRE_TOOL_USE: 'hook_pre_tool_use',
+    /**
+     * `PostToolUse` — the agent reported a tool call finished (Issue #1726).
+     *
+     * `running` like its `PreToolUse` counterpart, and for the same reason: a tool
+     * finishing is not a turn finishing. `Stop` is what says the turn ended, and
+     * it followed this by 1.3 s in the live capture.
+     */
+    POST_TOOL_USE: 'hook_post_tool_use',
+};
+/**
+ * The structured state machine: last lifecycle event -> `SessionStatus`
+ * (Issue #1723).
+ *
+ * Pure and total, so the whole table can be read in one place:
+ *
+ * | event                            | verdict            |
+ * |----------------------------------|--------------------|
+ * | `user_prompt_submit`             | `running`          |
+ * | `stop`                           | `ready`            |
+ * | `pre_tool_use`                   | `running`          |
+ * | `post_tool_use`                  | `running`          |
+ * | `notification(permission_prompt)`| `waiting`          |
+ * | `notification(idle_prompt)`      | `ready`            |
+ * | `notification(other/none)`       | none (scraper)     |
+ * | `session_start`                  | none (scraper)     |
+ * | `session_end`                    | none (scraper)     |
+ *
+ * `pre_tool_use` answers `running` for the same reason `user_prompt_submit`
+ * does: the agent is mid-turn. It has to answer *something*, because this table
+ * reads only the newest event — answering "none" would mean an `AskUserQuestion`
+ * invocation erased the `running` its own turn's `user_prompt_submit` had
+ * established, and a scraper that reads the picker as `ready`/`no_recent_output`
+ * (which is exactly the #1708 failure) would then let `commandmate wait` exit 0
+ * on a session with a dialog in front of it. `running` never overrides a scraper
+ * `waiting`, so promoting it costs nothing where the screen can be read.
+ *
+ * `session_start` answering "none" is not an oversight, it is a requirement.
+ * A folder that has not been trusted yet shows its trust dialog *before* any
+ * hook fires — 25.3 seconds of complete silence in the live capture
+ * (`docs/design/agent-hooks-live-verification.md` §5.6) — so the arrival of
+ * `SessionStart` cannot be used as "the session is up", and its absence cannot
+ * be used as "it is not". What `session_start` does do is start a new
+ * generation; that belongs to `agent-event-state`, not to this table.
+ *
+ * `session_end` answers none because the state is discarded, not because the
+ * session is idle: `/clear` emits `SessionEnd(reason=clear)` on a session that
+ * is alive and about to keep going (§1.1).
+ *
+ * @param detail - The event's subtype, for the events that have one
+ */
+function agentEventToSessionStatus(event, detail) {
+    switch (event) {
+        case 'user_prompt_submit':
+            return { status: 'running', reason: exports.HOOK_STATUS_REASON.PROMPT_SUBMIT };
+        case 'pre_tool_use':
+            return { status: 'running', reason: exports.HOOK_STATUS_REASON.PRE_TOOL_USE };
+        case 'post_tool_use':
+            return { status: 'running', reason: exports.HOOK_STATUS_REASON.POST_TOOL_USE };
+        case 'stop':
+            return { status: 'ready', reason: exports.HOOK_STATUS_REASON.STOP };
+        case 'notification':
+            // Matched on `notification_type`, never on the human-facing `message` (D3).
+            if (detail === 'permission_prompt') {
+                return { status: 'waiting', reason: exports.HOOK_STATUS_REASON.PERMISSION_PROMPT };
+            }
+            if (detail === 'idle_prompt') {
+                return { status: 'ready', reason: exports.HOOK_STATUS_REASON.IDLE_PROMPT };
+            }
+            return null;
+        case 'session_start':
+        case 'session_end':
+            return null;
+        default:
+            // exhaustive check: AgentEventType extensions cause a compile error
+            event;
+            return null;
+    }
+}
 /**
  * Project a detected `SessionStatus` onto the activity flags.
  *

package/dist/server/src/lib/session/structured-prompt.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * The prompt the structured layer publishes for a dialog nobody could parse
+ * (Issue #1725).
+ *
+ * `Notification(notification_type=permission_prompt)` tells us a dialog is on
+ * screen; it does not tell us what is in it. The live capture (#1721 §5.5)
+ * measured the whole payload: a `message` written for a human
+ * (`"Claude needs your permission to use Bash"`), a `notification_type`, and
+ * nothing resembling the options the dialog is offering. So the fact the
+ * structured layer can contribute is "a human has to act", and the shape below
+ * is that fact and no more — a question, no options, and the agent's own line
+ * kept verbatim for display.
+ *
+ * ## Why `type` is `unclassified` rather than a new prompt type
+ *
+ * `UNCLASSIFIED_PROMPT_TYPE` already means exactly this to every reader that
+ * matters: `commandmate wait` reports it as the kind of exit 10 that nobody can
+ * answer programmatically (#1708), `capture --prompts` renders it as its own
+ * state instead of a pending prompt, and PromptPanel now degrades on it. Adding
+ * a second word for "we know it is there, we cannot read it" would oblige each
+ * of them to learn both. It is deliberately NOT a member of `PromptType` —
+ * widening that union would force every exhaustive map over it (the contract
+ * parser's promptType allowlist among them) to grow a case for a value no
+ * prompt-answering path may accept. See the note on `UNCLASSIFIED_PROMPT_TYPE`
+ * in `types/models.ts`.
+ *
+ * ## Pure on purpose
+ *
+ * Type-only imports and string building, exactly like `status-mapping`, so a
+ * client component can import it: `PromptPanel`'s prop type widens to include
+ * {@link StructuredPromptWaitingData} and it must be able to name the type.
+ *
+ * @module lib/session/structured-prompt
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH = void 0;
+exports.buildStructuredPromptQuestion = buildStructuredPromptQuestion;
+exports.buildStructuredPromptData = buildStructuredPromptData;
+exports.buildStructuredPromptHistoryRecord = buildStructuredPromptHistoryRecord;
+exports.isStructuredPromptWaitingData = isStructuredPromptWaitingData;
+const models_1 = require("../../types/models");
+/** Bound on the agent's `message`, which is prose and only ever displayed. */
+exports.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH = 500;
+/** How each source reads in the one-line question. */
+const SOURCE_LABEL = {
+    notification: 'Notification(permission_prompt)',
+    'permission-request': 'PermissionRequest (no decision)',
+};
+/**
+ * The one line every surface shows for a structured prompt.
+ *
+ * It names the option NUMBER on purpose. `respond <id> yes` is not resolved
+ * semantically on a numbered dialog — Enter takes the highlighted default
+ * instead, so a "no" can be delivered as an approval (Issue #1681). This text
+ * is the only guidance a caller of `wait` gets, so it has to say which form
+ * actually works.
+ */
+function buildStructuredPromptQuestion(worktreeId, facts) {
+    const parts = [
+        `A dialog is open in ${worktreeId}: the agent reported it via ${SOURCE_LABEL[facts.source]}` +
+            `${facts.toolName ? ` for ${facts.toolName}` : ''}, but the detection layer published no ` +
+            `options for it.`,
+        `Answer it in the terminal, or send the option NUMBER with ` +
+            `\`commandmate respond ${worktreeId} <number>\` — yes/no is not resolved on a numbered ` +
+            `dialog (Issue #1681).`,
+    ];
+    if (facts.message) {
+        parts.push(`Agent message: "${facts.message}"`);
+    }
+    if (facts.askUserQuestion) {
+        const { question, labels, questionCount } = facts.askUserQuestion;
+        parts.push(`The agent asked${questionCount > 1 ? ` ${questionCount} questions, the first being` : ''}: ` +
+            `"${question}" — offering: ${labels.join(' / ')}. ` +
+            `The picker renumbers and adds its own entries, so read the option NUMBER off the ` +
+            `terminal rather than counting this list.`);
+    }
+    return parts.join(' ');
+}
+/** The live `promptData` for a structured prompt. */
+function buildStructuredPromptData(worktreeId, facts) {
+    return {
+        type: models_1.UNCLASSIFIED_PROMPT_TYPE,
+        status: 'pending',
+        question: buildStructuredPromptQuestion(worktreeId, facts),
+        options: [],
+        source: facts.source,
+        ...(facts.message ? { message: facts.message } : {}),
+        ...(facts.toolName ? { toolName: facts.toolName } : {}),
+        ...(facts.askUserQuestion ? { askUserQuestion: facts.askUserQuestion } : {}),
+    };
+}
+/** The prompt-history row for a structured prompt the scraper never saw. */
+function buildStructuredPromptHistoryRecord(worktreeId, facts) {
+    return {
+        type: models_1.UNCLASSIFIED_PROMPT_TYPE,
+        status: 'unclassified',
+        question: buildStructuredPromptQuestion(worktreeId, facts),
+        options: [],
+        source: facts.source,
+        ...(facts.message ? { message: facts.message } : {}),
+        ...(facts.toolName ? { toolName: facts.toolName } : {}),
+        ...(facts.askUserQuestion ? { askUserQuestion: facts.askUserQuestion } : {}),
+    };
+}
+/** Whether this prompt payload is the degraded structured form. */
+function isStructuredPromptWaitingData(value) {
+    return value?.type === models_1.UNCLASSIFIED_PROMPT_TYPE;
+}

package/dist/server/src/types/models.js

@@ -3,7 +3,9 @@
  * Data models for myCodeBranchDesk
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNCLASSIFIED_PROMPT_TYPE = void 0;
 exports.isValidSubmitMode = isValidSubmitMode;
+exports.isAnswerablePromptData = isAnswerablePromptData;
 /**
  * Type guard for SubmitMode values.
  * Validates that a string is a valid SubmitMode ('answer_only' or 'answer_then_enter').
@@ -13,3 +15,31 @@ exports.isValidSubmitMode = isValidSubmitMode;
 function isValidSubmitMode(value) {
     return value === 'answer_only' || value === 'answer_then_enter';
 }
+/**
+ * `promptData.type` written for an interactive frame nothing could classify.
+ *
+ * Deliberately NOT a member of {@link PromptType}: the detectors can never
+ * produce it, and widening that union would oblige every exhaustive map over it
+ * (the contract parser's promptType allowlist among them) to grow a case for a
+ * value no prompt-answering path is allowed to accept. Readers compare against
+ * this constant instead.
+ */
+exports.UNCLASSIFIED_PROMPT_TYPE = 'unclassified';
+/**
+ * Narrow a prompt payload to the answerable {@link PromptData} union.
+ *
+ * The one branch every reader of {@link LivePromptData} / {@link
+ * StoredPromptData} needs, defined once: `true` means the options, the default
+ * and `answer` are meaningful and the value may be answered by option number;
+ * `false` narrows to the degraded form, which by construction carries none of
+ * them. Both directions come out of this single predicate so no call site has
+ * to re-derive "is `type` the unclassified sentinel?" for itself.
+ *
+ * Deliberately not `isStructuredPromptWaitingData` from
+ * `lib/session/structured-prompt`: that one asserts the *live* degraded shape,
+ * which would be unsound over {@link StoredPromptData}, whose degraded members
+ * share its `type` but not its `status`/`source`.
+ */
+function isAnswerablePromptData(value) {
+    return value != null && value.type !== exports.UNCLASSIFIED_PROMPT_TYPE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.21.5",
+  "version": "0.22.0",
   "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
   "keywords": [
     "claude-code",
@@ -54,7 +54,8 @@
     "test:watch": "NODE_ENV=test vitest --watch",
     "db:init": "tsx scripts/init-db.ts",
     "db:reset": "rm -f db.sqlite && npm run db:init",
-    "catalog:refresh": "tsx scripts/refresh-slash-command-catalog.ts"
+    "catalog:refresh": "tsx scripts/refresh-slash-command-catalog.ts",
+    "canary": "tsx scripts/canary/index.ts"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",

package/scripts/hooks/cmate-agent-event.sh

@@ -23,9 +23,12 @@ Usage: cmate-agent-event.sh [options] [JSON]
 
 Options:
   --tool ID          Agent CLI id (default: $CM_AGENT_TOOL, else "claude")
-  --event EVENT      stop | notification | session_start (default: "stop")
+  --event EVENT      stop | notification | session_start | user_prompt_submit |
+                     session_end (default: "stop")
   --cwd PATH         Agent working directory (default: $CLAUDE_PROJECT_DIR, else $PWD)
   --session-id ID    Opaque agent session id
+  --worktree-id ID   CommandMate worktree id; skips cwd-based resolution
+  --instance-id ID   Agent instance id; without it the event lands on the primary
   --json JSON        Hook payload to read cwd/session/event from
   --stdin-json       Read that payload from stdin instead
   --url URL          Endpoint (default: http://$CM_HOST:$CM_PORT/api/hooks/agent-event)
@@ -63,6 +66,20 @@ map_event_name() {
     Stop|SubagentStop|agent-turn-complete) printf 'stop' ;;
     Notification) printf 'notification' ;;
     SessionStart) printf 'session_start' ;;
+    SessionEnd) printf 'session_end' ;;
+    UserPromptSubmit) printf 'user_prompt_submit' ;;
+    *) printf '' ;;
+  esac
+}
+
+# The event's subtype, where it has one. Each event spells it differently and
+# none of them share a field. Notification is judged on notification_type, never
+# on the human-facing "message" (Issue #1721, D3).
+detail_field_for_event() {
+  case "$1" in
+    notification) printf 'notification_type' ;;
+    session_end) printf 'reason' ;;
+    session_start) printf 'source' ;;
     *) printf '' ;;
   esac
 }
@@ -71,6 +88,9 @@ TOOL="${CM_AGENT_TOOL:-claude}"
 EVENT=""
 CWD=""
 SESSION_ID=""
+WORKTREE_ID=""
+INSTANCE_ID=""
+DETAIL=""
 HOOK_JSON=""
 READ_STDIN=0
 URL="${CM_HOOK_URL:-}"
@@ -82,6 +102,8 @@ while [ $# -gt 0 ]; do
     --event) [ $# -ge 2 ] || die "--event requires a value"; EVENT="$2"; shift 2 ;;
     --cwd) [ $# -ge 2 ] || die "--cwd requires a value"; CWD="$2"; shift 2 ;;
     --session-id) [ $# -ge 2 ] || die "--session-id requires a value"; SESSION_ID="$2"; shift 2 ;;
+    --worktree-id) [ $# -ge 2 ] || die "--worktree-id requires a value"; WORKTREE_ID="$2"; shift 2 ;;
+    --instance-id) [ $# -ge 2 ] || die "--instance-id requires a value"; INSTANCE_ID="$2"; shift 2 ;;
     --json) [ $# -ge 2 ] || die "--json requires a value"; HOOK_JSON="$2"; shift 2 ;;
     --url) [ $# -ge 2 ] || die "--url requires a value"; URL="$2"; shift 2 ;;
     --stdin-json) READ_STDIN=1; shift ;;
@@ -120,10 +142,17 @@ fi
 [ -n "$EVENT" ] || EVENT="stop"
 
 case "$EVENT" in
-  stop|notification|session_start) ;;
-  *) die "--event must be one of: stop, notification, session_start (got \"$EVENT\")" ;;
+  stop|notification|session_start|user_prompt_submit|session_end) ;;
+  *) die "--event must be one of: stop, notification, session_start, user_prompt_submit, session_end (got \"$EVENT\")" ;;
 esac
 
+if [ -z "$DETAIL" ] && [ -n "$HOOK_JSON" ]; then
+  DETAIL_FIELD="$(detail_field_for_event "$EVENT")"
+  if [ -n "$DETAIL_FIELD" ]; then
+    DETAIL="$(json_string_field "$HOOK_JSON" "$DETAIL_FIELD")"
+  fi
+fi
+
 [ -n "$TOOL" ] || die "--tool must not be empty"
 
 if [ -z "$CWD" ]; then
@@ -154,6 +183,18 @@ BODY="$BODY,\"cwd\":\"$(json_escape "$CWD")\""
 if [ -n "$SESSION_ID" ]; then
   BODY="$BODY,\"sessionId\":\"$(json_escape "$SESSION_ID")\""
 fi
+# Correlation keys are omitted when unset rather than sent empty: the receiver
+# falls back to resolving the worktree from cwd and to the primary instance,
+# which is exactly what a hand-configured hook from Issue #1549 wants.
+if [ -n "$WORKTREE_ID" ]; then
+  BODY="$BODY,\"worktreeId\":\"$(json_escape "$WORKTREE_ID")\""
+fi
+if [ -n "$INSTANCE_ID" ]; then
+  BODY="$BODY,\"instanceId\":\"$(json_escape "$INSTANCE_ID")\""
+fi
+if [ -n "$DETAIL" ]; then
+  BODY="$BODY,\"detail\":\"$(json_escape "$DETAIL")\""
+fi
 BODY="$BODY}"
 
 # Token via --header rather than the command line of a subprocess: argv is world