agent-sanitizer 2.47.2 → 2.47.4

package/README.md

@@ -250,6 +250,8 @@ To wire them yourself instead, one entry dispatches every mode on `--hook=`:
 
 **Wire all five.** The instruction-file scan is split across two of them: `SessionStart` covers the files that load at launch, and `InstructionsLoaded` covers every one a subdirectory loads later. A host that wires the first without the second leaves a nested `CLAUDE.md` scanned by nothing, and the one-time PreToolUse coverage notice is the only thing that says so.
 
+`InstructionsLoaded` needs Claude Code **2.1.69 or newer** — 2.1.68 does not emit the event, so the hook never fires however you wire it. Check with `claude --version`.
+
 `require.resolve("agent-sanitizer/claude-hooks")` gives the path without
 hardcoding a layout. Importing the module rather than spawning it is a no-op.
 

package/THREAT-MODEL.md

@@ -377,8 +377,9 @@ confined to `CLAUDE_PROJECT_DIR` in both — an ancestor file, or one under
 `~/.claude`, is shared with every other project on the machine, so it is reported
 through the cross-hook alert and never rewritten. Three things lose the lazy half
 entirely: a host that never wired the `InstructionsLoaded` event to
-`scan-loaded-instructions`, a Claude Code build that does not emit that event,
-and `scan-loaded-instructions` switched off in `AGENT_SANITIZER_DISABLED_HOOKS`.
+`scan-loaded-instructions`, a Claude Code older than 2.1.69, which is the first
+build that emits that event, and `scan-loaded-instructions` switched off in
+`AGENT_SANITIZER_DISABLED_HOOKS`.
 Nothing on disk tells them apart, so the PreToolUse gate names all three, once
 per session, rather than leaving the gap silent.
 

package/claude-hooks/lib/invisible-alert.mjs

@@ -302,6 +302,14 @@ export function recordInstructionsLoaded(sessionId) {
   sweepStaleSessions(sessionId);
 }
 
+/**
+ * The first `@anthropic-ai/claude-code` release that emits `InstructionsLoaded`.
+ * 2.1.68 carries no occurrence of the event name and 2.1.69 carries eight, so a
+ * CLI below this floor never fires the hook however it is wired. The gap notice
+ * quotes it: "upgrade" is unactionable without the number to compare against.
+ */
+const EVENT_MIN_CLI_VERSION = "2.1.69";
+
 /**
  * The one-time context line for a session where no InstructionsLoaded scan ran,
  * or null when the scan has been seen or the notice was already surfaced this
@@ -318,10 +326,10 @@ export function recordInstructionsLoaded(sessionId) {
  *
  * The notice names the OBSERVABLE — no scan ran — and all three causes, because
  * the marker cannot tell them apart: a host that never wired the event to
- * scan-loaded-instructions, a Claude Code that does not emit it, and the hook
- * switched off in AGENT_SANITIZER_DISABLED_HOOKS; asserting one sends a reader
- * who is in another to the wrong fix. The wiring cause leads because it is the
- * only one the reader can repair in this session, and nothing else reports it.
+ * scan-loaded-instructions, a Claude Code older than EVENT_MIN_CLI_VERSION, and
+ * the hook switched off in AGENT_SANITIZER_DISABLED_HOOKS; asserting one sends a
+ * reader who is in another to the wrong fix. The wiring cause leads because it is
+ * the only one the reader can repair in this session, and nothing else reports it.
  * @param {string} [sessionId]  the harness's session identity, so the answer
  *   belongs to THIS session (see instructionsLoadedFile)
  * @returns {string | null}
@@ -334,11 +342,15 @@ export function instructionsLoadedGapNotice(sessionId) {
     "instruction files loaded from SUBDIRECTORIES (a nested CLAUDE.md, a " +
     "directory-scoped rule) are reaching the model unscanned for hidden " +
     "Unicode — the session-start scan covers only the files loaded at launch. " +
-    "Tell the user, and name all three causes: this host never wired the " +
-    "InstructionsLoaded event to scan-loaded-instructions (wiring it restores " +
-    "the coverage), a Claude Code that does not emit the event (upgrading " +
-    "restores it), or scan-loaded-instructions switched off in " +
-    "AGENT_SANITIZER_DISABLED_HOOKS."
+    "Tell the user, and name all three causes with the command that decides " +
+    "each: this host never wired the InstructionsLoaded event to " +
+    "scan-loaded-instructions (the `/hooks` command lists what this session " +
+    "actually registered, whichever config dir or plugin root the host uses; " +
+    "wiring it restores the coverage), a Claude Code " +
+    `older than ${EVENT_MIN_CLI_VERSION}, the first build that emits the event ` +
+    "(`claude --version`; upgrading restores it), or scan-loaded-instructions " +
+    "switched off in AGENT_SANITIZER_DISABLED_HOOKS (`echo " +
+    "$AGENT_SANITIZER_DISABLED_HOOKS`)."
   );
 }
 

package/claude-hooks/pretooluse-sanitize.mjs

@@ -81,7 +81,8 @@ const HOOK_NAME = "pretooluse-sanitize";
  * must be blocked, or null to let the pipeline continue. Hosts use these for
  * policy the package has no view of (a required workflow step, a project-local
  * rule); the package ships none.
- * @typedef {(input: { tool_name: string | null, tool_input: any, session_id?: string })
+ * @typedef {(input: { tool_name: string | null, tool_input: any, session_id?: string,
+ *   permission_mode?: string })
  *   => string | null | undefined} HostGate
  */
 
