@decidio/sdk 0.11.0 → 0.12.0

package/dist/index.js

@@ -1,12 +1,13 @@
-import { DecidioSuspendedError, checkApproval } from "./resume.js";
-import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment } from "./signing.js";
+import { randomUUID } from "node:crypto";
+import { DecidioSuspendedError, checkApproval, claimApproval, newClaimKey, RETRY_DELAYS_MS } from "./resume.js";
+import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment, invocationRequestKey, ownRequestKey } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
-export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval, claimApproval, newClaimKey } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, boundScope, requestCommitment, idempotencyKey, committedRequestJson } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, boundScope, requestCommitment, idempotencyKey, invocationRequestKey, ownRequestKey, committedRequestJson } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
 export class DecidioBlockedError extends Error {
@@ -66,10 +67,12 @@ export function coreRequest(ctx, args) {
 export class DecidioTimeoutError extends Error {
     decisionId;
     withdrawn;
-    constructor(decisionId, withdrawn = false) {
+    shared;
+    constructor(decisionId, withdrawn = false, shared = false) {
         super(`Timed out waiting for human approval (${decisionId})`);
         this.decisionId = decisionId;
         this.withdrawn = withdrawn;
+        this.shared = shared;
         this.name = "DecidioTimeoutError";
     }
 }
@@ -78,12 +81,14 @@ export class DecidioRateLimitError extends Error {
     limit;
     remaining;
     resetAt;
-    constructor(limit, remaining, resetAt, serverMessage) {
+    code;
+    constructor(limit, remaining, resetAt, serverMessage, code) {
         super(`[decidio] governed-action rate limit reached${limit != null ? ` (${limit}/hour on this workspace)` : ""}${resetAt ? ` — resets ${resetAt}` : ""}. ` +
             `${serverMessage ? serverMessage + " " : ""}Nothing was routed or executed; retry after the reset.`);
         this.limit = limit;
         this.remaining = remaining;
         this.resetAt = resetAt;
+        this.code = code;
         this.name = "DecidioRateLimitError";
     }
 }
@@ -97,8 +102,9 @@ export class DecidioNetworkError extends Error {
                 ? `A refused localhost connection usually means the SDK never saw your config: if your settings live in .env, run node with --env-file=.env (or export DECIDIO_API_URL — the hosted sandbox is https://decidio-api.onrender.com). `
                 : "") +
             `Nothing was executed locally and no verdict was received — if a request reached Decidio it is ` +
-            `visible in your queue. Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe ` +
-            `(a retry creates a new request — it can never double-execute).`);
+            `visible in your queue. ` +
+            (/\/agent\/authorize/.test(op) ? `This SDK already retried it with the same request key. ` : "") +
+            `Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe — it can never double-execute.`);
         this.endpoint = endpoint;
         this.op = op;
         this.code = code;
@@ -132,7 +138,7 @@ async function post(cfg, path, body) {
     });
     if (res.status === 429) {
         const b = await res.json().catch(() => null);
-        throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
+        throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message, typeof b?.code === "string" ? b.code : undefined);
     }
     if (!res.ok) {
         const raw = await res.text().catch(() => "");
@@ -145,6 +151,56 @@ async function post(cfg, path, body) {
     }
     return res.json();
 }
