@getmarrow/mcp 3.9.98 → 3.9.99

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MARROW_AUTO_RESPONSE_BUDGET_MAX_MS = void 0;
+exports.AGENT_APPROVAL_SETTINGS_PATH = exports.HELD_ACTIONS_PATH = exports.ELICITATION_HOOK_EVENT = exports.MARROW_AUTO_RESPONSE_BUDGET_MAX_MS = void 0;
 exports.writeReconciliationDelayMs = writeReconciliationDelayMs;
 exports.validatePathParam = validatePathParam;
 exports.validateBaseUrl = validateBaseUrl;
@@ -12,9 +12,13 @@ exports.marrowRevokeKey = marrowRevokeKey;
 exports.marrowRotateKey = marrowRotateKey;
 exports.marrowGetKeyAudit = marrowGetKeyAudit;
 exports.marrowThink = marrowThink;
+exports.withoutOwnerApprovalClaim = withoutOwnerApprovalClaim;
 exports.marrowCommit = marrowCommit;
 exports.marrowModelUsage = marrowModelUsage;
+exports.approvalStatement = approvalStatement;
+exports.ordinaryHoldWaitText = ordinaryHoldWaitText;
 exports.marrowAuto = marrowAuto;
+exports.withoutServerNextActions = withoutServerNextActions;
 exports.marrowAgentPatterns = marrowAgentPatterns;
 exports.marrowOrient = marrowOrient;
 exports.marrowAsk = marrowAsk;
@@ -29,6 +33,11 @@ exports.marrowValueReport = marrowValueReport;
 exports.marrowDecisionBrief = marrowDecisionBrief;
 exports.marrowWorkflowGate = marrowWorkflowGate;
 exports.marrowAgentRuntime = marrowAgentRuntime;
+exports.marrowOwnerApprovalStatus = marrowOwnerApprovalStatus;
+exports.marrowRequestApprovalLink = marrowRequestApprovalLink;
+exports.marrowHeldActions = marrowHeldActions;
+exports.marrowAgentApprovalSettings = marrowAgentApprovalSettings;
+exports.marrowHostApproval = marrowHostApproval;
 exports.marrowEnforcement = marrowEnforcement;
 exports.marrowArbitrate = marrowArbitrate;
 exports.marrowGovernanceControlPlane = marrowGovernanceControlPlane;
