@getmarrow/mcp 3.9.98 → 3.9.100

package/dist/hook-pre-action.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DENIED_DECISION_CLOSE_TIMEOUT_MS = exports.PreActionControlTimeoutError = exports.PRE_ACTION_CONTROL_TIMEOUT_MS = exports.MAX_PRE_ACTION_INPUT_BYTES = exports.MARROW_OUTAGE_WARNING = void 0;
+exports.DENIED_DECISION_CLOSE_TIMEOUT_MS = exports.GROK_FIXED_DENIAL = exports.HELD_SLOW_TEXT = exports.HOLD_OWNER_DENIAL = exports.PreActionControlTimeoutError = exports.PRE_ACTION_CONTROL_TIMEOUT_MS = exports.MAX_PRE_ACTION_INPUT_BYTES = exports.MARROW_OUTAGE_WARNING = exports.NO_KEY_TEXT = void 0;
+exports.isMarrowControlTimeout = isMarrowControlTimeout;
 exports.isMarrowControlOutage = isMarrowControlOutage;
+exports.heldActionHookOutput = heldActionHookOutput;
+exports.passHookOutput = passHookOutput;
+exports.approvedHoldHookOutput = approvedHoldHookOutput;
 exports.isMarrowOutage = isMarrowOutage;
 exports.controlFailureKind = controlFailureKind;
 exports.controlRejectionMessage = controlRejectionMessage;
@@ -21,6 +25,7 @@ exports.geminiPreActionHookOutput = geminiPreActionHookOutput;
 exports.grokPreActionHookOutput = grokPreActionHookOutput;
 exports.preActionHookOutput = preActionHookOutput;
 exports.closeDeniedDecision = closeDeniedDecision;
+exports.localApprovalCategories = localApprovalCategories;
 exports.installPreActionHook = installPreActionHook;
 exports.runPreActionHookCommand = runPreActionHookCommand;
 const node_crypto_1 = require("node:crypto");
@@ -29,10 +34,15 @@ const request_reliability_1 = require("./request-reliability");
 const lifecycle_spool_1 = require("./lifecycle-spool");
 const control_state_1 = require("./control-state");
 const runtime_contract_1 = require("./runtime-contract");
+const host_approval_1 = require("./host-approval");
+const host_session_1 = require("./host-session");
+const normalized_action_1 = require("./normalized-action");
 const session_loop_guard_1 = require("./session-loop-guard");
 const hook_tool_policy_1 = require("./hook-tool-policy");
 const hook_contract_1 = require("./hook-contract");
 Object.defineProperty(exports, "MARROW_OUTAGE_WARNING", { enumerable: true, get: function () { return hook_contract_1.MARROW_OUTAGE_WARNING; } });
+/** A protected action with no Marrow key anywhere this machine keeps one (MARROW_API_KEY, ~/.marrow/env.local or ~/.marrow/env, owner-only). */
+exports.NO_KEY_TEXT = 'Marrow can\'t find your key: run `npx @getmarrow/install` once in this machine\'s terminal.';
 // Claude Code sends the whole tool input, and a Write of a long document grows
 // further once JSON-escaped, so tens of kilobytes of markdown must still parse.
 exports.MAX_PRE_ACTION_INPUT_BYTES = 4 * 1024 * 1024;
@@ -65,6 +75,20 @@ class PreActionControlTimeoutError extends Error {
     }
 }
 exports.PreActionControlTimeoutError = PreActionControlTimeoutError;
