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

package/README.md

@@ -24,7 +24,9 @@ authority layer — "no token, no action" before execution.
 
 | State | Result |
 |---|---|
-| Unconfigured (no `INTENDED_API_KEY` / `INTENDED_TENANT_ID`) | **allow** (fail-open — never bricks a repo) |
+| Unconfigured (no `INTENDED_API_KEY` / `INTENDED_TENANT_ID`, or either is blank) | **deny** every governed tool call, with a message naming what is missing and how to fix it |
+| Unconfigured with `INTENDED_HOOK_UNCONFIGURED=allow` | allow, **ungoverned**, with a warning on every call (for local trials only) |
+| Hook input that is not a JSON object, or any error inside the hook | **deny** (the hook always exits 0 with an answer, so a crash never lets a tool run) |
 | `200 APPROVED` | allow |
 | `202 ESCALATED` | **wait** for the approver in Intended (see below) |
 | `403 DENIED` | **deny** (with reason) |
@@ -59,9 +61,14 @@ seconds, raise the hook's `timeout` (in seconds) above the wait:
 
 and set `INTENDED_HOOK_ESCALATION_WAIT_SECONDS` below it (for example `280`).
 
-Config (env): `INTENDED_API_KEY`, `INTENDED_TENANT_ID`, `INTENDED_API_URL` (optional),
-`INTENDED_HOOK_ESCALATION_WAIT_SECONDS` (default `45`), `INTENDED_HOOK_ON_PENDING`
-(`deny` or `ask`, default `deny`).
+Config (env): `INTENDED_API_KEY` (scopes `intent:write` and `intent:read`), `INTENDED_TENANT_ID`,
+`INTENDED_API_URL` (optional), `INTENDED_HOOK_ESCALATION_WAIT_SECONDS` (default `45`),
+`INTENDED_HOOK_ON_PENDING` (`deny` or `ask`, default `deny`), `INTENDED_HOOK_UNCONFIGURED`
+(set to `allow` to let tool calls through ungoverned while the hook is unconfigured; anything
+else, or unset, denies).
+
+Upgrading from 0.2: an unconfigured hook used to allow every call silently. It now denies.
+Set the key and tenant, or set `INTENDED_HOOK_UNCONFIGURED=allow` while you try it out.
 Attribution: actor = `claude-code:<tool>`. Last decision → `~/.intended/last-decision.json`.
 
 It's a CLI (the SDK is the library). Apache-2.0.

package/dist/bin.js

@@ -162,15 +162,55 @@ function escalationWaitMs(env) {
 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, 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,
@@ -255,6 +295,19 @@ function settle(outcome, intentId, toolName, key, env, store, escalationReason =
   }
   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();
@@ -328,35 +381,66 @@ var FilePendingStore = class {
   }
 };
 