+function retriesSafely(e) {
+    if (e instanceof DecidioNetworkError)
+        return true;
+    if (e instanceof DecidioRateLimitError)
+        return e.code !== "AGENT_RATE";
+    if (e instanceof DecidioHttpError)
+        return (e.status >= 500 && e.status !== 501) || (e.status === 429 && e.body?.code !== "AGENT_RATE");
+    return false;
+}
+export async function sendAuthorize(config, first, opts = {}) {
+    const mayRetry = !!first.idempotencyKey || !first.requestCommitment;
+    let body = first;
+    const once = async () => {
+        if ((opts.rateLimit ?? "typed") === "typed")
+            return post(config, "/agent/authorize", body);
+        const f = config.fetchImpl ?? fetch;
+        assertSafeTransport(config.apiUrl, carriesCredential(config));
+        const res = await reach(f, config.apiUrl.replace(/\/$/, "") + "/agent/authorize", "POST /agent/authorize", {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const raw = await res.text().catch(() => "");
+            let parsed = raw;
+            try {
+                parsed = raw ? JSON.parse(raw) : undefined;
+            }
+            catch { }
+            throw new DecidioHttpError(res.status, "/agent/authorize", parsed);
+        }
+        return res.json();
+    };
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await once();
+        }
+        catch (e) {
+            if (!mayRetry || attempt >= RETRY_DELAYS_MS.length || !retriesSafely(e))
+                throw e;
+            await sleep(RETRY_DELAYS_MS[attempt]);
+            const fresh = first.requesterIdentity && opts.resign ? opts.resign() : undefined;
+            if (fresh)
+                body = { ...first, requesterIdentity: fresh };
+        }
+    }
+}
+export function claimRefusal(claim) {
+    return new DecidioBlockedError(claim.ok ? "the approval was collected" : claim.reason, claim.decisionId);
+}
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
     assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
