passcontrol 1.6.0 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -92,6 +92,7 @@ import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from
92
92
  import { startSidecar } from "../cli/sidecar.mjs";
93
93
  import { listProfiles, profilePath, readProfile, TOOL_PROFILE_PORTS, writeProfile } from "../cli/profiles.mjs";
94
94
  import {
95
+ apiToolHooks,
95
96
  claudeCodeEnv,
96
97
  claudeCodeSettingsPath,
97
98
  removeClaudeCodeSettings,
@@ -282,6 +283,8 @@ ${heading("Integrate")}
282
283
  ${cmd} env [integration] print settings without writing anything
283
284
  ${cmd} configure <integration> [--write] [--force] [--dedicated]
284
285
  preview or write integration config
286
+ ${cmd} configure claude-code --write
287
+ route model calls; tools ask the sidecar first
285
288
  ${cmd} configure claude-code --subscription [--write|--remove]
286
289
  a Pro/Max login: stops, calls, usage window
287
290
  ${cmd} configure codex --subscription [--write|--remove]
@@ -2784,7 +2787,7 @@ function aiderConfig(opts = {}) {
2784
2787
  /**
2785
2788
  * Claude Code's own model calls, through the sidecar (cli/claude-code.mjs). The
2786
2789
  * project's settings by default; `--global` for every session; `--remove` takes
2787
- * PassControl's two keys back out. The MCP chat tool stays a separate command
2790
+ * PassControl's env keys and tool hook back out. The MCP chat tool stays a separate command
2788
2791
  * Claude Code owns.
2789
2792
  */
2790
2793
  function configureClaudeCode(opts = {}) {
@@ -2799,11 +2802,11 @@ function configureClaudeCode(opts = {}) {
2799
2802
  }
2800
2803
  const { baseUrl, port } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
2801
2804
  const note = Boolean(opts.agentNote);
2802
- const preview = { env: claudeCodeEnv(baseUrl) };
2803
- if (note) preview.hooks = { UserPromptSubmit: [{ hooks: [{ type: "http", url: `http://127.0.0.1:${port}/_passcontrol/hook?note=only`, timeout: 5 }] }] };
2805
+ const preview = { env: claudeCodeEnv(baseUrl), hooks: apiToolHooks(port) };
2806
+ if (note) preview.hooks = { ...preview.hooks, UserPromptSubmit: [{ hooks: [{ type: "http", url: `http://127.0.0.1:${port}/_passcontrol/hook?note=only`, timeout: 5 }] }] };
2804
2807
  console.log(`Preview: ${target}\n\n${JSON.stringify(preview, null, 2)}`);
2805
2808
  if (!opts.write) {
2806
- step(`Dry run only. Re-run with \`--write\` to merge these two keys${scope === "project" ? " (or --write --global for every session)" : ""}.`);
2809
+ step(`Dry run only. Re-run with \`--write\` to merge these env keys and the tool hook${scope === "project" ? " (or --write --global for every session)" : ""}.`);
2807
2810
  } else {
2808
2811
  const result = writeClaudeCodeSettings({
2809
2812
  target,
@@ -2811,12 +2814,14 @@ function configureClaudeCode(opts = {}) {
2811
2814
  force: Boolean(opts.force),
2812
2815
  statusLineCommand: opts.statusline ? statusLineSettingsCommand(port) : null,
2813
2816
  noteHookPort: note ? port : null,
2817
+ toolHookPort: port,
2814
2818
  });
2815
2819
  if (!result.changed) ok(`${target} already routes Claude Code through PassControl`);
2816
2820
  else {
2817
2821
  if (result.backupPath) step(`backed up ${result.backupPath}`);
2818
2822
  ok(`wrote ${target}`);
2819
2823
  }
2824
+ ok("Claude Code’s tools now ask the sidecar first for the agent’s tool rules and the injection guard’s hold.");
2820
2825
  if (result.statusLine?.existing) {
2821
2826
  warn(`${target} already has a status line (${result.statusLine.existing}); it was left as it is. To show the budget there, add \`${statusLineSettingsCommand(port)}\` to it yourself.`);
2822
2827
  } else if (result.statusLine?.changed) ok("added the agent's budget to Claude Code's status line");
@@ -2982,7 +2987,7 @@ function profileCommand(rest, opts) {
2982
2987
  /**
2983
2988
  * Subscription mode for Codex (cli/codex-hooks.mjs): a ChatGPT login keeps talking
2984
2989
  * to OpenAI directly; PassControl's stops and tool rules reach the session through
2985
- * two hooks in $CODEX_HOME/hooks.json, next to anyone else's.
2990
+ * three hooks in $CODEX_HOME/hooks.json, next to anyone else's.
2986
2991
  */
2987
2992
  function configureCodexSubscription(opts = {}) {
2988
2993
  const target = codexHooksPath();
@@ -2998,14 +3003,14 @@ function configureCodexSubscription(opts = {}) {
2998
3003
  const command = codexHookCommand({ port, entry: fs.realpathSync(CLI_ENTRY) });
2999
3004
  console.log(`Preview: added to ${target} (anything already there is kept)\n\n${JSON.stringify(codexHookEntries(command), null, 2)}`);
3000
3005
  if (!opts.write) {
3001
- step("Dry run only. Re-run with `--write` to add these two hooks.");
3006
+ step("Dry run only. Re-run with `--write` to add these three hooks.");
3002
3007
  } else {
3003
3008
  const result = writeCodexHooks({ target, command });
3004
3009
  if (!result.changed) ok(`${target} already has PassControl's hooks`);
3005
3010
  else {
3006
3011
  if (result.backupPath) step(`backed up ${result.backupPath}`);
3007
3012
  ok(`wrote ${target}`);
3008
- warn("Not on yet: Codex runs a hook only after you trust it. Open Codex, type /hooks, and trust PassControl's two hooks. Until then they are skipped without a word.");
3013
+ warn("Not on yet: Codex runs a hook only after you trust it. Open Codex, type /hooks, and trust PassControl's three hooks (any you trusted before stay trusted). Until then they are skipped without a word.");
3009
3014
  }
3010
3015
  const probe = probeCodexHookCommand(command);
3011
3016
  if (probe.ok) ok("the hook command runs on its own, without your shell's PATH");
@@ -3013,6 +3018,7 @@ function configureCodexSubscription(opts = {}) {
3013
3018
  }
3014
3019
  step(`Start the sidecar before Codex: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
3015
3020
  step("Your ChatGPT login stays between Codex and OpenAI. PassControl never sees it or sits in the path.");
3021
+ step("For the injection guard, the tool output Codex hands its PostToolUse hook is also checked on this machine; some built-in or hosted tools may not hand theirs over. That hook never blocks a tool or changes what it returned.");
3016
3022
  step("What it does: a suspended agent, or the kill switch, blocks the next prompt and refuses tools. The agent's tool rules refuse what they deny; an \"ask the owner\" rule waits for the owner's answer.");
3017
3023
  step("What it cannot do, plainly:");
3018
3024
  step(" Codex has no strict hook mode. If the sidecar is not running, or a hook fails, Codex goes ahead (with a warning when the sidecar is down).");
@@ -3475,14 +3481,20 @@ async function verifyCommand(rest, opts) {
3475
3481
  // Lineage is DECLARED by the client: any local process can send those
3476
3482
  // headers. Say so on the same line, so nobody reads it as passport-proven.
3477
3483
  // Printable ASCII only: a signed value is still not a terminal's to obey.
3484
+ const shown = (v) => String(v).replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
3478
3485
  if (c.ctx?.ses) {
3479
- const shown = (v) => String(v).replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
3480
3486
  const who = c.ctx.agt
3481
3487
  ? `sub-agent ${shown(c.ctx.agt)}${c.ctx.par ? `, spawned by ${shown(c.ctx.par)}` : ""}`
3482
3488
  : "main agent";
3483
3489
  step(`Session: ${shown(c.ctx.ses)} · ${who}`);
3484
3490
  step(` declared by the client (${shown(c.ctx.cli ?? "unknown")}), not verified`);
3485
3491
  }
3492
+ const inj = c.inj;
3493
+ if (typeof inj === "object" && inj !== null && !Array.isArray(inj) &&
3494
+ typeof inj.d === "string" && inj.d && Number.isSafeInteger(inj.n) && inj.n >= 1 && Array.isArray(inj.f)) {
3495
+ step(`Injection: ${inj.n} block(s) of tool output carried injection tells (${shown(inj.d)})`);
3496
+ step(` kinds: ${inj.f.slice(0, 16).map(shown).join(", ")}`);
3497
+ }
3486
3498
  }
3487
3499
  if (c.own) {
3488
3500
  step(
@@ -6,7 +6,7 @@
6
6
  // Bearer token with no "use this API key?" prompt. The sidecar strips it and the
7
7
  // gateway injects the real key, so Claude Code never holds one.
8
8
  //
9
- // The settings file belongs to the user. Only these two keys, and with
9
+ // The settings file belongs to the user. The env keys and tool hook, and with
10
10
  // --statusline a `statusLine` running `passcontrol statusline`, are written or
11
11
  // removed, in one save; the previous file is backed up, a file that is not a JSON
12
12
  // object is refused rather than overwritten, a different gateway already
@@ -96,7 +96,7 @@ function withNoteOnlyHook(hooks, port) {
96
96
  * The env keys, and with `statusLineCommand` the status line too, in ONE save:
97
97
  * two saves would back up the first save's output and lose the user's original.
98
98
  */
99
- export function writeClaudeCodeSettings({ target, baseUrl, force = false, statusLineCommand = null, noteHookPort = null }) {
99
+ export function writeClaudeCodeSettings({ target, baseUrl, force = false, statusLineCommand = null, noteHookPort = null, toolHookPort = null }) {
100
100
  const { exists, value } = readSettings(target);
101
101
  const env = typeof value.env === "object" && value.env !== null && !Array.isArray(value.env) ? value.env : {};
102
102
  const rawKeyFound = typeof env.ANTHROPIC_API_KEY === "string" && env.ANTHROPIC_API_KEY.length > 0;
@@ -114,7 +114,8 @@ export function writeClaudeCodeSettings({ target, baseUrl, force = false, status
114
114
  next = line.value;
115
115
  statusLine = line.existing !== undefined ? { changed: false, existing: line.existing } : { changed: line.changed };
116
116
  }
117
- const hooks = withNoteOnlyHook(value.hooks, noteHookPort);
117
+ // configure passes the sidecar's port; URL.port is "" for :80, which would write a hook to nowhere.
118
+ const hooks = withApiTools(withNoteOnlyHook(value.hooks, noteHookPort), toolHookPort ?? (new URL(baseUrl).port || 80));
118
119
  const hooksChanged = !same(hooks ?? null, value.hooks ?? null);
119
120
  if (hooksChanged) {
120
121
  next = { ...next };
@@ -126,7 +127,7 @@ export function writeClaudeCodeSettings({ target, baseUrl, force = false, status
126
127
  return { changed, backupPath, rawKeyFound, ...(statusLine ? { statusLine } : {}) };
127
128
  }
128
129
 
129
- /** PassControl's two env keys and its status line, in one save. */
130
+ /** PassControl's env keys, tool hook, optional note and status line, in one save. */
130
131
  export function removeClaudeCodeSettings({ target }) {
131
132
  if (!fs.existsSync(target)) return { changed: false };
132
133
  const { value } = readSettings(target);
@@ -145,7 +146,7 @@ export function removeClaudeCodeSettings({ target }) {
145
146
  next = rest;
146
147
  }
147
148
  if (isObject(next.hooks)) {
148
- const hooks = withNoteOnlyHook(next.hooks, null);
149
+ const hooks = withApiTools(withNoteOnlyHook(next.hooks, null), null);
149
150
  if (!same(hooks, next.hooks)) {
150
151
  next = { ...next };
151
152
  if (Object.keys(hooks).length) next.hooks = hooks;
@@ -218,11 +219,10 @@ export function removeClaudeCodeStatusLine({ target }) {
218
219
 
219
220
  const LOOPBACK_BASE = "http://127.0.0.1:";
220
221
  const OUR_LOGS_ENDPOINT = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/otlp\/v1\/logs$/;
221
- const OUR_HOOK_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook(\?(t=\d{1,4}|note=1))?$/;
222
+ const OUR_HOOK_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook(\?(t=\d{1,4}(&mode=api)?|note=1))?$/;
222
223
  // API mode's own prompt hook, for the agent's note only (1.6.0): never a stop.
223
224
  const OUR_NOTE_ONLY_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook\?note=only$/;
224
225
  const OUR_SIDECAR_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}$/;
225
- const GATED_EVENTS = ["UserPromptSubmit", "PreToolUse", "PostToolBatch"];
226
226
  // The log-export settings this mode owns, with the value it writes.
227
227
  const LOGS_ENV = {
228
228
  OTEL_LOGS_EXPORTER: "otlp",
@@ -250,8 +250,38 @@ function gateHook(port, note = false) {
250
250
  // told, and a Phase 1 hook (no `t`, 5 s) refuses a tool that would need the owner
251
251
  // instead of letting it through on the timeout.
252
252
  export const TOOL_HOOK_TIMEOUT_S = 600;
253
- function toolHook(port) {
254
- return { type: "http", url: `${LOOPBACK_BASE}${port}/_passcontrol/hook?t=${TOOL_HOOK_TIMEOUT_S}`, timeout: TOOL_HOOK_TIMEOUT_S };
253
+ function toolHook(port, api = false) {
254
+ return { type: "http", url: `${LOOPBACK_BASE}${port}/_passcontrol/hook?t=${TOOL_HOOK_TIMEOUT_S}${api ? "&mode=api" : ""}`, timeout: TOOL_HOOK_TIMEOUT_S };
255
+ }
256
+
257
+ /** API mode always asks the sidecar before a tool. */
258
+ export function apiToolHooks(port) {
259
+ return { PreToolUse: [{ matcher: "*", hooks: [toolHook(port, true)] }] };
260
+ }
261
+
262
+ const OUR_API_TOOL_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook\?t=\d{1,4}&mode=api$/;
263
+
264
+ // Writing: the same ownership matcher and merge as subscription mode, scoped to tools, so
265
+ // an API setup replaces subscription mode's tool hook instead of adding a second one.
266
+ // Removing (port null): only API mode's own hook. Subscription mode's stays, or a Pro/Max
267
+ // setup would keep its prompt and batch hooks and lose its tool rules.
268
+ function withApiTools(hooks, port) {
269
+ const base = isObject(hooks) ? hooks : {};
270
+ const tools = Object.hasOwn(base, "PreToolUse") ? { PreToolUse: base.PreToolUse } : {};
271
+ const next = { ...base };
272
+ delete next.PreToolUse;
273
+ if (port !== null) return { ...next, ...withOurHooks(tools, port, false, apiToolHooks(port)) };
274
+ if (!Array.isArray(tools.PreToolUse)) return isObject(hooks) ? { ...next, ...tools } : hooks;
275
+ const isApiTool = (h) => isObject(h) && h.type === "http" && typeof h.url === "string" && OUR_API_TOOL_URL.test(h.url);
276
+ const kept = [];
277
+ for (const group of tools.PreToolUse) {
278
+ if (!isObject(group) || !Array.isArray(group.hooks) || !group.hooks.some(isApiTool)) kept.push(group);
279
+ else {
280
+ const rest = group.hooks.filter((h) => !isApiTool(h));
281
+ if (rest.length) kept.push({ ...group, hooks: rest });
282
+ }
283
+ }
284
+ return kept.length ? { ...next, PreToolUse: kept } : next;
255
285
  }
256
286
 
257
287
  /** `note`: the agent's opt-in note rides on the prompt hook (`--agent-note`). */
@@ -292,11 +322,10 @@ function withoutOurHooks(hooks) {
292
322
  }
293
323
 
294
324
  /** `hooks` with exactly this port's gate hooks, leaving them where they are when already right. */
295
- function withOurHooks(hooks, port, note = false) {
296
- const ours = subscriptionHooks(port, { note });
325
+ function withOurHooks(hooks, port, note = false, ours = subscriptionHooks(port, { note })) {
297
326
  const base = isObject(hooks) ? hooks : {};
298
327
  const next = withoutOurHooks(base);
299
- for (const event of GATED_EVENTS) {
328
+ for (const event of Object.keys(ours)) {
300
329
  const current = Array.isArray(base[event]) ? base[event] : [];
301
330
  const already = current.filter((g) => isObject(g) && Array.isArray(g.hooks) && g.hooks.some(isOurHook));
302
331
  if (already.length === 1 && same(already[0], ours[event][0])) next[event] = current;
@@ -40,6 +40,8 @@ const newKey = () => `evt_${randomBytes(16).toString("base64url")}`;
40
40
  /** One event from readClaudeCodeEvents, as the gateway takes it. Absent fields are left out. */
41
41
  function toWire(event, key) {
42
42
  if (event.kind === "tool_decision") return toolDecisionWire(event, key);
43
+ if (event.kind === "injection_finding") return injectionFindingWire(event, key);
44
+ if (event.kind === "injection_incomplete") return injectionIncompleteWire(event, key);
43
45
  const wire = {
44
46
  key,
45
47
  kind: event.kind === "api_error" ? "model_error" : "model_call",
@@ -75,6 +77,46 @@ function toolDecisionWire(event, key) {
75
77
  return wire;
76
78
  }
77
79
 
80
+ // What the sidecar's scan of a tool's output found (cli/injection-sidecar.mjs): the
81
+ // gateway's fixed fields only (plans/injection-guard.md §2b), so nothing a caller adds,
82
+ // least of all text, is ever sent.
83
+ function injectionFindingWire(event, key) {
84
+ const wire = {
85
+ key,
86
+ kind: "injection_finding",
87
+ at: event.at,
88
+ source: event.source,
89
+ path: event.path,
90
+ tool: event.tool,
91
+ families: event.families,
92
+ severity: event.severity,
93
+ detector: event.detector,
94
+ normalization_version: event.normalization_version,
95
+ block_sha256: event.block_sha256,
96
+ };
97
+ for (const name of Object.keys(wire)) if (wire[name] === null || wire[name] === undefined) delete wire[name];
98
+ return wire;
99
+ }
100
+
101
+ // What the sidecar could not fully check (1.7.1): why, where, and a hash over what went
102
+ // unread. No families: nothing was found, because not all of it was read.
103
+ function injectionIncompleteWire(event, key) {
104
+ const wire = {
105
+ key,
106
+ kind: "injection_incomplete",
107
+ at: event.at,
108
+ source: event.source,
109
+ path: event.path,
110
+ tool: event.tool,
111
+ gap: event.gap,
112
+ detector: event.detector,
113
+ normalization_version: event.normalization_version,
114
+ block_sha256: event.block_sha256,
115
+ };
116
+ for (const name of Object.keys(wire)) if (wire[name] === null || wire[name] === undefined) delete wire[name];
117
+ return wire;
118
+ }
119
+
78
120
  /**
79
121
  * @param {{
80
122
  * send: (events: object[]) => Promise<{ status: number, error?: string, retryAfterS?: number }>,
@@ -3,13 +3,14 @@
3
3
  // A Codex session signed in with a ChatGPT plan talks to OpenAI directly, so the
4
4
  // gateway cannot refuse its calls, as with a Claude Pro/Max login
5
5
  // (cli/subscription-gate.mjs). The stops and tool rules still reach it through
6
- // Codex's hooks: `passcontrol configure codex --subscription` adds two to
6
+ // Codex's hooks: `passcontrol configure codex --subscription` adds three to
7
7
  // `$CODEX_HOME/hooks.json`, each running `passcontrol codex-hook`, which hands
8
8
  // Codex's input to the sidecar's hook endpoint (the one Claude Code calls) and
9
9
  // answers in Codex's terms:
10
10
  //
11
11
  // UserPromptSubmit a stopped agent's prompt is blocked and the turn ends
12
12
  // PreToolUse a stopped agent's tools, and the tool rules' denials, are refused
13
+ // PostToolUse tool output is scanned for injection tells; always neutral
13
14
  //
14
15
  // Codex has command hooks only (no http hook), hence the relay. Three differences
15
16
  // from Claude Code are handled here, not in the sidecar:
@@ -46,7 +47,8 @@ import { GATE_HOOK_TIMEOUT_S, HOOK_PATH } from "./subscription-gate.mjs";
46
47
  export const CODEX_TOOL_HOOK_TIMEOUT_S = 600;
47
48
  const PROMPT_RELAY_MS = GATE_HOOK_TIMEOUT_S * 1000 - 500;
48
49
  const TOOL_RELAY_MS = (CODEX_TOOL_HOOK_TIMEOUT_S - 10) * 1000;
49
- const EVENTS = ["UserPromptSubmit", "PreToolUse"];
50
+ const POST_TOOL_RELAY_MS = 1500;
51
+ const EVENTS = ["UserPromptSubmit", "PreToolUse", "PostToolUse"];
50
52
  const BACKUP_SUFFIX = ".passcontrol-backup";
51
53
 
52
54
  const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -62,7 +64,7 @@ export function isPassControlCodexHook(hook) {
62
64
  }
63
65
 
64
66
  /**
65
- * The command both hooks run: node and the CLI by absolute path, so PATH never
67
+ * The command all hooks run: node and the CLI by absolute path, so PATH never
66
68
  * decides whether it runs. Refuses a path a shell would read differently.
67
69
  */
68
70
  export function codexHookCommand({ port, node = process.execPath, entry }) {
@@ -91,12 +93,13 @@ export function probeCodexHookCommand(command) {
91
93
  return { ok: true };
92
94
  }
93
95
 
94
- /** The two entries PassControl adds, as a hooks file of their own. */
96
+ /** The three entries PassControl adds, as a hooks file of their own. */
95
97
  export function codexHookEntries(command) {
96
98
  return {
97
99
  hooks: {
98
100
  UserPromptSubmit: [{ hooks: [{ type: "command", command, timeout: GATE_HOOK_TIMEOUT_S }] }],
99
101
  PreToolUse: [{ matcher: ".*", hooks: [{ type: "command", command, timeout: CODEX_TOOL_HOOK_TIMEOUT_S }] }],
102
+ PostToolUse: [{ matcher: ".*", hooks: [{ type: "command", command, timeout: GATE_HOOK_TIMEOUT_S }] }],
100
103
  },
101
104
  };
102
105
  }
@@ -141,12 +144,19 @@ function save(target, value) {
141
144
  fs.renameSync(temp, target);
142
145
  }
143
146
 
144
- /** Add PassControl's two hooks, replacing any earlier ones of its own and nobody else's. */
147
+ /** Add PassControl's three hooks, replacing any earlier ones of its own and nobody else's. */
145
148
  export function writeCodexHooks({ target, command }) {
146
149
  const { value, exists } = readHooksFile(target);
147
150
  const hooks = withoutOurs(value.hooks ?? {});
148
151
  for (const [event, groups] of Object.entries(codexHookEntries(command).hooks)) {
149
- hooks[event] = [...(Array.isArray(hooks[event]) ? hooks[event] : []), ...groups];
152
+ // Codex keys trust by place (`<file>:<event>:<group>:<hook>`), so an entry of ours
153
+ // goes back where it stood: appended, it would swap with a hook added after it and
154
+ // both would quietly lose their trust. The groups before it held none of ours, so
155
+ // they are still the first `at`.
156
+ const before = Array.isArray(value.hooks?.[event]) ? value.hooks[event] : [];
157
+ const at = before.findIndex((g) => isObject(g) && Array.isArray(g.hooks) && g.hooks.some(isPassControlCodexHook));
158
+ const rest = Array.isArray(hooks[event]) ? hooks[event] : [];
159
+ hooks[event] = at < 0 ? [...rest, ...groups] : [...rest.slice(0, at), ...groups, ...rest.slice(at)];
150
160
  }
151
161
  const next = { ...value, hooks };
152
162
  if (JSON.stringify(next) === JSON.stringify(value)) return { changed: false, backupPath: null };
@@ -180,6 +190,7 @@ const ASK_IN_CODEX =
180
190
  * and a failed hook lets the tool run.
181
191
  */
182
192
  export function codexHookAnswer(event, out) {
193
+ if (event === "PostToolUse") return {}; // Telemetry must never alter Codex output.
183
194
  const o = isObject(out) ? out : {};
184
195
  const systemMessage = text(o.systemMessage);
185
196
  const warning = systemMessage ? { systemMessage } : {};
@@ -209,9 +220,10 @@ export function codexHookAnswer(event, out) {
209
220
  /**
210
221
  * What `passcontrol codex-hook` prints for one hook run: Codex's input in, the
211
222
  * sidecar's answer out, or nothing. Never throws, and never blocks on its own
212
- * failure: a sidecar that is down or slow lets the action go ahead, with a warning.
223
+ * failure: a sidecar that is down or slow lets the action go ahead, with a warning
224
+ * for prompts/pre-tool events. Post-tool telemetry always prints nothing.
213
225
  */
214
- export async function runCodexHook({ input, port, fetchImpl = fetch, promptTimeoutMs = PROMPT_RELAY_MS, toolTimeoutMs = TOOL_RELAY_MS }) {
226
+ export async function runCodexHook({ input, port, fetchImpl = fetch, promptTimeoutMs = PROMPT_RELAY_MS, toolTimeoutMs = TOOL_RELAY_MS, postToolTimeoutMs = POST_TOOL_RELAY_MS }) {
215
227
  let parsed;
216
228
  try {
217
229
  parsed = JSON.parse(input);
@@ -221,6 +233,30 @@ export async function runCodexHook({ input, port, fetchImpl = fetch, promptTimeo
221
233
  const event = isObject(parsed) ? parsed.hook_event_name : null;
222
234
  if (!EVENTS.includes(event)) return "";
223
235
  const tool = event === "PreToolUse";
236
+ const postTool = event === "PostToolUse";
237
+ // A post-tool hook is telemetry only. Bound the entire operation, including a
238
+ // stalled response body or a transport that does not honor AbortSignal.
239
+ if (postTool) {
240
+ const controller = new AbortController();
241
+ let timer;
242
+ try {
243
+ const timeout = new Promise((resolve) => {
244
+ timer = setTimeout(() => { controller.abort(); resolve(""); }, postToolTimeoutMs);
245
+ });
246
+ const relay = async () => {
247
+ await fetchImpl(`http://127.0.0.1:${port}${HOOK_PATH}`, {
248
+ method: "POST", headers: { "content-type": "application/json" }, body: input, signal: controller.signal,
249
+ });
250
+ return "";
251
+ };
252
+ return await Promise.race([relay(), timeout]);
253
+ } catch {
254
+ return "";
255
+ } finally {
256
+ clearTimeout(timer);
257
+ controller.abort();
258
+ }
259
+ }
224
260
  const controller = new AbortController();
225
261
  const timer = setTimeout(() => controller.abort(), tool ? toolTimeoutMs : promptTimeoutMs);
226
262
  const warn = (why) => JSON.stringify({ systemMessage: `PassControl: ${why}, so this goes ahead unchecked.` });
@@ -0,0 +1,7 @@
1
+ import type { ToolRuleVerdict } from "./tool-rules.mjs";
2
+
3
+ export type TaintVerdict = ToolRuleVerdict | { effect: "ask_owner"; reason: "injection_taint" };
4
+
5
+ export const INJECTION_HOLD_TOOLS: ReadonlySet<string>;
6
+ export function heldUnderTaint(toolName: unknown): boolean;
7
+ export function underTaint<V extends ToolRuleVerdict>(verdict: V, toolName: unknown): V | { effect: "ask_owner"; reason: "injection_taint" };
@@ -0,0 +1,30 @@
1
+ // Injection guard Phase 2, `hold`: which tools wait for the owner while an agent is
2
+ // tainted (owner, 2026-10-30; plans/injection-guard.md §4).
3
+ //
4
+ // Shared by the sidecar's tool gate and the gateway's re-check in
5
+ // POST /api/v1/tool-approvals, so what the sidecar holds is exactly what the gateway
6
+ // will put to the owner. Reading goes on: Read, Glob and Grep pass. Acting waits:
7
+ // running a command, writing a file, fetching a URL (a URL can carry data out) and any
8
+ // MCP tool. An explicit deny rule still wins, as everywhere in the rule language.
9
+ // `apply_patch` is Codex's file edit (its shell arrives as `Bash`; seen live, Codex
10
+ // 0.163, 2026-10-30).
11
+
12
+ export const INJECTION_HOLD_TOOLS = new Set(["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "WebFetch", "apply_patch"]);
13
+
14
+ /** True for a tool a tainted agent may not run without the owner. */
15
+ export function heldUnderTaint(toolName) {
16
+ if (typeof toolName !== "string") return false;
17
+ if (INJECTION_HOLD_TOOLS.has(toolName)) return true;
18
+ // `mcp__<server>__<tool>`: anything past the prefix.
19
+ return toolName.startsWith("mcp__") && toolName.length > "mcp__".length;
20
+ }
21
+
22
+ /**
23
+ * The verdict while tainted: a held tool is put to the owner unless a rule already
24
+ * denies it or already asks the owner. Any other verdict comes back unchanged.
25
+ */
26
+ export function underTaint(verdict, toolName) {
27
+ if (!heldUnderTaint(toolName)) return verdict;
28
+ if (verdict?.effect === "deny" || verdict?.effect === "ask_owner") return verdict;
29
+ return { effect: "ask_owner", reason: "injection_taint" };
30
+ }
@@ -0,0 +1,11 @@
1
+ export type InjectionFamily = "role_markup" | "instruction_override" | "exfil_directive" | "authority_claim" | "hidden_text";
2
+ export type InjectionSeverity = "high" | "low";
3
+ export interface InjectionHit {
4
+ family: InjectionFamily;
5
+ severity: InjectionSeverity;
6
+ }
7
+
8
+ export const INJECTION_DETECTOR: "pc-heuristic-1";
9
+ export const INJECTION_NORMALIZATION: 1;
10
+ export const INJECTION_FAMILIES: readonly InjectionFamily[];
11
+ export function scanText(raw: string): InjectionHit[];