@@ -913,10 +922,25 @@ async function marrowThink(apiKey, baseUrl, params, sessionId, agentId, signal,
 /**
  * Explicitly commit the result of an action to Marrow.
  */
+/**
+ * A caller-written proof.owner_approval is not an approval: the server issues
+ * approvals (host prompt or dashboard) and binds them to the gate receipt. The
+ * client never sends such a claim, so a model cannot approve its own hold.
+ */
+function withoutOwnerApprovalClaim(proof) {
+    if (!proof || typeof proof !== 'object' || Array.isArray(proof))
+        return undefined;
+    if (!Object.prototype.hasOwnProperty.call(proof, 'owner_approval'))
+        return proof;
+    const { owner_approval: _claim, ...rest } = proof;
+    return Object.keys(rest).length > 0 ? rest : undefined;
+}
 async function marrowCommit(apiKey, baseUrl, params, sessionId, agentId, signal, idempotencyKey) {
     let runtimeGate = null;
     let gateReceiptId = params.gate_receipt_id || params.gate_receipt;
     let observationOnly = false;
+    // An approval is issued by the server (host prompt or dashboard), never written by the caller.
+    const commitProof = withoutOwnerApprovalClaim(params.proof);
     for (const [field, value] of [
         ['gate receipt', gateReceiptId],
         ['arbitration receipt', params.arbitration_receipt_id],
@@ -936,7 +960,7 @@ async function marrowCommit(apiKey, baseUrl, params, sessionId, agentId, signal,
                 target: params.target ? (0, redact_1.redactSensitiveText)(params.target) : undefined,
                 surfaces: params.surfaces || [],
                 context: { mcp_commit_auto_gate: true },
-                proof: params.proof ? (0, redact_1.redactSensitiveValue)(params.proof) : undefined,
+                proof: commitProof ? (0, redact_1.redactSensitiveValue)(commitProof) : undefined,
             }, sessionId, agentId, signal);
         }
         catch (err) {
@@ -970,8 +994,8 @@ async function marrowCommit(apiKey, baseUrl, params, sessionId, agentId, signal,
         outcome: (0, redact_1.redactSensitiveText)(params.outcome),
         caused_by: params.caused_by ? (0, redact_1.redactSensitiveText)(params.caused_by) : undefined,
     };
-    if (params.proof)
-        body.proof = (0, redact_1.redactSensitiveValue)(params.proof);
+    if (commitProof)
+        body.proof = (0, redact_1.redactSensitiveValue)(commitProof);
     if (gateReceiptId)
         body.gate_receipt_id = gateReceiptId;
     if (params.arbitration_receipt_id)
@@ -1175,6 +1199,14 @@ async function waitForAutoContinuation(pending, startedAt, responseBudgetMs, aut
     }
     return responseBudgetMs - (Date.now() - startedAt) > AUTO_RESPONSE_DEADLINE_MARGIN_MS;
 }
+/** Link refusals that another request cannot change. */
+const FINAL_OWNER_LINK_CODES = new Set([
+    'MARROW_APPROVAL_CHANNEL_UNAVAILABLE', 'MARROW_APPROVAL_LINK_LIMITED', 'MARROW_APPROVAL_LINK_NOT_HELD',
+    'MARROW_APPROVAL_LINK_SCOPE_MISMATCH', 'MARROW_APPROVAL_LINK_INVALID', 'MARROW_APPROVAL_LINK_DECISION_REQUIRED',
+    'MARROW_PRE_ACTION_GATE_USED', 'MARROW_PRE_ACTION_GATE_EXPIRED', 'MARROW_OWNER_APPROVAL_ALREADY_DECIDED',
+    'MARROW_GATE_RECEIPT_NOT_FOUND',
+]);
+const MAX_OWNER_LINK_ATTEMPTS = 3;
 function autoPartial(input) {
     const resumable = input.resumable !== false;
     return {
@@ -1191,6 +1223,7 @@ function autoPartial(input) {
                 exact_next_action: 'Resume marrow_auto with this same operation_id, tenant, agent, session, action, surfaces, outcome, proof, and approval receipts after retry_after_ms. Pending is not confirmation of closure.',
             } : {}),
         ...(input.runtimeGate ? { runtime_gate: input.runtimeGate } : {}),
+        ...(input.approval ? { approval: input.approval } : {}),
         phase_timings_ms: {
             ...input.timings,
             total: Date.now() - input.startedAt,
@@ -1198,6 +1231,141 @@ function autoPartial(input) {
         http_attempt_trace: snapshotAutoHttpTrace(input.autoHttpTrace),
     };
 }
+function autoApprovalState(guidance, status, state) {
+    return {
+        state: state || status?.state || 'unavailable',
+        gate_receipt_id: guidance.gateReceiptId,
+        approver: guidance.approvalAuthority,
+        verified_approval_required: guidance.verifiedApprovalRequired,
+        verified_approval_categories: guidance.verifiedApprovalCategories,
+        approval_source: status?.approval_source ?? null,
+        answered_by: status?.approval_answered_by ?? null,
+        poll_after_ms: status?.poll_after_ms ?? guidance.pollAfterMs,
+        expires_at: status?.expires_at ?? guidance.expiresAt,
+    };
+}
+/**
+ * What the status says about an approval of this receipt. "The account owner"
+ * only for the owner's verified approval; anything else is named for what it is.
+ */
+function approvalStatement(status, gateReceiptId) {
+    if (status.approval_source === 'host_prompt') {
+        return status.approval_answered_by === 'host_operator' ? `The operator approved gate receipt ${gateReceiptId} in the host prompt (client-attested).`
+            : status.approval_answered_by === 'owner_chat_preapproval' ? `The account owner's chat pre-approval covers gate receipt ${gateReceiptId} (client-attested).`
+                : `An allow rule in the host approved gate receipt ${gateReceiptId} (client-attested).`;
+    }
+    if (status.approval_trust === 'verified'
+        && (status.approval_answered_by === 'account_owner' || status.approval_source === 'dashboard' || status.approval_source === 'one_tap')) {
+        return `The account owner approved gate receipt ${gateReceiptId}.`;
+    }
+    return `Marrow recorded an approval for gate receipt ${gateReceiptId}.`;
+}
+/** What happened to the owner's one-tap link in this operation. Never claims a send that did not happen. */
+function ownerLinkSentence(guidance, link) {
+    if (!guidance.hostApprovalSupported) {
+        return 'This Marrow service does not support chat or terminal approvals yet, so only the account owner can approve it.';
+    }
+    if (link?.sent)
+        return `An approval link was sent to the account owner${link.channel ? ` (${link.channel})` : ''}.`;
+    if (link?.final) {
+        return `Marrow could not send the account owner an approval link${link.finalCode ? ` (${link.finalCode})` : ''}; tell the operator this action is waiting for the account owner's approval.`;
+    }
+    if (link?.notSent)
+        return 'Nothing was sent to anyone; it waits quietly until a person approves it.';
+    if (link && link.attempts > 0) {
+        return 'Marrow could not send the account owner an approval link yet; calling marrow_auto again with this same operation_id tries again.';
+    }
+    // Owner rule: an ordinary hold sends no email. It waits quietly.
+    return 'Nobody can approve it from this tool call, so it waits quietly; nothing was sent to anyone. Carry on with other work; a person approves it at their next interactive session, where the host asks them.';
+}
+/**
+ * The text an agent follows while auto waits on a held action. It never asks
+ * the agent to write an approval: only the account owner (one-tap link) or
+ * the operator's host prompt can approve, and the server records it.
+ */
+function ordinaryHoldWaitText(guidance, link) {
+    if (guidance.hostApprovalRefusal === 'owner_decline_stands' && !link?.sent) {
+        // The owner said no: the owner is asked again only when the operator asks.
+        const ask = guidance.approvalLinkPath
+            ? link && link.attempts > 0
+                ? ` ${ownerLinkSentence(guidance, link)}`
+                : ' If the operator asks you to ask the owner again, call marrow_auto again with this same operation_id and request_owner_link: true; Marrow then sends the owner a one-tap approval link.'
+            : '';
+        return `Marrow is holding this action (gate receipt ${guidance.gateReceiptId}). Do not run it. The account owner declined this action${guidance.ownerDeclinedAt ? ` at ${guidance.ownerDeclinedAt}` : ' earlier'}, and only the owner can reverse that.${ask} Never write or claim an approval yourself.`;
+    }
+    const why = guidance.verifiedApprovalRequired === true
+        ? ` The account owner approves ${guidance.verifiedApprovalCategories.join(', ') || 'these'} actions personally.`
+        : guidance.hostApprovalRefusal === 'owner_decline_stands'
+            ? ` The account owner declined this action${guidance.ownerDeclinedAt ? ` at ${guidance.ownerDeclinedAt}` : ' earlier'}.`
+            : '';
+    return `Marrow is holding this action for approval (gate receipt ${guidance.gateReceiptId}). Do not run it yet.${why} ${ownerLinkSentence(guidance, link)} Call marrow_auto again with this same operation_id after retry_after_ms; Marrow resumes on the same gate receipt once it is approved. Never write or claim an approval yourself.`;
+}
+/**
+ * Asks Marrow to send the account owner a one-tap link once per operation; a
+ * retryable failure is tried again on a later call, within the server's limit.
+ */
+async function requestAutoOwnerLink(input) {
+    const previous = input.binding.ownerLink;
+    // Nothing was sent because nobody had asked: the operator asking now is a new request.
+    const askedAfterQuiet = previous?.notSent === true && input.personPresent === true;
+    if (previous?.sent || (previous?.final && !askedAfterQuiet) || (previous?.attempts ?? 0) >= MAX_OWNER_LINK_ATTEMPTS)
+        return;
+    const attempts = (previous?.attempts ?? 0) + 1;
+    const timeout = createTimeoutSignal(input.timeoutMs);
+    try {
+        const link = await marrowRequestApprovalLink(input.apiKey, input.baseUrl, input.gateReceiptId, input.decisionId, input.sessionId, input.agentId, timeout.signal, typeof input.personPresent === 'boolean' ? { personPresent: input.personPresent } : {});
+        if (link.ok) {
+            input.binding.ownerLink = { sent: true, ...(link.alreadySent ? { alreadySent: true } : {}), expiresAt: link.link.expires_at ?? null, channel: link.link.channel, attempts, finalCode: null, final: false };
+        }
+        else if (link.notSent) {
+            input.binding.ownerLink = { sent: false, notSent: true, channel: null, attempts, finalCode: link.code, final: true };
+        }
+        else {
+            const final = (!link.retryable && Boolean(link.code && FINAL_OWNER_LINK_CODES.has(link.code))) || attempts >= MAX_OWNER_LINK_ATTEMPTS;
+            input.binding.ownerLink = { sent: false, channel: null, attempts, finalCode: link.code, final };
+        }
+    }
+    catch {
+        input.binding.ownerLink = { sent: false, channel: null, attempts, finalCode: null, final: attempts >= MAX_OWNER_LINK_ATTEMPTS };
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+async function readOrdinaryApprovalForAuto(input) {
+    let status = null;
+    const maxReads = Math.max(1, Math.min(3, input.maxReads ?? 3));
+    // Poll as the server advises, inside auto's bounded response budget.
+    for (let reads = 0; reads < maxReads; reads += 1) {
+        const remaining = input.responseBudgetMs - (Date.now() - input.startedAt) - AUTO_RESPONSE_DEADLINE_MARGIN_MS;
+        if (remaining < 250)
+            break;
+        const timeout = createTimeoutSignal(input.responseBudgetMs, input.startedAt);
+        try {
+            const result = await marrowOwnerApprovalStatus(input.apiKey, input.baseUrl, input.guidance.gateReceiptId, input.sessionId, input.agentId, timeout.signal);
+            if (result.kind === 'not_found')
+                return { status: null, notFound: true };
+            status = result.status;
+        }
+        catch (error) {
+            const failure = (0, request_reliability_1.normalizeRequestError)(error);
+            if (failure.retryable || failure.code === 'request_timeout')
+                break;
+            throw error;
+        }
+        finally {
+            timeout.cancel();
+        }
+        if (!status || (status.state !== 'pending' && status.state !== 'unavailable' && status.state !== 'arbitration_review'))
+            break;
+        if (reads + 1 >= maxReads)
+            break;
+        const waitMs = status.poll_after_ms ?? input.guidance.pollAfterMs;
+        if (!await waitForAutoContinuation({ retry_after_ms: waitMs }, input.startedAt, input.responseBudgetMs, input.autoHttpTrace))
+            break;
+    }
+    return { status, notFound: false };
+}
 /**
  * Bounded outcome logging helper for tool hooks and simple integrations.
  * One outer invocation logs intent and, when an outcome is supplied, continues
@@ -1205,16 +1373,78 @@ function autoPartial(input) {
  * caller's deadline is reached, the same operation ID resumes without opening
  * another decision.
  */
-async function marrowAuto(apiKey, baseUrl, params, sessionId, agentId, timeoutMs) {
+async function marrowAuto(apiKey, baseUrl, params, sessionId, agentId, timeoutMs, options) {
     const autoHttpTrace = { attempts: [], dropped_count: 0 };
     try {
-        return await marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId, timeoutMs, autoHttpTrace);
+        const result = await marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId, timeoutMs, autoHttpTrace, options);
+        // The runtime's next-step texts are written for API clients (endpoints to
+        // call); the raw runtime_gate an agent reads never carries them.
+        return result.runtime_gate ? { ...result, runtime_gate: withoutServerNextActions(result.runtime_gate) } : result;
     }
     catch (error) {
         throw attachAutoHttpTrace(error, autoHttpTrace);
     }
 }
-async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId, timeoutMs, autoHttpTrace) {
+/** Removes every exact_next_action(s) from a server response (bounded depth). */
+function withoutServerNextActions(value, depth = 0) {
+    if (depth > 16 || !value || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => withoutServerNextActions(item, depth + 1));
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (key === 'exact_next_action' || key === 'exact_next_actions')
+            continue;
+        out[key] = withoutServerNextActions(item, depth + 1);
+    }
+    return out;
+}
+/**
+ * The operator marker the backend needs to count an elicitation answer as the
+ * operator's. Client-attested: Marrow trusts the MCP client to show the dialog
+ * to a person (the agent cannot answer it through any tool argument). A client
+ * that let the model answer elicitation requests would make the agent's own
+ * answer count as the operator's.
+ */
+exports.ELICITATION_HOOK_EVENT = 'mcp_elicitation';
+async function elicitAutoApproval(input) {
+    const askedAt = new Date().toISOString();
+    const notice = input.guidance.operatorNotice ? ` Note: ${input.guidance.operatorNotice}` : '';
+    let answer = null;
+    try {
+        answer = await input.elicit({
+            gateReceiptId: input.guidance.gateReceiptId,
+            message: `Marrow holds this action for your approval: ${input.action}.${input.reason ? ` Reason: ${input.reason}` : ''}${notice} Approve only if you authorize this exact action.`.slice(0, 900),
+        });
+    }
+    catch {
+        answer = null;
+    }
+    if (!answer)
+        return null;
+    const report = {
+        verdict: answer,
+        host: input.host || 'other',
+        host_session_id: input.hostSessionId || input.sessionId || 'mcp-session',
+        hook_event: exports.ELICITATION_HOOK_EVENT,
+        pre_action_event_id: null,
+        asked_at: askedAt,
+        answered_at: new Date().toISOString(),
+        ...(input.decisionId ? { decision_id: input.decisionId } : {}),
+    };
+    const timeout = createTimeoutSignal(4_000);
+    try {
+        const result = await marrowHostApproval(input.apiKey, input.baseUrl, input.guidance.gateReceiptId, report, input.sessionId, input.agentId, timeout.signal);
+        return result.ok ? answer : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId, timeoutMs, autoHttpTrace, options) {
     const startedAt = Date.now();
     const responseBudgetMs = autoResponseBudget(timeoutMs);
     const operationId = resolveAutoOperationId(params.operation_id);
@@ -1286,7 +1516,8 @@ async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId,
     }
     const thinkStarted = Date.now();
     let decisionId = operationBinding.decisionId || null;
-    const ordinaryApprovalDeclared = Boolean(runtimeGate && (0, runtime_contract_1.runtimeDeclaresOrdinaryOwnerApproval)(runtimeGate));
+    const ordinaryGuidance = runtimeGate ? (0, runtime_contract_1.ordinaryApprovalGuidance)(runtimeGate) : null;
+    const ordinaryApprovalDeclared = Boolean(ordinaryGuidance);
     if (runtimeGate && !runtimeGate.arbitration && (runtimeGate.decision_id || ordinaryApprovalDeclared)) {
         if (!(0, runtime_contract_1.runtimeDecisionMatchesAutoScope)(runtimeGate, {
             action: (0, redact_1.redactSensitiveText)(params.action_for_gate || params.action), agentId, sessionId,
@@ -1319,7 +1550,7 @@ async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId,
                 message: 'marrow_auto operation is already bound to a different decision than the runtime arbitration receipt.',
                 status: 409,
                 retryable: false,
-                exactFix: 'Stop this operation. Start a new arbitrated marrow_auto operation and preserve the arbitration decision_id, gate receipt, arbitration receipt, and dashboard approval receipt together.',
+                exactFix: 'Stop this operation. Start a new arbitrated marrow_auto operation and preserve the arbitration decision_id, gate receipt, arbitration receipt, and owner approval receipt together.',
             });
         }
         decisionId = arbitrationDecisionId;
@@ -1392,18 +1623,6 @@ async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId,
         }
     }
     timings.think = reusedDecision ? 0 : Date.now() - thinkStarted;
-    if (params.outcome === undefined || typeof params.success !== 'boolean') {
-        return autoPartial({
-            operationId,
-            decisionId,
-            phase: 'decision_created',
-            runtimeGate,
-            timings,
-            startedAt,
-            autoHttpTrace,
-            retryAfterMs: null,
-        });
-    }
     const runtimeReviewRequired = Boolean(runtimeGate && (runtimeGate.risk_gate?.decision === 'review_required'
         || runtimeGate.gate_receipt?.decision === 'review_required'
         || runtimeGate.gate_receipt?.decision === 'owner_approval_required'
@@ -1418,23 +1637,226 @@ async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId,
             || runtimeGate.arbitration.owner_approval_required === true));
     const genericReviewRequired = runtimeReviewRequired && !runtimeGate?.arbitration;
     const runtimeArbitrationReceiptId = runtimeGate?.arbitration?.receipt_id;
-    const matchingRequiredApprovalReceipts = Boolean(params.owner_approval_receipt_id
+    // Arbitration review with the server's one-tap path: the owner picks a
+    // proposal through a link, and the status read hands over the owner's receipt.
+    let ownerApprovalReceiptForCommit = params.owner_approval_receipt_id;
+    let arbitrationReceiptForCommit = params.arbitration_receipt_id;
+    const arbitrationGuidance = arbitrationRequiresOwnerApproval && !params.owner_approval_receipt_id
+        ? (0, runtime_contract_1.arbitrationApprovalGuidance)(runtimeGate)
+        : null;
+    if (arbitrationGuidance) {
+        const arbitrationWait = (exactNextAction, retryAfterMs, resumable = true) => autoPartial({
+            operationId, decisionId, phase: 'owner_approval_required', runtimeGate, timings, startedAt, autoHttpTrace,
+            resumable, retryAfterMs: retryAfterMs ?? undefined, exactNextAction,
+        });
+        const linkBudget = responseBudgetMs - (Date.now() - startedAt) - AUTO_RESPONSE_DEADLINE_MARGIN_MS - 300;
+        if (linkBudget > 300) {
+            await requestAutoOwnerLink({
+                apiKey, baseUrl, gateReceiptId: arbitrationGuidance.gateReceiptId, decisionId, sessionId, agentId,
+                binding: operationBinding, timeoutMs: Math.min(2_000, linkBudget),
+                // Client-attested: a person at this session asked only when the operator asked for the link.
+                personPresent: params.request_owner_link === true,
+            });
+        }
+        const read = await readOrdinaryApprovalForAuto({
+            apiKey, baseUrl, guidance: arbitrationGuidance, sessionId, agentId, startedAt, responseBudgetMs, autoHttpTrace,
+        });
+        const status = read.status;
+        const link = operationBinding.ownerLink;
+        const linkText = link?.alreadySent ? `The account owner already has a one-tap approval link${link.channel ? ` (${link.channel}${link.expiresAt ? `, until ${link.expiresAt}` : ''})` : ''}; wait for their answer.`
+            : link?.sent ? `An approval link was sent to the account owner${link.channel ? ` (${link.channel})` : ''}.`
+                : link?.notSent ? 'Nothing was sent to the account owner. If the operator wants the owner asked now, call marrow_auto again with this same operation_id and request_owner_link: true; Marrow then sends the owner a one-tap link.'
+                    : link?.final ? `Marrow could not send the account owner an approval link${link.finalCode ? ` (${link.finalCode})` : ''}; tell the operator this action is waiting for the account owner's choice.`
+                        : link && link.attempts > 0 ? 'Marrow could not send the account owner an approval link yet; calling marrow_auto again with this same operation_id tries again.'
+                            : 'Tell the operator this action is waiting for the account owner\'s choice.';
+        if (read.notFound) {
+            return arbitrationWait(`Marrow could not find gate receipt ${arbitrationGuidance.gateReceiptId} for this agent and session. Do not run any proposal; request fresh runtime guidance for it.`, null, false);
+        }
+        if (!status || status.state === 'arbitration_review' || status.state === 'pending' || status.state === 'unavailable') {
+            return arbitrationWait(`Marrow is holding this action for arbitration review (gate receipt ${arbitrationGuidance.gateReceiptId}). Do not run any proposal yet. The account owner picks and approves one proposal. ${linkText} Call marrow_auto again with this same operation_id after retry_after_ms. Never write or claim an approval yourself.`, status?.poll_after_ms ?? arbitrationGuidance.pollAfterMs);
+        }
+        if (status.state === 'approved' && status.owner_approval_receipt_id) {
+            ownerApprovalReceiptForCommit = status.owner_approval_receipt_id;
+            arbitrationReceiptForCommit = arbitrationGuidance.arbitrationReceiptId;
+        }
+        else if (status.state === 'used') {
+            return {
+                operation_id: operationId, decision_id: decisionId, committed: false, phase: 'closed', resumable: false, retry_after_ms: null,
+                exact_next_action: `Gate receipt ${arbitrationGuidance.gateReceiptId} is already used: this operation is closed. Do not run this action again.`,
+                runtime_gate: runtimeGate, closure: status.owner_approval_receipt_id ? 'already_closed' : 'already_closed_denial',
+                phase_timings_ms: { ...timings, total: Date.now() - startedAt }, http_attempt_trace: snapshotAutoHttpTrace(autoHttpTrace),
+            };
+        }
+        else if (status.state === 'declined') {
+            return arbitrationWait(`The account owner approved none of the proposals (gate receipt ${arbitrationGuidance.gateReceiptId}). Do not run any proposal. If nothing ran, close it with marrow_commit: success false, an outcome that starts "Denied by Marrow pre-action gate", and the same gate_receipt_id.`, null, false);
+        }
+        else {
+            return arbitrationWait(`Gate receipt ${arbitrationGuidance.gateReceiptId} is not waiting for the owner's choice (${status.state}). Do not run any proposal; request fresh runtime guidance for this exact action.`, null, false);
+        }
+    }
+    const matchingRequiredApprovalReceipts = Boolean(ownerApprovalReceiptForCommit
         && (!runtimeArbitrationReceiptId
-            || params.arbitration_receipt_id === runtimeArbitrationReceiptId));
-    if (genericReviewRequired && ordinaryApprovalDeclared && runtimeGate) {
-        if (!(0, runtime_contract_1.hasOrdinaryOwnerApprovalProof)(params.proof)) {
+            || arbitrationReceiptForCommit === runtimeArbitrationReceiptId));
+    // An ordinary hold: wait for the approval through the agent-key status read
+    // (bounded by this call's budget), then resume on the same gate receipt.
+    // Approval comes only from the server (the account owner's one-tap link, or
+    // the operator's host prompt recorded by the host hook), never from proof.
+    let ordinaryApproval = null;
+    let ordinaryApprovalState;
+    if (genericReviewRequired && ordinaryGuidance && runtimeGate) {
+        // In flow first: where the MCP client can ask its user (elicitation), the
+        // person answers right here, once per held action; the answer is reported
+        // through the host-approval route (client-attested), never by the agent.
+        let elicited = null;
+        if (ordinaryGuidance.hostApprovalAccepted && options?.elicitApproval && !operationBinding.elicitedReceipts?.includes(ordinaryGuidance.gateReceiptId)) {
+            operationBinding.elicitedReceipts = [...(operationBinding.elicitedReceipts || []), ordinaryGuidance.gateReceiptId].slice(-8);
+            elicited = await elicitAutoApproval({
+                apiKey, baseUrl, guidance: ordinaryGuidance, decisionId, sessionId, agentId,
+                action: (0, redact_1.redactSensitiveText)(params.action_for_gate || params.action).slice(0, 300),
+                reason: typeof runtimeGate.risk_gate?.reasons?.[0]?.message === 'string' ? runtimeGate.risk_gate.reasons[0].message.slice(0, 240) : '',
+                elicit: options.elicitApproval,
+                host: options.elicitHost,
+                hostSessionId: options.elicitHostSessionId,
+            });
+        }
+        // Owner rule: the owner's link only for an owner-locked category, the owner's
+        // own standing decline when the operator asks, or (with no way to ask anyone
+        // here) an unattended run whose owner turned on pings. Otherwise quiet.
+        const policy = (0, runtime_contract_1.ownerLinkPolicy)(ordinaryGuidance, { unattended: !options?.elicitApproval });
+        const linkWanted = elicited === null && (policy === 'now' || (policy === 'on_request' && params.request_owner_link === true));
+        const linkBudget = responseBudgetMs - (Date.now() - startedAt) - AUTO_RESPONSE_DEADLINE_MARGIN_MS - 300;
+        if (ordinaryGuidance.approvalLinkPath && linkWanted && linkBudget > 300) {
+            await requestAutoOwnerLink({
+                apiKey, baseUrl, gateReceiptId: ordinaryGuidance.gateReceiptId, decisionId, sessionId, agentId,
+                binding: operationBinding, timeoutMs: Math.min(2_000, linkBudget),
+            });
+        }
+        // After a person answered here, read the status once with its own time (the answer took human time).
+        const read = elicited
+            ? await readOrdinaryApprovalForAuto({
+                apiKey, baseUrl, guidance: ordinaryGuidance, sessionId, agentId, startedAt: Date.now(), responseBudgetMs, autoHttpTrace,
+            })
+            : await readOrdinaryApprovalForAuto({
+                apiKey, baseUrl, guidance: ordinaryGuidance, sessionId, agentId, startedAt, responseBudgetMs, autoHttpTrace,
+                maxReads: ordinaryGuidance.hostApprovalSupported ? 3 : 1,
+            });
+        const status = read.status;
+        ordinaryApprovalState = autoApprovalState(ordinaryGuidance, status, read.notFound ? 'not_found' : undefined);
+        const terminal = (exactNextAction) => autoPartial({
+            operationId, decisionId, phase: 'review_required', runtimeGate, timings, startedAt, autoHttpTrace,
+            resumable: false, exactNextAction, approval: ordinaryApprovalState,
+        });
+        if (read.notFound) {
+            return terminal(`Marrow could not find gate receipt ${ordinaryGuidance.gateReceiptId} for this agent and session. Do not run the action; request fresh runtime guidance for it.`);
+        }
+        if (!status || status.state === 'pending' || status.state === 'unavailable') {
             return autoPartial({
                 operationId, decisionId, phase: 'owner_approval_required', runtimeGate, timings, startedAt, autoHttpTrace,
-                resumable: false,
-                exactNextAction: 'Wait for explicit owner approval of this exact work. Then supply the server-supported proof.owner_approval object with the required measured proof and call marrow_auto with this same operation_id. Preserve the original decision and gate receipt. Do not infer or manufacture approval.',
+                resumable: true,
+                retryAfterMs: status?.poll_after_ms ?? ordinaryGuidance.pollAfterMs,
+                exactNextAction: ordinaryHoldWaitText(ordinaryGuidance, operationBinding.ownerLink),
+                approval: ordinaryApprovalState,
             });
         }
-        proofCanClose = (0, runtime_contract_1.ordinaryOwnerApprovalCanAttemptCommit)(runtimeGate, params.proof, gateReceiptId);
+        if (status.state === 'declined') {
+            const declinedBy = status.approval_source === 'host_prompt' ? 'The operator declined it in the host prompt' : 'The account owner declined it';
+            if (params.outcome === undefined && decisionId && Date.now() - startedAt < responseBudgetMs - 250) {
+                // The action has not run: close the decision as a verified gate denial.
+                const denialTimeout = createTimeoutSignal(responseBudgetMs, startedAt);
+                try {
+                    const denial = await marrowCommit(apiKey, baseUrl, {
+                        decision_id: decisionId,
+                        success: false,
+                        outcome: `Denied by Marrow pre-action gate: ${declinedBy.charAt(0).toLowerCase()}${declinedBy.slice(1)} (gate receipt ${ordinaryGuidance.gateReceiptId}); the action did not run.`,
+                        gate_receipt_id: gateReceiptId,
+                        auto_gate: false,
+                        [AUTO_MANAGED_WRITE]: true,
+                        [AUTO_HTTP_TRACE]: autoHttpTrace,
+                    }, sessionId, agentId, denialTimeout.signal, autoIdempotencyKey(operationId, 'commit'));
+                    if (denial.committed) {
+                        return {
+                            operation_id: operationId,
+                            decision_id: decisionId,
+                            committed: true,
+                            phase: 'closed',
+                            resumable: false,
+                            retry_after_ms: null,
+                            exact_next_action: `${declinedBy}. Marrow closed this decision as a denial. Do not run this action.`,
+                            runtime_gate: runtimeGate,
+                            approval: ordinaryApprovalState,
+                            closure: 'gate_denial',
+                            phase_timings_ms: { ...timings, total: Date.now() - startedAt },
+                            http_attempt_trace: snapshotAutoHttpTrace(autoHttpTrace),
+                        };
+                    }
+                }
+                catch { /* the decline stands; the denial closure stays open below */ }
+                finally {
+                    denialTimeout.cancel();
+                }
+            }
+            return terminal(`${declinedBy} (gate receipt ${ordinaryGuidance.gateReceiptId}). Do not run this action. If it has not run, close it with marrow_commit: success false, an outcome that starts "Denied by Marrow pre-action gate", and the same gate_receipt_id.`);
+        }
+        if (status.state === 'expired') {
+            return terminal(`Gate receipt ${ordinaryGuidance.gateReceiptId} expired before it was approved. Do not run the action on it. If the work is still needed and has not run, start a new marrow_auto operation for a fresh gate.`);
+        }
+        if (status.state === 'used') {
+            // A spent receipt is final: never resume from it, and never call it approved now.
+            const approvedBefore = Boolean(status.owner_approval_receipt_id);
+            return {
+                operation_id: operationId,
+                decision_id: decisionId,
+                committed: false,
+                phase: 'closed',
+                resumable: false,
+                retry_after_ms: null,
+                exact_next_action: approvedBefore
+                    ? `Gate receipt ${ordinaryGuidance.gateReceiptId} was approved and is already used: this operation is closed. Do not run this action again.`
+                    : `The approval request for gate receipt ${ordinaryGuidance.gateReceiptId} was declined, and the decision is closed as a denial. Do not run this action.`,
+                runtime_gate: runtimeGate,
+                approval: ordinaryApprovalState,
+                closure: approvedBefore ? 'already_closed' : 'already_closed_denial',
+                phase_timings_ms: { ...timings, total: Date.now() - startedAt },
+                http_attempt_trace: snapshotAutoHttpTrace(autoHttpTrace),
+            };
+        }
+        if (status.state === 'approved') {
+            ordinaryApproval = status;
+        }
+        else {
+            return terminal(`Gate receipt ${ordinaryGuidance.gateReceiptId} is not waiting for an approval (${status.state}). Do not run the action on it; stop this operation and request fresh runtime guidance for this exact action.`);
+        }
+    }
+    if (params.outcome === undefined || typeof params.success !== 'boolean') {
+        return autoPartial({
+            operationId,
+            decisionId,
+            phase: 'decision_created',
+            runtimeGate,
+            timings,
+            startedAt,
+            autoHttpTrace,
+            retryAfterMs: null,
+            ...(arbitrationGuidance && ownerApprovalReceiptForCommit ? {
+                exactNextAction: `The account owner approved one proposal for arbitration receipt ${arbitrationGuidance.arbitrationReceiptId} (owner_approval_receipt_id ${ownerApprovalReceiptForCommit}). Run only the approved proposal now, then call marrow_auto with this same operation_id, the real outcome and success${arbitrationGuidance.proofRequired ? `, and proof with ${arbitrationGuidance.proofFields.join(', ') || 'the required fields'}` : ''}. Marrow closes it with that receipt.`,
+            } : {}),
+            ...(ordinaryApproval && ordinaryGuidance ? {
+                exactNextAction: `${approvalStatement(ordinaryApproval, ordinaryGuidance.gateReceiptId)} Run only this exact action now, then call marrow_auto with this same operation_id, the real outcome and success${ordinaryGuidance.proofRequired ? `, and proof with ${ordinaryGuidance.proofFields.join(', ') || 'the required fields'}` : ''}. Marrow closes it on the same gate receipt.`,
+                approval: ordinaryApprovalState,
+            } : {}),
+        });
+    }
+    if (ordinaryApproval && ordinaryGuidance) {
+        // A proof-required hold closes trusted only with its proof; committing
+        // without it would leave an unverified observation that blocks the later
+        // trusted close, so auto waits for the proof instead.
+        const commitProof = withoutOwnerApprovalClaim(params.proof);
+        proofCanClose = !ordinaryGuidance.proofRequired || Boolean(commitProof && Object.keys(commitProof).length > 0);
         if (!proofCanClose) {
             return autoPartial({
-                operationId, decisionId, phase: 'review_required', runtimeGate, timings, startedAt, autoHttpTrace,
-                resumable: false,
-                exactNextAction: 'The original ordinary approval receipt is expired or its enforced completion contract is not valid. Stop and reconcile fresh server guidance for this exact operation before attempting commit.',
+                operationId, decisionId, phase: 'proof_required', runtimeGate, timings, startedAt, autoHttpTrace,
+                retryAfterMs: null, approval: ordinaryApprovalState,
+                exactNextAction: `Approved. Attach measured proof with ${ordinaryGuidance.proofFields.join(', ') || 'the required fields'} and call marrow_auto again with this same operation_id; Marrow closes it on gate receipt ${ordinaryGuidance.gateReceiptId}.`,
             });
         }
     }
@@ -1510,8 +1932,8 @@ async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId,
                 outcome: params.outcome,
                 proof: params.proof,
                 gate_receipt_id: gateReceiptId,
-                arbitration_receipt_id: params.arbitration_receipt_id,
-                owner_approval_receipt_id: params.owner_approval_receipt_id,
+                arbitration_receipt_id: arbitrationReceiptForCommit,
+                owner_approval_receipt_id: ownerApprovalReceiptForCommit,
                 action: params.action_for_gate || params.action,
                 type: params.type || 'general',
                 surfaces: params.surfaces,
@@ -1560,6 +1982,7 @@ async function marrowAutoWithTrace(apiKey, baseUrl, params, sessionId, agentId,
         resumable: false,
         retry_after_ms: null,
         ...(runtimeGate ? { runtime_gate: runtimeGate } : {}),
+        ...(ordinaryApprovalState ? { approval: { ...ordinaryApprovalState, state: 'used' } } : {}),
         phase_timings_ms: {
             ...timings,
             total: Date.now() - startedAt,
@@ -1978,6 +2401,298 @@ async function marrowAgentRuntime(apiKey, baseUrl, input, sessionId, agentId, si
     }
     return runtime;
 }
+const GATE_RECEIPT_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{2,199}$/;
+const OWNER_APPROVAL_STATES = new Set(['pending', 'approved', 'declined', 'expired', 'used', 'not_held', 'arbitration_review', 'unavailable']);
+const SAFE_STATUS_TEXT = (value, limit) => typeof value === 'string' && value.trim() ? (0, redact_1.redactSensitiveText)(value.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()).slice(0, limit) : null;
+const SAFE_STATUS_ID = (value) => typeof value === 'string' && GATE_RECEIPT_IDENTIFIER.test(value) ? value : null;
+const SAFE_STATUS_TIME = (value) => typeof value === 'string' && value.length <= 40 && Number.isFinite(Date.parse(value)) ? value : null;
+function normalizeOwnerApprovalStatus(value, gateReceiptId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const view = value;
+    if (view.gate_receipt_id !== gateReceiptId)
+        return null;
+    const state = typeof view.state === 'string' && OWNER_APPROVAL_STATES.has(view.state) ? view.state : 'unavailable';
+    return {
+        gate_receipt_id: gateReceiptId,
+        decision_id: SAFE_STATUS_ID(view.decision_id),
+        state,
+        gate_decision: SAFE_STATUS_TEXT(view.gate_decision, 64),
+        owner_approval_receipt_id: SAFE_STATUS_ID(view.owner_approval_receipt_id),
+        decided_at: SAFE_STATUS_TIME(view.decided_at),
+        approval_source: SAFE_STATUS_TEXT(view.approval_source, 32),
+        approval_trust: SAFE_STATUS_TEXT(view.approval_trust, 32),
+        approval_answered_by: SAFE_STATUS_TEXT(view.approval_answered_by, 32),
+        expires_at: SAFE_STATUS_TIME(view.expires_at),
+        terminal: view.terminal === true,
+        retryable: view.retryable === true,
+        poll_after_ms: typeof view.poll_after_ms === 'number' && Number.isFinite(view.poll_after_ms) ? (0, runtime_contract_1.boundedPollAfterMs)(view.poll_after_ms) : null,
+        exact_next_action: SAFE_STATUS_TEXT(view.exact_next_action, 600) || '',
+    };
+}
+/**
+ * GET /v1/agent/gate-receipts/:id/owner-approval with the agent's own key:
+ * whether a held gate receipt was approved (host prompt or dashboard),
+ * declined, expired or used. An unknown receipt, or one of another agent or
+ * session, answers not_found. Never authorizes anything by itself.
+ */
+async function marrowOwnerApprovalStatus(apiKey, baseUrl, gateReceiptId, sessionId, agentId, signal) {
+    if (!GATE_RECEIPT_IDENTIFIER.test(gateReceiptId))
+        throw new TypeError('gate_receipt_id is not a valid gate receipt identifier.');
+    return fetch(`${baseUrl}${(0, runtime_contract_1.ownerApprovalStatusPath)(gateReceiptId)}`, {
+        method: 'GET',
+        headers: buildHeaders(apiKey, sessionId, undefined, agentId),
+        signal,
+    }, {
+        consumeResponse: async (response) => {
+            if (response.status === 404) {
+                await response.body?.cancel().catch(() => undefined);
+                return { kind: 'not_found', status: null };
+            }
+            const json = await safeJsonResponse(response);
+            const status = normalizeOwnerApprovalStatus(json.data, gateReceiptId);
+            if (!status)
+                throw (0, request_reliability_1.invalidResponseError)();
+            return { kind: 'found', status };
+        },
+    });
+}
+function normalizeHostApprovalReceipt(value, gateReceiptId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const receipt = value;
+    if (receipt.gate_receipt_id !== gateReceiptId
+        || (receipt.verdict !== 'approved' && receipt.verdict !== 'declined')
+        || receipt.source !== 'host_prompt' || receipt.trust !== 'client_attested')
+        return null;
+    return {
+        owner_approval_receipt_id: SAFE_STATUS_ID(receipt.owner_approval_receipt_id),
+        owner_decline_receipt_id: SAFE_STATUS_ID(receipt.owner_decline_receipt_id),
+        gate_receipt_id: gateReceiptId,
+        decision_id: SAFE_STATUS_ID(receipt.decision_id),
+        verdict: receipt.verdict,
+        source: 'host_prompt',
+        trust: 'client_attested',
+        answered_by: receipt.answered_by === 'host_operator' || receipt.answered_by === 'owner_chat_preapproval' ? receipt.answered_by : 'host_allow_rule',
+        host: SAFE_STATUS_TEXT(receipt.host, 32) || 'other',
+        recorded_at: SAFE_STATUS_TIME(receipt.recorded_at) || '',
+        expires_at: SAFE_STATUS_TIME(receipt.expires_at) || '',
+    };
+}
+/**
+ * POST /v1/agent/gate-receipts/:id/approval-link: asks Marrow to send the
+ * account owner a one-tap approval link for one held receipt, to the owner's
+ * own channel. The response never contains the link; the owner approves
+ * without a login. Returns the channel only (no recipient details).
+ */
+async function marrowRequestApprovalLink(apiKey, baseUrl, gateReceiptId, decisionId, sessionId, agentId, signal, options = {}) {
+    if (!GATE_RECEIPT_IDENTIFIER.test(gateReceiptId))
+        throw new TypeError('gate_receipt_id is not a valid gate receipt identifier.');
+    const body = decisionId && GATE_RECEIPT_IDENTIFIER.test(decisionId) ? { decision_id: decisionId } : {};
+    if (typeof options.personPresent === 'boolean')
+        body.person_present = options.personPresent;
+    const result = await requestApprovalLinkOnce(apiKey, baseUrl, gateReceiptId, body, sessionId, agentId, signal);
+    // A service before round 6 refuses person_present as an unknown field: send the request without it.
+    if (!result.ok && 'person_present' in body && result.status === 400 && result.code === 'MARROW_APPROVAL_LINK_INVALID' && result.fields?.includes('person_present')) {
+        const { person_present: _omitted, ...plain } = body;
+        return requestApprovalLinkOnce(apiKey, baseUrl, gateReceiptId, plain, sessionId, agentId, signal);
+    }
+    return result;
+}
+async function requestApprovalLinkOnce(apiKey, baseUrl, gateReceiptId, body, sessionId, agentId, signal) {
+    return fetch(`${baseUrl}${(0, runtime_contract_1.approvalLinkPath)(gateReceiptId)}`, {
+        method: 'POST',
+        headers: buildHeaders(apiKey, sessionId, 'application/json', agentId),
+        body: JSON.stringify(body),
+        signal,
+    }, {
+        retryOwner: 'caller',
+        consumeResponse: async (response) => {
+            let json = null;
+            try {
+                if ((response.headers.get('content-type') || '').includes('json'))
+                    json = await response.json();
+                else
+                    await response.body?.cancel().catch(() => undefined);
+            }
+            catch (error) {
+                const failure = (0, request_reliability_1.normalizeRequestError)(error);
+                if (failure.code === 'request_timeout')
+                    throw failure;
+                json = null;
+            }
+            if (response.ok) {
+                const data = json?.data && typeof json.data === 'object' ? json.data : null;
+                // Quiet by default: the service sent nothing (owner_ping_off), stored nothing, counted nothing.
+                if (data?.sent === false && data.state === 'not_sent') {
+                    const reason = typeof data.reason === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(data.reason) ? data.reason : 'not_sent';
+                    return { ok: false, status: response.status, code: reason, retryable: false, notSent: true };
+                }
+                const link = data?.approval_link && typeof data.approval_link === 'object' ? data.approval_link : null;
+                // One live link per arbitration: a repeat names that link and sends nothing new.
+                const alreadySent = data?.sent === false && data.state === 'already_sent';
+                if (!link || (link.gate_receipt_id !== undefined && link.gate_receipt_id !== gateReceiptId) || (!alreadySent && link.gate_receipt_id !== gateReceiptId))
+                    throw (0, request_reliability_1.invalidResponseError)();
+                return { ok: true, ...(alreadySent ? { alreadySent: true } : {}), link: {
+                        channel: typeof link.channel === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(link.channel) ? link.channel : 'owner channel',
+                        expires_at: SAFE_STATUS_TIME(link.expires_at),
+                    } };
+            }
+            const details = json?.details && typeof json.details === 'object' && !Array.isArray(json.details)
+                ? json.details
+                : {};
+            const code = typeof details.code === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(details.code) ? details.code : null;
+            const fields = Array.isArray(details.fields) ? details.fields.filter((field) => typeof field === 'string').slice(0, 10) : undefined;
+            return { ok: false, status: response.status, code, retryable: response.status === 429 || response.status >= 500 || details.retryable === true, ...(fields ? { fields } : {}) };
+        },
+    });
+}
+/**
+ * GET /v1/agent/held-actions: the held actions still waiting for a person, for
+ * the next interactive session's "N held actions are waiting for you". null
+ * on a service without the read (404).
+ */
+async function marrowHeldActions(apiKey, baseUrl, query = {}, sessionId, agentId, signal) {
+    const params = new URLSearchParams({ scope: query.scope || 'agent', limit: String(Math.min(Math.max(Math.trunc(query.limit || 20), 1), 50)) });
+    return fetch(`${baseUrl}${exports.HELD_ACTIONS_PATH}?${params}`, {
+        method: 'GET',
+        headers: buildHeaders(apiKey, sessionId, undefined, agentId),
+        signal,
+    }, {
+        retryOwner: 'caller',
+        consumeResponse: async (response) => {
+            if (response.status === 404) {
+                await response.body?.cancel().catch(() => undefined);
+                return null;
+            }
+            if (!response.ok)
+                throw await (0, request_reliability_1.requestErrorFromResponse)(response);
+            const json = await safeJsonResponse(response);
+            const data = json.data && typeof json.data === 'object' ? json.data : null;
+            if (!data || !Array.isArray(data.holds))
+                throw (0, request_reliability_1.invalidResponseError)();
+            const holds = data.holds.slice(0, 50).flatMap((item) => {
+                if (!item || typeof item !== 'object')
+                    return [];
+                const hold = item;
+                const id = SAFE_STATUS_ID(hold.gate_receipt_id);
+                if (!id)
+                    return [];
+                return [{
+                        gate_receipt_id: id,
+                        agent_id: SAFE_STATUS_ID(hold.agent_id),
+                        decision_type: typeof hold.decision_type === 'string' && /^[A-Za-z0-9][A-Za-z0-9 _.:-]{0,63}$/.test(hold.decision_type) ? hold.decision_type : null,
+                        age_seconds: typeof hold.age_seconds === 'number' && Number.isFinite(hold.age_seconds) ? Math.max(0, Math.round(hold.age_seconds)) : 0,
+                        expired: hold.expired === true,
+                    }];
+            });
+            const count = typeof data.count === 'number' && Number.isInteger(data.count) && data.count >= holds.length ? Math.min(data.count, 500) : holds.length;
+            return { count, countCapped: data.count_capped === true, more: data.more === true, holds };
+        },
+    });
+}
+/**
+ * The account's owner-locked categories, for keeping those actions held on a
+ * machine that has not seen them yet while Marrow cannot be reached. Agent
+ * key; null on a service without the read (404). Proposed route:
+ * GET /v1/agent/approval-settings -> { verified_approval_categories, unattended_owner_ping }.
+ */
+async function marrowAgentApprovalSettings(apiKey, baseUrl, sessionId, agentId, signal) {
+    return fetch(`${baseUrl}${exports.AGENT_APPROVAL_SETTINGS_PATH}`, {
+        method: 'GET',
+        headers: buildHeaders(apiKey, sessionId, undefined, agentId),
+        signal,
+    }, {
+        retryOwner: 'caller',
+        consumeResponse: async (response) => {
+            if (response.status === 404) {
+                await response.body?.cancel().catch(() => undefined);
+                return null;
+            }
+            if (!response.ok)
+                throw await (0, request_reliability_1.requestErrorFromResponse)(response);
+            const json = await safeJsonResponse(response);
+            const data = json.data && typeof json.data === 'object' ? json.data : null;
+            if (!data || !Array.isArray(data.verified_approval_categories))
+                throw (0, request_reliability_1.invalidResponseError)();
+            return {
+                verified_approval_categories: data.verified_approval_categories
+                    .filter((item) => typeof item === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(item)).slice(0, 16),
+                unattended_owner_ping: typeof data.unattended_owner_ping === 'boolean' ? data.unattended_owner_ping : null,
+            };
+        },
+    });
+}
+exports.HELD_ACTIONS_PATH = '/v1/agent/held-actions';
+exports.AGENT_APPROVAL_SETTINGS_PATH = '/v1/agent/approval-settings';
+const HOST_APPROVAL_REPORT_FIELDS = ['verdict', 'host', 'host_session_id', 'hook_event', 'pre_action_event_id', 'asked_at', 'answered_at', 'decision_id', 'normalized_action'];
+/**
+ * POST /v1/agent/gate-receipts/:id/host-approval: the host's Marrow hook
+ * records the operator's answer in the host's own permission prompt (or a
+ * typed reply). Recorded client-attested; the server labels it an operator
+ * answer only with a dialog or typed-reply marker at a human pace. Hooks call
+ * this only for an answer the host actually reported; the model never does.
+ */
+async function marrowHostApproval(apiKey, baseUrl, gateReceiptId, report, sessionId, agentId, signal) {
+    if (!GATE_RECEIPT_IDENTIFIER.test(gateReceiptId))
+        throw new TypeError('gate_receipt_id is not a valid gate receipt identifier.');
+    const body = {};
+    for (const field of HOST_APPROVAL_REPORT_FIELDS) {
+        const value = report[field];
+        if ((field === 'decision_id' || field === 'normalized_action') && (value === undefined || value === null))
+            continue;
+        body[field] = value ?? null;
+    }
+    return fetch(`${baseUrl}${(0, runtime_contract_1.hostApprovalPath)(gateReceiptId)}`, {
+        method: 'POST',
+        headers: buildHeaders(apiKey, sessionId, 'application/json', agentId),
+        body: JSON.stringify(body),
+        signal,
+    }, {
+        // The caller resends the identical report; the server replays it.
+        retryOwner: 'caller',
+        consumeResponse: async (response) => {
+            let json = null;
+            try {
+                if ((response.headers.get('content-type') || '').includes('json'))
+                    json = await response.json();
+                else
+                    await response.body?.cancel().catch(() => undefined);
+            }
+            catch (error) {
+                const failure = (0, request_reliability_1.normalizeRequestError)(error);
+                if (failure.code === 'request_timeout')
+                    throw failure;
+                json = null;
+            }
+            if (response.ok) {
+                const data = json?.data && typeof json.data === 'object' ? json.data : null;
+                const receipt = normalizeHostApprovalReceipt(data?.host_approval, gateReceiptId);
+                if (!receipt)
+                    throw (0, request_reliability_1.invalidResponseError)();
+                return { ok: true, receipt, replayed: data?.replayed === true };
+            }
+            const details = json?.details && typeof json.details === 'object' && !Array.isArray(json.details)
+                ? json.details
+                : {};
+            const code = typeof details.code === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(details.code) ? details.code : null;
+            const existing = details.existing_verdict === 'approved' || details.existing_verdict === 'declined' ? details.existing_verdict : null;
+            const retryAfter = (0, request_reliability_1.responseRetryAfter)(response);
+            const fields = Array.isArray(details.fields)
+                ? details.fields.filter((item) => typeof item === 'string' && /^[a-z_]{1,64}$/.test(item)).slice(0, 10)
+                : [];
+            return {
+                ok: false,
+                status: response.status,
+                code,
+                existingVerdict: existing,
+                retryable: response.status === 429 || response.status >= 500 || details.retryable === true,
+                retryAfterMs: retryAfter.valid ? retryAfter.delayMs : null,
+                ...(fields.length ? { fields } : {}),
+            };
+        },
+    });
+}
 async function marrowEnforcement(apiKey, baseUrl, input, sessionId, agentId, signal) {
     const body = {
         ...input,