@@ -595,13 +596,16 @@ export async function judgePreToolUseSanitize(event, rehydrate, opts = {}) {
   // a pass is the one incentive a gate must never create.
   if (event.event === EventKind.UNKNOWN)
     return { decision: Decision.DENY, reason: messages.unknownEvent };
-  // The session identity travels in `meta`, not alongside the tool input; a host
-  // gate keyed on the session (a once-per-session checkpoint) cannot tell two
-  // sessions apart without it.
+  // The session identity and the permission mode travel in `meta`, not alongside
+  // the tool input. A gate keyed on the session (a once-per-session checkpoint)
+  // cannot tell two sessions apart without the first, and a gate keyed on the
+  // mode reads `undefined` without the second — so it fires in EVERY mode, which
+  // is the safe direction but not the intended one.
   const input = {
     tool_name: event.tool,
     tool_input: event.input,
     session_id: event.meta?.session_id,
+    permission_mode: event.meta?.permission_mode,
   };
   // Host gates run BEFORE any rewriting layer, because they decide whether the
   // call may happen at all rather than what its input contains — and returning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.47.2",
+  "version": "2.47.4",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/types/claude-hooks/lib/invisible-alert.d.mts

@@ -90,10 +90,10 @@ export function recordInstructionsLoaded(sessionId?: string): void;
  *
  * The notice names the OBSERVABLE — no scan ran — and all three causes, because
  * the marker cannot tell them apart: a host that never wired the event to
- * scan-loaded-instructions, a Claude Code that does not emit it, and the hook
- * switched off in AGENT_SANITIZER_DISABLED_HOOKS; asserting one sends a reader
- * who is in another to the wrong fix. The wiring cause leads because it is the
- * only one the reader can repair in this session, and nothing else reports it.
+ * scan-loaded-instructions, a Claude Code older than EVENT_MIN_CLI_VERSION, and
+ * the hook switched off in AGENT_SANITIZER_DISABLED_HOOKS; asserting one sends a
+ * reader who is in another to the wrong fix. The wiring cause leads because it is
+ * the only one the reader can repair in this session, and nothing else reports it.
  * @param {string} [sessionId]  the harness's session identity, so the answer
  *   belongs to THIS session (see instructionsLoadedFile)
  * @returns {string | null}

package/types/claude-hooks/pretooluse-sanitize.d.mts

@@ -188,7 +188,8 @@ export function cliMain(opts?: {
  * must be blocked, or null to let the pipeline continue. Hosts use these for
  * policy the package has no view of (a required workflow step, a project-local
  * rule); the package ships none.
- * @typedef {(input: { tool_name: string | null, tool_input: any, session_id?: string })
+ * @typedef {(input: { tool_name: string | null, tool_input: any, session_id?: string,
+ *   permission_mode?: string })
  *   => string | null | undefined} HostGate
  */
 /**
@@ -221,6 +222,7 @@ export type HostGate = (input: {
     tool_name: string | null;
     tool_input: any;
     session_id?: string;
+    permission_mode?: string;
 }) => string | null | undefined;
 declare const rehydrateRedacted: typeof import("agent-sanitizer/rehydrate").rehydrateRedacted;
 export {};