commandmate 0.22.2 → 0.23.0

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;
+}