@@ -190,13 +246,30 @@ export function withApproval(fn, describe, config, opts) {
         const material = bindingMaterial(config);
         const committed = coreRequest(ctx, args);
         const sentCommitment = material ? requestCommitment(material, committed) : undefined;
-        const auth = await post(config, "/agent/authorize", {
+        let requestKey;
+        if (opts?.requestKey) {
+            const own = opts.requestKey(...args);
+            if (typeof own !== "string" || own.length === 0)
+                throw new Error(`[decidio] requestKey(...) must return a non-empty string naming this call (got ${JSON.stringify(own ?? null)}). Nothing was routed or executed.`);
+            if (!material)
+                throw new Error("[decidio] requestKey needs this agent's key material (DECIDIO_AGENT_KEY + DECIDIO_AGENT_DID, or DECIDIO_API_TOKEN): a key rides only beside the request commitment that material makes, and Decidio refuses one alone. Nothing was routed or executed.");
+            requestKey = ownRequestKey(material, own);
+        }
+        else if (material && sentCommitment) {
+            requestKey = invocationRequestKey(material, config.invocationId ? String(config.invocationId()) : randomUUID(), sentCommitment);
+        }
+        const auth = await sendAuthorize(config, {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
             ...(ctx.context ? { context: ctx.context } : {}),
             ...(requesterIdentity ? { requesterIdentity } : {}),
             ...(resumeUrl ? { resumeUrl } : {}),
             ...(sentCommitment ? { requestCommitment: sentCommitment } : {}),
+            ...(requestKey ? { idempotencyKey: requestKey } : {}),
+        }, {
+            resign: () => (config.agentKey && config.agentDid)
+                ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
+                : undefined,
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
@@ -238,13 +311,18 @@ export function withApproval(fn, describe, config, opts) {
                 if (Date.now() > deadline) {
                     let withdrawn = false;
                     let lateState = null;
-                    try {
-                        await post(config, `/agent/withdraw/${encodeURIComponent(auth.decisionId)}`, { reason: "timeout" });
-                        withdrawn = true;
-                    }
-                    catch (e) {
-                        if (e instanceof DecidioHttpError && e.status === 409 && typeof e.body?.state === "string")
-                            lateState = e.body.state;
+                    let shared = auth.idempotentReplay === true || auth.openTwin === true;
+                    if (!shared) {
+                        try {
+                            await post(config, `/agent/withdraw/${encodeURIComponent(auth.decisionId)}`, { reason: "timeout" });
+                            withdrawn = true;
+                        }
+                        catch (e) {
+                            if (e instanceof DecidioHttpError && e.status === 409 && typeof e.body?.state === "string")
+                                lateState = e.body.state;
+                            else if (e instanceof DecidioHttpError && e.status === 409 && e.body?.code === "SHARED_REQUEST")
+                                shared = true;
+                        }
                     }
                     if (lateState === "approved" || lateState === "auto_approved")
                         break;
@@ -252,14 +330,19 @@ export function withApproval(fn, describe, config, opts) {
                         throw new DecidioRejectedError("rejected by approver", auth.decisionId);
                     if (lateState === "blocked")
                         throw new DecidioBlockedError("blocked", auth.decisionId);
-                    console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} ${withdrawn ? "was withdrawn in Decidio (the queue no longer shows it; a later approval does nothing)" : "is still open in Decidio (the withdraw call failed), but this process stopped waiting"} and nothing was executed. Re-run to request again, or use durable resume (guard.worker()) so an approval is never lost.`);
-                    throw new DecidioTimeoutError(auth.decisionId, withdrawn);
+                    console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} ${withdrawn ? "was withdrawn in Decidio (the queue no longer shows it; a later approval does nothing)" : shared ? "is shared with another caller (or an earlier try of this one), so it was left open for a person to decide - this process stopped waiting" : "is still open in Decidio (the withdraw call failed), but this process stopped waiting"} and nothing was executed. Re-run to request again, or use durable resume (guard.worker()) so an approval is never lost.`);
+                    throw new DecidioTimeoutError(auth.decisionId, withdrawn, shared);
                 }
                 await sleep(pollInterval);
             }
             const check = await checkApproval(config, auth.decisionId, committed, { sent: !!sentCommitment, ...(approvedStatus ? { status: approvedStatus } : {}) });
             if (!check.ok)
                 throw approvalRefusal(check);
+            if (check.state === "approved") {
+                const claimed = await claimApproval(config, auth.decisionId, newClaimKey());
+                if (!claimed.ok)
+                    throw claimRefusal(claimed);
+            }
         }
         const result = opts?.withContext
             ? await fn({ decisionId: auth.decisionId, attemptId: null, idempotencyKey: auth.decisionId }, ...args)
@@ -299,6 +382,6 @@ export function withApproval(fn, describe, config, opts) {
         }
         if (evidenceProblem)
             confirmation.evidenceError = evidenceProblem;
-        return { value: result, decisionId: auth.decisionId, confirmation };
+        return { value: result, decisionId: auth.decisionId, confirmation, ...(requestKey ? { requestKey } : {}) };
     };
 }

package/dist/inngest.d.ts

@@ -39,6 +39,7 @@ export type GateStepOutcome<R> =
     decisionId: string;
     value: R;
     confirmation: EvidenceOutcome;
+    requestKey?: string;
 }
 /** The action never ran — a human said no, or a rule blocked it — so there is nothing to confirm. */
  | {
@@ -70,6 +71,10 @@ export declare function decidioGateStep<R>(args: {
      *  path takes. This door's own confirm chokepoint tells callers to use it; until 0.2.0 no
      *  adapter door accepted one, so the advice was unfollowable everywhere it was printed. */
     evidence?: (result: R) => unknown;
+    /** Inngest's id for THIS function run - the handler's `runId` (0.12.0, 11f). The request key is keyed on it, so Inngest
+     *  retrying the authorize step is the same request while it waits. Without it the key is
+     *  over a fresh id for the call (a retried step may then ask again). */
+    runId?: string;
 }): Promise<GateStepOutcome<R>>;
 /**
  * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's

package/dist/inngest.js

@@ -4,7 +4,7 @@ import { approvalRefusal } from "./index.js";
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
 export async function decidioGateStep(args) {
     const { step, config, ctx } = args;
-    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx));
+    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx, typeof args.runId === "string" && args.runId ? { naturalId: { engine: "inngest", runId: args.runId, step: "decidio-authorize" } } : {}));
     assertAuthorizeVerdict(auth, auth?.decisionId);
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
@@ -31,7 +31,7 @@ export async function decidioGateStep(args) {
     }
     const result = await step.run("agent-action", args.run);
     const confirmation = await step.run("decidio-confirm", async () => gateConfirm(config, auth.decisionId, result, args.evidence));
-    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation };
+    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation, ...(typeof auth.requestKey === "string" ? { requestKey: auth.requestKey } : {}) };
 }
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";

package/dist/resume.d.ts

@@ -38,6 +38,13 @@ export interface PendingAction {
      *  compared with the commitment Decidio returns. Absent on entries parked before 0.7.0 (and by
      *  an agent with no key material), which are checked on Decidio's state alone. */
     requestCommitment?: string;
+    /** THE RUN'S CLAIM KEY (0.12.0, founder call 24): made at random when the action is parked, and the key this parked
+     *  action collects a person's approval with (POST /agent/claim) right before it runs. It lives HERE, with the parked
+     *  action, so every resume of it - a worker that restarts, a signal after a lost answer, a claim an operator released -
+     *  is the same run to Decidio (`again: true`), while another process that parked its own copy of the request holds its
+     *  own key and is told the approval was used. Covered by the payload signature. Absent on entries parked before 0.12.0:
+     *  those claim with a fresh key each time (a lost answer then costs a new approval, never a second run). */
+    claimKey?: string;
 }
 /** Where suspended actions live between request and approval. The default is a
  *  file store; swap in Redis/Postgres/your queue for production. AGENT-SIDE only —
@@ -636,7 +643,11 @@ export interface ResumeController extends ResumeConfig {
      *  /agent/status + the request commitment — `checkApproval`). Decidio still pending → `not_approved`;
      *  Decidio says rejected/blocked → recorded as that denial; an approval that cannot be tied to these
      *  arguments → `request_unverified`. A transport failure during that check throws (nothing ran). A
-     *  `rejected`/`blocked` verdict is applied as given — it can only ever prevent execution. */
+     *  `rejected`/`blocked` verdict is applied as given — it can only ever prevent execution.
+     *
+     *  A PERSON'S approval is then COLLECTED ONCE (0.12.0, `claimApproval`) with the claim key parked with the action:
+     *  another run already used it, or it expired → `blocked` with the reason (recorded like a block; nothing ran); a 404
+     *  or a claim that could not be sent → throws (nothing ran, the entry stays parked for the next signal). */
     resolve(input: {
         decisionId: string;
         verdict: "approved" | "rejected" | "blocked";
@@ -704,7 +715,9 @@ export declare function assertConfirmRecorded(body: any, decisionId: string, sig
  *  authorized with, or null for a decision whose request was never bound. `spent` and `grantExpiresAt` (0.8.0,
  *  mini-approvals): the grant is ONE-TIME - `spent` once an execution was recorded on it, `grantExpiresAt` when
  *  it lapses (the seal's time plus the gate's TTL) for a granted decision, null otherwise. A gate that predates
- *  them answers neither. */
+ *  them answers neither. `handedBackAt` (when a replay handed the grant to a retry) and `claimed` (0.12.0: whether a
+ *  run has collected a person's approval - never by whom) are informational: reading the status claims NOTHING, and
+ *  this SDK decides a claim only by claiming (claimApproval). */
 export interface DecisionStatus {
     state: string;
     decisionId?: string;
@@ -713,6 +726,8 @@ export interface DecisionStatus {
     requestCommitment?: string | null;
     spent?: boolean;
     grantExpiresAt?: string | null;
+    handedBackAt?: string | null;
+    claimed?: boolean;
 }
 type StatusConfig = {
     apiUrl: string;
@@ -764,6 +779,41 @@ export declare function checkApproval(cfg: StatusConfig, decisionId: string, req
     sent?: boolean;
     status?: DecisionStatus;
 }): Promise<ApprovalCheck>;
+/** How long the SDK waits before each retry of a call it may safely repeat (11f): the authorize POST (with the same
+ *  body, so the same request key) and the claim (with the same claim key). Bounded: two retries, then the failure is the
+ *  caller's to see. Python twin: RETRY_DELAYS. */
+export declare const RETRY_DELAYS_MS: readonly number[];
+/** The grammar the gate takes for a request key and a claim key alike. */
+export declare const REQUEST_KEY_RE: RegExp;
+/** A claim key: RANDOM PER RUN (two workers with one key would be one run to Decidio, and both would run). The durable
+ *  path makes one when it parks an action and keeps it there; the blocking wait and the OpenAI resume make one per call. */
+export declare function newClaimKey(): string;
+/** Why a claim did not let this run go ahead. already_used / expired / not_claimable are Decidio's FINAL answers (409):
+ *  this approval will never run here. not_found (404: no such decision for this credential, or a gate that predates
+ *  claims), refused (any other 4xx), unreachable (a network failure or a 5xx after the retries) and unrecognized (an
+ *  answer this SDK does not understand) may change - nothing ran, and a later try may succeed. */
+export type ClaimCode = "already_used" | "expired" | "not_claimable" | "not_found" | "refused" | "unreachable" | "unrecognized";
+/** The outcome of one claim. Plain JSON on purpose, like ApprovalCheck: an engine that must run HTTP in an activity
+ *  (Temporal) returns it across its serialization boundary. */
+export type ClaimOutcome = {
+    ok: true;
+    decisionId: string;
+    again: boolean;
+} | {
+    ok: false;
+    decisionId: string;
+    code: ClaimCode;
+    final: boolean;
+    reason: string;
+    status?: number;
+};
+/** COLLECT A PERSON'S APPROVAL FOR THIS RUN, ONCE (POST /agent/claim/:decisionId) - the step every door that RUNS on a
+ *  person's approval takes right before it runs: the blocking wait, the durable resume, Temporal and the OpenAI resume. The
+ *  first claim wins; the same key claiming again is the same run retrying (`again: true`); any other key is told the
+ *  approval was already used. Reading the status claims nothing, so nothing that only watches ever calls this. An
+ *  auto-approval is never claimed (it is never shared). Retried with the SAME key on a network failure or a 5xx; every
+ *  answer other than a 200 that says `claimed: true` means DO NOT RUN. Never throws for an answer - a refusal is a value. */
+export declare function claimApproval(cfg: StatusConfig, decisionId: string, claimKey: string): Promise<ClaimOutcome>;
 /** The webhook handlers' refusal when no webhook secret is configured - with the remedy. */
 /** The one remedy every webhook-secret refusal names (#4B review W3): the dedicated webhook secret - NEVER the
  *  server's API_AUTH_TOKEN, the admin bearer, which a refusal that said "the value your deployment signs

package/dist/resume.js

@@ -1,4 +1,4 @@
-import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, randomUUID } from "node:crypto";
+import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, randomUUID, randomBytes } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync, openSync, closeSync, fsyncSync, linkSync } from "node:fs";
 import { join } from "node:path";
 import { userInfo } from "node:os";
@@ -7,7 +7,7 @@ import { signConfirm, canonicalize as jcs, assertSafeTransport, carriesCredentia
 import { canonicalize as toCanonical, DecidioUnsafeArgumentsError } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody, tierConfirms, tombstoneTier } from "./evidence.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
-const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args, ...(p.requestCommitment !== undefined ? { requestCommitment: p.requestCommitment } : {}) }), "utf8");
+const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args, ...(p.requestCommitment !== undefined ? { requestCommitment: p.requestCommitment } : {}), ...(p.claimKey !== undefined ? { claimKey: p.claimKey } : {}) }), "utf8");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
     if (agentKey) {
@@ -882,6 +882,55 @@ export async function checkApproval(cfg, decisionId, request, opts = {}) {
     }
     return { ok: true, decisionId, state };
 }
+export const RETRY_DELAYS_MS = [300, 1_000];
+export const REQUEST_KEY_RE = /^[A-Za-z0-9._:-]{16,128}$/;
+export function newClaimKey() {
+    return `run_${randomBytes(18).toString("base64url")}`;
+}
+export async function claimApproval(cfg, decisionId, claimKey) {
+    const no = (code, reason, status) => ({ ok: false, decisionId, code, final: code === "already_used" || code === "expired" || code === "not_claimable", reason, ...(status !== undefined ? { status } : {}) });
+    if (typeof claimKey !== "string" || !REQUEST_KEY_RE.test(claimKey))
+        return no("refused", "this run's claim key is not one Decidio accepts (16-128 letters, digits, dot, colon, underscore or dash). Nothing ran.");
+    const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
+    const url = cfg.apiUrl.replace(/\/$/, "") + "/agent/claim/" + encodeURIComponent(decisionId);
+    let last = "";
+    for (let attempt = 0;; attempt++) {
+        let res;
+        try {
+            res = await f(url, { method: "POST", headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) }, body: JSON.stringify({ claimKey }) });
+        }
+        catch (e) {
+            last = `could not reach Decidio: ${e?.cause?.code ?? e?.code ?? e?.message ?? e}`;
+        }
+        if (res) {
+            const body = await res.json().catch(() => null);
+            if (res.status === 200) {
+                if (body && body.ok === true && body.claimed === true)
+                    return { ok: true, decisionId, again: body.again === true };
+                return no("unrecognized", "Decidio answered the claim with HTTP 200 but did not say this run collected the approval, and an answer this SDK does not understand is never permission. Nothing ran.", 200);
+            }
+            if (res.status === 409) {
+                const code = body?.code;
+                if (code === "ALREADY_USED")
+                    return no("already_used", "this approval was already used by another run. Ask again for a new approval. Nothing ran.", 409);
+                if (code === "EXPIRED")
+                    return no("expired", "this approval has expired. Ask again for a new approval. Nothing ran.", 409);
+                if (code === "NOT_CLAIMABLE")
+                    return no("not_claimable", "Decidio says this approval can't be collected by a run (only a person's approval is, and a deploy approval belongs to its deploy job). Nothing ran.", 409);
+                return no("unrecognized", `Decidio refused the claim with a code this SDK does not know (${JSON.stringify(code ?? null)}). Nothing ran.`, 409);
+            }
+            if (res.status === 404)
+                return no("not_found", "Decidio did not let this agent collect the approval (HTTP 404: it does not know this decision for this credential, or it predates approval claims). Nothing ran.", 404);
+            if (!(res.status === 429 || (res.status >= 500 && res.status !== 501)))
+                return no("refused", `Decidio refused to let this run collect the approval (HTTP ${res.status}). Nothing ran.`, res.status);
+            last = `HTTP ${res.status}`;
+        }
+        if (attempt >= RETRY_DELAYS_MS.length)
+            return no("unreachable", `could not collect the approval from Decidio after ${attempt + 1} tries (${last}). Nothing ran.`);
+        await sleep(RETRY_DELAYS_MS[attempt]);
+    }
+}
 const V2_STORE_METHODS = [
     "put", "get", "delete", "list",
     "claim", "markInvoking", "recordExecuted", "markIndeterminate", "markReported",
@@ -1125,6 +1174,25 @@ export function createDecidioResume(opts) {
             refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: ${check.reason}. Nothing ran; the parked entry is untouched for inspection. If the request really changed, reject this decision and re-run the action to request a fresh approval.`);
             return finish({ status: "request_unverified", decisionId, action: pending.action, reason: check.reason });
         }
+        if (check.state === "approved") {
+            let claimed;
+            try {
+                claimed = await claimApproval(ctrl, decisionId, pending.claimKey ?? newClaimKey());
+            }
+            catch (e) {
+                await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+                throw e;
+            }
+            if (!claimed.ok) {
+                if (claimed.final) {
+                    await ctrl.store.markDiscarded(decisionId, "blocked", claimed.reason);
+                    await ctrl.store.delete(decisionId);
+                    return finish({ status: "blocked", decisionId, action: pending.action, reason: claimed.reason });
+                }
+                await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+                throw new Error(`[decidio] ${decisionId}: ${claimed.reason} The entry stays parked; the next signal tries again with the same claim key.`);
+            }
+        }
         try {
             await ctrl.store.markInvoking(decisionId, attemptId);
         }
@@ -1194,10 +1262,11 @@ export function createDecidioResume(opts) {
             catch (e) {
                 throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} NOT parked and NOT executable — but decision ${p.decisionId} may already be routed; reject it in your queue: npx @decidio/sdk approvals reject ${p.decisionId}`, p.decisionId);
             }
-            const argsSig = signArgs(p, ctrl.agentKey, integrityKey());
+            const parked = { ...p, claimKey: p.claimKey ?? newClaimKey() };
+            const argsSig = signArgs(parked, ctrl.agentKey, integrityKey());
             if (!argsSig)
                 console.warn(`[decidio] parking ${p.decisionId} UNBOUND — no agent key or webhook secret to sign the payload with, so a modified pending file could not be detected. Run \`npx @decidio/sdk init\` to configure keys.`);
-            await ctrl.store.put({ ...p, createdAt: new Date().toISOString(), ...(argsSig ? { argsSig } : {}) });
+            await ctrl.store.put({ ...parked, createdAt: new Date().toISOString(), ...(argsSig ? { argsSig } : {}) });
         },
         async resolve(input) { return resolveCore(input); },
         webhookHandler() {
@@ -1478,7 +1547,7 @@ export function createDecidioResume(opts) {
                             else if (outcome.status === "rejected")
                                 console.error(`[decidio] resumed ${p.decisionId}: REJECTED — the parked "${p.action}" was discarded, nothing executed.`);
                             else if (outcome.status === "blocked")
-                                console.error(`[decidio] resumed ${p.decisionId}: BLOCKED by policy — the parked "${p.action}" was discarded, nothing executed.`);
+                                console.error(`[decidio] resumed ${p.decisionId}: BLOCKED ${outcome.reason ? `(${outcome.reason})` : "by policy"} — the parked "${p.action}" was discarded, nothing executed.`);
                             workerOpts?.onResolved?.(outcome);
                         }
                         catch (e) {

package/dist/signing.d.ts

@@ -126,6 +126,14 @@ export declare function requestCommitment(material: BindingMaterial, request: Co
 /** lowercase-hex idempotency key over an execution identity (e.g. LangGraph's thread + task +
  *  commitment), keyed so the host's thread ids never reach Decidio in the clear. */
 export declare function idempotencyKey(material: BindingMaterial, identity: Record<string, JsonValue>): string;
+/** THE REQUEST KEY A CALL SENDS BY DEFAULT (11f, founder 2026-10-30): an idempotency key over a per-call random id and
+ *  the request's commitment, so the SDK's own retry of one call is the same request (the gate answers the decision it
+ *  already made) while two calls stay two requests. Python twin: invocation_request_key. */
+export declare function invocationRequestKey(material: BindingMaterial, invocationId: string, commitment: string): string;
+/** A CALLER'S OWN REQUEST KEY (11f), e.g. an order id: keyed like every other identity, so the caller's id never reaches
+ *  Decidio in the clear. Deliberately NOT over the commitment: the same key for a changed request is the gate's 409
+ *  IDEMPOTENCY_CONFLICT, never a silent second request. Python twin: own_request_key. */
+export declare function ownRequestKey(material: BindingMaterial, key: string): string;
 /** The Claude Code hook's request scope: `cmd-` + 16 hex of a KEYED digest over the command text and its subject
  *  (chat approvals follow-up, invariant-guard 2026-10-15). The text may carry a credential the display redacts; an
  *  unkeyed digest sealed beside the redacted text would be an offline oracle for a weak password. Keyed under its own

package/dist/signing.js

@@ -198,6 +198,12 @@ export function requestCommitment(material, request) {
 export function idempotencyKey(material, identity) {
     return createHmac("sha256", bindingSubkey(material, "decidio.idempotency-key.v1")).update(canonicalJson(identity, "idempotency identity"), "utf8").digest("hex");
 }
+export function invocationRequestKey(material, invocationId, commitment) {
+    return idempotencyKey(material, { invocation: invocationId, commitment });
+}
+export function ownRequestKey(material, key) {
+    return idempotencyKey(material, { requestKey: key });
+}
 export function boundScope(material, text) {
     return "cmd-" + createHmac("sha256", bindingSubkey(material, "decidio.hook-scope.v1")).update(text, "utf8").digest("hex").slice(0, 16);
 }