+/**
+ * A timeout (the hook's own budget, or a request that did not answer in time):
+ * Marrow is slow, not known to be down. It is never treated as an outage.
+ */
+function isMarrowControlTimeout(error) {
+    if (error instanceof PreActionControlTimeoutError)
+        return true;
+    if (error instanceof request_reliability_1.MarrowRequestError)
+        return error.code === 'request_timeout';
+    if (!error || typeof error !== 'object')
+        return false;
+    const named = error;
+    return named.name === 'AbortError' || named.name === 'TimeoutError';
+}
 function isMarrowControlOutage(error) {
     if (error instanceof PreActionControlTimeoutError)
         return true;
@@ -79,6 +103,89 @@ function isMarrowControlOutage(error) {
         return true;
     return error instanceof TypeError && /fetch|network|getaddrinfo/i.test(String(named.message || ''));
 }
+/** Fixed, privacy-preserving hold texts for hosts whose adapters accept only fixed strings. */
+exports.HOLD_OWNER_DENIAL = 'Marrow is holding this action for approval. Retry it after approval.';
+/** Marrow did not answer within the hook's time limit: an action that can be held stays held. */
+exports.HELD_SLOW_TEXT = 'Marrow did not answer in time, so this action is held. Retry it in a moment.';
+/** The only denial @getmarrow/install's Grok guard passes through (any other output blocks with a launch failure). */
+exports.GROK_FIXED_DENIAL = 'Marrow blocked this protected action.';
+/**
+ * The hook's answer for an ordinary held action, per host. A Claude Code "ask"
+ * reason is shown to the user only; a Cursor user_message is shown only in the
+ * client; neither ever reaches the agent with an approval code.
+ */
+function heldActionHookOutput(harness, plan, code = null) {
+    if (harness === 'windsurf')
+        return null;
+    if (plan.kind === 'pass')
+        return passHookOutput(harness, plan.contextText);
+    if (plan.kind === 'ask') {
+        if (harness === 'cursor')
+            return { permission: 'ask', user_message: plan.promptText, agent_message: 'Marrow asked the user to approve this held action in Cursor.' };
+        return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask', permissionDecisionReason: plan.promptText } };
+    }
+    // The approval code goes only to a user-only channel: Cursor user_message,
+    // Codex and Gemini CLI systemMessage. The agent's text never contains it.
+    if (harness === 'cursor') {
+        return {
+            permission: 'deny',
+            user_message: code ? (0, host_approval_1.typedReplyUserText)(plan.userText, code) : plan.userText,
+            agent_message: plan.agentText,
+        };
+    }
+    if (harness === 'cline')
+        return { cancel: true, errorMessage: plan.agentText };
+    if (harness === 'gemini') {
+        // Without a typed reply the Gemini adapter's fixed denial text is kept.
+        return code
+            ? { decision: 'deny', reason: plan.agentText, systemMessage: (0, host_approval_1.typedReplyUserText)(plan.userText, code) }
+            : { decision: 'deny', reason: 'Marrow blocked this action because required governance approval or proof is unavailable.' };
+    }
+    if (harness === 'grok')
+        return { decision: 'deny', reason: exports.GROK_FIXED_DENIAL };
+    return {
+        hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: plan.agentText },
+        ...(harness === 'codex' && code ? { systemMessage: (0, host_approval_1.typedReplyUserText)(plan.userText, code) } : {}),
+    };
+}
+/**
+ * The hook's answer when the host's own approval step decides (owner rule):
+ * neutral, never an explicit allow, so the host's normal permission flow runs.
+ * Codex: no permissionDecision (only context for the agent); Cline: not
+ * cancelled; Windsurf: exit 0 (emitted by the caller). Any other host has no
+ * neutral answer here and never gets a pass plan.
+ */
+function passHookOutput(harness, contextText) {
+    if (harness === 'windsurf')
+        return null;
+    if (harness === 'cline')
+        return { cancel: false };
+    if (harness === 'codex')
+        return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: contextText } };
+    throw new Error(`no neutral pre-tool answer for ${harness}`);
+}
+/** The hook's answer when a waited hold was approved and the same action is retried. */
+function approvedHoldHookOutput(harness, contextText) {
+    if (harness === 'windsurf')
+        return null;
+    if (harness === 'cursor')
+        return { permission: 'allow' };
+    if (harness === 'cline')
+        return { cancel: false };
+    if (harness === 'gemini' || harness === 'grok')
+        return { decision: 'allow' };
+    return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: contextText } };
+}
+function emitHookOutput(harness, output, deniedText) {
+    if (harness === 'windsurf') {
+        process.exitCode = deniedText ? 2 : 0;
+        if (deniedText)
+            process.stderr.write(`${deniedText}\n`);
+        return;
+    }
+    if (output)
+        process.stdout.write(JSON.stringify(output));
+}
 function isMarrowOutage(result) {
     return result.outage === true;
 }
@@ -95,8 +202,35 @@ function controlFailureKind(error) {
         return 'credential_scope';
     return CONTROL_UNAVAILABLE_CODES.has(error.code) ? 'unavailable' : undefined;
 }
