@intended-inc/claude-code-hook 0.1.1 → 0.3.0

package/dist/bin.mjs

@@ -1,10 +1,146 @@
 #!/usr/bin/env node
-import { readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, renameSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+
+var FINAL = /* @__PURE__ */ new Set(["ALLOW", "DENY", "EXPIRED"]);
+var MAX_POLL_SECONDS = 50;
+var MAX_BACKOFF_MS = 1e4;
+var MIN_REPOLL_MS = 1e3;
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+function str(v) {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function base(intentId, status, reason) {
+  return {
+    intentId,
+    status,
+    reason,
+    token: null,
+    decidedBy: null,
+    decidedAt: null,
+    escalationId: null,
+    expiresAt: null,
+    receiptUrl: null
+  };
+}
+function parseBody(intentId, body, apiUrl) {
+  const status = body.status;
+  if (status !== "ALLOW" && status !== "DENY" && status !== "PENDING" && status !== "EXPIRED") return null;
+  const receipt = str(body.receiptUrl);
+  return {
+    intentId: str(body.intentId) ?? intentId,
+    status,
+    reason: str(body.reason) ?? `Decision: ${status}`,
+    token: status === "ALLOW" ? str(body.token) : null,
+    decidedBy: body.decidedBy && typeof body.decidedBy === "object" ? body.decidedBy : null,
+    decidedAt: str(body.decidedAt),
+    escalationId: str(body.escalationId),
+    expiresAt: str(body.expiresAt),
+    receiptUrl: receipt ? /^https?:\/\//.test(receipt) ? receipt : `${apiUrl}${receipt.startsWith("/") ? "" : "/"}${receipt}` : null
+  };
+}
+function retryAfterHeaderMs(res) {
+  const raw = res.headers?.get?.("retry-after");
+  const n = raw == null ? NaN : Number(raw);
+  return Number.isFinite(n) && n > 0 ? n * 1e3 : 0;
+}
+async function waitForDecision(intentId, opts) {
+  const apiUrl = (opts.apiUrl ?? "https://api.intended.so").replace(/\/$/, "");
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? defaultSleep;
+  const deadline = now() + Math.max(0, opts.timeoutMs);
+  const headers = {
+    authorization: `Bearer ${opts.apiKey}`,
+    "x-tenant-id": opts.tenantId
+  };
+  let backoffMs = 1e3;
+  for (; ; ) {
+    const remaining = deadline - now();
+    const timeoutSec = remaining <= 0 ? 0 : Math.min(MAX_POLL_SECONDS, Math.ceil(remaining / 1e3));
+    const url = `${apiUrl}/v1/decisions/${encodeURIComponent(intentId)}/wait?timeout=${timeoutSec}&tenantId=${encodeURIComponent(opts.tenantId)}`;
+    const startedAt = now();
+    let res = null;
+    try {
+      res = await fetchImpl(url, {
+        headers,
+        // The server holds at most timeoutSec; give the network some slack beyond that.
+        signal: AbortSignal.timeout(timeoutSec * 1e3 + 15e3)
+      });
+    } catch {
+      res = null;
+    }
+    let transientWaitMs = 0;
+    if (res) {
+      if (res.status === 401) {
+        return { ...base(intentId, "ERROR", "The Intended API rejected the API key (401). The action is not approved."), error: "unauthorized" };
+      }
+      if (res.status === 403) {
+        return {
+          ...base(
+            intentId,
+            "ERROR",
+            "This API key cannot read decisions: it needs the intent:read scope. The action is not approved."
+          ),
+          error: "forbidden"
+        };
+      }
+      if (res.status === 404) {
+        return { ...base(intentId, "ERROR", `Intended has no decision for intent ${intentId}. The action is not approved.`), error: "not_found" };
+      }
+      if (res.status === 429 || res.status >= 500) {
+        transientWaitMs = Math.max(backoffMs, retryAfterHeaderMs(res));
+      } else {
+        const body = await res.json().catch(() => null);
+        const parsed = res.status === 200 && body ? parseBody(intentId, body, apiUrl) : null;
+        if (!parsed) {
+          return {
+            ...base(intentId, "ERROR", `Unrecognised decision response (HTTP ${res.status}). The action is not approved.`),
+            error: "bad_response"
+          };
+        }
+        if (FINAL.has(parsed.status)) return parsed;
+        if (now() >= deadline) return { ...parsed, timedOut: true };
+        const retryAfterMs = typeof body?.retryAfterMs === "number" && body.retryAfterMs > 0 ? body.retryAfterMs : 0;
+        const answeredFast = now() - startedAt < Math.min(timeoutSec * 1e3, MIN_REPOLL_MS) / 2;
+        const pause = retryAfterMs > 0 ? retryAfterMs : answeredFast ? MIN_REPOLL_MS : 0;
+        if (pause > 0) await sleep(Math.min(pause, Math.max(0, deadline - now())));
+        backoffMs = 1e3;
+        continue;
+      }
+    } else {
+      transientWaitMs = backoffMs;
+    }
+    if (now() >= deadline) {
+      return {
+        ...base(
+          intentId,
+          "PENDING",
+          "The Intended decision service could not be reached before the wait ended. The action is still not approved."
+        ),
+        timedOut: true
+      };
+    }
+    await sleep(Math.min(transientWaitMs, Math.max(0, deadline - now())));
+    backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+  }
+}
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const obj = value;
+  return `{${Object.keys(obj).sort().filter((k) => obj[k] !== void 0).map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+function toolCallKey(toolName, args) {
+  return createHash("sha256").update(`${toolName}
+${canonicalJson(args ?? {})}`).digest("hex");
+}
 
 // src/evaluate.ts
 var AUTHORITY_STATUSES = /* @__PURE__ */ new Set([200, 202, 403]);
+var DEFAULT_ESCALATION_WAIT_SECONDS = 45;
 var MAX_DESCRIBED_KEYS = 20;
 var SAFE_KEY = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
 function describeToolCall(name, args) {
@@ -15,15 +151,79 @@ function describeToolCall(name, args) {
   const list = [...named, ...unnamed > 0 ? [`+${unnamed} more`] : []].join(", ");
   return `Call tool "${name}" with args: ${list}`;
 }
+function escalationWaitMs(env) {
+  const raw = env.INTENDED_HOOK_ESCALATION_WAIT_SECONDS;
+  if (raw === void 0 || raw.trim() === "") return DEFAULT_ESCALATION_WAIT_SECONDS * 1e3;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.round(n * 1e3) : DEFAULT_ESCALATION_WAIT_SECONDS * 1e3;
+}
+function onPending(env) {
+  return env.INTENDED_HOOK_ON_PENDING?.trim().toLowerCase() === "ask" ? "ask" : "deny";
+}
+var UNCONFIGURED_OPT_OUT = "allow";
+function unconfiguredOptOut(env) {
+  return env.INTENDED_HOOK_UNCONFIGURED?.trim().toLowerCase() === UNCONFIGURED_OPT_OUT;
+}
+function missingConfig(env) {
+  const missing = [];
+  if (!env.INTENDED_API_KEY?.trim()) missing.push("INTENDED_API_KEY");
+  if (!env.INTENDED_TENANT_ID?.trim()) missing.push("INTENDED_TENANT_ID");
+  return missing;
+}
+function unconfiguredDenyReason(missing, toolName) {
+  return `Intended: blocked "${toolName}" because the Intended Claude Code hook is not configured (missing ${missing.join(" and ")}). The hook fails closed: without a key it cannot get an authority decision, so it denies every tool call it governs. To configure it, set INTENDED_API_KEY (an Intended API key with the intent:write and intent:read scopes) and INTENDED_TENANT_ID (your workspace id) in the environment Claude Code runs in, for example in the "env" block of .claude/settings.json or your shell profile, then retry. For a local trial without Intended, set INTENDED_HOOK_UNCONFIGURED=allow: tool calls then run ungoverned, with a warning on every call. Setup: https://www.intended.so/developers/docs/developer/decision-outcomes#claude-code-hook`;
+}
+function unconfiguredAllowWarning(missing, toolName) {
+  return `WARNING: Intended is NOT governing tool calls. "${toolName}" is running without an authority decision because INTENDED_HOOK_UNCONFIGURED=allow is set and the hook is not configured (missing ${missing.join(" and ")}). Use this only for local trials. Set INTENDED_API_KEY and INTENDED_TENANT_ID and remove INTENDED_HOOK_UNCONFIGURED to govern tool calls.`;
+}
 async function evaluateHookDecision(input) {
-  const { event, env } = input;
+  const { event, env, pendingStore } = input;
+  if (event === null || typeof event !== "object" || Array.isArray(event) || event.tool_input !== void 0 && (event.tool_input === null || typeof event.tool_input !== "object" || Array.isArray(event.tool_input))) {
+    const reason2 = "Intended: the tool call from Claude Code is not in the expected format, so it is not authorized (fail-closed).";
+    return {
+      permissionDecision: "deny",
+      reason: reason2,
+      record: { tool: "unknown", verdict: "UNREADABLE", reason: reason2, intentId: null, tokenIssued: false }
+    };
+  }
   const fetchImpl = input.fetchImpl ?? globalThis.fetch;
   const toolName = event.tool_name ?? "unknown";
   const args = { ...event.tool_input ?? {} };
-  const apiKey = env.INTENDED_API_KEY;
-  const tenantId = env.INTENDED_TENANT_ID;
   const apiUrl = (env.INTENDED_API_URL ?? "https://api.intended.so").replace(/\/$/, "");
-  if (!apiKey || !tenantId) return { permissionDecision: "allow" };
+  const missing = missingConfig(env);
+  if (missing.length > 0) {
+    if (unconfiguredOptOut(env)) {
+      const warning = unconfiguredAllowWarning(missing, toolName);
+      return {
+        permissionDecision: "allow",
+        warning,
+        record: { tool: toolName, verdict: "UNGOVERNED", reason: warning, intentId: null, tokenIssued: false }
+      };
+    }
+    const reason2 = unconfiguredDenyReason(missing, toolName);
+    return {
+      permissionDecision: "deny",
+      reason: reason2,
+      record: { tool: toolName, verdict: "UNCONFIGURED", reason: reason2, intentId: null, tokenIssued: false }
+    };
+  }
+  const apiKey = env.INTENDED_API_KEY.trim();
+  const tenantId = env.INTENDED_TENANT_ID.trim();
+  const key = toolCallKey(toolName, args);
+  const wait = (intentId) => waitForDecision(intentId, {
+    apiUrl,
+    apiKey,
+    tenantId,
+    fetchImpl,
+    timeoutMs: escalationWaitMs(env),
+    now: input.now,
+    sleep: input.sleep
+  });
+  const pendingIntentId = safe(() => pendingStore?.get(key));
+  if (pendingIntentId) {
+    const outcome = await wait(pendingIntentId);
+    return settle(outcome, pendingIntentId, toolName, key, env, pendingStore);
+  }
   let res;
   try {
     res = await fetchImpl(`${apiUrl}/v1/agent-intent`, {
@@ -54,38 +254,191 @@ async function evaluateHookDecision(input) {
     tokenIssued: Boolean(data.authorityDecisionToken)
   };
   if (verdict === "APPROVED") return { permissionDecision: "allow", record };
-  if (verdict === "ESCALATED") return { permissionDecision: "ask", reason: `Intended: requires human approval \u2014 ${reason}`, record };
+  if (verdict === "ESCALATED") {
+    if (!data.intentId) {
+      return { permissionDecision: "deny", reason: "Intended: escalated without an intent id to wait on \u2014 fail-closed.", record };
+    }
+    const outcome = await wait(data.intentId);
+    return settle(outcome, data.intentId, toolName, key, env, pendingStore, reason);
+  }
   return { permissionDecision: "deny", reason: `Intended: denied \u2014 ${reason || "fail-closed (unrecognized decision)"}`, record };
 }
+function settle(outcome, intentId, toolName, key, env, store, escalationReason = "") {
+  const record = {
+    tool: toolName,
+    verdict: outcome.status === "ALLOW" ? "APPROVED_AFTER_ESCALATION" : outcome.status === "PENDING" ? "ESCALATED" : outcome.status,
+    reason: outcome.reason || escalationReason,
+    intentId,
+    tokenIssued: Boolean(outcome.token)
+  };
+  if (outcome.status === "ALLOW") {
+    safe(() => store?.delete(key));
+    return { permissionDecision: "allow", record };
+  }
+  if (outcome.status === "PENDING") {
+    safe(() => store?.set(key, intentId, outcome.expiresAt));
+    const message = `Intended: awaiting human approval (intent ${intentId}). Ask an approver to approve it in the Intended console, then retry the same tool call; it will be allowed then.` + (outcome.timedOut && /could not be reached/.test(outcome.reason) ? ` (${outcome.reason})` : "");
+    return { permissionDecision: onPending(env), reason: message, record };
+  }
+  safe(() => store?.delete(key));
+  if (outcome.status === "EXPIRED") {
+    return {
+      permissionDecision: "deny",
+      reason: `Intended: denied \u2014 no approver decided before the approval request expired (intent ${intentId}).`,
+      record
+    };
+  }
+  if (outcome.status === "ERROR") {
+    return { permissionDecision: "deny", reason: `Intended: could not get the approval decision \u2014 ${outcome.reason}`, record };
+  }
+  return { permissionDecision: "deny", reason: `Intended: denied \u2014 ${outcome.reason}`, record };
+}
+function hookOutput(decision) {
+  if (decision.permissionDecision === "allow") {
+    return decision.warning ? { systemMessage: decision.warning } : null;
+  }
+  return {
+    ...decision.warning ? { systemMessage: decision.warning } : {},
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: decision.permissionDecision,
+      permissionDecisionReason: decision.reason
+    }
+  };
+}
+function safe(fn) {
+  try {
+    return fn();
+  } catch {
+    return void 0;
+  }
+}
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+var FilePendingStore = class {
+  constructor(path, maxEntries = 200, now = Date.now) {
+    this.path = path;
+    this.maxEntries = maxEntries;
+    this.now = now;
+  }
+  path;
+  maxEntries;
+  now;
+  get(key) {
+    const entries = this.load();
+    const e = entries[key];
+    if (!e) return void 0;
+    if (e.expiresAt <= this.now()) {
+      delete entries[key];
+      this.save(entries);
+      return void 0;
+    }
+    return e.intentId;
+  }
+  set(key, intentId, expiresAt) {
+    const entries = this.load();
+    const parsed = expiresAt ? Date.parse(expiresAt) : NaN;
+    entries[key] = {
+      intentId,
+      expiresAt: Number.isFinite(parsed) ? parsed : this.now() + DEFAULT_TTL_MS,
+      savedAt: this.now()
+    };
+    const keys = Object.keys(entries).sort((a, b) => entries[a].savedAt - entries[b].savedAt);
+    for (const k of keys.slice(0, Math.max(0, keys.length - this.maxEntries))) delete entries[k];
+    this.save(entries);
+  }
+  delete(key) {
+    const entries = this.load();
+    if (!(key in entries)) return;
+    delete entries[key];
+    this.save(entries);
+  }
+  /** Read the file and drop expired entries. */
+  load() {
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(this.path, "utf8"));
+    } catch {
+      return {};
+    }
+    const out = {};
+    if (!raw || typeof raw !== "object") return out;
+    const t = this.now();
+    for (const [k, v] of Object.entries(raw)) {
+      const e = v;
+      if (e && typeof e.intentId === "string" && typeof e.expiresAt === "number" && typeof e.savedAt === "number" && e.expiresAt > t) {
+        out[k] = { intentId: e.intentId, expiresAt: e.expiresAt, savedAt: e.savedAt };
+      }
+    }
+    return out;
+  }
+  save(entries) {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(entries, null, 2), { mode: 384 });
+    renameSync(tmp, this.path);
+  }
+};
 
