commandmate 0.22.1 → 0.23.0

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

@@ -9,19 +9,18 @@
  * 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.
+ * **Nothing here names a tool.** It used to: `CLAUDE_HOOK_EVENT_NAMES` and
+ * `extractClaudeEventDetail` lived beside the words until Issue #1759 moved
+ * them to `lib/hooks/sources/hook-event-vocabulary`, where a source *selects*
+ * them. One tool's spellings sitting in the module every tool-agnostic consumer
+ * imports is how the next tool ends up appended to the same table instead of
+ * bringing its own — the copy-paste Epic #1720 exists to stop.
  *
  * @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.MAX_EVENT_DETAIL_LENGTH = exports.AGENT_EVENT_TYPES = void 0;
 exports.isAgentEventType = isAgentEventType;
-exports.mapClaudeHookEventName = mapClaudeHookEventName;
-exports.extractClaudeEventDetail = extractClaudeEventDetail;
 /**
  * Event kinds accepted by `POST /api/hooks/agent-event`.
  *
@@ -49,83 +48,5 @@ exports.AGENT_EVENT_TYPES = [
 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/hook-settings-generator.js

@@ -28,6 +28,12 @@
  *  - **Every hook failure is fail-open.** A refused connection or a timeout
  *    costs the event, never the session.
  *
+ * Issue #1759 made this module *Claude's* config serialiser rather than *the*
+ * config serialiser: it is reached through `claudeAgentEventSource.prepareLaunch`
+ * (seams S3/S4/S5), and the four other hook tools each bring their own — their
+ * files live in different places, nest differently, and cannot use `type:"http"`
+ * at all. Nothing here changed; only who calls it did.
+ *
  * The generated file is written rather than passed inline. `--settings` does
  * accept a JSON string (D2), but the launch command travels to the CLI through
  * `tmux send-keys` as a single line, and a ~1 KB argument of braces, quotes and
@@ -55,8 +61,10 @@ const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const safe_directory_1 = require("../../config/safe-directory");
 const env_1 = require("../../lib/env");
 const types_1 = require("../../lib/cli-tools/types");
+const tool_id_1 = require("../../lib/hooks/sources/claude/tool-id");
 const permission_request_payload_1 = require("../../lib/hooks/permission-request-payload");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('lib/hooks/hook-settings-generator');
@@ -178,18 +186,25 @@ function isHookInjectionEnabled() {
 function isAuthTokenExpected() {
     return Boolean(process.env[exports.AUTH_TOKEN_ENV_VAR] || process.env.CM_AUTH_TOKEN_HASH);
 }
-/** Directory the generated settings files live in. */
+/**
+ * Directory the generated settings files live in.
+ *
+ * Issue #1774: `writeAgentHookSettings` calls `mkdirSync(…, {recursive:true})`
+ * on the result, so a value inside `/proc`, `/sys` or `/dev` would spin the
+ * event loop forever rather than throw — the fail-open `try/catch` below is
+ * never reached, because the call never returns. Such a value is refused here
+ * and the default is used.
+ */
 function getHookSettingsDirectory(options = {}) {
-    if (options.directory)
-        return options.directory;
-    const override = process.env.CM_AGENT_HOOKS_DIR;
-    if (override)
-        return override;
-    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'hooks');
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'hooks');
+    if (options.directory) {
+        return (0, safe_directory_1.resolveSafeDirectory)(options.directory, fallback, 'HookSettingsOptions.directory');
+    }
+    return (0, safe_directory_1.resolveSafeDirectory)(process.env.CM_AGENT_HOOKS_DIR, fallback, 'CM_AGENT_HOOKS_DIR');
 }
 /** The instance this settings file speaks for; primary when unspecified. */
 function resolveTargetInstanceId(target) {
-    const cliToolId = target.cliToolId ?? 'claude';
+    const cliToolId = target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID;
     const instanceId = target.instanceId ?? cliToolId;
     return instanceId;
 }
