@decidio/sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,7 +7,117 @@ allowlist. Each entry names what changed, what a reader must do on upgrade, and
 
 ## Unreleased
 
-## 0.10.0 — connect a coding assistant in one tap
+## 0.12.0 — request keys by default; an approval is collected once; the owner's guard controls
+
+- **A request key by default** (founder 11f). Every authorize that carries a request commitment now carries an
+  `idempotencyKey` too: a keyed digest of a fresh id for the call and the commitment. The SDK retries the authorize twice
+  (after 0.3 s and 1 s) with the same request when the network fails, on a 5xx, or on a 429 that is not the workspace's
+  hourly limit - so a retry never runs an action twice, and a retry of a request still waiting is answered with the one
+  already waiting. A 4xx is never retried. A retry signs a fresh
+  identity proof (its nonce is single-use); nothing else changes. No key material: no commitment and no key, as before.
+  - `withApproval(..., { requestKey: (...args) => string })` / `protect(..., { requestKey })` uses your own key (an order
+    id) instead, keyed before it is sent. The same key for a changed request is refused (409 IDEMPOTENCY_CONFLICT).
+  - The result names the key it sent: `ProtectedExecution.requestKey`. `ExecutionContext.idempotencyKey` stays the
+    decision id - keep using it downstream.
+  - The engines key on their own ids: OpenAI on the tool call id; Temporal on the activity's workflow, run and activity
+    ids (`authorizeActivity`, new); Inngest on `runId` (new argument of `decidioGateStep`).
+- **An approval is collected once** (founder call 24 "(a)"). Before the SDK runs an action on a person's approval it
+  claims it (`POST /agent/claim/<decisionId>`, `claimApproval`) with a key random to that run, and runs only if Decidio
+  says this run collected it. Otherwise it raises `DecidioBlockedError` in plain words, e.g. "This approval was already
+  used by another run. Ask again for a new approval." This covers the blocking wait, the durable resume, Temporal and the
+  OpenAI verified resume. A durable action keeps its claim key with it (`PendingAction.claimKey`), so a restarted worker
+  claims with the same key and is answered as the same run; a claim refused as used or expired is recorded like a block
+  (`status: "blocked"` with the reason). Auto-approvals are never claimed, and reading the status never claims.
+- **A shared request is left open.** The blocking timeout no longer withdraws a request the authorize answered as
+  `idempotentReplay` or `openTwin`, and a 409 `SHARED_REQUEST` from the withdraw is reported, not thrown:
+  `DecidioTimeoutError.shared` is true and `withdrawn` false.
+- The messages that said "a retry creates a NEW request" now say the SDK already retried with the same request.
+
+On upgrade: the gate must have `POST /agent/claim` (the server's claim-once release). Against an older gate the claim
+answers 404 and nothing runs on a person's approval - durable entries stay parked until the gate is upgraded. Temporal:
+pass `claim: (decisionId, claimKey) => executeActivity(claimActivity, decisionId, claimKey)` (the activity returns
+`claimApprovalActivity(config, decisionId, claimKey)`) beside `verify` - an injected `authorize` without it is refused
+before anything is routed - and return `authorizeActivity(config, ctx)` from the authorize activity. Entries parked by an
+older SDK (or put into a store directly) still resume, but carry no claim key: they claim with a fresh random key on
+every resolve, so an answer lost on the way back costs a new approval - never a second run. Proved by: smoke.ts
+(256 -> 292), adapters-smoke.ts (74 -> 83), cli-smoke.ts (416 -> 418), the conformance runners (a refusal-advice vector)
+and the three-door gate (the authorize bodies stay byte-identical with a pinned invocation id).
+
+### The owner's guard controls (connect-once slice 4)
+
+Cycle connect-once's slice 4 (founder 2026-10-30: "the owner would have controls to make the guard mandatory, disable pause").
+Upgrade: nothing to do for a person; a team that wants its repositories held runs `connect --team` again and commits the file.
+
+- **A team's committed hook line carries its guard policy key.** `connect --team` writes `--policy=<key>` into the tell line
+  (Team and Enterprise). A computer that isn't connected sends the key when it starts its link, and the start answers one
+  yes/no: whether the workspace owner holds computers that aren't connected. Held, a destructive command is refused until the
+  computer connects, instead of being told once and let through. If Decidio can't answer (unreachable, a server error, rate
+  limited), a keyed line holds; Decidio's connect switched off (404) falls back to the line's own `--unconnected`. An older
+  server that refuses the key is asked again without it. Editing the key out of the line is switching the check off, so it
+  is refused like any other such edit. A keyed line tells once ONLY when Decidio answered for its key that the team doesn't hold
+  (or connect is switched off): a project `.env` naming an agent or another server, or a link another check is starting, holds.
+- **`connect --team` says when the line carries no team key** - a connection made before 0.12.0, or credentials from the shell
+  or `.env` - so the owner's hold won't reach the repository, and how to fix it (`connect --team --force`).
+- **Claude Code cloud sessions**: when the hook can't reach Decidio, it says the environment's network access must allow
+  Decidio's host, under Network access → Allowed domains (the default level doesn't list it), with the docs link.
+- **`hook managed-settings`** prints the Decidio hooks as JSON for Claude Code's managed settings (an organisation-wide
+  install), from the same set `hook install` writes - a test holds it equal to the plugin's `hooks.json`. Where the file goes,
+  and what it does and doesn't guarantee, go to stderr.
+- **The session line follows the owner's keep-on switch** from the next pause answer (the computer remembers it).
+- Proved by: cli-smoke 418 -> 427 (the keyed line held, told, unanswerable, a `.env` or a lock in the way, connect off, the key edited
+  out, the cloud network words, the keyless `--team` line, managed-settings equal to hooks.json, the remembered answer); connect.smoke and the integration suite on the server side. 
+
+
+## 0.11.0 — connect once, on in every project; no surprises; the connector connects a computer
+
+0.10.0's tag was held for this release, so 0.11.0 is the first release meant to carry `connect` (0.10.0 was then published by
+mistake on 2026-10-30, from a tag on its own merge; 0.11.0 supersedes it). It carries
+cycle connect-once's slice 1, 2a and 2b (founder 2026-10-29: one tag, after they merge).
+
+- **One connect per computer.** A connection now covers every repository on the computer, and `connect` switches the hook
+  on in your own `~/.claude/settings.json`, which every project reads. A repository connected the 0.10.0 way keeps its own
+  connection (read first). A cloud session and `--team` still use the repository's `.claude/settings.json`.
+- **The hook connects the computer itself.** A destructive command on a computer with no credential is refused with a link
+  and a short code (to Claude, and in a line to the person); once the workspace owner allows it, the next try finishes
+  connecting and asks for the approval in the same run. It never writes Claude Code's settings - in auto mode the assistant
+  may not, and a person put the hook there. Two hooks at once share one link. It connects only the Decidio your shell
+  names (or the default), never one a repository's `.env` names, and only over HTTPS; a project whose `.env` names an agent
+  with no token is refused by name rather than given the computer's connection. The run that connects tells the person which
+  workspace and who allowed it, even when the command then runs at once.
+- **The computer-wide hook is the pinned `npx -y @decidio/sdk@0.11.0` command**, so it works in every project; a project
+  install still writes `$CLAUDE_PROJECT_DIR` unescaped, so Claude Code expands it. The settings file is written whole, and
+  through a symlink.
+- **No surprises** (founder 2026-10-29: "the user is fully aware and not surprised"):
+  - `hook session`, a SessionStart hook: every session opens with one line - approvals are on here, what waits and for whom,
+    or that this computer isn't connected yet. Local only, never blocks;
+  - `connect` says what waits for approval and that everything else runs as before;
+  - a held command names who approves and where they see it;
+  - the plugin skill says what connecting does before doing it, and has the person run `! npx @decidio/sdk connect` when
+    auto mode refuses it.
+- **The plugin** (0.5.0) carries the SessionStart hook, and a marketplace file ready to publish - not published (founder:
+  nothing public until the listing is ready).
+- **The connector connects a computer** (slice 2a):
+  - `connect --ticket <ticket>` finishes the link the Decidio connector allowed (`connect_device` returns the ticket): the
+    poll carries this computer's own secret and the ticket, and only the credential is written;
+  - the hook names the connector's way first when a computer isn't connected (call `connect_device` with the code, run what
+    it returns), then the link and code; a link the connector allowed is kept while it waits for its ticket.
+- **Pause and resume** (slice 2b): `hook prompt`, a UserPromptSubmit hook that `hook install`, `connect` and the plugin add
+  behind a shell pre-filter, acts on the person's own typed "decidio pause" / "decidio start" (exact words, `source: user`
+  only) and keeps the words from the model. While paused a gated command runs with a line and no decision - asked of Decidio only
+  in a session paused on this computer; the settings guard (now run over the whole line, inside `sh -c` too, for the pause and
+  the shared file's notice alike) and the self-decide refusal stay on; an agent running `hook prompt` itself is refused. The
+  session line says how to pause, or that the organisation keeps the guard on.
+- **A shared file tells, then lets through** (slice 2a): `hook pretool --unconnected=tell`, which `connect` writes into a
+  shared file, refuses a computer with no credential once per session and command, then lets the same call pass with a line
+  to the person - never an `allow`, so Claude Code's own permission check still decides. No flag, a value it doesn't know,
+  or no session id holds, as before. `connect --team --hold-everyone` writes the holding hook instead.
+
+On upgrade: nothing to do; 0.10.0 repository connections keep working. Proved by: cli-smoke.ts (378 -> 400; slice 1: one connect for
+two repositories, the 0.10.0 file read first, the hook's own link - wait - collect-then-ask without touching settings, two
+hooks sharing a link, a refused link, the approver in holds, the session line, SessionStart installed; slice 2a: the
+connector's way, the ticket's usage, secret and ticket on the poll, tell once then a line, hold by default, --hold-everyone).
+
+## 0.10.0 — connect a coding assistant in one tap (not published; folded into 0.11.0)
 
 - **`npx @decidio/sdk connect`** (cycle connect). A coding assistant sets Decidio up for you: it runs `connect`, which prints a
   link and a short code (on a real terminal also a QR, and it opens the browser); the workspace owner opens the link signed in,
@@ -16,8 +126,8 @@ allowlist. Each entry names what changed, what a reader must do on upgrade, and
   ask-only credential - never a session - kept OUTSIDE the repository (the config dir, owner-only, keyed by the repository root
   and the Decidio), and the hooks switch on in `.claude/settings.local.json` (`--team`: the shared `.claude/settings.json`).
   No `.env`, nothing to paste, the word "agent" nowhere in the setup.
-- **In a cloud session the hooks go in `.claude/settings.json`.** A cloud session reads only the repository's own settings file,
-  never `.claude/settings.local.json` (Claude Code's docs), so that is where they work. connect leaves it uncommitted and says to ask
+- **In a cloud session the hooks go in `.claude/settings.json`.** A cloud session reads the repository's files, not your
+  computer's, and only the committed shared file reaches the next cloud machine, so that is where they go. connect leaves it uncommitted and says to ask
   the person before committing it (committed, every cloud session of the repository and every teammate's clone ask too). The
   credential is that cloud machine's: a fresh one refuses destructive commands until it connects again.
 - **The machine proves its key.** The start is signed with the machine's own key (the request-bound proof every signed

package/README.md

@@ -528,6 +528,9 @@ wake-up.
 - **Temporal**: whenever you pass `authorize`, also pass `verify: (id) => executeActivity(verifyActivity, id)`,
   where the activity returns `verifyApprovalActivity(config, id, ctx)` (from `@decidio/sdk/temporal`)
   for the same `ctx`. A signal only wakes the workflow; still pending → it waits for the next one.
+  Since 0.12.0 also pass `claim: (id, key) => executeActivity(claimActivity, id, key)`, where the
+  activity returns `claimApprovalActivity(config, id, key)`, and return `authorizeActivity(config, ctx)`
+  from the authorize activity: it keys the request on the activity's workflow, run and activity ids.
 - **Inngest**: the check runs as a memoized step after the event; a premature or forged event waits again.
 - **OpenAI Agents**: `applyResume(state, item, verdict)` is removed. Use
   `await applyVerifiedResume(config, state, item, decisionId, describe)`, which approves the
@@ -541,11 +544,16 @@ wake-up.
   whole node on resume, so an earlier gate in the same node runs again: if its request auto-approved and
   its action already ran, the replay answers `proceed` to your verified agent and the action runs twice.
   Put each gated action in its own node, or make the actions idempotent.
-- **Known limit — LangGraph and OpenAI Agents have no single-execution claim** (true before 0.7.0 too).
-  The checkpoint or the RunState is your storage, so two concurrent resumes of the same thread or run
-  can both pass the check and both run the action. Resume each one from one place (one worker per
-  thread/run id, or a lock). The core durable path claims each execution in its store; Temporal and
-  Inngest rely on their engine's own activity/step semantics.
+- **An approval is collected once (0.12.0).** Before acting on a person's approval, the blocking wait,
+  the durable resume, Temporal and `applyVerifiedResume` claim it (`POST /agent/claim/<id>`) with a key
+  random to that run, and run only if Decidio says this run collected it - otherwise
+  `DecidioBlockedError`: "This approval was already used by another run. Ask again for a new
+  approval." Auto-approvals are never claimed; reading the status never claims. Every authorize with a
+  request commitment also sends a request key (a fresh id per call, your own `requestKey`, or the
+  engine's id for the call), and a retried authorize carries the same key.
+- **Known limit — LangGraph and Inngest do not claim yet.** Two concurrent resumes of the same LangGraph
+  thread (the checkpoint is your storage) can both pass the check and both run the action; resume each
+  one from one place (one worker per thread id, or a lock). Inngest relies on its own step semantics.
 - **Upgrade the gate first.** A keyed SDK refuses a routed approval from a Decidio gate that does not
   return commitments (`commitment_missing`) — it fails closed, never silently passes.
 
@@ -759,14 +767,15 @@ manager for production.
 - `DecidioRequestChangedError` (0.7.0, a `DecidioBlockedError`) — Decidio approved the decision for a *different* request than the one about to run ("the request changed after approval"); nothing executed. Ask again for the request you mean to run.
 - `DecidioApprovalUnverifiedError` (0.7.0, a `DecidioBlockedError`) — the approval could not be tied to this request: `code: "commitment_missing"` (Decidio returned no request commitment although this SDK sent one — typically a gate older than 0.7.0) or `"unverifiable"`. Nothing executed.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
-- `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); nothing executed locally. Since 0.6.4 the SDK's last act before throwing is to tell Decidio it gave up, so the request is closed as **withdrawn** (it leaves the queue; a later approval does nothing) — `error.withdrawn` is `true` when that landed and `false` when the call failed and the request may still be open. Withdrawing needs the bound agent token and the signing key `init` writes (an unbound or unsigned caller cannot withdraw anything — it just gets `withdrawn:false`). If a human decided in the last poll window, the SDK honours that decision instead: the action runs as approved, or `DecidioRejectedError` is thrown. The durable path never withdraws: its parked action is what a later approval resumes.
+- `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); nothing executed locally. Since 0.6.4 the SDK's last act before throwing is to tell Decidio it gave up, so the request is closed as **withdrawn** (it leaves the queue; a later approval does nothing) — `error.withdrawn` is `true` when that landed and `false` when the call failed and the request may still be open. Withdrawing needs the bound agent token and the signing key `init` writes (an unbound or unsigned caller cannot withdraw anything — it just gets `withdrawn:false`). If a human decided in the last poll window, the SDK honours that decision instead: the action runs as approved, or `DecidioRejectedError` is thrown. The durable path never withdraws: its parked action is what a later approval resumes. Since 0.12.0 a request that may be shared is never withdrawn: after an `idempotentReplay` or `openTwin` answer, or a 409 `SHARED_REQUEST`, `error.shared` is `true` and a person still decides it.
 - `DecidioRateLimitError` — the workspace's governed-action limit was hit; carries the server's `limit` / `remaining` / `resetAt`.
 - `DecidioHttpError` — the gate refused the call. Carries `status`, `endpoint`, the parsed `body`,
   and **`retryable`** — the field to branch on. A 401/403 is terminal (the agent token expired, or
   someone re-ran `init` for that agent and revoked it): retrying cannot help, so the message names
-  the fix. Anything else is transient, and retrying is safe because a retry creates a *new* request
-  and can never double-execute.
-- `DecidioNetworkError` — the gate was unreachable. Nothing executed locally.
+  the fix. Anything else is transient: the SDK already retried the authorize with the same request key
+  (0.12.0) - a request still waiting is answered with the one already waiting - and retrying is safe: it
+  can never double-execute.
+- `DecidioNetworkError` — the gate was unreachable (after the SDK's own retries, for the authorize). Nothing executed locally.
 - `DecidioUnsafeArgumentsError` — your call arguments cannot survive JSON with their meaning intact, so nothing was routed and nothing ran. The message names the field and the fix. Most often: `NaN`/`Infinity`, `-0`, a `Date`, `Map` or class instance, a `BigInt`, or a sparse array — anything whose serialized form would differ from the value the approval and signature cover. Pass the already-serialized form.
 
 ```js

package/dist/adapters/_gate.d.ts

@@ -1,13 +1,19 @@
-import { type GuardConfig, type ApprovalContext, type EvidenceOutcome, type ApprovalCheck, type CommittedRequest } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type EvidenceOutcome, type ApprovalCheck, type ClaimOutcome, type CommittedRequest, type JsonValue } from "../index.js";
 /** The ONLY authorization verdicts this SDK understands. A gate answer outside this set means
  *  the SDK does not understand the decision — and an answer you do not understand means NO. */
 export declare const AUTHORIZE_VERDICTS: readonly ["proceed", "route", "block"];
 export type AuthorizeVerdict = (typeof AUTHORIZE_VERDICTS)[number];
+/** `requestKey` (0.12.0): the request key this authorize sent, when it sent one. `idempotentReplay` / `openTwin`: the gate
+ *  answered with a request that already existed (the same key asked again, or the same keyless request another caller is
+ *  waiting on). */
 export interface GateAuth {
     decision: AuthorizeVerdict;
     decisionId: string;
     receiptId?: string;
     reason?: string;
+    requestKey?: string;
+    idempotentReplay?: boolean;
+    openTwin?: boolean;
 }
 /** Fail-closed verdict allow-list. Called INSIDE gateAuthorize, so every adapter that authorizes
  *  through the shared gate is protected by construction rather than by remembering — an adapter
@@ -57,10 +63,21 @@ export declare function gateAuthorizeTwinAware(config: GuardConfig, ctx: Approva
     request?: CommittedRequest;
     justification?: string;
 }): Promise<GateAuth | GateDuplicate>;
+/** `naturalId` (0.12.0, 11f): the engine's own name for THIS call - an OpenAI tool call id, a Temporal workflow run and
+ *  activity, an Inngest run - so the engine retrying the same call is the same request. The request key is keyed over it
+ *  and the commitment. Without one (and without `idempotencyKey`) the key is over a fresh id for this call, as on the core
+ *  path. No key material: no commitment, so no key - as before. */
 export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext, opts?: {
     idempotencyKey?: string;
     request?: CommittedRequest;
+    naturalId?: Record<string, JsonValue>;
 }): Promise<GateAuth>;
+/** COLLECT A PERSON'S APPROVAL ONCE on an engine door (0.12.0, call 24) - claimApproval, as a plain-JSON value an engine
+ *  that must run HTTP in an activity (Temporal) returns unchanged. */
+export declare function gateClaim(config: GuardConfig, decisionId: string, claimKey: string): Promise<ClaimOutcome>;
+/** Validate a claim outcome that crossed a serialization boundary (a Temporal activity result). Anything that is not a
+ *  well-formed outcome for THIS decision is refused - "an answer you do not understand is never permission". */
+export declare function assertClaimShape(raw: unknown, decisionId: string): ClaimOutcome;
 /** Report an adapter-path execution and RETURN what Decidio recorded.
  *
  *  Two 0.2.0 changes, both closing the same gap. It applies the caller's `evidence` mapper — the

package/dist/adapters/_gate.js

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
-import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, assertDescribed, readConfirmResponse, buildConfirmBody, decisionIdProblem, bindingMaterial, requestCommitment, checkApproval } from "../index.js";
+import { randomUUID } from "node:crypto";
+import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, assertDescribed, readConfirmResponse, buildConfirmBody, decisionIdProblem, bindingMaterial, requestCommitment, idempotencyKey, invocationRequestKey, sendAuthorize, checkApproval, claimApproval } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -45,48 +46,54 @@ export const isGateDuplicate = (a) => {
     return a?.decision === "duplicate" && !!d && typeof d === "object" && typeof d.decisionId === "string" && decisionIdProblem(d.decisionId) === null;
 };
 export async function gateAuthorizeTwinAware(config, ctx, opts = {}) {
-    const a = await postAuthorize(config, ctx, { ...opts, twinCheck: true });
+    const { answer: a } = await postAuthorize(config, ctx, { ...opts, twinCheck: true });
     if (isGateDuplicate(a))
         return a;
     return assertAuthorizeVerdict(a, "unknown");
 }
 export async function gateAuthorize(config, ctx, opts = {}) {
-    return assertAuthorizeVerdict(await postAuthorize(config, ctx, opts), "unknown");
+    const { answer, requestKey } = await postAuthorize(config, ctx, opts);
+    const auth = assertAuthorizeVerdict(answer, "unknown");
+    return requestKey ? { ...auth, requestKey } : auth;
 }
 async function postAuthorize(config, ctx, opts = {}) {
     ctx = canonicalize(ctx, "describe(...)");
     assertDescribed(ctx);
     assertSafeTransport(config.apiUrl, carriesCredential(config));
-    const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
-    const requesterIdentity = (config.agentKey && config.agentDid)
+    const sign = () => (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;
+    const requesterIdentity = sign();
     const material = bindingMaterial(config);
     const commitment = material ? requestCommitment(material, opts.request ?? adapterRequest(ctx)) : undefined;
-    const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/authorize", {
-        method: "POST",
-        headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
-        body: JSON.stringify({
-            requester: config.agentId, action: ctx.action, amount: ctx.amount, scope: ctx.scope,
-            sourceSystem: config.sourceSystem, ...(ctx.context ? { context: ctx.context } : {}),
-            ...(requesterIdentity ? { requesterIdentity } : {}), ...(resumeUrl ? { resumeUrl } : {}),
-            ...(commitment ? { requestCommitment: commitment } : {}),
-            ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
-            ...(opts.twinCheck ? { twinCheck: true } : {}),
-            ...(opts.justification ? { justification: opts.justification } : {}),
-        }),
-    });
-    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);
+    const requestKey = opts.idempotencyKey
+        ?? (material && commitment
+            ? (opts.naturalId ? idempotencyKey(material, { ...opts.naturalId, commitment }) : invocationRequestKey(material, config.invocationId ? String(config.invocationId()) : randomUUID(), commitment))
+            : undefined);
+    const answer = 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 } : {}),
+        ...(commitment ? { requestCommitment: commitment } : {}),
+        ...(requestKey ? { idempotencyKey: requestKey } : {}),
+        ...(opts.twinCheck ? { twinCheck: true } : {}),
+        ...(opts.justification ? { justification: opts.justification } : {}),
+    }, { rateLimit: "http", resign: sign });
+    return { answer, ...(requestKey ? { requestKey } : {}) };
+}
+export function gateClaim(config, decisionId, claimKey) {
+    return claimApproval(config, decisionId, claimKey);
+}
+export function assertClaimShape(raw, decisionId) {
+    const c = raw;
+    if (c && typeof c === "object" && c.decisionId === decisionId) {
+        if (c.ok === true && typeof c.again === "boolean")
+            return { ok: true, decisionId, again: c.again };
+        if (c.ok === false && typeof c.code === "string" && typeof c.reason === "string" && typeof c.final === "boolean")
+            return c;
     }
-    return res.json();
+    return { ok: false, decisionId, code: "unrecognized", final: false, reason: `the claim for decision ${decisionId} came back malformed (${JSON.stringify(raw ?? null).slice(0, 120)}) - return claimApprovalActivity(...) from your activity unchanged. Nothing ran.` };
 }
 export async function gateConfirm(config, decisionId, result, evidence) {
     const f = config.fetchImpl ?? fetch;

package/dist/adapters/langgraph.js

@@ -58,7 +58,7 @@ export async function decidioGate(config, ctx, run, opts) {
     }
     const result = await run();
     const confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
-    return { value: result, decisionId: auth.decisionId, confirmation };
+    return { value: result, decisionId: auth.decisionId, confirmation, ...(typeof auth.requestKey === "string" ? { requestKey: auth.requestKey } : {}) };
 }
 export function decidioResumeCommand(body) {
     const decisionId = body?.decisionId;

package/dist/adapters/openai.d.ts

@@ -34,9 +34,10 @@ interface RunStateLike {
  * the call itself - its name, call id and exact argument string (toolCallRequest). An item edited after
  * approval, or a second identical call (another call id), never rides the approval.
  *
- * KNOWN LIMIT (predates 0.7.0): this door has no single-execution claim. The RunState is the host's own
- * storage, so two concurrent resumes of the same parked state can both apply the approval and both run
- * the tool; serialize resumes per run on your side (one worker per run id, or a lock).
+ * ONE APPROVAL, ONE RUN (0.12.0, founder call 24): applyVerifiedResume COLLECTS a person's approval before it
+ * approves the item (POST /agent/claim, a key random per call), so two concurrent resumes of the same parked state
+ * cannot both run the tool - the second is told the approval was already used and the RunState is not modified.
+ * A request key rides with every authorize, keyed on the tool call id: the same call asked again is the same request.
  *
  * Duck-typed on the state/item (no hard @openai/agents import) so it stays thin.
  *
@@ -82,10 +83,16 @@ export declare const gateInterruptions: typeof authorizeInterruptions;
  *  state.reject(item), returns that verdict. Still pending, or approved for a DIFFERENT request, or not
  *  tied to one → throws the typed refusal and the RunState is NOT modified.
  *
+ *  A PERSON'S approval is COLLECTED ONCE before the item is approved (0.12.0, call 24): with `opts.claimKey` (yours to
+ *  keep for a retry of THIS resume) or a fresh random one. Another run already used it, or it expired, or the claim could
+ *  not be made → DecidioBlockedError, saying so, and the RunState is NOT modified. An auto-approval is never claimed.
+ *
  *  REPLACES `applyResume(state, item, verdict)`, REMOVED in 0.7.0. It applied a bare verdict string
  *  with no decision attached, so correctness depended entirely on the host routing the right verdict
  *  to the right item. It was removed rather than deprecated: a deprecated function that still approves
  *  keeps the hole open for every integration that never reads the warning, and one that refused
  *  approvals at runtime would fail AFTER a human approved - the removal fails at build time instead. */
-export declare function applyVerifiedResume(config: GuardConfig, state: RunStateLike, item: ToolApprovalItem, decisionId: string, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<"approved" | "rejected" | "blocked">;
+export declare function applyVerifiedResume(config: GuardConfig, state: RunStateLike, item: ToolApprovalItem, decisionId: string, describe: (item: ToolApprovalItem) => ApprovalContext, opts?: {
+    claimKey?: string;
+}): Promise<"approved" | "rejected" | "blocked">;
 export {};

package/dist/adapters/openai.js

@@ -1,11 +1,11 @@
-import { gateAuthorize, gateCheckApproval, toolCallRequest, checkEngineVersion } from "./_gate.js";
-import { DecidioBlockedError, approvalRefusal, decisionIdProblem } from "../index.js";
+import { gateAuthorize, gateCheckApproval, gateClaim, toolCallRequest, checkEngineVersion } from "./_gate.js";
+import { DecidioBlockedError, approvalRefusal, claimRefusal, decisionIdProblem, newClaimKey } from "../index.js";
 export async function authorizeInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
     const batch = state.getInterruptions().map((item) => { const ctx = describe(item); return { item, ctx, request: toolCallRequest(item, ctx) }; });
     for (const { item, ctx, request } of batch) {
-        const auth = await gateAuthorize(config, ctx, { request });
+        const auth = await gateAuthorize(config, ctx, { request, naturalId: { engine: "openai-agents", callId: request.args[0].callId } });
         if (auth.decision === "proceed") {
             state.approve(item);
             resolved.push({ item, verdict: "approved", decisionId: auth.decisionId });
@@ -22,13 +22,21 @@ export async function authorizeInterruptions(config, state, describe) {
     return { resolved, pending, confirmationSupported: false };
 }
 export const gateInterruptions = authorizeInterruptions;
-export async function applyVerifiedResume(config, state, item, decisionId, describe) {
+export async function applyVerifiedResume(config, state, item, decisionId, describe, opts = {}) {
     const idProblem = decisionIdProblem(decisionId);
     if (idProblem)
         throw new DecidioBlockedError(`applyVerifiedResume needs the decision this item was routed as (${idProblem}) - pass the decisionId authorizeInterruptions returned for it. The RunState was NOT modified.`, typeof decisionId === "string" ? decisionId : "");
     const ctx = describe(item);
     const check = await gateCheckApproval(config, decisionId, ctx, toolCallRequest(item, ctx));
     if (check.ok) {
+        if (check.state === "approved") {
+            const claimed = await gateClaim(config, decisionId, opts.claimKey ?? newClaimKey());
+            if (!claimed.ok) {
+                const refusal = claimRefusal(claimed);
+                refusal.message += " The RunState was NOT modified.";
+                throw refusal;
+            }
+        }
         state.approve(item);
         return "approved";
     }

package/dist/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome, type ApprovalCheck } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome, type ApprovalCheck, type ClaimOutcome } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -8,8 +8,9 @@ import { type GateAuth } from "./_gate.js";
  * Inside your workflow:
  * const verdicts = installDecidioSignal();                 // wires the resume signal
  * const out = await decidioGate(config, ctx, () => createOpp(o), verdicts, {
- * authorize: () => executeActivity(authorizeActivity, ...),   // HTTP belongs in activities
+ * authorize: () => executeActivity(authorizeActivity, ...),   // HTTP belongs in activities; body: return authorizeActivity(config, ctx)
  * verify:    (id) => executeActivity(verifyActivity, id),      // body: return verifyApprovalActivity(config, id, ctx)
+ * claim:     (id, key) => executeActivity(claimActivity, id, key), // body: return claimApprovalActivity(config, id, key)
  * confirm:   (id, r) => executeActivity(confirmActivity, ...),
  * });
  * Decidio's webhook bridges to: handle.signal(decidioResumeSignal, decisionId, verdict, reason)
@@ -21,6 +22,13 @@ import { type GateAuth } from "./_gate.js";
  * → the typed refusal. `verify` is HTTP, so it must be an ACTIVITY, never workflow code (determinism) -
  * and it is required whenever `authorize` is.
  *
+ * ONE APPROVAL, ONE RUN (0.12.0, founder call 24): once Decidio confirms a PERSON'S approval, the workflow collects
+ * it (`claim`, an activity) with a key made from the workflow's own deterministic uuid4 - the same key on a replay or an
+ * activity retry, a different one in any other run - and runs only if Decidio says this run collected it. Another run
+ * already used it, or it expired → DecidioBlockedError, and the action never runs. `claim` is required whenever
+ * `authorize` is. A request key rides with every authorize: `authorizeActivity` keys it on the activity's own workflow,
+ * run and activity ids, so Temporal retrying the activity is the same request.
+ *
  * (This wiring doc ships in the .d.ts — the README points here.)
  */
 export declare const decidioResumeSignal: import("@temporalio/workflow").SignalDefinition<[string, string, (string | undefined)?]>;
@@ -35,6 +43,20 @@ export declare function installDecidioSignal(): Map<string, {
  *  and route `verify` through it. GET /agent/status + the request commitment recomputed over `ctx`, which
  *  must be the same context the gate authorized. Never call it from workflow code (it is HTTP). */
 export declare function verifyApprovalActivity(config: GuardConfig, decisionId: string, ctx: ApprovalContext): Promise<ApprovalCheck>;
+/** The ids that name ONE activity execution across its retries: the workflow, its run, and the activity. */
+export interface TemporalActivityIds {
+    workflowId: string;
+    runId: string;
+    activityId: string;
+}
+/** The authorize ACTIVITY body (0.12.0) - register an activity that returns this, unchanged, and route `authorize`
+ *  through it. The request key is keyed on Temporal's own ids for this activity (11f): passed as `ids`, or read from the
+ *  running activity's context - so Temporal retrying the activity after a timeout is the SAME request while it waits.
+ *  Outside an activity, with no `ids`, the key is over a fresh id for the call. */
+export declare function authorizeActivity(config: GuardConfig, ctx: ApprovalContext, ids?: TemporalActivityIds): Promise<GateAuth>;
+/** The claim as an ACTIVITY body (0.12.0, call 24) - register an activity that returns this, unchanged, and route `claim`
+ *  through it: POST /agent/claim with the key the workflow made. Never call it from workflow code (it is HTTP). */
+export declare function claimApprovalActivity(config: GuardConfig, decisionId: string, claimKey: string): Promise<ClaimOutcome>;
 export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
     /** THE APPROVAL CHECK, run after the resume signal and before `run()` (0.7.0). It is HTTP, so route it
@@ -42,6 +64,11 @@ export interface DecidioGateOpts<R = unknown> {
      *  `ctx` this gate authorized - and return that value unchanged. Required whenever `authorize` is
      *  supplied; without either it defaults to a direct call (tests only - a workflow must not do I/O). */
     verify?: (decisionId: string) => Promise<ApprovalCheck>;
+    /** THE CLAIM (0.12.0, call 24), run after the approval check and before `run()` when a PERSON approved: collect the
+     *  approval for this run, once. HTTP, so route it through an ACTIVITY whose body is
+     *  `return claimApprovalActivity(config, decisionId, claimKey)` - return that value unchanged. Required whenever
+     *  `authorize` is supplied; without either it defaults to a direct call (tests only). */
+    claim?: (decisionId: string, claimKey: string) => Promise<ClaimOutcome>;
     /** Reports through YOUR activity. Return the gate's confirm response body (validated with
      *  `readConfirmResponse`) and it becomes the outcome; return nothing and the outcome says the SDK could
      *  not read back what Decidio recorded (prodsec V035-03: a returned outcome used to be discarded). */

package/dist/adapters/temporal.js

@@ -1,6 +1,7 @@
-import { condition, defineSignal, setHandler } from "@temporalio/workflow";
-import { DecidioBlockedError, approvalRefusal } from "../index.js";
-import { gateAuthorize, gateConfirm, gateCheckApproval, assertApprovalCheckShape, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
+import { condition, defineSignal, setHandler, uuid4 } from "@temporalio/workflow";
+import { createRequire } from "node:module";
+import { DecidioBlockedError, approvalRefusal, claimRefusal, newClaimKey } from "../index.js";
+import { gateAuthorize, gateConfirm, gateCheckApproval, gateClaim, assertApprovalCheckShape, assertClaimShape, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
 export const decidioResumeSignal = defineSignal("decidioResume");
 export function installDecidioSignal() {
     const verdicts = new Map();
@@ -10,12 +11,40 @@ export function installDecidioSignal() {
 export function verifyApprovalActivity(config, decisionId, ctx) {
     return gateCheckApproval(config, decisionId, ctx);
 }
+function currentActivityIds() {
+    try {
+        const info = createRequire(import.meta.url)("@temporalio/activity").Context.current().info;
+        const ids = { workflowId: info?.workflowExecution?.workflowId, runId: info?.workflowExecution?.runId, activityId: info?.activityId };
+        return typeof ids.workflowId === "string" && typeof ids.runId === "string" && typeof ids.activityId === "string" ? ids : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function authorizeActivity(config, ctx, ids) {
+    const natural = ids ?? currentActivityIds();
+    return gateAuthorize(config, ctx, natural ? { naturalId: { engine: "temporal", workflowId: natural.workflowId, runId: natural.runId, activityId: natural.activityId } } : {});
+}
+export function claimApprovalActivity(config, decisionId, claimKey) {
+    return gateClaim(config, decisionId, claimKey);
+}
+function workflowClaimKey() {
+    try {
+        return `run_${uuid4()}`;
+    }
+    catch {
+        return newClaimKey();
+    }
+}
 let confirmWarned = false;
 export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     if (opts.authorize && !opts.verify) {
         throw new Error("[decidio] temporal: `authorize` runs in your activity, so the approval check must too - pass `verify: (decisionId) => executeActivity(verifyActivity, decisionId)`, where the activity returns verifyApprovalActivity(config, decisionId, ctx) (from @decidio/sdk/temporal) unchanged. Since 0.7.0 a resume signal only wakes the workflow; the approval is confirmed with Decidio before your action runs. Nothing was routed or executed.");
     }
-    const auth = assertAuthorizeVerdict(await (opts.authorize ?? (() => gateAuthorize(config, ctx)))(), "unknown");
+    if (opts.authorize && !opts.claim) {
+        throw new Error("[decidio] temporal: `authorize` runs in your activity, so the claim must too - pass `claim: (decisionId, claimKey) => executeActivity(claimActivity, decisionId, claimKey)`, where the activity returns claimApprovalActivity(config, decisionId, claimKey) (from @decidio/sdk/temporal) unchanged. Since 0.12.0 a person's approval is collected once, by the run that acts on it, before your action runs. Nothing was routed or executed.");
+    }
+    const auth = assertAuthorizeVerdict(await (opts.authorize ?? (() => authorizeActivity(config, ctx)))(), "unknown");
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
@@ -24,8 +53,15 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
             await condition(() => verdicts.has(auth.decisionId));
             verdicts.delete(auth.decisionId);
             const check = assertApprovalCheckShape(await verify(auth.decisionId), auth.decisionId);
-            if (check.ok)
+            if (check.ok) {
+                if (check.state === "approved") {
+                    const claim = opts.claim ?? ((decisionId, claimKey) => gateClaim(config, decisionId, claimKey));
+                    const claimed = assertClaimShape(await claim(auth.decisionId, workflowClaimKey()), auth.decisionId);
+                    if (!claimed.ok)
+                        throw claimRefusal(claimed);
+                }
                 break;
+            }
             if (check.code !== "pending")
                 throw approvalRefusal(check);
         }
@@ -52,6 +88,6 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     else {
         confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     }
-    return { value: result, decisionId: auth.decisionId, confirmation };
+    return { value: result, decisionId: auth.decisionId, confirmation, ...(typeof auth.requestKey === "string" ? { requestKey: auth.requestKey } : {}) };
 }
 checkEngineVersion("temporal");

package/dist/cli.d.ts

@@ -18,6 +18,8 @@ export declare function defaultAgentId(dir?: string): string;
  *  distinct decision ids can never share a file (first-run review of 0.4.1: dots were STRIPPED, `a.b` and `ab`
  *  collided). `~` is outside the allowed set, so the escape is unambiguous. Exported for the smokes. */
 export declare function receiptFileName(id: string): string;
+/** Exactly what the person types to pause or resume the guard - nothing else is read. PURE. */
+export declare function guardWords(prompt: unknown): "pause" | "start" | null;
 /** Scoped packs (GitHub App design §2): a pack's scope in words - the organisation's, a unit's (its type, and its name when
  *  the server sent one: names that fail its person check are withheld there), or the reader's own. Null for an older server. */
 export declare function packScopeLabel(scope: any): string | null;