-// src/bin.ts
-async function main() {
-  let event;
+// src/run.ts
+var UNREADABLE_INPUT_REASON = "Intended: could not read the tool call from Claude Code, so it is not authorized (fail-closed).";
+var HOOK_ERROR_REASON = "Intended: the hook failed before reaching a decision, so the tool call is not authorized (fail-closed).";
+function failClosedOutput(reason = HOOK_ERROR_REASON) {
+  return JSON.stringify(hookOutput({ permissionDecision: "deny", reason }));
+}
+function parseHookEvent(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+async function runHook(io) {
+  let decision;
   try {
-    event = JSON.parse(readFileSync(0, "utf8"));
+    const event = parseHookEvent(io.readInput());
+    if (!event) {
+      io.write(failClosedOutput(UNREADABLE_INPUT_REASON));
+      return;
+    }
+    const pendingStore = new FilePendingStore(join(io.stateDir, "pending.json"));
+    decision = await (io.evaluate ?? evaluateHookDecision)({ event, env: io.env, pendingStore });
   } catch {
-    process.exit(0);
+    io.write(failClosedOutput());
     return;
   }
-  const decision = await evaluateHookDecision({ event, env: process.env });
+  if (decision.warning) {
+    try {
+      io.writeError(`${decision.warning}
+`);
+    } catch {
+    }
+  }
   if (decision.record) {
     try {
-      const dir = join(homedir(), ".intended");
-      mkdirSync(dir, { recursive: true });
-      writeFileSync(join(dir, "last-decision.json"), JSON.stringify({ ...decision.record, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2));
+      mkdirSync(io.stateDir, { recursive: true });
+      writeFileSync(
+        join(io.stateDir, "last-decision.json"),
+        JSON.stringify({ ...decision.record, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+      );
     } catch {
     }
   }
-  if (decision.permissionDecision === "allow") process.exit(0);
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        permissionDecision: decision.permissionDecision,
-        permissionDecisionReason: decision.reason
-      }
-    })
-  );
-  process.exit(0);
+  const output = hookOutput(decision);
+  if (output) io.write(JSON.stringify(output));
 }
-void main();
+
+// src/bin.ts
+runHook({
+  readInput: () => readFileSync(0, "utf8"),
+  env: process.env,
+  write: (text) => process.stdout.write(text),
+  writeError: (text) => process.stderr.write(text),
+  stateDir: join(homedir(), ".intended")
+}).catch(() => {
+  try {
+    process.stdout.write(failClosedOutput());
+  } catch {
+  }
+}).finally(() => process.exit(0));

package/dist/index.d.mts

@@ -1,15 +1,3 @@
-/**
- * Pure, testable core of the Intended Claude Code PreToolUse hook.
- *
- * Contract:
- *  - Unconfigured (no API key / tenant) → ALLOW (fail-open; never bricks a repo).
- *  - Configured:
- *      200 APPROVED → allow
- *      202 ESCALATED → ask (human)
- *      403 DENIED → deny
- *      any other status (401/429/5xx/…), a network throw, or an unrecognized body
- *        → DENY (fail-closed). Never falls through to allow.
- */
 interface HookEvent {
     tool_name?: string;
     tool_input?: Record<string, unknown>;
@@ -18,10 +6,21 @@ interface HookEnv {
     INTENDED_API_KEY?: string;
     INTENDED_TENANT_ID?: string;
     INTENDED_API_URL?: string;
+    /** Seconds to wait for the approver on ESCALATED (default 45). */
+    INTENDED_HOOK_ESCALATION_WAIT_SECONDS?: string;
+    /** What to do when the decision is still pending after the wait: "deny" (default) or "ask". */
+    INTENDED_HOOK_ON_PENDING?: string;
+    /**
+     * What to do when the hook has no key or tenant: "deny" (default, fail-closed)
+     * or "allow" (local trials only; every call is ungoverned and warned about).
+     */
+    INTENDED_HOOK_UNCONFIGURED?: string;
 }
 interface HookDecision {
     permissionDecision: "allow" | "deny" | "ask";
     reason?: string;
+    /** A warning to show the user (Claude Code `systemMessage`), e.g. when running ungoverned. */
+    warning?: string;
     record?: {
         tool: string;
         verdict: string;
@@ -34,11 +33,76 @@ interface HookDecision {
 type FetchLike = (url: string, init?: unknown) => Promise<{
     status: number;
     json: () => Promise<unknown>;
+    headers?: {
+        get(name: string): string | null;
+    };
 }>;
+/**
+ * Where escalations still waiting on an approver are remembered between hook
+ * runs (each run is a separate process). Keyed by toolCallKey(tool, args).
+ */
+interface PendingStore {
+    get(key: string): string | undefined;
+    set(key: string, intentId: string, expiresAt?: string | null): void;
+    delete(key: string): void;
+}
+/** Claude Code hooks time out at 60s by default; leave headroom. */
+declare const DEFAULT_ESCALATION_WAIT_SECONDS = 45;
+/**
+ * The action text Intended stores (and explain_decision returns): the tool name
+ * and argument KEYS, never values. Values (e.g. the Bash command) travel only in
+ * `arguments`, which the API evaluates in memory and stores as a sha256 digest.
+ */
+declare function describeToolCall(name: string, args: Record<string, unknown>): string;
+/** INTENDED_HOOK_ESCALATION_WAIT_SECONDS → ms. Unset or invalid → 45s. */
+declare function escalationWaitMs(env: HookEnv): number;
+/** The documented opt-out value. Anything else (unset, "deny", a typo) keeps the hook fail-closed. */
+declare const UNCONFIGURED_OPT_OUT = "allow";
+/** True only when INTENDED_HOOK_UNCONFIGURED is exactly "allow" (case and surrounding space ignored). */
+declare function unconfiguredOptOut(env: HookEnv): boolean;
+/** Which required settings are missing ([] when configured). */
+declare function missingConfig(env: HookEnv): string[];
 declare function evaluateHookDecision(input: {
     event: HookEvent;
     env: HookEnv;
     fetchImpl?: FetchLike;
+    /** Remembers pending escalations across hook runs. Optional: without it, every call is a fresh intent. */
+    pendingStore?: PendingStore;
+    /** Clock + sleep overrides (tests). */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
 }): Promise<HookDecision>;
+/** The hook's stdout for a decision (Claude Code PreToolUse JSON), or null for a plain allow. */
+declare function hookOutput(decision: HookDecision): Record<string, unknown> | null;
+
+declare class FilePendingStore implements PendingStore {
+    private readonly path;
+    private readonly maxEntries;
+    private readonly now;
+    constructor(path: string, maxEntries?: number, now?: () => number);
+    get(key: string): string | undefined;
+    set(key: string, intentId: string, expiresAt?: string | null): void;
+    delete(key: string): void;
+    /** Read the file and drop expired entries. */
+    private load;
+    private save;
+}
+
+interface HookIo {
+    /** Raw stdin text from Claude Code. */
+    readInput: () => string;
+    env: HookEnv;
+    write: (text: string) => void;
+    writeError: (text: string) => void;
+    /** Directory for pending.json and last-decision.json (default ~/.intended). */
+    stateDir: string;
+    /** Override the decision (tests). */
+    evaluate?: typeof evaluateHookDecision;
+}
+/** The deny Claude Code gets when the hook cannot decide. */
+declare function failClosedOutput(reason?: string): string;
+/** Parse the event; anything but a JSON object is unreadable. */
+declare function parseHookEvent(raw: string): HookEvent | null;
+declare function runHook(io: HookIo): Promise<void>;
 
-export { type FetchLike, type HookDecision, type HookEnv, type HookEvent, evaluateHookDecision };
+export { DEFAULT_ESCALATION_WAIT_SECONDS, type FetchLike, FilePendingStore, type HookDecision, type HookEnv, type HookEvent, type HookIo, type PendingStore, UNCONFIGURED_OPT_OUT, describeToolCall, escalationWaitMs, evaluateHookDecision, failClosedOutput, hookOutput, missingConfig, parseHookEvent, runHook, unconfiguredOptOut };

package/dist/index.d.ts

@@ -1,15 +1,3 @@
-/**
- * Pure, testable core of the Intended Claude Code PreToolUse hook.
- *
- * Contract:
- *  - Unconfigured (no API key / tenant) → ALLOW (fail-open; never bricks a repo).
- *  - Configured:
- *      200 APPROVED → allow
- *      202 ESCALATED → ask (human)
- *      403 DENIED → deny
- *      any other status (401/429/5xx/…), a network throw, or an unrecognized body
- *        → DENY (fail-closed). Never falls through to allow.
- */
 interface HookEvent {
     tool_name?: string;
     tool_input?: Record<string, unknown>;
@@ -18,10 +6,21 @@ interface HookEnv {
     INTENDED_API_KEY?: string;
     INTENDED_TENANT_ID?: string;
     INTENDED_API_URL?: string;
+    /** Seconds to wait for the approver on ESCALATED (default 45). */
+    INTENDED_HOOK_ESCALATION_WAIT_SECONDS?: string;
+    /** What to do when the decision is still pending after the wait: "deny" (default) or "ask". */
+    INTENDED_HOOK_ON_PENDING?: string;
+    /**
+     * What to do when the hook has no key or tenant: "deny" (default, fail-closed)
+     * or "allow" (local trials only; every call is ungoverned and warned about).
+     */
+    INTENDED_HOOK_UNCONFIGURED?: string;
 }
 interface HookDecision {
     permissionDecision: "allow" | "deny" | "ask";
     reason?: string;
+    /** A warning to show the user (Claude Code `systemMessage`), e.g. when running ungoverned. */
+    warning?: string;
     record?: {
         tool: string;
         verdict: string;
@@ -34,11 +33,76 @@ interface HookDecision {
 type FetchLike = (url: string, init?: unknown) => Promise<{
     status: number;
     json: () => Promise<unknown>;
+    headers?: {
+        get(name: string): string | null;
+    };
 }>;
+/**
+ * Where escalations still waiting on an approver are remembered between hook
+ * runs (each run is a separate process). Keyed by toolCallKey(tool, args).
+ */
+interface PendingStore {
+    get(key: string): string | undefined;
+    set(key: string, intentId: string, expiresAt?: string | null): void;
+    delete(key: string): void;
+}
+/** Claude Code hooks time out at 60s by default; leave headroom. */
+declare const DEFAULT_ESCALATION_WAIT_SECONDS = 45;
+/**
+ * The action text Intended stores (and explain_decision returns): the tool name
+ * and argument KEYS, never values. Values (e.g. the Bash command) travel only in
+ * `arguments`, which the API evaluates in memory and stores as a sha256 digest.
+ */
+declare function describeToolCall(name: string, args: Record<string, unknown>): string;
+/** INTENDED_HOOK_ESCALATION_WAIT_SECONDS → ms. Unset or invalid → 45s. */
+declare function escalationWaitMs(env: HookEnv): number;
+/** The documented opt-out value. Anything else (unset, "deny", a typo) keeps the hook fail-closed. */
+declare const UNCONFIGURED_OPT_OUT = "allow";
+/** True only when INTENDED_HOOK_UNCONFIGURED is exactly "allow" (case and surrounding space ignored). */
+declare function unconfiguredOptOut(env: HookEnv): boolean;
+/** Which required settings are missing ([] when configured). */
+declare function missingConfig(env: HookEnv): string[];
 declare function evaluateHookDecision(input: {
     event: HookEvent;
     env: HookEnv;
     fetchImpl?: FetchLike;
+    /** Remembers pending escalations across hook runs. Optional: without it, every call is a fresh intent. */
+    pendingStore?: PendingStore;
+    /** Clock + sleep overrides (tests). */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
 }): Promise<HookDecision>;
+/** The hook's stdout for a decision (Claude Code PreToolUse JSON), or null for a plain allow. */
+declare function hookOutput(decision: HookDecision): Record<string, unknown> | null;
+
+declare class FilePendingStore implements PendingStore {
+    private readonly path;
+    private readonly maxEntries;
+    private readonly now;
+    constructor(path: string, maxEntries?: number, now?: () => number);
+    get(key: string): string | undefined;
+    set(key: string, intentId: string, expiresAt?: string | null): void;
+    delete(key: string): void;
+    /** Read the file and drop expired entries. */
+    private load;
+    private save;
+}
+
+interface HookIo {
+    /** Raw stdin text from Claude Code. */
+    readInput: () => string;
+    env: HookEnv;
+    write: (text: string) => void;
+    writeError: (text: string) => void;
+    /** Directory for pending.json and last-decision.json (default ~/.intended). */
+    stateDir: string;
+    /** Override the decision (tests). */
+    evaluate?: typeof evaluateHookDecision;
+}
+/** The deny Claude Code gets when the hook cannot decide. */
+declare function failClosedOutput(reason?: string): string;
+/** Parse the event; anything but a JSON object is unreadable. */
+declare function parseHookEvent(raw: string): HookEvent | null;
+declare function runHook(io: HookIo): Promise<void>;
 
-export { type FetchLike, type HookDecision, type HookEnv, type HookEvent, evaluateHookDecision };
+export { DEFAULT_ESCALATION_WAIT_SECONDS, type FetchLike, FilePendingStore, type HookDecision, type HookEnv, type HookEvent, type HookIo, type PendingStore, UNCONFIGURED_OPT_OUT, describeToolCall, escalationWaitMs, evaluateHookDecision, failClosedOutput, hookOutput, missingConfig, parseHookEvent, runHook, unconfiguredOptOut };