-// Names a reached control failure by HTTP status and stable failure code only, so the
-// denial is diagnosable without echoing private service text into the agent transcript.
+const DOCTOR_FIX = 'Run `npx -y @getmarrow/install@latest doctor` in this terminal to check this machine\'s Marrow setup, then retry.';
+/**
+ * A plain fix for a reached control failure: a known code's own fix, or the
+ * service's exact_fix when it is plain (no API calls, dashboard steps or
+ * links), else the doctor command. Service text other than exact_fix is never
+ * echoed into the agent transcript.
+ */
+function plainControlFix(error) {
+    if (!(error instanceof request_reliability_1.MarrowRequestError))
+        return DOCTOR_FIX;
+    const code = String(error.backendCode || '');
+    if (code === 'AGENT_NOT_REGISTERED' || code === 'MARROW_AGENT_NOT_REGISTERED') {
+        if (/agent limit/i.test(error.message)) {
+            return 'Marrow could not add this agent: this account has reached its plan\'s agent limit. The account owner can archive an unused agent or change the plan in Marrow, then retry.';
+        }
+        if (/not active/i.test(error.message)) {
+            return 'This agent is turned off in this Marrow account. The account owner can turn it back on in Marrow, then retry.';
+        }
+        return 'Marrow doesn\'t know this agent yet. Run `npx @getmarrow/install` again in this terminal, then retry.';
+    }
+    if (error.status === 429 || error.code === 'rate_limited')
+        return 'Marrow is busy right now. Retry in a minute.';
+    const fix = error.exactFix.replace(/\s+/g, ' ').trim();
+    const plain = fix.length > 0 && fix.length <= 240 && /[.!]$/.test(fix)
+        && !/\/v1\/|\b(?:POST|GET|PATCH|PUT|DELETE)\b|dashboard|https?:\/\/|X-Marrow|agent_id|api key|curl\b/i.test(fix);
+    return plain ? fix : DOCTOR_FIX;
+}
+// Names a reached control failure by HTTP status and stable failure code, with a plain
+// fix (see plainControlFix); private service text is never echoed into the agent transcript.
 function controlRejectionMessage(error, agentId) {
     const detail = [];
     if (error instanceof request_reliability_1.MarrowRequestError) {
@@ -117,7 +251,7 @@ function controlRejectionMessage(error, agentId) {
     if (kind === 'unavailable') {
         return `Marrow is unavailable, so this protected action was denied${suffix}. Retry when Marrow is reachable.`;
     }
-    return `Marrow rejected this protected action${suffix}. Restore trusted governance before retrying.`;
+    return `Marrow did not allow this protected action${suffix}. ${plainControlFix(error)}`;
 }
 // Claude Code permission modes in which a PreToolUse "ask" reaches a person.
 // bypassPermissions disables prompts, dontAsk auto-denies anything that would
@@ -125,6 +259,8 @@ function controlRejectionMessage(error, agentId) {
 // https://code.claude.com/docs/en/hooks#pretooluse-decision-control
 // https://code.claude.com/docs/en/permission-modes
 const OWNER_PROMPT_PERMISSION_MODES = new Set(['default', 'acceptEdits', 'auto']);
+/** Claude Code entrypoints with no one at a dialog (claude -p and the Agent SDKs); hooks inherit it. */
+const HEADLESS_CLAUDE_ENTRYPOINTS = host_approval_1.HEADLESS_CLAUDE_ENTRYPOINTS;
 const NO_OWNER_PROMPT = { available: false, unavailableReason: 'this agent host cannot prompt the owner' };
 /**
  * Whether a PreToolUse "ask" from this hook reaches a person who can approve.
@@ -138,6 +274,10 @@ function ownerApprovalPrompt(harness, event, env = process.env) {
             ? { available: false, unavailableReason: 'Codex hooks cannot prompt the owner' }
             : NO_OWNER_PROMPT;
     }
+    const entrypoint = typeof env.CLAUDE_CODE_ENTRYPOINT === 'string' ? env.CLAUDE_CODE_ENTRYPOINT : '';
+    if (HEADLESS_CLAUDE_ENTRYPOINTS.has(entrypoint)) {
+        return { available: false, unavailableReason: `${entrypoint}, no one sees a dialog`, headless: true };
+    }
     const mode = typeof event.permission_mode === 'string' && /^[A-Za-z]{1,32}$/.test(event.permission_mode) ? event.permission_mode : '';
     if (!OWNER_PROMPT_PERMISSION_MODES.has(mode)) {
         return { available: false, unavailableReason: `Claude Code permission mode ${mode || 'unknown'} cannot guarantee an owner prompt` };
@@ -160,14 +300,14 @@ function boundedText(value, limit) {
 function asOptionalRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
 }
-// Arbitration review is satisfied only by an authenticated-dashboard receipt,
-// never by a host prompt, so any arbitration signal keeps the denial.
+// Arbitration review is satisfied only by the account owner's choice of a
+// proposal (one-tap link), never by a host prompt, so any arbitration signal keeps the denial.
 function arbitrationReview(runtime) {
     const completion = runtime.completion_contract;
     const approval = asOptionalRecord(completion?.owner_approval);
     return Boolean(runtime.arbitration)
         || completion?.arbitration_receipt_required === true
-        || approval?.dashboard_receipt_required === true
+        || (0, runtime_contract_1.ownerReceiptRequired)(approval)
         || (approval?.mode !== undefined && approval.mode !== 'ordinary_non_arbitrated');
 }
 /**
@@ -209,10 +349,10 @@ function runtimeGateAdvisory(runtime) {
 function runtimeGateEnforced(runtime) {
     return !runtimeGateAdvisory(runtime);
 }
+// Why the gate held or blocked the action. The runtime's exact_next_action is
+// written for API clients (endpoints to call) and is never relayed by a hook.
 function gateReason(runtime) {
-    const why = boundedText(runtime.risk_gate.reasons?.[0]?.message, 240);
-    const next = boundedText(runtime.exact_next_action, 240);
-    return why && next && why !== next ? `${why}${/[.!?]$/.test(why) ? '' : '.'} Next: ${next}` : why || next;
+    return boundedText(runtime.risk_gate.reasons?.[0]?.message, 240);
 }
 /** A warning for a non-allow gate the runtime does not enforce on this plan. */
 function advisoryGateNotice(runtime) {
@@ -248,12 +388,12 @@ function gateDecisionMessage(verdict, ask, prompt = NO_OWNER_PROMPT) {
     const headline = verdict.kind === 'block'
         ? 'Marrow blocked this action under the current policy.'
         : verdict.kind === 'arbitration_review'
-            ? 'Marrow arbitration requires owner approval in the authenticated Marrow dashboard before this action.'
+            ? 'Marrow is holding this action for arbitration review: the account owner picks and approves one proposal before it runs. Do not run it yet.'
             : verdict.kind === 'denied'
                 ? 'Marrow did not allow this action.'
                 : ask
                     ? 'Marrow requires owner review before this action. Approve only if you authorize this exact action.'
-                    : `Marrow requires owner review before this action, and no owner approval prompt is available (${prompt.unavailableReason}), so it was denied. Ask the owner to approve or run it.`;
+                    : `Marrow requires owner review before this action, and no owner approval prompt is available (${prompt.unavailableReason}), so it was denied. Tell the operator it is waiting for the account owner's approval.`;
     return boundedText(verdict.reason ? `${headline} Reason: ${verdict.reason}` : headline, 500);
 }
 const SAFE_DECISION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
@@ -406,16 +546,16 @@ function clinePreActionHookOutput(result) {
         };
     }
     if (result.protectedRisk && (!result.runtime || !result.permit?.verified)) {
-        const credentialsUnavailable = /credentials are unavailable/i.test(String(result.enforcementError || ''));
+        const credentialsUnavailable = result.enforcementError === exports.NO_KEY_TEXT;
         return {
             cancel: true,
             errorMessage: credentialsUnavailable
-                ? 'Marrow credentials are unavailable for this protected action. Restore the configured agent key and retry.'
+                ? exports.NO_KEY_TEXT
                 : result.failure === 'credential_scope'
                     ? 'This Marrow API key is not authorized to obtain action permits for this agent. Use the API key issued to this agent and retry.'
                     : result.failure === 'unavailable'
                         ? 'Marrow is unavailable, so this protected action was denied. Retry when Marrow is reachable.'
-                        : 'Marrow could not verify the required action permit. Restore trusted governance and retry.',
+                        : `Marrow could not confirm a permit for this protected action. ${DOCTOR_FIX}`,
         };
     }
     return { cancel: false };
@@ -453,7 +593,9 @@ function grokPreActionHookOutput(result) {
         ? { decision: 'deny', reason: 'Marrow blocked this protected action.' }
         : { decision: 'allow' };
 }
-function preActionHookOutput(result, harness = 'claude-code', prompt = NO_OWNER_PROMPT) {
+function preActionHookOutput(result, harness = 'claude-code', prompt = NO_OWNER_PROMPT, 
+/** An older service without host approvals: Claude Code asks in its dialog exactly as 3.9.98 did. */
+legacyServiceAsk = false) {
     if (harness === 'cursor')
         return cursorPreActionHookOutput(result);
     if (harness === 'cline')
@@ -480,15 +622,28 @@ function preActionHookOutput(result, harness = 'claude-code', prompt = NO_OWNER_
         ].filter(Boolean).join('\n'),
     } : {};
     const verdict = runtimeGateVerdict(runtime);
+    if (verdict && legacyServiceAsk && verdict.kind === 'review' && prompt.available && harness !== 'codex') {
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'ask',
+                permissionDecisionReason: gateDecisionMessage(verdict, true, prompt),
+                ...context,
+            },
+        };
+    }
     if (verdict) {
-        // Only an ordinary review in a session that shows the owner a prompt asks;
-        // block, arbitration and every host where no person would see it deny.
-        const ask = verdict.kind === 'review' && prompt.available && harness !== 'codex';
+        // An ordinary hold the server lets the host approve is answered by
+        // heldActionHookOutput. Here every gate denies: block, arbitration, and a
+        // review the server offered no chat or terminal approval for.
+        const reason = verdict.kind === 'review' && prompt.available && !legacyServiceAsk
+            ? { available: false, unavailableReason: 'this Marrow service did not offer a chat or terminal approval for this hold' }
+            : prompt;
         return {
             hookSpecificOutput: {
                 hookEventName: 'PreToolUse',
-                permissionDecision: ask ? 'ask' : 'deny',
-                permissionDecisionReason: gateDecisionMessage(verdict, ask, prompt),
+                permissionDecision: 'deny',
+                permissionDecisionReason: gateDecisionMessage(verdict, false, reason),
                 ...context,
             },
         };
@@ -512,7 +667,7 @@ function preActionHookOutput(result, harness = 'claude-code', prompt = NO_OWNER_
         },
     };
 }
-function emitDecision(result, harness = 'claude-code', prompt = NO_OWNER_PROMPT) {
+function emitDecision(result, harness = 'claude-code', prompt = NO_OWNER_PROMPT, legacyServiceAsk = false) {
     if (harness === 'windsurf') {
         const decision = windsurfPreActionDecision(result);
         process.exitCode = decision.exitCode;
@@ -522,7 +677,7 @@ function emitDecision(result, harness = 'claude-code', prompt = NO_OWNER_PROMPT)
     }
     if (result.outage)
         process.stderr.write(`${hook_contract_1.MARROW_OUTAGE_WARNING}\n`);
-    const output = preActionHookOutput(result, harness, prompt);
+    const output = preActionHookOutput(result, harness, prompt, legacyServiceAsk);
     process.stdout.write(JSON.stringify(output));
     const specific = asRecord(output.hookSpecificOutput);
     if (specific?.permissionDecision === 'deny')
@@ -574,7 +729,7 @@ async function closeDeniedDecision(apiKey, baseUrl, held, reason, sessionId, age
             clearTimeout(timer);
     }
 }
-async function withTimeout(operation) {
+async function withTimeout(operation, timeoutMs = exports.PRE_ACTION_CONTROL_TIMEOUT_MS) {
     const controller = new AbortController();
     let timer;
     try {
@@ -584,7 +739,7 @@ async function withTimeout(operation) {
                 timer = setTimeout(() => {
                     controller.abort();
                     reject(new PreActionControlTimeoutError());
-                }, exports.PRE_ACTION_CONTROL_TIMEOUT_MS);
+                }, timeoutMs);
             }),
         ]);
     }