-// 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 {
-    event = JSON.parse(fs.readFileSync(0, "utf8"));
+    const value = JSON.parse(raw);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+    return value;
   } catch {
-    process.exit(0);
+    return null;
+  }
+}
+async function runHook(io) {
+  let decision;
+  try {
+    const event = parseHookEvent(io.readInput());
+    if (!event) {
+      io.write(failClosedOutput(UNREADABLE_INPUT_REASON));
+      return;
+    }
+    const pendingStore = new FilePendingStore(path.join(io.stateDir, "pending.json"));
+    decision = await (io.evaluate ?? evaluateHookDecision)({ event, env: io.env, pendingStore });
+  } catch {
+    io.write(failClosedOutput());
     return;
   }
-  const pendingStore = new FilePendingStore(path.join(os.homedir(), ".intended", "pending.json"));
-  const decision = await evaluateHookDecision({ event, env: process.env, pendingStore });
+  if (decision.warning) {
+    try {
+      io.writeError(`${decision.warning}
+`);
+    } catch {
+    }
+  }
   if (decision.record) {
     try {
-      const dir = path.join(os.homedir(), ".intended");
-      fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(path.join(dir, "last-decision.json"), JSON.stringify({ ...decision.record, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2));
+      fs.mkdirSync(io.stateDir, { recursive: true });
+      fs.writeFileSync(
+        path.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: () => fs.readFileSync(0, "utf8"),
+  env: process.env,
+  write: (text) => process.stdout.write(text),
+  writeError: (text) => process.stderr.write(text),
+  stateDir: path.join(os.homedir(), ".intended")
+}).catch(() => {
+  try {
+    process.stdout.write(failClosedOutput());
+  } catch {
+  }
+}).finally(() => process.exit(0));

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, mkdirSync, writeFileSync, renameSync } from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, renameSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
 import { createHash } from 'crypto';
@@ -160,15 +160,55 @@ function escalationWaitMs(env) {
 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, 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,
@@ -253,6 +293,19 @@ function settle(outcome, intentId, toolName, key, env, store, escalationReason =
   }
   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();
@@ -326,35 +379,66 @@ var FilePendingStore = class {
   }
 };
 
-// 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 {
-    event = JSON.parse(readFileSync(0, "utf8"));
+    const value = JSON.parse(raw);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+    return value;
   } catch {
-    process.exit(0);
+    return null;
+  }
+}
+async function runHook(io) {
+  let decision;
+  try {
+    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 {
+    io.write(failClosedOutput());
     return;
   }
-  const pendingStore = new FilePendingStore(join(homedir(), ".intended", "pending.json"));
-  const decision = await evaluateHookDecision({ event, env: process.env, pendingStore });
+  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

@@ -10,10 +10,17 @@ interface HookEnv {
     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;
@@ -49,6 +56,12 @@ declare const DEFAULT_ESCALATION_WAIT_SECONDS = 45;
 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;
@@ -59,6 +72,8 @@ declare function evaluateHookDecision(input: {
     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;
@@ -73,4 +88,21 @@ declare class FilePendingStore implements PendingStore {
     private save;
 }
 
-export { DEFAULT_ESCALATION_WAIT_SECONDS, type FetchLike, FilePendingStore, type HookDecision, type HookEnv, type HookEvent, type PendingStore, describeToolCall, escalationWaitMs, evaluateHookDecision };
+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 { 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

@@ -10,10 +10,17 @@ interface HookEnv {
     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;
@@ -49,6 +56,12 @@ declare const DEFAULT_ESCALATION_WAIT_SECONDS = 45;
 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;
@@ -59,6 +72,8 @@ declare function evaluateHookDecision(input: {
     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;
@@ -73,4 +88,21 @@ declare class FilePendingStore implements PendingStore {
     private save;
 }
 
-export { DEFAULT_ESCALATION_WAIT_SECONDS, type FetchLike, FilePendingStore, type HookDecision, type HookEnv, type HookEvent, type PendingStore, describeToolCall, escalationWaitMs, evaluateHookDecision };
+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 { 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.js

@@ -161,15 +161,55 @@ function escalationWaitMs(env) {
 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, 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,
@@ -254,6 +294,19 @@ function settle(outcome, intentId, toolName, key, env, store, escalationReason =
   }
   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();
@@ -326,9 +379,64 @@ var FilePendingStore = class {
     fs.renameSync(tmp, this.path);
   }
 };
+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 {
+    const event = parseHookEvent(io.readInput());
+    if (!event) {
+      io.write(failClosedOutput(UNREADABLE_INPUT_REASON));
+      return;
+    }
+    const pendingStore = new FilePendingStore(path.join(io.stateDir, "pending.json"));
+    decision = await (io.evaluate ?? evaluateHookDecision)({ event, env: io.env, pendingStore });
+  } catch {
+    io.write(failClosedOutput());
+    return;
+  }
+  if (decision.warning) {
+    try {
+      io.writeError(`${decision.warning}
+`);
+    } catch {
+    }
+  }
+  if (decision.record) {
+    try {
+      fs.mkdirSync(io.stateDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(io.stateDir, "last-decision.json"),
+        JSON.stringify({ ...decision.record, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+      );
+    } catch {
+    }
+  }
+  const output = hookOutput(decision);
+  if (output) io.write(JSON.stringify(output));
+}
 
 exports.DEFAULT_ESCALATION_WAIT_SECONDS = DEFAULT_ESCALATION_WAIT_SECONDS;
 exports.FilePendingStore = FilePendingStore;
+exports.UNCONFIGURED_OPT_OUT = UNCONFIGURED_OPT_OUT;
 exports.describeToolCall = describeToolCall;
 exports.escalationWaitMs = escalationWaitMs;
 exports.evaluateHookDecision = evaluateHookDecision;
+exports.failClosedOutput = failClosedOutput;
+exports.hookOutput = hookOutput;
+exports.missingConfig = missingConfig;
+exports.parseHookEvent = parseHookEvent;
+exports.runHook = runHook;
+exports.unconfiguredOptOut = unconfiguredOptOut;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createHash } from 'crypto';
 import { readFileSync, mkdirSync, writeFileSync, renameSync } from 'fs';
-import { dirname } from 'path';
+import { dirname, join } from 'path';
 
 // src/wait.ts
 var FINAL = /* @__PURE__ */ new Set(["ALLOW", "DENY", "EXPIRED"]);
@@ -159,15 +159,55 @@ function escalationWaitMs(env) {
 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, 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,
@@ -252,6 +292,19 @@ function settle(outcome, intentId, toolName, key, env, store, escalationReason =
   }
   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();
@@ -324,5 +377,53 @@ var FilePendingStore = class {
     renameSync(tmp, this.path);
   }
 };
+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 {
+    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 {
+    io.write(failClosedOutput());
+    return;
+  }
+  if (decision.warning) {
+    try {
+      io.writeError(`${decision.warning}
+`);
+    } catch {
+    }
+  }
+  if (decision.record) {
+    try {
+      mkdirSync(io.stateDir, { recursive: true });
+      writeFileSync(
+        join(io.stateDir, "last-decision.json"),
+        JSON.stringify({ ...decision.record, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+      );
+    } catch {
+    }
+  }
+  const output = hookOutput(decision);
+  if (output) io.write(JSON.stringify(output));
+}
 
-export { DEFAULT_ESCALATION_WAIT_SECONDS, FilePendingStore, describeToolCall, escalationWaitMs, evaluateHookDecision };
+export { DEFAULT_ESCALATION_WAIT_SECONDS, FilePendingStore, UNCONFIGURED_OPT_OUT, describeToolCall, escalationWaitMs, evaluateHookDecision, failClosedOutput, hookOutput, missingConfig, parseHookEvent, runHook, unconfiguredOptOut };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@intended-inc/claude-code-hook",
-  "version": "0.2.0",
-  "description": "Claude Code PreToolUse hook — govern every tool call through Intended's authority layer. Fail-open when unconfigured, fail-closed on DENY / unreachable / non-2xx. npx-invokable from .claude/settings.json.",
+  "version": "0.3.0",
+  "description": "Claude Code PreToolUse hook — govern every tool call through Intended's authority layer. Fail-closed when unconfigured (opt out with INTENDED_HOOK_UNCONFIGURED=allow) and on DENY / unreachable / non-2xx. npx-invokable from .claude/settings.json.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",