@@ -202,7 +217,7 @@ function resolveTargetInstanceId(target) {
  * restart overwrites rather than accumulates.
  */
 function getHookSettingsPath(target, options = {}) {
-    const cliToolId = target.cliToolId ?? 'claude';
+    const cliToolId = target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID;
     const instanceId = resolveTargetInstanceId(target);
     const slug = `${cliToolId}-${target.worktreeId}-${instanceId}`.replace(/[^a-zA-Z0-9_-]/g, '_');
     const digest = (0, crypto_1.createHash)('sha256')
@@ -236,7 +251,7 @@ function buildPermissionRequestUrl(target, options = {}) {
     return buildReceiverUrl(exports.PERMISSION_REQUEST_PATH, target, options);
 }
 function buildReceiverUrl(path, target, options) {
-    const cliToolId = target.cliToolId ?? 'claude';
+    const cliToolId = target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID;
     const port = options.port ?? (0, env_1.getServerPort)();
     const params = new URLSearchParams({
         tool: cliToolId,
@@ -285,7 +300,7 @@ function buildSessionStartCommand(target, options = {}) {
         return [
             shellQuote(relay),
             '--tool',
-            shellQuote(target.cliToolId ?? 'claude'),
+            shellQuote(target.cliToolId ?? tool_id_1.CLAUDE_CLI_TOOL_ID),
             '--event',
             'session_start',
             '--worktree-id',

package/dist/server/src/lib/hooks/permission-decision-service.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * Auto-Yes v2: adjudicating Claude's `PermissionRequest` hook (Issue #1724).
+ *
+ * Auto-Yes has always worked by reading the pane with a regex and injecting a
+ * keystroke. This module is the structured replacement: Claude asks *before*
+ * drawing the dialog, over HTTP, with the tool call attached, and the answer is
+ * a verdict rather than a key. Three bug families stop being possible rather
+ * than being fixed — a dialog the detectors cannot read (#1708) never has to be
+ * read, deny patterns cannot be poisoned by scrollback (#1699) because there is
+ * no scrollback in the input, and an overlay cannot be mistaken for a prompt
+ * (#1495) because nothing is typed anywhere.
+ *
+ * ## The safety rule
+ *
+ * **A wrong `allow` executes a command; a wrong no-decision costs a dialog.**
+ * Every branch that is not certain therefore returns no-decision, which the
+ * Issue #1721 spike measured (D5) as landing back in the ordinary TUI approval
+ * flow — the behaviour of a machine where this feature does not exist. Timeouts
+ * and refused connections are fail-open for the same reason (§1.1).
+ *
+ * `deny` is never returned. Today's Auto-Yes suppression means *"do not answer
+ * this"*, not *"refuse this"*, and a contract's `denyPatterns` is a rule about
+ * what may be auto-answered — not a rule about what the human may approve.
+ * Turning suppression into a `Denied by PermissionRequest hook` would change the
+ * meaning of every existing contract in the field.
+ *
+ * ## Why the verdict is computed as a `multiple_choice`
+ *
+ * The dialog this hook pre-empts is detected on screen as a `multiple_choice`
+ * prompt ("Do you want to proceed? / 1. Yes / 2. Yes, and … / 3. No"). Feeding
+ * that same type into the shared policy evaluator is what stops the hook from
+ * being *more permissive* than the poller it front-runs: under `mode: safe` the
+ * screen path suppresses a permission dialog, so this one must too.
+ *
+ * @module lib/hooks/permission-decision-service
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSION_DECISION_SLOW_MS = exports.PERMISSION_REQUEST_PROMPT_TYPE = void 0;
+exports.decidePermissionRequest = decidePermissionRequest;
+exports.resolvePermissionRequest = resolvePermissionRequest;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const db_instance_1 = require("../../lib/db/db-instance");
+const chat_db_1 = require("../../lib/db/chat-db");
+const auto_yes_policy_1 = require("../../lib/polling/auto-yes-policy");
+const auto_yes_resolver_1 = require("../../lib/polling/auto-yes-resolver");
+const auto_yes_suppression_state_1 = require("../../lib/polling/auto-yes-suppression-state");
+const agent_event_state_1 = require("../../lib/session/agent-event-state");
+const logger_1 = require("../../lib/logger");
+const ask_user_question_payload_1 = require("./ask-user-question-payload");
+const permission_request_payload_1 = require("./permission-request-payload");
+const logger = (0, logger_1.createLogger)('lib/hooks/permission-decision-service');
+/**
+ * How the pre-empted dialog would have been classified on screen.
+ *
+ * Not cosmetic: it is what `mode: safe` (yes_no only) and `mode: allow-listed`
+ * are evaluated against, so the hook and the poller agree.
+ */
+exports.PERMISSION_REQUEST_PROMPT_TYPE = 'multiple_choice';
+/** Response time past which the hook is holding the agent up noticeably. */
+exports.PERMISSION_DECISION_SLOW_MS = 500;
+const NO_DECISION = (reason) => ({
+    behavior: null,
+    reason,
+});
+/**
+ * The verdict for one permission request. Pure apart from reading Auto-Yes
+ * state and the (TTL-cached) contract policy; the recording side effects live
+ * in {@link resolvePermissionRequest}.
+ *
+ * Order matters and mirrors the table in Issue #1724:
+ *
+ * | condition | verdict |
+ * |---|---|
+ * | payload unreadable | no-decision |
+ * | `AskUserQuestion` | no-decision |
+ * | Auto-Yes off / expired | no-decision |
+ * | policy suppresses (mode off, deny pattern, type) | no-decision + suppression |
+ * | otherwise | allow |
+ *
+ * @param session - Worktree / tool / instance the request came from
+ * @param payload - Parsed payload, or null when it could not be parsed
+ */
+function decidePermissionRequest(session, payload) {
+    if (!payload) {
+        return NO_DECISION('unknown-payload');
+    }
+    // Before the Auto-Yes check on purpose: this verdict must not depend on
+    // whether Auto-Yes happens to be on, so that turning Auto-Yes on can never
+    // start approving questions.
+    if (payload.toolName === permission_request_payload_1.ASK_USER_QUESTION_TOOL) {
+        return NO_DECISION('ask-user-question');
+    }
+    const { worktreeId, cliToolId, instanceId } = session;
+    // Returns null for "never enabled" and for expired (it disables on read), so
+    // the expiry boundary is the same one the poller sees.
+    const state = (0, auto_yes_state_1.getAutoYesState)(worktreeId, cliToolId, instanceId);
+    if (!state?.enabled) {
+        return NO_DECISION('auto-yes-disabled');
+    }
+    const policy = (0, auto_yes_policy_1.getSessionAutoYesPolicy)(worktreeId, cliToolId, instanceId);
+    const denial = (0, auto_yes_resolver_1.evaluatePolicyAgainstTexts)(exports.PERMISSION_REQUEST_PROMPT_TYPE, (0, permission_request_payload_1.collectToolInputMatchTexts)(payload.toolName, payload.toolInput), policy);
+    if (denial) {
+        return {
+            behavior: null,
+            reason: 'policy-suppressed',
+            suppressedBy: denial.reason,
+            pattern: denial.pattern,
+            mode: policy?.mode ?? null,
+        };
+    }
+    return { behavior: 'allow', reason: 'auto-yes', mode: policy?.mode ?? null };
+}
+/**
+ * Persist an `allow` to the prompt history `capture --prompts` reads
+ * (Issue #1685's layer).
+ *
+ * Only `allow` is written here, and that asymmetry is deliberate. An allowed
+ * request never draws a dialog, so this row is the *only* record that anything
+ * happened — without it, Auto-Yes v2 approves commands invisibly. Every other
+ * verdict ends in the dialog being drawn, where the existing response poller
+ * records the prompt exactly as it does today; a second row would double-count
+ * the audit trail, and writing it as `pending` would be worse still, because
+ * `recordAnsweredPrompt` stamps the newest pending row when the real answer
+ * arrives and would attach the human's answer to this synthetic one.
+ *
+ * A new row is always created rather than reusing `recordAnsweredPrompt`, which
+ * looks for a pending row to stamp: on this path there is no dialog, so any
+ * pending row it found would belong to a *different*, still-unanswered prompt.
+ *
+ * Never throws — the verdict has already been decided and the agent is waiting.
+ */
+function recordAllowedPermission(session, payload) {
+    const texts = (0, permission_request_payload_1.collectToolInputMatchTexts)(payload.toolName, payload.toolInput);
+    const target = texts.join('\n').slice(0, auto_yes_resolver_1.MAX_DENY_MATCH_TEXT_LENGTH);
+    const now = new Date();
+    try {
+        (0, chat_db_1.createMessage)((0, db_instance_1.getDbInstance)(), {
+            worktreeId: session.worktreeId,
+            role: 'assistant',
+            content: `${payload.toolName}: ${target}`.slice(0, auto_yes_resolver_1.MAX_DENY_MATCH_TEXT_LENGTH),
+            // D2: there is no tool_use_id. `prompt_id` + `tool_name` is the
+            // correlation key that actually exists in the payload.
+            summary: `PermissionRequest allow · tool=${payload.toolName} · prompt_id=${payload.promptId ?? 'unknown'}`,
+            messageType: 'prompt',
+            promptData: {
+                type: 'multiple_choice',
+                question: `Approve ${payload.toolName}?`,
+                // Empty on purpose: the hook fires before the dialog exists, so the
+                // options Claude would have offered were never rendered. Inventing
+                // them would put text in the audit trail that nobody ever saw.
+                options: [],
+                status: 'answered',
+                answer: 'allow',
+                answeredAt: now.toISOString(),
+                answeredBy: 'auto',
+                // Exactly what the deny patterns were judged against (#1699).
+                approvalTarget: target,
+            },
+            timestamp: now,
+            cliToolId: session.cliToolId,
+            instanceId: session.instanceId,
+        });
+    }
+    catch (error) {
+        logger.warn('permission-request:audit-record-failed', {
+            worktreeId: session.worktreeId,
+            instanceId: session.instanceId,
+            toolName: payload.toolName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Permission modes in which declining to decide does NOT produce a dialog.
+ *
+ * `bypassPermissions` is Claude's "do not ask me" mode. If the hook fires at
+ * all there, a no-decision is answered by the agent itself and no human is ever
+ * blocked — so reporting a dialog would make `wait --on-prompt agent` exit 10
+ * on a session that is running perfectly well. Whether the hook fires in that
+ * mode was NOT measured by the #1721 spike; this guard costs nothing and
+ * removes the question.
+ */
+const NON_BLOCKING_PERMISSION_MODES = new Set(['bypassPermissions']);
+/**
+ * Tell the detection layer that a dialog is about to be drawn (Issue #1725).
+ *
+ * A no-decision means precisely this: D5 measured `{}` landing back in the
+ * ordinary TUI approval flow, i.e. the dialog appears. That is ~6 seconds
+ * before `Notification(permission_prompt)` announces the same dialog (§5.5), so
+ * it is the earliest moment anything in this system can know a human is needed.
+ *
+ * It is a prediction rather than an observation, and it is recorded as one:
+ * `agent-event-state` expires a `permission-request` record that nothing
+ * corroborates within 20 s. See STRUCTURED_PROMPT_PROVISIONAL_MAX_AGE_MS for
+ * why the asymmetry with the notification source is deliberate.
+ *
+ * `AskUserQuestion` is included even though this Issue does not claim to detect
+ * its screens: it also raises a `PermissionRequest`, and allowing it does not
+ * dismiss the picker (§5.6), so a no-decision there is followed by a screen a
+ * human must act on just the same. What is NOT claimed is that the state
+ * survives — nothing about that screen produces events, so unless the scraper
+ * corroborates it the record expires, which is the honest outcome for a screen
+ * this layer cannot see. That screen belongs to #1708 / #1726.
+ */
+function reportPendingDialog(session, payload) {
+    if (payload?.permissionMode && NON_BLOCKING_PERMISSION_MODES.has(payload.permissionMode)) {
+        return;
+    }
+    (0, agent_event_state_1.reportPermissionRequestPending)(session.worktreeId, session.cliToolId, session.instanceId, payload?.toolName ?? null);
+}
+/**
+ * Adjudicate a permission request and record the outcome.
+ *
+ * @param session - Worktree / tool / instance the request came from
+ * @param payload - Parsed payload, or null when it could not be parsed
+ * @returns The verdict the route serialises
+ */
+function resolvePermissionRequest(session, payload) {
+    const decision = decidePermissionRequest(session, payload);
+    // Issue #1726: `AskUserQuestion` raises a `PermissionRequest` carrying the
+    // same `tool_input` its `PreToolUse` does (§5.6), so the questions are
+    // recorded from here too. Redundant on a session this server started — both
+    // hooks are injected — and the only source on a session started before the
+    // upgrade, whose settings file has no `PreToolUse` entry at all. The two
+    // deliveries carry identical content, so the second is a harmless overwrite.
+    //
+    // This does NOT adjudicate anything: `decidePermissionRequest` still answers
+    // no-decision for `AskUserQuestion`, unchanged from #1724, because allowing it
+    // does not dismiss the picker.
+    if (payload?.toolName === permission_request_payload_1.ASK_USER_QUESTION_TOOL) {
+        const spec = (0, ask_user_question_payload_1.parseAskUserQuestionPayload)({
+            tool_name: payload.toolName,
+            tool_input: payload.toolInput,
+            prompt_id: payload.promptId,
+        });
+        if (spec) {
+            (0, agent_event_state_1.recordAskUserQuestion)(session.worktreeId, session.cliToolId, session.instanceId, spec);
+        }
+    }
+    if (decision.behavior !== 'allow') {
+        reportPendingDialog(session, payload);
+    }
+    if (decision.reason === 'policy-suppressed' && decision.suppressedBy) {
+        // Issue #1684's record, so `capture --json` can say why the worker is
+        // waiting on a dialog it never asked for. Recording it — and NOT denying —
+        // is what keeps the meaning of `denyPatterns` unchanged.
+        (0, auto_yes_suppression_state_1.recordPolicySuppression)(session.worktreeId, session.cliToolId, session.instanceId, {
+            reason: decision.suppressedBy,
+            mode: decision.mode ?? null,
+            promptType: exports.PERMISSION_REQUEST_PROMPT_TYPE,
+            pattern: decision.pattern,
+        });
+        logger.warn('permission-request:suppressed-by-policy', {
+            worktreeId: session.worktreeId,
+            cliToolId: session.cliToolId,
+            instanceId: session.instanceId,
+            toolName: payload?.toolName,
+            promptId: payload?.promptId,
+            reason: decision.suppressedBy,
+            mode: decision.mode ?? null,
+            pattern: decision.pattern,
+        });
+    }
+    if (decision.behavior === 'allow' && payload) {
+        recordAllowedPermission(session, payload);
+    }
+    return decision;
+}

package/dist/server/src/lib/hooks/sources/abstain.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * What it costs to not decide (Issue #1759, constraint C3).
+ *
+ * Auto-Yes v2 abstains constantly — it is off, the worktree has no policy, the
+ * payload did not parse, the tool is `AskUserQuestion`. On Claude that is free:
+ * #1721 D5 measured an empty reply as indistinguishable from having no hook, so
+ * the dialog appears and a human answers it. The rule the codebase learned from
+ * that measurement is "when in doubt, say nothing", and it is written into
+ * comments in several files.
+ *
+ * **That rule is false on two of the six tools.**
+ *
+ * - opencode waits, with no timeout at all. #1758 §5.5.3 left a permission
+ *   unanswered for 10 minutes 19 seconds and it was still pending; the session
+ *   does not fall through to a TUI prompt, because the TUI prompt and the API
+ *   request are the same pending object. Abstaining stops the agent silently.
+ * - antigravity reads an empty `{}` as a *denial* and refuses the tool call
+ *   (#1757 P10, confirmed against a hooks-free control run). Its `PreToolUse`
+ *   `decision` field is required, and "required" turns out to mean fail-closed.
+ *
+ * Neither failure produces an error anywhere. The session just stops, which is
+ * the same thing a thinking agent looks like. So abstention has to be a
+ * decision the caller makes knowingly, and this module is the thing that makes
+ * it knowing: it reads {@link AgentEventSource.noDecision} and says, in one
+ * struct, whether silence is safe and what to tell the operator when it is not.
+ *
+ * @module lib/hooks/sources/abstain
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeNoDecision = describeNoDecision;
+exports.describeAbstain = describeAbstain;
+exports.isAbstainSafe = isAbstainSafe;
+/**
+ * Judge one {@link NoDecisionBehavior}.
+ *
+ * Split from {@link describeAbstain} so a source can be judged before it exists
+ * — Phase 4-2…4-5 tests a spec's declared value without constructing anything.
+ */
+function describeNoDecision(behavior) {
+    switch (behavior.kind) {
+        case 'proceeds':
+            return {
+                safe: true,
+                blocksForMs: 0,
+                summary: 'the agent continues with its own approval flow',
+            };
+        case 'blocks':
+            return {
+                safe: false,
+                blocksForMs: null,
+                summary: 'the agent waits indefinitely; nothing else will unblock it',
+            };
+        case 'blocksUntil':
+            return {
+                safe: false,
+                blocksForMs: behavior.timeoutMs,
+                summary: `the agent waits up to ${behavior.timeoutMs}ms before continuing`,
+            };
+    }
+}
+/**
+ * What happens if this source is given no verdict.
+ *
+ * @param source - The source about to be abstained on
+ * @returns Whether silence is safe, and the sentence to log when it is not
+ */
+function describeAbstain(source) {
+    return describeNoDecision(source.noDecision);
+}
+/**
+ * Shorthand for the common guard.
+ *
+ * @returns Whether abstaining leaves the agent able to make progress
+ */
+function isAbstainSafe(source) {
+    return describeAbstain(source).safe;
+}