@decidio/sdk 0.11.0 → 0.12.0

package/dist/cli.js

@@ -78,6 +78,7 @@ const DEFAULT_API = "https://decidio-api.onrender.com";
 let API = (process.env.DECIDIO_API_URL ?? DEFAULT_API).replace(/\/$/, "");
 const COMPUTER = "*";
 const EVERY_PROJECT = "every project";
+const GUARD_POLICY_RE = /^[A-Za-z0-9_-]{20,64}$/;
 let CONNECTED_APPROVER = null;
 let CONNECTED_UNANSWERED = false;
 let CONNECTED_APP_URL = null;
@@ -3450,10 +3451,12 @@ async function cmdHookPrompt() {
         const body = await r.json().catch(() => null);
         if (r.status === 403 && body?.code === "ORGANISATION_KEEPS_ON") {
             notePause(session, false);
+            rememberPausable(false);
             return block(ORGANISATION_KEEPS_ON);
         }
         if (r.ok && body?.state === "paused") {
             notePause(session, true);
+            rememberPausable(true);
             return block(`Decidio guard paused for this session: destructive commands run without a person's approval - each one is recorded in your workspace's audit log - until you type "decidio start" (or for ${GUARD_PAUSE_HOURS} hours). Decidio still asks before a command edits Claude Code's settings to switch its check off.`);
         }
         if (r.ok && body?.state === "on") {
@@ -3468,6 +3471,17 @@ async function cmdHookPrompt() {
         return block(`Decidio couldn't ${action} the guard just now (${String(e?.message ?? e).replace(/^\[decidio\] /, "").slice(0, 160)}) - ${action === "pause" ? "it stays on" : "if it was paused, type \"decidio start\" again"}.`);
     }
 }
+function rememberPausable(pausable) {
+    if (CREDS_FROM !== "connection")
+        return;
+    const c = activeConnection(projectRoot(), API);
+    if (!c || (c.guardPausable !== false) === pausable)
+        return;
+    try {
+        writeSecretFile(connectionFile(c.root), JSON.stringify({ ...c, guardPausable: pausable }) + "\n");
+    }
+    catch { }
+}
 function hookForgesPrompt(command, depth = 0) {
     const hit = hookSegments(command).some((s) => {
         const a = s.args.map((x) => x.replace(/^["']|["']$/g, ""));
@@ -3555,8 +3569,11 @@ async function cmdHookPretool(opts = { unconnected: "hold" }) {
         const short = hookShort(hookRedact(g.text.replace(/\s+/g, " ").trim()));
         let cfg = hookConfig();
         if ("missing" in cfg) {
-            const got = await hookProvision();
+            const got = await hookProvision(opts.policy);
             if (!got.ok) {
+                const held = got.hold === true || (opts.policy !== undefined && got.hold !== false);
+                if (opts.unconnected === "tell" && held && !g.offSwitch)
+                    return deny(`Decidio: "${short}" is a ${g.category} ${w.noun} that needs a person's approval - ${got.reason} ${w.ran} ${got.holdWhy ?? (got.hold === true ? "This team's Decidio holds a computer that isn't connected until it connects." : "This repository's Decidio line holds a computer that isn't connected unless Decidio confirms this team lets it through, and it couldn't confirm that here.")}`, got.user);
                 if (opts.unconnected === "tell" && !g.offSwitch) {
                     const told = toldOnce(typeof input.session_id === "string" ? input.session_id : "", g.binding);
                     if (told === "passed")
@@ -3819,6 +3836,53 @@ function hookRunner(portable = false) {
 const hookPromptLine = (runner) => `cd "$CLAUDE_PROJECT_DIR" && IN=$(cat) && case "$IN" in *[Dd][Ee][Cc][Ii][Dd][Ii][Oo]*) printf '%s' "$IN" | ${runner} hook prompt;; esac`;
 const HOOK_FILE_TOOLS = ["Write", "Edit", "MultiEdit"];
 const HOOK_GUARD_PATHS = ["**/.claude/settings*.json", "~/.claude/settings*.json", "~/.claude/plugins/**"];
+function decidioHookSet(runner, preLine, postLine) {
+    const set = [
+        { event: "PreToolUse", matcher: "Bash|PowerShell", command: preLine, extra: { timeout: 150, onFailure: "block" } },
+        { event: "PostToolUse", matcher: "Bash|PowerShell", command: postLine, extra: { timeout: 30 } },
+        { event: "SessionStart", matcher: "startup|resume", command: `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook session`, extra: { timeout: 15 } },
+        { event: "UserPromptSubmit", matcher: "", command: hookPromptLine(runner), extra: { timeout: 15 } },
+    ];
+    for (const t of HOOK_FILE_TOOLS)
+        for (const p of HOOK_GUARD_PATHS) {
+            set.push({ event: "PreToolUse", matcher: t, iff: `${t}(${p})`, command: preLine, extra: { timeout: 150, onFailure: "block" } });
+            set.push({ event: "PostToolUse", matcher: t, iff: `${t}(${p})`, command: postLine, extra: { timeout: 30 } });
+        }
+    return set;
+}
+function decidioHooksJson(runner) {
+    const hooks = {};
+    for (const h of decidioHookSet(runner, `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook pretool`, `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook posttool`)) {
+        const handler = { type: "command", ...(h.iff ? { if: h.iff } : {}), command: h.command, ...h.extra };
+        (hooks[h.event] ??= []).push(h.matcher ? { matcher: h.matcher, hooks: [handler] } : { hooks: [handler] });
+    }
+    return hooks;
+}
+function cmdHookManagedSettings() {
+    process.stdout.write(JSON.stringify({ hooks: decidioHooksJson(`npx -y @decidio/sdk@${VERSION}`) }, null, 2) + "\n");
+    for (const line of [
+        "Decidio hooks for Claude Code's managed settings (stdout above). Merge the \"hooks\" block into your organisation's managed settings:",
+        "  macOS   /Library/Application Support/ClaudeCode/managed-settings.json  (or the MDM profile domain com.anthropic.claudecode)",
+        "  Linux   /etc/claude-code/managed-settings.json   (WSL too)",
+        "  Windows C:\\Program Files\\ClaudeCode\\managed-settings.json  (or HKLM\\SOFTWARE\\Policies\\ClaudeCode, value \"Settings\")",
+        "  or a drop-in file in managed-settings.d/ beside it.",
+        "What it does: managed hooks run beside people's own hooks and can't be removed from their settings; a user's or project's",
+        "  disableAllHooks doesn't reach them. Never set disableAllHooks in managed settings - it would turn these off too.",
+        "Watch out:",
+        "  - Server-managed settings (the Claude admin console) and MDM/registry policies outrank this file - by default the first source",
+        "    found wins and the rest are skipped. Put these hooks in the highest-ranked source you deploy (server-managed hooks show each",
+        "    person an approval dialog first), or set \"managedSourcesBehavior\": \"merge\" there (Claude Code 2.1.242+).",
+        "  - Claude Code cloud sessions (claude.ai/code) read neither this file nor an MDM profile - only server-managed settings reach them.",
+        "  - Every computer needs Node 18+ and the npm registry: the pretool hook blocks the call if it can't run (fail closed).",
+        "  - Each computer still connects once - the first destructive command shows a link the workspace owner allows; until then it waits.",
+        "  - A repository whose committed settings already carry Decidio's hook runs both (one request; test it once).",
+        "  - A local administrator can edit this file.",
+        "  - allowManagedHooksOnly: true would also stop people's own hooks - your choice; Decidio doesn't need it.",
+        `  - To update, redeploy with the new version (pinned here: @decidio/sdk@${VERSION}).`,
+    ])
+        err(line);
+    return 0;
+}
 async function cmdHookInstall(opts) {
     const settingsPath = joinPath(opts.dir ?? ".", ".claude", opts.project ? "settings.json" : "settings.local.json");
     let settings = {};
@@ -3865,17 +3929,16 @@ async function cmdHookInstall(opts) {
             hooks[event].push(matcher ? { matcher, hooks: [want] } : { hooks: [want] });
         return state;
     };
-    const preLine = `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook pretool${opts.unconnected === "tell" ? " --unconnected=tell" : ""}`, postLine = `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook posttool`;
+    const preLine = `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook pretool${opts.unconnected === "tell" ? ` --unconnected=tell${opts.policy && GUARD_POLICY_RE.test(opts.policy) ? ` --policy=${opts.policy}` : ""}` : ""}`, postLine = `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook posttool`;
+    const set = decidioHookSet(runner, preLine, postLine);
     const pre = place("PreToolUse", "Bash|PowerShell", undefined, preLine, { timeout: 150, onFailure: "block" });
     const post = place("PostToolUse", "Bash|PowerShell", undefined, postLine, { timeout: 30 });
-    place("SessionStart", "startup|resume", undefined, `cd "$CLAUDE_PROJECT_DIR" && ${runner} hook session`, { timeout: 15 });
-    place("UserPromptSubmit", "", undefined, hookPromptLine(runner), { timeout: 15 });
     const guard = { added: 0, updated: 0, kept: 0 };
-    for (const t of HOOK_FILE_TOOLS)
-        for (const p of HOOK_GUARD_PATHS) {
-            guard[place("PreToolUse", t, `${t}(${p})`, preLine, { timeout: 150, onFailure: "block" })]++;
-            guard[place("PostToolUse", t, `${t}(${p})`, postLine, { timeout: 30 })]++;
-        }
+    for (const h of set.slice(2)) {
+        const st = place(h.event, h.matcher, h.iff, h.command, h.extra);
+        if (h.iff)
+            guard[st]++;
+    }
     mkdirSync(dirname(settingsPath), { recursive: true });
     const target = realOrSame(settingsPath), tmpSettings = `${target}.decidio-${process.pid}.tmp`;
     writeFileSync(tmpSettings, JSON.stringify(settings, null, 2) + "\n", { mode: existsSync(target) ? statSync(target).mode & 0o777 : 0o644 });
@@ -4028,25 +4091,45 @@ function openInBrowser(url) {
 const CONNECT_WAIT_S = () => { const n = Number(process.env.DECIDIO_CONNECT_WAIT_S ?? 90); return Number.isFinite(n) && n >= 1 && n <= 110 ? n : 90; };
 let lastHookInstall = null;
 let connectError = "";
-async function startConnect(root, host, quiet = false) {
-    const fail = (m) => { connectError = m; if (!quiet)
+function hostOf(url) {
+    try {
+        return new URL(url).host || "Decidio's API host";
+    }
+    catch {
+        return "Decidio's API host";
+    }
+}
+function cloudNetworkWords() {
+    const host = hostOf(API);
+    return `this is a Claude Code cloud session: its environment's network access must allow ${host}. Edit the environment and add ${host} under Network access → Allowed domains, keeping the package-manager defaults (on Team and Enterprise an Owner can set it once on a shared environment): https://code.claude.com/docs/en/cloud-environments#network-access`;
+}
+let connectFailure = "other";
+async function startConnect(root, host, quiet = false, policy) {
+    const fail = (m, kind = "other") => { connectError = m; connectFailure = kind; if (!quiet)
         err(`✘ ${m}`); return null; };
     const prior = connectionRecord(root, API);
     const kp = prior && !inCloudSession() ? { did: prior.did, privateKeyBase64: prior.key } : generateKeypair();
     const cloud = inCloudSession();
     const project = (root === COMPUTER ? EVERY_PROJECT : projectLabel(root)).trim() || "project", machine = machineLabel(cloud).trim() || "machine";
     const proof = signBoundProof(kp.privateKeyBase64, { agentId: "connect", did: kp.did, action: "connect.start", amount: 0, scope: [host, project, machine, cloud ? "cloud" : "local"].join("\n") });
-    const r = await api("/connect/start", { method: "POST", body: JSON.stringify({ host, project, machine, did: kp.did, cloud, proof }) }, "", true);
+    const startBody = { host, project, machine, did: kp.did, cloud, proof };
+    let r = await api("/connect/start", { method: "POST", body: JSON.stringify(policy ? { ...startBody, policy } : startBody) }, "", true);
+    let asked = !!policy;
+    if (policy && r.status === 400 && r.body?.code === "VALIDATION") {
+        asked = false;
+        r = await api("/connect/start", { method: "POST", body: JSON.stringify(startBody) }, "", true);
+    }
     if (r.status === 0)
-        return fail(`couldn't reach Decidio at ${API} - check your connection and run npx @decidio/sdk connect again.`);
+        return fail(`couldn't reach Decidio at ${API} - ${inCloudSession() ? cloudNetworkWords() : "check your connection and run npx @decidio/sdk connect again."}`, "unreachable");
     if (r.status === 404 || r.status === 401)
-        return fail(`${r.body?.message ?? "Connecting a coding assistant isn't switched on for this Decidio yet - it is on in the Decidio lab."} (${API})`);
+        return fail(`${r.body?.message ?? "Connecting a coding assistant isn't switched on for this Decidio yet - it is on in the Decidio lab."} (${API})`, "off");
     if (r.status === 429)
-        return fail(`${r.body?.message ?? "Too many tries - wait a minute and try again."}`);
+        return fail(`${r.body?.message ?? "Too many tries - wait a minute and try again."}`, "unreachable");
     if (r.status !== 201 || typeof r.body?.pollSecret !== "string" || typeof r.body?.link !== "string")
-        return fail(`couldn't start a connection (${r.status}${r.body?.message ? `: ${r.body.message}` : ""}). Nothing was saved.`);
+        return fail(`couldn't start a connection (${r.status}${r.body?.message ? `: ${r.body.message}` : ""}). Nothing was saved.`, r.status >= 500 ? "unreachable" : "other");
     const p = { v: 1, api: API, root, project, host, machine, cloud, did: kp.did, key: kp.privateKeyBase64, code: String(r.body.code), link: String(r.body.link),
-        pollSecret: r.body.pollSecret, expiresAt: String(r.body.expiresAt), interval: Number(r.body.interval) || 2, startedAt: new Date().toISOString() };
+        pollSecret: r.body.pollSecret, expiresAt: String(r.body.expiresAt), interval: Number(r.body.interval) || 2, startedAt: new Date().toISOString(),
+        ...(asked && policy && typeof r.body.hold === "boolean" ? { policy, hold: r.body.hold } : {}) };
     mkdirSync(connectDir(), { recursive: true });
     writeSecretFile(pendingConnectFile(root), JSON.stringify(p) + "\n");
     if (typeof r.body.qr === "string")
@@ -4058,8 +4141,10 @@ function readPendingConnect(root) {
     const p = readJsonQuiet(pendingConnectFile(root));
     return p && p.v === 1 && p.api === API && p.root === root && typeof p.pollSecret === "string" ? p : null;
 }
-async function hookProvision() {
+async function hookProvision(policy) {
     const scope = COMPUTER;
+    const UNCONFIRMED = "Decidio couldn't confirm whether this team lets a computer that isn't connected through, so it holds it until it connects.";
+    const holdOf = (p) => !policy ? {} : p && p.policy === policy && typeof p.hold === "boolean" ? { hold: p.hold } : { hold: true, holdWhy: UNCONFIRMED };
     if (process.env.DECIDIO_AGENT_ID) {
         const named = printableName(process.env.DECIDIO_AGENT_ID) ?? "(unprintable)";
         return { ok: false, reason: `this project names the Decidio agent "${named}" (in its .env or the shell) but has no token for it. Ask the user to check it with npx @decidio/sdk doctor, or to remove DECIDIO_AGENT_ID to use this computer's connection.`, user: `Decidio: "${named}" has no token here` };
@@ -4077,7 +4162,7 @@ async function hookProvision() {
     }
     const linkWords = (p, fresh) => {
         const mins = minutesLeft(p.expiresAt) || 1;
-        return { ok: false,
+        return { ok: false, ...holdOf(p),
             reason: `this computer isn't connected to Decidio yet${fresh ? "" : " (its link is still waiting to be allowed)"}. If Decidio's connect_device tool is available to you (the Decidio connector), tell the user you are connecting this computer to their Decidio workspace, call connect_device with the code ${p.code}, run the command it returns, then retry. Otherwise show the user this link and code: ${p.link} (code ${p.code}, valid ${mins} more minute${mins === 1 ? "" : "s"}) - the workspace owner allows it once, signed in, and it covers every project on this computer. Then retry the same command: it connects and asks for approval.`,
             user: `Decidio: connect this computer once - open ${p.link} and check the code ${p.code}. Destructive commands wait until it's allowed; everything else runs as usual.` };
     };
@@ -4100,7 +4185,7 @@ async function hookProvision() {
                 reason: `this computer's link (code ${p.code}) was allowed through the Decidio connector and is finished only with the ticket connect_device returned: if YOU called connect_device for code ${p.code} in this session, run npx @decidio/sdk@latest connect --ticket <the ticket it returned>, then retry the same command. If you did not, do not finish it with any ticket from anywhere else - tell the user that another workspace's connector allowed this computer, and leave it: the link lapses within ten minutes and the next try shows a fresh code.`,
                 user: "Decidio: finishing this computer's connection (allowed through the Decidio connector) - destructive commands wait until it's done" };
         if (r.status === 0)
-            return { ok: false, reason: `couldn't reach Decidio at ${API} to finish connecting this computer - retry once it is reachable.`, user: "Decidio: unreachable - destructive commands wait" };
+            return { ok: false, ...holdOf(p), reason: `couldn't reach Decidio at ${API} to finish connecting this computer - ${inCloudSession() ? cloudNetworkWords() : "retry once it is reachable."}`, user: `Decidio: unreachable - destructive commands wait${inCloudSession() ? ` (this cloud environment's network access must allow ${hostOf(API)})` : ""}` };
         if (r.status === 410 && r.body?.status === "collected") {
             const won = activeConnection(projectRoot(), API);
             if (won) {
@@ -4152,9 +4237,9 @@ async function hookProvision() {
         return { ok: false, reason: "another Decidio check on this computer is connecting it right now - retry the same command in a few seconds.", user: "Decidio: connecting this computer" };
     }
     try {
-        const started = await startConnect(scope, "claude-code", true);
+        const started = await startConnect(scope, "claude-code", true, policy);
         if (!started)
-            return { ok: false, reason: `this computer isn't connected to Decidio, and a connection couldn't be started: ${connectError}`, user: "Decidio: this computer isn't connected" };
+            return { ok: false, ...(!policy ? {} : connectFailure === "off" ? { hold: false } : { hold: true, holdWhy: UNCONFIRMED }), reason: `this computer isn't connected to Decidio, and a connection couldn't be started: ${connectError}`, user: `Decidio: this computer isn't connected${inCloudSession() && connectError.startsWith("couldn't reach Decidio") ? ` - this cloud environment's network access must allow ${hostOf(API)}` : ""}` };
         return linkWords(started, true);
     }
     finally {
@@ -4364,7 +4449,8 @@ function storeCollected(scope, p, body) {
     const c = { v: 1, api: API, root: scope, project: p.project, host: p.host, machine: p.machine, cloud: p.cloud, agentId: String(body.agentId), did: p.did, key: p.key,
         token: body.token, jti: String(body.jti), expiresAt: String(body.expiresAt), workspaceId: String(body.workspaceId), workspaceName: body.workspace?.name ?? null,
         approver: body.approver?.name ?? null, approvedBy: body.approvedBy?.name ?? null, appUrl: typeof body.appUrl === "string" ? body.appUrl : null, connectedAt: new Date().toISOString(),
-        guardPausable: body.guardPausable !== false, ...(body.answered === false ? { answered: false } : {}) };
+        guardPausable: body.guardPausable !== false, ...(body.answered === false ? { answered: false } : {}),
+        ...(typeof body.guardPolicyKey === "string" && GUARD_POLICY_RE.test(body.guardPolicyKey) ? { guardPolicyKey: body.guardPolicyKey } : {}) };
     mkdirSync(connectDir(), { recursive: true });
     try {
         writeSecretFile(connectionFile(scope), JSON.stringify(c) + "\n");
@@ -4458,7 +4544,7 @@ async function finishConnect(root, c, opts, fresh) {
     const home = process.platform === "win32" ? (SHELL_ENV.USERPROFILE ?? homedir()) : (SHELL_ENV.HOME ?? homedir());
     const plugin = !cloud && decidioPluginEnabled(root);
     if (!plugin) {
-        const rc = await cmdHookInstall({ project: shared || everywhere, dir: everywhere ? home : root, quiet: true, portable: everywhere, ...(shared && !opts.holdEveryone ? { unconnected: "tell" } : {}) });
+        const rc = await cmdHookInstall({ project: shared || everywhere, dir: everywhere ? home : root, quiet: true, portable: everywhere, ...(shared && !opts.holdEveryone ? { unconnected: "tell", ...(c?.guardPolicyKey ? { policy: c.guardPolicyKey } : {}) } : {}) });
         if (rc !== 0)
             return rc;
     }
@@ -4497,10 +4583,15 @@ async function finishConnect(root, c, opts, fresh) {
         log(`• A cloud session reads the repository's settings, not a computer's, so the hooks are in ${settings} - not committed. Ask the person before committing it: committed, every cloud session of this repository asks too, and so does every teammate's clone (a teammate connects with npx @decidio/sdk connect).`);
     else if (shared)
         log(`• Commit ${settings}: every clone then asks before destructive commands (a teammate connects with npx @decidio/sdk connect).`);
+    const keyed = !!c?.guardPolicyKey && GUARD_POLICY_RE.test(c.guardPolicyKey);
     if (shared && !plugin)
         log(dim(opts.holdEveryone
             ? "  A computer that isn't connected is refused every destructive command until it connects (--hold-everyone)."
-            : "  A computer that isn't connected is told once (with how to connect), then the same command runs without Decidio's approval. To keep refusing it until it connects: npx @decidio/sdk connect --team --hold-everyone"));
+            : `  A computer that isn't connected is told once (with how to connect), then the same command runs without Decidio's approval${keyed ? " - unless the workspace owner holds computers that aren't connected (the Agents page)" : ""}. To keep refusing it until it connects: npx @decidio/sdk connect --team --hold-everyone`));
+    if (shared && !plugin && !opts.holdEveryone && !keyed)
+        log(`⚠ This file's Decidio line carries no team key, so the workspace owner's "Hold computers that aren't connected" won't reach this repository. ${c
+            ? "This computer's connection was made before that switch existed: run npx @decidio/sdk connect --team --force (the workspace owner allows it once more), then commit the file."
+            : "These credentials come from the shell or .env: run npx @decidio/sdk connect --team from a computer connected with npx @decidio/sdk connect, then commit the file."}`);
     if (fresh && c?.answered !== false)
         log(dim(`  Try it: ask ${hostName} to delete a scratch folder with rm -rf - the approval reaches ${approverName ?? "the approver"} on their phone.`));
     return 0;
@@ -5849,6 +5940,9 @@ CODING AGENTS (Claude Code)
                                        refused: store the user's one-line reason it is different, then retry the same
                                        command - the request reaches the approver with that reason beside the refusal
   npx @decidio/sdk hook rules          the command patterns the hook gates (DECIDIO_HOOK_EXTRA_RULES adds yours)
+  npx @decidio/sdk hook managed-settings  the Decidio hooks for Claude Code's managed settings (an Enterprise admin deploys
+                                       them to every developer's computer) - the JSON on stdout, where it goes and what it
+                                       does and doesn't guarantee on stderr; writes nothing
   npx @decidio/sdk hook pretool|posttool   the hooks themselves: run by Claude Code with the tool call as JSON on
                                        stdin, never by hand. A gated command is held up to DECIDIO_HOOK_HOLD_MS
                                        (90 s; at most 120 s) for the approver, then refused with its decision id; the SAME command
@@ -5857,8 +5951,9 @@ CODING AGENTS (Claude Code)
                                        --unconnected=tell (written into a shared file by connect): a computer with no
                                        credential is refused once per session and command, then let through with a line.
   npx @decidio/sdk hook prompt         the UserPromptSubmit hook: the person's own typed "decidio pause" / "decidio start"
-                                       pauses or resumes the guard for that session (never on an enterprise plan; every
-                                       pause and every command run under it is recorded); other prompts pass untouched.
+                                       pauses or resumes the guard for that session (not where the workspace keeps the
+                                       guard on - Enterprise by default; every pause and every command run under it is
+                                       recorded); other prompts pass untouched.
 
 CONTEXT PACKS (Claude Code, Claude.ai, ChatGPT)
   npx @decidio/sdk context create <slug> --title "ACME application" --trigger "whenever we discuss the ACME application"
@@ -6094,7 +6189,7 @@ async function main(argv) {
         verify: { flags: ["--allow-unpinned"], valued: ["--issuer"] },
         tokens: { flags: ["--mine"] },
         dev: { flags: [], valued: ["--target", "--port"] },
-        hook: { flags: ["--project"], valued: ["--timeout", "--approver", "--cli", "--unconnected"] },
+        hook: { flags: ["--project"], valued: ["--timeout", "--approver", "--cli", "--unconnected", "--policy"] },
         github: { flags: ["--agents-md"], valued: ["--environment", "--justification", "--decision", "--workflow", "--api"] },
         deploys: { flags: ["--watch", "--json"], valued: ["--environment", "--repo", "--limit"] },
         controls: { flags: ["--json"] },
@@ -6299,10 +6394,10 @@ async function main(argv) {
             ticket: valuedOpt(argsIn, "--ticket"), holdEveryone: argsIn.includes("--hold-everyone") });
         case "disconnect": return cmdDisconnect();
         case "hook": {
-            const VALUED = ["--timeout", "--approver", "--cli", "--unconnected"];
+            const VALUED = ["--timeout", "--approver", "--cli", "--unconnected", "--policy"];
             const pos = argsIn.filter((x, i) => !x.startsWith("-") && !VALUED.includes(argsIn[i - 1] ?? ""));
             const sub = pos[0];
-            const allowed = { pretool: ["--unconnected"], posttool: [], session: [], prompt: [], wait: ["--timeout"], install: ["--project", "--approver", "--cli"], rules: [], justify: [] };
+            const allowed = { pretool: ["--unconnected", "--policy"], posttool: [], session: [], prompt: [], wait: ["--timeout"], install: ["--project", "--approver", "--cli"], rules: [], justify: [], "managed-settings": [] };
             const given = argsIn.filter((x) => x.startsWith("--")).map((x) => x.split("=")[0]);
             if (sub && allowed[sub]) {
                 const stray = given.find((f) => !allowed[sub].includes(f));
@@ -6312,7 +6407,10 @@ async function main(argv) {
                 }
             }
             switch (sub) {
-                case "pretool": return cmdHookPretool({ unconnected: valuedOpt(argsIn, "--unconnected") === "tell" ? "tell" : "hold" });
+                case "pretool": {
+                    const pol = valuedOpt(argsIn, "--policy");
+                    return cmdHookPretool({ unconnected: valuedOpt(argsIn, "--unconnected") === "tell" ? "tell" : "hold", ...(pol && GUARD_POLICY_RE.test(pol) ? { policy: pol } : {}) });
+                }
                 case "posttool": return cmdHookPosttool();
                 case "session": return cmdHookSession();
                 case "prompt": return cmdHookPrompt();
@@ -6327,8 +6425,9 @@ async function main(argv) {
                 case "install": return cmdHookInstall({ project: argsIn.includes("--project"), approver: valuedOpt(argsIn, "--approver"), cli: valuedOpt(argsIn, "--cli") });
                 case "rules": return cmdHookRules();
                 case "justify": return cmdHookJustify(pos[1], pos.slice(2).join(" "));
+                case "managed-settings": return cmdHookManagedSettings();
                 default:
-                    err(`✘ hook needs a subcommand: install | wait <decision-id> | justify <decision-id> "<what changed>" | rules (pretool, posttool and session are run by Claude Code).\n\n${USAGE}`);
+                    err(`✘ hook needs a subcommand: install | wait <decision-id> | justify <decision-id> "<what changed>" | rules | managed-settings (pretool, posttool and session are run by Claude Code).\n\n${USAGE}`);
                     return 2;
             }
         }

package/dist/demo-gate.js

@@ -41,6 +41,7 @@ export async function startDemoGate(opts = {}) {
     let relayCode = null;
     let relayOk = null;
     let committed = null;
+    let claimedBy = null;
     const relayFetch = async (path, init = {}) => {
         if (!relayBase)
             return null;
@@ -112,6 +113,7 @@ export async function startDemoGate(opts = {}) {
                     return send({ ok: true, changed: true });
                 if (path === "/agent/authorize") {
                     verdict = null;
+                    claimedBy = null;
                     committed = typeof body?.requestCommitment === "string" && /^[0-9a-f]{64}$/.test(body.requestCommitment) ? body.requestCommitment : null;
                     return send({ decision: "route", decisionId: DECISION_ID, receiptId: "R-DEMO-1", requestCommitment: committed });
                 }
@@ -128,6 +130,18 @@ export async function startDemoGate(opts = {}) {
                         return send({ state: "rejected", reason: "quickstart: withdrawn — the tour stopped waiting", requestCommitment: committed });
                     return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver", requestCommitment: committed } : { state: verdict === "approve" ? "approved" : "pending", requestCommitment: committed });
                 }
+                if (path.startsWith("/agent/claim/")) {
+                    const key = typeof body?.claimKey === "string" && /^[A-Za-z0-9._:-]{16,128}$/.test(body.claimKey) ? body.claimKey : null;
+                    if (!key)
+                        return send({ code: "VALIDATION", message: "claimKey must be 16-128 characters of letters, digits, dot, colon, underscore or dash" }, 400);
+                    if (verdict !== "approve")
+                        return send({ code: "NOT_CLAIMABLE", decisionId: DECISION_ID, state: verdict === "reject" ? "rejected" : "pending", message: "only a person's approval is collected here" }, 409);
+                    if (claimedBy && claimedBy !== key)
+                        return send({ code: "ALREADY_USED", decisionId: DECISION_ID, state: "approved", message: "another caller already collected this approval - ask again for a new one" }, 409);
+                    const again = claimedBy === key;
+                    claimedBy = key;
+                    return send({ ok: true, claimed: true, decisionId: DECISION_ID, again });
+                }
                 if (path.startsWith("/agent/withdraw/")) {
                     if (verdict)
                         return send({ code: "NOT_OPEN", state: verdict === "approve" ? "approved" : "rejected", decisionId: DECISION_ID }, 409);

package/dist/errors.js

@@ -30,7 +30,9 @@ export class DecidioHttpError extends Error {
                         ? ` — this looks transient. Your action ALREADY RAN; do NOT re-run it — only its report failed to land, and the door's own note says whether a report was kept to re-send.`
                         : /\/agent\/status/.test(endpoint)
                             ? ` — this looks transient; polling again is safe (a status read changes nothing).`
-                            : ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute).`)
+                            : /\/agent\/authorize/.test(endpoint)
+                                ? ` — this looks transient. This SDK already retried it with the same request key (a request still waiting is answered with the one already waiting); retrying is safe and can never double-execute.`
+                                : ` — this looks transient; retrying is safe and can never double-execute.`)
                     : ` — the server refused the request itself, so retrying it unchanged will fail the same way. Fix the request (or the decision it names) first.`) +
             sideEffectNote(endpoint, typeof body?.code === "string" ? body.code : undefined));
         this.status = status;

package/dist/guard.d.ts

@@ -17,6 +17,8 @@ export interface GuardFacadeConfig {
     workspaceId?: string;
     /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
+    /** The per-call id behind the default request key (0.12.0) - see GuardConfig.invocationId. Leave it unset. */
+    invocationId?: () => string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
@@ -53,6 +55,9 @@ export interface ProtectOptions {
      *  success indication, so instead of forcing your API into magic field names:
      *  `evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" })`. */
     evidence?: (result: any) => unknown;
+    /** YOUR OWN REQUEST KEY for a call, from its arguments (0.12.0) - e.g. `(inv) => inv.id` - so the same call asked again,
+     *  even from a new process, is the same request. Without it each call sends a fresh random key. See withApproval. */
+    requestKey?: (...args: any[]) => string;
 }
 export declare class Guard {
     config: GuardFacadeConfig;

package/dist/guard.js

@@ -60,6 +60,7 @@ export class Guard {
         const base = {
             apiUrl: c.apiUrl, agentId: c.agentId, apiToken: c.apiToken,
             sourceSystem: c.sourceSystem, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId, appUrl: c.appUrl, fetchImpl: c.fetchImpl,
+            ...(c.invocationId ? { invocationId: c.invocationId } : {}),
             pollTimeoutMs: opts?.pollTimeoutMs, pollIntervalMs: opts?.pollIntervalMs,
         };
         if ((opts?.mode ?? "durable") === "blocking") {
@@ -68,12 +69,12 @@ export class Guard {
                 `(pollTimeoutMs), and when it does, this process stops waiting and the request is withdrawn in Decidio: ` +
                 `a later approval does nothing. Only safe for short, watched approvals — omit mode:"blocking" for ` +
                 `durable async resume on real (minutes-to-days) approvals.`);
-            return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
+            return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}), ...(opts?.requestKey ? { requestKey: opts.requestKey } : {}) });
         }
         const resume = this.ensureResume();
         if (opts?.action)
             resume.register(opts.action, fn, opts?.evidence, opts?.withContext);
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}), ...(opts?.requestKey ? { requestKey: opts.requestKey } : {}) });
     }
     protectBestEffort(fn, describe, opts) {
         const wrapped = this.protect(fn, describe, opts);

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import type { ResumeController, ApprovalCheck } from "./resume.js";
+import type { ResumeController, ApprovalCheck, ClaimOutcome } from "./resume.js";
 import { type CommittedRequest } from "./signing.js";
 import { type EvidenceOutcome } from "./evidence.js";
-export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval } from "./resume.js";
-export type { PendingAction, PendingStore, ResumeController, ResumeOutcome, ApprovalCheck, ApprovalCheckCode, DecisionStatus } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval, claimApproval, newClaimKey } from "./resume.js";
+export type { PendingAction, PendingStore, ResumeController, ResumeOutcome, ApprovalCheck, ApprovalCheckCode, DecisionStatus, ClaimOutcome, ClaimCode } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
 export { 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 type { BindingMaterial, CommittedRequest } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export type { JsonValue, JsonPrimitive } from "./canonical.js";
@@ -61,6 +61,11 @@ export interface GuardConfig {
      *  Sent on /agent/authorize so the decision carries it. Falls back to
      *  resume.resumeUrl. Omit when using the poll worker. */
     resumeUrl?: string;
+    /** Where the per-call id behind the DEFAULT REQUEST KEY comes from (0.12.0, 11f). Every call that sends a request
+     *  commitment also sends a request key derived from a fresh random id and that commitment, so this SDK's own retry of
+     *  the authorize is the same request. Leave it unset: a fixed id makes every call the SAME request. It exists so a
+     *  test or a conformance harness can pin the bytes it compares. */
+    invocationId?: () => string;
     fetchImpl?: typeof fetch;
 }
 export interface ApprovalContext {
@@ -115,11 +120,15 @@ export declare function coreRequest(ctx: {
 export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     withdrawn: boolean;
+    shared: boolean;
     /** `withdrawn` (0.6.4+): true when the SDK told Decidio it gave up and the request was closed as
      *  WITHDRAWN (the queue no longer carries it; a later approval does nothing); false when that
      *  best-effort call failed, so the request may still be open in Decidio. Nothing was executed
-     *  locally either way. */
-    constructor(decisionId: string, withdrawn?: boolean);
+     *  locally either way.
+     *  `shared` (0.12.0): true when the request was left open on purpose because it may be shared - the authorize
+     *  answered an earlier request (`idempotentReplay`) or joined one another caller is waiting on (`openTwin`), or the
+     *  withdraw was refused because another caller joined it (409 SHARED_REQUEST). A person still decides it. */
+    constructor(decisionId: string, withdrawn?: boolean, shared?: boolean);
 }
 /** A transport failure with GUIDANCE instead of a raw fetch stack. Carries the endpoint, the
  *  operation, the underlying code, and the safety state a caller cares about most: whether
@@ -132,7 +141,10 @@ export declare class DecidioRateLimitError extends Error {
     limit: number | undefined;
     remaining: number | undefined;
     resetAt: string | undefined;
-    constructor(limit: number | undefined, remaining: number | undefined, resetAt: string | undefined, serverMessage?: string);
+    code?: string | undefined;
+    /** `code` (0.12.0): the server's own code - `AGENT_RATE` for the workspace's hourly allowance, which is never retried;
+     *  a 429 without it is a transport throttle the SDK retries before it gives up. */
+    constructor(limit: number | undefined, remaining: number | undefined, resetAt: string | undefined, serverMessage?: string, code?: string | undefined);
 }
 export declare class DecidioNetworkError extends Error {
     endpoint: string;
@@ -145,6 +157,18 @@ export declare class DecidioNetworkError extends Error {
  *  every engine door reached the mock authorization path with a request the core would have refused.
  *  Exported so `adapters/_gate.ts` calls the same function rather than a second copy that can drift. */
 export declare function assertDescribed(ctx: ApprovalContext): void;
+/** THE ONE AUTHORIZE POST (0.12.0, 11f) - the core wrapper and every engine adapter send through here. A network failure
+ *  or a transient answer is retried a bounded number of times with the SAME body: under a request key that is the same
+ *  request (the gate answers the decision it already made, `idempotentReplay`), and a keyless request asked again while
+ *  it waits joins the one waiting (`openTwin`). A body that carries a commitment WITHOUT a key is never retried - nothing
+ *  would make the retry the same request. `rateLimit: "http"` keeps an adapter's 429 a DecidioHttpError, as it always was. */
+export declare function sendAuthorize(config: GuardConfig, first: Record<string, unknown>, opts?: {
+    rateLimit?: "typed" | "http";
+    resign?: () => unknown;
+}): Promise<any>;
+/** The typed refusal for a claim that did not let this run go ahead (0.12.0) - DecidioBlockedError, so code that treats
+ *  a block as "did not run" keeps doing so; the words say what happened and what to do ("ask again"). */
+export declare function claimRefusal(claim: ClaimOutcome): DecidioBlockedError;
 /**
  * Wrap an async action behind the Decidio gate. `describe` extracts the approval
  * context (action, amount, scope) from the call arguments. Returns a function with
@@ -172,6 +196,9 @@ export interface ProtectedExecution<R> {
     /** What Decidio recorded. `reportRecorded` false means the execution happened and Decidio does
      *  NOT know; `executionConfirmed` false means it knows but could not attest a commit. */
     confirmation: EvidenceOutcome;
+    /** The request key this call sent with its authorize (0.12.0, 11f) - absent when none was sent (no key material, so no
+     *  commitment). It names the REQUEST to Decidio; your downstream idempotency key stays `decisionId`. */
+    requestKey?: string;
 }
 export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig, opts?: {
     /** Map YOUR function's natural return value to the evidence Decidio records. The gate awards
@@ -183,4 +210,9 @@ export declare function withApproval<A extends any[], R>(fn: (...args: A) => Pro
      *  idempotencyKey }`. Opt-in, never inferred from the function's arity — guessing wrong means
      *  passing a context object as someone's first business argument. */
     withContext?: boolean;
+    /** YOUR OWN REQUEST KEY for a call (0.12.0, 11f), from its arguments - an order or invoice id - so the same call asked
+     *  again, even from a new process, is the same request. Keyed with this agent's material before it is sent (your id
+     *  never reaches Decidio in the clear). The same key for a CHANGED request is refused by the gate (409
+     *  IDEMPOTENCY_CONFLICT), never a silent second request. Without it each call sends a fresh random key. */
+    requestKey?: (...args: A) => string;
 }): (...args: A) => Promise<ProtectedExecution<R>>;