@@ -593,6 +748,72 @@ async function withTimeout(operation) {
             clearTimeout(timer);
     }
 }
+/**
+ * The gate's risk categories for this classified action, as the server
+ * derives them from the same action, type and surfaces (risk-categories.ts).
+ * Used only while Marrow cannot be reached, to keep owner-protected actions held.
+ */
+const LOCAL_CATEGORY_PATTERNS = [
+    ['production_deploy', /\b(deploy|release|rollback|rollout|production|prod)\b/i],
+    ['source_control', /\b(merge|pull request|pr|github|main|master)\b/i],
+    ['data_migration', /\b(migration|migrate|schema|database|sql|table|column)\b/i],
+    ['secrets_security', /\b(secret|token|key|credential|rotate|revoke|security|waf|auth)\b/i],
+    ['billing_access', /\b(billing|payment|invoice|subscription|plan|tier|permission|access)\b/i],
+    ['destructive_action', /\b(?:delete|drop|truncate|purge|destroy|remove all|wipe)\b/i],
+];
+function localApprovalCategories(action) {
+    const text = `${action.action} ${action.type} ${action.surfaces.join(' ')}`;
+    const categories = LOCAL_CATEGORY_PATTERNS.filter(([, pattern]) => pattern.test(text)).map(([category]) => category);
+    // Broader than the server's package-publish check on purpose: it only keeps an action held.
+    if (action.type.toLowerCase() === 'publish' || /\bpublish\b/i.test(text))
+        categories.unshift('package_publish');
+    return categories;
+}
+/**
+ * Positive evidence that a person is at this host for a call Marrow cannot ask
+ * about: a local interactive Codex, Gemini CLI or Cline CLI process, Cline or
+ * Windsurf inside the editor app, or a local Cursor session (sessionStart).
+ * Missing evidence is not attended.
+ */
+function attendedConfirmed(ctx, cursorInteractive) {
+    if (ctx.host === 'codex' || ctx.host === 'gemini' || ctx.host === 'cline' || ctx.host === 'windsurf')
+        return (0, host_session_1.localInteractiveSession)(ctx.host) === true;
+    if (ctx.host === 'cursor')
+        return cursorInteractive === true;
+    return false;
+}
+/**
+ * Nobody is in this run: headless Claude Code (sdk-*, its GitHub Action), a
+ * scripted Codex or Gemini CLI run (`codex exec`, `gemini -p`), or a Cursor
+ * background agent. Missing evidence is not unattended.
+ */
+function unattendedRun(ctx, claudePrompt, cursorInteractive) {
+    if (ctx.host === 'claude-code')
+        return claudePrompt.headless === true;
+    if (ctx.host === 'codex' || ctx.host === 'gemini')
+        return (0, host_session_1.localInteractiveSession)(ctx.host) === false;
+    // Cursor: sessionStart reports local sessions; without it (cloud agents) or as a background agent, nobody is there.
+    if (ctx.host === 'cursor')
+        return cursorInteractive !== true;
+    // Grok, Cline, Windsurf: attended only with positive evidence of a person's session.
+    if (ctx.host === 'grok' || ctx.host === 'cline' || ctx.host === 'windsurf')
+        return (0, host_session_1.localInteractiveSession)(ctx.host) !== true;
+    return false;
+}
+/** The hook's answer for a held action on any host (Windsurf answers through its exit code). */
+function emitHeldPlan(harness, plan, code = null) {
+    emitHookOutput(harness, heldActionHookOutput(harness, plan, code), plan.kind === 'deny' ? plan.agentText : undefined);
+}
+/** Work that does not decide the answer, done after it is written and inside the hook's budget. */
+async function afterAnswer(ctx, work) {
+    try {
+        if (work.link)
+            await (0, host_approval_1.requestOwnerLink)(ctx, work.link, 0);
+        if ((0, host_approval_1.remainingMs)(ctx) > 800)
+            await (0, host_approval_1.flushHoldOutbox)(ctx, 2, Math.min(4_000, (0, host_approval_1.remainingMs)(ctx) - 200));
+    }
+    catch { /* best effort: a later hook resends queued work */ }
+}
 function installPreActionHook(startDir = process.cwd()) {
     const fs = require('node:fs');
     const path = (0, hook_contract_1.findHookSettingsPath)(startDir);
@@ -668,8 +889,7 @@ async function runPreActionHookCommand(input) {
         if (resolved.apiKey) {
             try {
                 const baseUrl = (0, index_1.validateBaseUrl)(resolved.baseUrl || 'https://api.getmarrow.ai');
-                await (0, lifecycle_spool_1.recordLifecycleEvent)({ apiKey: resolved.apiKey, baseUrl, event: {
-                        event_id: `owner-bypass-${correlation}`,
+                await (0, lifecycle_spool_1.recordLifecycleEvent)({ apiKey: resolved.apiKey, baseUrl, event: (0, lifecycle_spool_1.payloadBoundEvent)(`owner-bypass-${correlation}`, {
                         event_type: 'pre_action_checked',
                         ...(0, hook_contract_1.clientReportedHookLifecycleIdentity)(identity),
                         session_id: sessionId,
@@ -681,7 +901,7 @@ async function runPreActionHookCommand(input) {
                         outcome_state: 'pending',
                         intervention_disposition: 'overridden',
                         action_changed: false,
-                    } }).catch(() => null);
+                    }) }).catch(() => null);
             }
             catch { /* owner bypass is not trapped by telemetry configuration */ }
         }
@@ -719,8 +939,7 @@ async function runPreActionHookCommand(input) {
         if (resolved.apiKey) {
             try {
                 const loopBaseUrl = (0, index_1.validateBaseUrl)(resolved.baseUrl || 'https://api.getmarrow.ai');
-                await (0, lifecycle_spool_1.recordLifecycleEvent)({ apiKey: resolved.apiKey, baseUrl: loopBaseUrl, event: {
-                        event_id: `loop-block-${loopDecision.receipt.slice(4)}`,
+                await (0, lifecycle_spool_1.recordLifecycleEvent)({ apiKey: resolved.apiKey, baseUrl: loopBaseUrl, event: (0, lifecycle_spool_1.payloadBoundEvent)(`loop-block-${loopDecision.receipt.slice(4)}`, {
                         event_type: 'pre_action_checked',
                         ...(0, hook_contract_1.clientReportedHookLifecycleIdentity)(identity),
                         session_id: sessionId,
@@ -733,7 +952,7 @@ async function runPreActionHookCommand(input) {
                         outcome_state: 'pending',
                         intervention_disposition: 'followed',
                         action_changed: true,
-                    } }).catch(() => null);
+                    }) }).catch(() => null);
             }
             catch { /* local denial remains authoritative when telemetry is unavailable */ }
         }
@@ -757,7 +976,7 @@ async function runPreActionHookCommand(input) {
             runtime: null,
             permit: null,
             protectedRisk: enforcementRequired,
-            enforcementError: 'Marrow enforcement configuration is unavailable. Restore the trusted configuration before retrying this protected action.',
+            enforcementError: 'The Marrow address in this machine\'s settings is not valid, so this protected action was held. Run `npx @getmarrow/install` again in this terminal, then retry.',
         }, identity.harness);
         return;
     }
@@ -766,27 +985,72 @@ async function runPreActionHookCommand(input) {
             runtime: null,
             permit: null,
             protectedRisk: enforcementRequired,
-            enforcementError: 'Marrow credentials are unavailable for this protected action. Restore the configured agent key before retrying.',
+            enforcementError: exports.NO_KEY_TEXT,
         }, identity.harness);
         return;
     }
-    const lifecycle = (0, lifecycle_spool_1.recordLifecycleEvent)({
+    const holdContext = {
         apiKey: resolved.apiKey,
         baseUrl,
-        event: {
-            event_id: `pretool-${correlation}`,
-            event_type: 'pre_action_checked',
-            ...(0, hook_contract_1.clientReportedHookLifecycleIdentity)(identity),
-            session_id: sessionId,
-            workflow_id: (0, hook_contract_1.stableSessionWorkflowId)(sessionId, source.generation_id || source.tool_use_id || source.task_id),
-            correlation_id: correlation,
-            action: classified.action,
-            target: classified.target,
-            surfaces: classified.surfaces,
-            risk_level: classified.risk,
-            outcome_state: 'pending',
-        },
-    }).catch(() => null);
+        sessionId,
+        agentId,
+        harness: identity.harness,
+        host: (0, host_approval_1.approvalHostFor)(identity.harness),
+        hostSessionId: (0, host_approval_1.hostSessionIdFor)([source.session_id, source.conversation_id, source.task_id], sessionId),
+        // One total budget for this hook's answer and its follow-up work.
+        deadlineAt: (0, host_approval_1.preToolDeadline)((0, host_approval_1.approvalHostFor)(identity.harness)),
+    };
+    const toolUseId = typeof source.tool_use_id === 'string' ? source.tool_use_id : null;
+    const generationId = typeof source.generation_id === 'string' ? source.generation_id : null;
+    // Cursor runs an MCP call through preToolUse and then beforeMCPExecution, the
+    // only event where Cursor shows its own approval prompt. In a local
+    // interactive session preToolUse defers to it; cloud agents never run
+    // beforeMCPExecution, so there preToolUse is the gate and holds quietly.
+    const cursorMcpPreToolUse = holdContext.host === 'cursor' && String(source.hook_event_name || '').toLowerCase() === 'pretooluse'
+        && /^MCP:/i.test(String(source.tool_name || ''));
+    if (cursorMcpPreToolUse && (0, host_approval_1.cursorSessionEvidence)(holdContext).interactive === true) {
+        process.stdout.write(JSON.stringify({ permission: 'allow' }));
+        return;
+    }
+    // The same action retried after a hold that waited for approval: its status decides.
+    const dialogAvailable = holdContext.host === 'claude-code' && ownerApprovalPrompt(identity.harness, source).available;
+    const waited = await (0, host_approval_1.resumeWaitingHold)(holdContext, { correlation, toolUseId, generationId, dialogAvailable }).catch(() => null);
+    if (waited?.kind === 'allow') {
+        emitHookOutput(identity.harness, approvedHoldHookOutput(identity.harness, waited.contextText));
+        await afterAnswer(holdContext, {});
+        return;
+    }
+    if (waited?.kind === 'ask') {
+        emitHookOutput(identity.harness, heldActionHookOutput(identity.harness, { kind: 'ask', promptText: waited.promptText }, null));
+        await afterAnswer(holdContext, {});
+        return;
+    }
+    if (waited?.kind === 'deny') {
+        emitHeldPlan(identity.harness, { kind: 'deny', agentText: waited.agentText, userText: waited.userText, code: Boolean(waited.hold.code) }, waited.hold.code);
+        await afterAnswer(holdContext, { link: waited.deferredLink ? waited.hold : null });
+        return;
+    }
+    // One lifecycle record per attempt: its id names its payload (a retried action
+    // is a new attempt), and a hold names the record of the attempt that created it.
+    const preActionEvent = (0, lifecycle_spool_1.payloadBoundEvent)(`pretool-${correlation}`, {
+        event_type: 'pre_action_checked',
+        ...(0, hook_contract_1.clientReportedHookLifecycleIdentity)(identity),
+        session_id: sessionId,
+        workflow_id: (0, hook_contract_1.stableSessionWorkflowId)(sessionId, source.generation_id || source.tool_use_id || source.task_id),
+        correlation_id: correlation,
+        action: classified.action,
+        target: classified.target,
+        surfaces: classified.surfaces,
+        risk_level: classified.risk,
+        outcome_state: 'pending',
+    });
+    const preActionEventId = preActionEvent.event_id;
+    const lifecycle = (0, lifecycle_spool_1.recordLifecycleEvent)({ apiKey: resolved.apiKey, baseUrl, event: preActionEvent }).catch(() => null);
+    // Normalizing has its own share of the host's budget: past it the action is
+    // a truncated placeholder, so the hook still answers (deny first) in time.
+    const normalizedAction = (0, normalized_action_1.normalizedHookAction)(source, {
+        deadlineAt: Math.min(Date.now() + 750, (holdContext.deadlineAt ?? Number.POSITIVE_INFINITY) - 1_000),
+    });
     // The decision and gate receipt this control path holds, so a denial can close them.
     const held = { decisionId: null, gateReceiptId: null };
     const control = async (signal) => {
@@ -796,6 +1060,9 @@ async function runPreActionHookCommand(input) {
             type: classified.type,
             role: classified.role,
             surfaces: classified.surfaces,
+            // The exact command or tool call (secrets removed), so Marrow binds the
+            // gate and any approval to this action, not to its coarse class.
+            normalized_action: normalizedAction,
             // Without a risk level the runtime may take its low-risk fast path, whose
             // non-durable fast_gate receipt can never back an action permit.
             ...(enforcementRequired ? { risk_level: classified.risk } : {}),
@@ -889,25 +1156,147 @@ async function runPreActionHookCommand(input) {
             ...(verifiedExactly ? {} : { enforcementError: 'Marrow permit verification did not match the issued permit.' }),
         };
     };
+    // Codex and Cursor stop the hook at 5 s (and Codex then lets the call run):
+    // the control path ends inside the hook's budget, leaving time to answer.
+    const controlTimeoutMs = Math.max(1_000, Math.min(exports.PRE_ACTION_CONTROL_TIMEOUT_MS, (0, host_approval_1.remainingMs)(holdContext) - 400));
     const [result] = await Promise.all([
-        withTimeout(control).catch((error) => (isMarrowControlOutage(error)
+        withTimeout(control, controlTimeoutMs).catch((error) => (isMarrowControlTimeout(error)
             ? {
                 runtime: null,
                 permit: null,
                 protectedRisk: enforcementRequired,
-                outage: true,
+                timedOut: true,
                 enforcementError: hook_contract_1.MARROW_OUTAGE_WARNING,
             }
-            : {
-                runtime: null,
-                permit: null,
-                protectedRisk: enforcementRequired,
-                enforcementError: controlRejectionMessage(error, agentId),
-                ...(controlFailureKind(error) ? { failure: controlFailureKind(error) } : {}),
-            })),
+            : isMarrowControlOutage(error)
+                ? {
+                    runtime: null,
+                    permit: null,
+                    protectedRisk: enforcementRequired,
+                    outage: true,
+                    enforcementError: hook_contract_1.MARROW_OUTAGE_WARNING,
+                }
+                : {
+                    runtime: null,
+                    permit: null,
+                    protectedRisk: enforcementRequired,
+                    enforcementError: controlRejectionMessage(error, agentId),
+                    ...(controlFailureKind(error) ? { failure: controlFailureKind(error) } : {}),
+                })),
         lifecycle,
     ]);
-    const emitted = emitDecision(result, identity.harness, ownerApprovalPrompt(identity.harness, source));
+    const claudePrompt = ownerApprovalPrompt(identity.harness, source);
+    if (result.timedOut) {
+        // Marrow is slow, not down: a self-imposed budget is never an outage. An
+        // action that can be held stays held; routine actions keep flowing.
+        const holdable = classified.protected || classified.risk === 'high'
+            || (0, host_approval_1.protectedAmong)(holdContext, localApprovalCategories(classified)).length > 0;
+        if (holdable) {
+            emitHeldPlan(identity.harness, { kind: 'deny', agentText: exports.HELD_SLOW_TEXT, userText: exports.HELD_SLOW_TEXT, code: false });
+            return;
+        }
+        emitDecision({ ...result, outage: true, timedOut: false }, identity.harness, claudePrompt);
+        return;
+    }
+    if (result.outage) {
+        // Marrow cannot be reached. An action in a category the account owner
+        // protects stays held on every host; everything else keeps the outage policy.
+        const protectedNow = (0, host_approval_1.protectedAmong)(holdContext, localApprovalCategories(classified));
+        if (protectedNow.length) {
+            emitHeldPlan(identity.harness, { kind: 'deny', agentText: host_approval_1.HELD_UNREACHABLE_TEXT, userText: host_approval_1.HELD_UNREACHABLE_TEXT, code: false });
+            return;
+        }
+    }
+    const verdict = result.outage ? null : runtimeGateVerdict(result.runtime);
+    const guidance = verdict?.kind === 'review' ? (0, runtime_contract_1.ordinaryApprovalGuidance)(result.runtime) : null;
+    const arbitration = verdict?.kind === 'arbitration_review' ? (0, runtime_contract_1.arbitrationApprovalGuidance)(result.runtime) : null;
+    if (verdict && guidance && !guidance.hostApprovalSupported && holdContext.host === 'claude-code') {
+        // An older service without host approvals: exactly as released 3.9.98 —
+        // ask in Claude Code's dialog (the close stays unverified), never wait.
+        const emitted = emitDecision(result, identity.harness, claudePrompt, true);
+        if (emitted.denied)
+            await closeDeniedDecision(resolved.apiKey, baseUrl, held, emitted.reason, sessionId, agentId);
+        return;
+    }
+    if (verdict && (guidance || arbitration)) {
+        // A hold: ask in the host's own prompt where it counts and is shown,
+        // otherwise deny and wait for the approval. Never close the decision here;
+        // that would spend the receipt the operator or owner is about to approve.
+        const hookEvent = typeof source.hook_event_name === 'string' ? source.hook_event_name : 'PreToolUse';
+        let plan;
+        const cursor = holdContext.host === 'cursor' ? (0, host_approval_1.cursorSessionEvidence)(holdContext) : null;
+        const nobodyHere = cursorMcpPreToolUse || unattendedRun(holdContext, claudePrompt, cursor?.interactive ?? null);
+        if (guidance) {
+            (0, host_approval_1.rememberProtection)(holdContext, guidance);
+            plan = (0, host_approval_1.planHeldAction)({
+                unattended: nobodyHere,
+                attendedConfirmed: !cursorMcpPreToolUse && attendedConfirmed(holdContext, cursor?.interactive ?? null),
+                hostPromptOff: (0, host_session_1.hostApprovalPromptOff)(holdContext.host),
+                guidance,
+                host: holdContext.host,
+                hookEvent,
+                // Only why it is held: the server's next-action text is written for API
+                // clients and names endpoints, so it is never relayed.
+                reason: boundedText(result.runtime?.risk_gate?.reasons?.[0]?.message, 240),
+                claudePrompt,
+                cursorInteractive: cursor?.interactive ?? null,
+                typedReply: (0, host_approval_1.typedReplyAvailable)(holdContext),
+            });
+        }
+        else {
+            plan = (0, host_approval_1.planArbitrationHold)(arbitration, { unattended: nobodyHere });
+        }
+        let code = null;
+        let effective = plan;
+        let linkOutcome = { kind: 'none' };
+        let laterLink = null;
+        try {
+            // An unreadable approval state leaves nothing to wait on: the next attempt starts over.
+            const hold = plan.kind === 'deny' && plan.retryFresh ? null : (0, host_approval_1.rememberHold)(holdContext, {
+                guidance: guidance || (0, host_approval_1.arbitrationHoldGuidance)(arbitration),
+                correlation,
+                toolUseId,
+                generationId,
+                toolName: String(source.tool_name || 'tool'),
+                hookEvent,
+                // ask and pass: the host decides now; deny: the hold waits for an approval.
+                mode: plan.kind === 'deny' ? 'wait' : 'ask',
+                withCode: plan.kind === 'deny' && plan.code,
+                preActionEventId,
+                action: { action: classified.action, target: classified.target, type: classified.type, surfaces: classified.surfaces },
+                ...(plan.kind === 'deny' && plan.ownerLink ? { ownerLink: plan.ownerLink } : {}),
+                ...(plan.kind === 'deny' && plan.dialogLater ? { dialogLater: true, laterPrompt: plan.laterPrompt } : {}),
+                ...(plan.kind === 'deny' && plan.quiet ? { quiet: plan.quiet } : {}),
+                ...(plan.kind === 'pass' ? { notObserved: true } : {}),
+                normalizedAction,
+                ...(guidance ? {} : { personPresent: !nobodyHere }),
+            });
+            code = hold?.code ?? null;
+            if (hold && plan.kind === 'deny' && plan.ownerLink === 'now') {
+                linkOutcome = await (0, host_approval_1.requestOwnerLink)(holdContext, hold);
+                if (linkOutcome.kind === 'deferred')
+                    laterLink = hold;
+            }
+        }
+        catch {
+            // Without local state the answer could not be linked to this hold, so it is not asked for.
+            if (plan.kind === 'ask' || plan.kind === 'pass') {
+                const text = `Marrow is holding this action for approval (gate receipt ${guidance?.gateReceiptId || arbitration?.gateReceiptId}), so it did not run. Tell the operator it is waiting for approval; local approval state is unavailable on this machine.`;
+                effective = { kind: 'deny', agentText: text, userText: (0, host_approval_1.forPerson)(text), code: false };
+            }
+        }
+        effective = (0, host_approval_1.finalizeOwnerRequest)(effective, linkOutcome);
+        if (effective.kind === 'pass') {
+            // The hook does not block and does not allow: the host's own approval step decides.
+            emitHookOutput(identity.harness, passHookOutput(identity.harness, effective.contextText));
+            await afterAnswer(holdContext, {});
+            return;
+        }
+        emitHeldPlan(identity.harness, effective, code);
+        await afterAnswer(holdContext, { link: laterLink });
+        return;
+    }
+    const emitted = emitDecision(result, identity.harness, claudePrompt);
     if (emitted.denied && !result.outage) {
         await closeDeniedDecision(resolved.apiKey, baseUrl, held, emitted.reason, sessionId, agentId);
     }