@brunobracaioli/aibrain 0.4.0-beta.11 → 0.4.0-beta.13

package/dist/codex-permissions.mjs

@@ -499,15 +499,22 @@ async function request(child, id, method, params) {
   return message.result;
 }
 
-/** @param {string} executable @param {string} cwd @param {string|undefined} profile @param {NodeJS.ProcessEnv} environment */
-export async function readEffectiveWritableRoots(executable, cwd, profile, environment) {
-  validateProfile(profile);
+/**
+ * Run one short-lived, initialized app-server for a preflight read, then stop it
+ * and its process group. `body` gets the child and whether a signal cancelled it.
+ * @template T
+ * @param {{ executable: string, cwd: string, profile: string|undefined, environment: NodeJS.ProcessEnv, configArgs?: string[] }} options
+ * @param {(child: OwnedChild, cancelled: () => boolean) => Promise<T>} body
+ * @returns {Promise<T>}
+ */
+async function withPreflightServer(options, body) {
+  validateProfile(options.profile);
   const args = [];
-  if (profile !== undefined) args.push('--profile', profile);
-  args.push('app-server', '--listen', 'stdio://');
-  const child = spawn(executable, args, {
-    cwd,
-    env: childEnvironment(environment),
+  if (options.profile !== undefined) args.push('--profile', options.profile);
+  args.push(...(options.configArgs ?? []), 'app-server', '--listen', 'stdio://');
+  const child = spawn(options.executable, args, {
+    cwd: options.cwd,
+    env: childEnvironment(options.environment),
     stdio: ['pipe', 'pipe', 'ignore'],
     detached: process.platform !== 'win32',
   });
@@ -531,32 +538,7 @@ export async function readEffectiveWritableRoots(executable, cwd, profile, envir
     } catch {
       fail('preflight_failed');
     }
-    const result = await request(child, 1, 'config/read', { cwd, includeLayers: true });
-    const rawConfig = result.config;
-    if (
-      rawConfig === undefined ||
-      rawConfig === null ||
-      typeof rawConfig !== 'object' ||
-      Array.isArray(rawConfig)
-    )
-      fail('preflight_roots_unavailable');
-    const config = /** @type {JsonObject} */ (rawConfig);
-    const rawSandbox = config.sandbox_workspace_write;
-    if (cancelled) fail('preflight_cancelled');
-    if (rawSandbox === undefined || rawSandbox === null) return [];
-    if (typeof rawSandbox !== 'object' || Array.isArray(rawSandbox))
-      fail('preflight_roots_unavailable');
-    const sandbox = /** @type {JsonObject} */ (rawSandbox);
-    const roots = sandbox.writable_roots;
-    if (cancelled) fail('preflight_cancelled');
-    if (roots === undefined || roots === null) return [];
-    if (
-      !Array.isArray(roots) ||
-      roots.some((path) => typeof path !== 'string' || !isAbsolute(path))
-    )
-      fail('preflight_roots_unavailable');
-    if (cancelled) fail('preflight_cancelled');
-    return deduplicate(roots);
+    return await body(child, () => cancelled);
   } finally {
     process.removeListener('SIGINT', cancel);
     process.removeListener('SIGTERM', cancel);
@@ -565,6 +547,57 @@ export async function readEffectiveWritableRoots(executable, cwd, profile, envir
   }
 }
 
+/** @param {string} executable @param {string} cwd @param {string|undefined} profile @param {NodeJS.ProcessEnv} environment */
+export async function readEffectiveWritableRoots(executable, cwd, profile, environment) {
+  return withPreflightServer(
+    { executable, cwd, profile, environment },
+    async (child, cancelled) => {
+      const result = await request(child, 1, 'config/read', { cwd, includeLayers: true });
+      const rawConfig = result.config;
+      if (
+        rawConfig === undefined ||
+        rawConfig === null ||
+        typeof rawConfig !== 'object' ||
+        Array.isArray(rawConfig)
+      )
+        fail('preflight_roots_unavailable');
+      const config = /** @type {JsonObject} */ (rawConfig);
+      const rawSandbox = config.sandbox_workspace_write;
+      if (cancelled()) fail('preflight_cancelled');
+      if (rawSandbox === undefined || rawSandbox === null) return [];
+      if (typeof rawSandbox !== 'object' || Array.isArray(rawSandbox))
+        fail('preflight_roots_unavailable');
+      const sandbox = /** @type {JsonObject} */ (rawSandbox);
+      const roots = sandbox.writable_roots;
+      if (cancelled()) fail('preflight_cancelled');
+      if (roots === undefined || roots === null) return [];
+      if (
+        !Array.isArray(roots) ||
+        roots.some((path) => typeof path !== 'string' || !isAbsolute(path))
+      )
+        fail('preflight_roots_unavailable');
+      if (cancelled()) fail('preflight_cancelled');
+      return deduplicate(roots);
+    },
+  );
+}
+
+/**
+ * What Codex reports for a set of session-flag hooks (`hooks/list` for one
+ * folder), read from a short-lived app-server started with those flags and the
+ * user's own CODEX_HOME, where the trust records live. It writes no config and
+ * no trust record (spec aisac-engineering-extensions FR6, part 1 Q4).
+ * @param {{ executable: string, cwd: string, profile: string|undefined, environment: NodeJS.ProcessEnv, configArgs: string[] }} options
+ * @returns {Promise<JsonObject>}
+ */
+export async function readCodexHookList(options) {
+  return withPreflightServer(options, async (child, cancelled) => {
+    const result = await request(child, 1, 'hooks/list', { cwds: [options.cwd] });
+    if (cancelled()) fail('preflight_cancelled');
+    return result;
+  });
+}
+
 /** @param {LaunchPlan} plan @param {string[]} configuredRoots */
 export function makeCodexLaunchEnvelope(plan, configuredRoots) {
   const roots = deduplicate([...configuredRoots, ...plan.additionalRoots]);

package/dist/extensions-catalog.mjs

@@ -35,7 +35,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'secrets-guard',
     mode: 'block',
     defaultOn: true,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [
       { event: 'PreToolUse', matcher: 'Read|Edit|MultiEdit|Write|NotebookEdit|Grep|Bash' },
     ],
@@ -49,7 +49,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'git-guard',
     mode: 'block',
     defaultOn: false,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [{ event: 'PreToolUse', matcher: 'Bash' }],
     description: {
       en: 'Refuses git push to main or master and force pushes (--force-with-lease passes).',
@@ -60,7 +60,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'destructive-guard',
     mode: 'block',
     defaultOn: false,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [{ event: 'PreToolUse', matcher: 'Bash' }],
     description: {
       en: 'Refuses rm -rf on /, ~, . or .. and DROP DATABASE, DROP TABLE or TRUNCATE.',
@@ -71,7 +71,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'format-on-edit',
     mode: 'advise',
     defaultOn: false,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [{ event: 'PostToolUse', matcher: EDIT_TOOLS }],
     description: {
       en: "Formats the edited file with the project's own formatter, when one is installed.",
@@ -82,7 +82,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'docs-reminder',
     mode: 'advise',
     defaultOn: true,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [{ event: 'PostToolUse', matcher: EDIT_TOOLS }, { event: 'UserPromptSubmit' }],
     description: {
       en: 'After a source file changes in a project with docs/, reminds once per turn to update the docs.',
@@ -94,7 +94,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'session-context',
     mode: 'context',
     defaultOn: true,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [{ event: 'SessionStart', matcher: 'startup|resume|clear' }],
     description: {
       en: 'Starts the session with a short repository snapshot (branch, status, recent commits).',
@@ -105,7 +105,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'compact-continuity',
     mode: 'context',
     defaultOn: true,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [{ event: 'PreCompact' }, { event: 'SessionStart', matcher: 'compact' }],
     description: {
       en: 'Saves a repository snapshot before a compaction and restores it right after.',
@@ -116,7 +116,7 @@ export const HOOK_CATALOG = Object.freeze([
     id: 'continuity-reminder',
     mode: 'block',
     defaultOn: true,
-    clients: ['claude'],
+    clients: ['claude', 'codex'],
     bindings: [
       { event: 'PostToolUse', matcher: EDIT_TOOLS },
       { event: 'UserPromptSubmit' },
@@ -130,6 +130,24 @@ export const HOOK_CATALOG = Object.freeze([
   },
 ]);
 
+/**
+ * Codex hook positions (spec FR6, E6b). Codex keys a user's trust and off switch
+ * by position (`<event>:<group>:<handler>`), so each event lists its hooks in a
+ * fixed order and the launcher always emits all of them. This list is
+ * append-only: a new hook goes at the end of its event, and a retired id stays
+ * in place (the dispatcher ignores an id the catalog no longer has), so a review
+ * the user made in `/hooks` never moves to another hook.
+ * @type {Readonly<Record<HookEvent, readonly string[]>>}
+ */
+export const CODEX_HOOK_POSITIONS = Object.freeze({
+  PreToolUse: Object.freeze(['secrets-guard', 'git-guard', 'destructive-guard']),
+  PostToolUse: Object.freeze(['format-on-edit', 'docs-reminder', 'continuity-reminder']),
+  UserPromptSubmit: Object.freeze(['docs-reminder', 'continuity-reminder']),
+  SessionStart: Object.freeze(['session-context', 'compact-continuity']),
+  PreCompact: Object.freeze(['compact-continuity']),
+  Stop: Object.freeze(['continuity-reminder']),
+});
+
 /** @param {string} id @returns {HookEntry | undefined} */
 export function hookById(id) {
   return HOOK_CATALOG.find((entry) => entry.id === id);

package/dist/extensions-cli.mjs

@@ -59,13 +59,13 @@ const LOGIN_LABEL = Object.freeze({
 /** @type {ExtensionKind} */
 const HOOKS = {
   key: 'hooks',
-  title: 'AISAC Engineering hooks (Claude Code)',
+  title: 'AISAC Engineering hooks (Claude Code, and Codex 0.166+ after one review in /hooks)',
   ids: hookIds,
   resolve: resolveHooks,
   unknown: unknownHookIds,
   column: (id) => hookById(id)?.mode ?? '',
   nextSession:
-    'Applies to the next `aisac claude` session; running sessions keep their current set.',
+    'Applies to the next `aisac claude` or `aisac codex` session; running sessions keep their current set. In Codex the AISAC hooks run only after you approve them once in /hooks, and you can switch each one off there too.',
 };
 
 /** @type {ExtensionKind} */

package/dist/guardrails/guards.mjs

@@ -7,6 +7,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { isAbsolute, resolve } from 'node:path';
+import { PATCH_TOOL, patchPaths } from './patch.mjs';
 import { effectiveWords, programName, splitShell } from './shell-words.mjs';
 
 /**
@@ -14,6 +15,8 @@ import { effectiveWords, programName, splitShell } from './shell-words.mjs';
  * @property {string} projectDir
  * @property {string} home
  * @property {string} prefsPath The extensions preferences file (FR2.2).
+ * @property {readonly string[]} [codexConfigs] Codex's user config files, which hold
+ *   the switches for the AISAC hooks in Codex (FR2.2, E6b).
  * @property {'pt-BR' | 'en'} locale
  */
 /** @typedef {{ tool_name?: unknown, tool_input?: unknown, cwd?: unknown }} ToolEvent */
@@ -68,6 +71,10 @@ const DATABASE_CLIENTS = new Set([
   'cockroach',
   'duckdb',
 ]);
+// Codex's user config named through a variable or `~` (`~/.codex/config.toml`,
+// `$CODEX_HOME/config.toml`); resolved paths are compared as well.
+const CODEX_CONFIG_MENTION =
+  /(?:~|\$\{?HOME\}?)\/\.codex\/config\.toml|\$\{?CODEX_HOME\}?\/config\.toml/u;
 const DESTRUCTIVE_SQL =
   /\b(?:DROP\s+(?:DATABASE|TABLE|SCHEMA)|TRUNCATE(?:\s+TABLE)?\s+[A-Za-z_"`])/iu;
 
@@ -76,6 +83,8 @@ const MESSAGES = {
     secret: 'refused: this touches a secret file (rule: %s). Ask the user to do it themselves.',
     extensions:
       'refused: AISAC extensions are changed only by the user, from their own terminal (aisac hooks / aisac mcp).',
+    codexConfig:
+      "refused: Codex's config.toml holds the switches for the AISAC guardrails; only the user changes it, from their own terminal.",
     pushProtected: 'refused: push to %s. Open a pull request instead.',
     pushForce:
       'refused: force push. Use --force-with-lease on your own branch if it is really needed.',
@@ -87,6 +96,8 @@ const MESSAGES = {
       'recusado: isto mexe num arquivo de segredo (regra: %s). Peça ao usuário para fazer isso.',
     extensions:
       'recusado: as extensões do AISAC só são mudadas pelo usuário, no terminal dele (aisac hooks / aisac mcp).',
+    codexConfig:
+      'recusado: o config.toml do Codex guarda os interruptores dos guardrails do AISAC; só o usuário muda esse arquivo, no terminal dele.',
     pushProtected: 'recusado: push na %s. Abra um pull request.',
     pushForce:
       'recusado: push forçado. Use --force-with-lease na sua branch, se for mesmo preciso.',
@@ -142,9 +153,19 @@ function resolvePath(path, context) {
   return isAbsolute(expanded) ? resolve(expanded) : resolve(context.projectDir, expanded);
 }
 
-/** @param {string} path @param {GuardContext} context */
-function isPreferencesPath(path, context) {
-  return path.length > 0 && resolvePath(path, context) === resolve(context.prefsPath);
+/**
+ * The FR2.2 refusal for a path that names a file only the user may change: the
+ * preferences file, or Codex's user config. Null for any other path.
+ * @param {string} path @param {GuardContext} context
+ * @returns {string | null}
+ */
+function protectedRefusal(path, context) {
+  if (path.length === 0) return null;
+  const resolved = resolvePath(path, context);
+  if (resolved === resolve(context.prefsPath)) return message(context, 'extensions');
+  if ((context.codexConfigs ?? []).some((config) => resolved === resolve(config)))
+    return message(context, 'codexConfig');
+  return null;
 }
 
 /** Path-like parts of a word: the word itself and a `--flag=value` / `VAR=value` value. @param {string} word */
@@ -179,17 +200,45 @@ export function secretsGuard(event, context) {
   const input = record(event.tool_input);
   if (tool === 'Bash')
     return secretsInCommand(typeof input.command === 'string' ? input.command : '', context);
+  // A Codex patch writes every file its headers name (E6b).
+  if (tool === PATCH_TOOL) {
+    for (const path of patchPaths(input.command)) {
+      const refusal = writeRefusal(path, context);
+      if (refusal !== null) return refusal;
+    }
+    return null;
+  }
   const pathValue = tool === 'Grep' ? input.path : (input.file_path ?? input.notebook_path);
   if (typeof pathValue !== 'string' || pathValue.length === 0) return null;
-  if (tool !== 'Read' && tool !== 'Grep' && isPreferencesPath(pathValue, context))
-    return message(context, 'extensions');
-  const rule = secretRule(pathValue);
+  if (tool === 'Read' || tool === 'Grep') {
+    const rule = secretRule(pathValue);
+    return rule === null ? null : message(context, 'secret', rule);
+  }
+  return writeRefusal(pathValue, context);
+}
+
+/** A write to a protected file or a secret file. @param {string} path @param {GuardContext} context */
+function writeRefusal(path, context) {
+  const refusal = protectedRefusal(path, context);
+  if (refusal !== null) return refusal;
+  const rule = secretRule(path);
   return rule === null ? null : message(context, 'secret', rule);
 }
 
-/** @param {string} text @param {GuardContext} context */
-function mentionsPreferences(text, context) {
-  return text.includes(resolve(context.prefsPath)) || text.includes('.aibrain/extensions.json');
+/**
+ * The FR2.2 refusal for text that names a protected file anywhere in it.
+ * @param {string} text @param {GuardContext} context
+ * @returns {string | null}
+ */
+function mentionsProtected(text, context) {
+  if (text.includes(resolve(context.prefsPath)) || text.includes('.aibrain/extensions.json'))
+    return message(context, 'extensions');
+  if (
+    CODEX_CONFIG_MENTION.test(text) ||
+    (context.codexConfigs ?? []).some((config) => text.includes(resolve(config)))
+  )
+    return message(context, 'codexConfig');
+  return null;
 }
 
 /** Contents of `$(...)` and backtick substitutions in a word. @param {string} word */
@@ -209,10 +258,12 @@ function substitutions(word) {
  * @returns {string | null}
  */
 function wordRefusal(word, context, depth) {
-  if (mentionsPreferences(word, context)) return message(context, 'extensions');
+  const mention = mentionsProtected(word, context);
+  if (mention !== null) return mention;
   if (!/\s/u.test(word)) {
     for (const candidate of pathCandidates(word)) {
-      if (isPreferencesPath(candidate, context)) return message(context, 'extensions');
+      const refusal = protectedRefusal(candidate, context);
+      if (refusal !== null) return refusal;
       const rule = secretRule(candidate);
       if (rule !== null) return message(context, 'secret', rule);
     }
@@ -256,7 +307,8 @@ function secretsInCommand(command, context, depth = 0) {
   if (command.length === 0) return null;
   const parsed = splitShell(command);
   if (!parsed.ok) {
-    if (mentionsPreferences(command, context)) return message(context, 'extensions');
+    const mention = mentionsProtected(command, context);
+    if (mention !== null) return mention;
     for (const name of command.split(NAME_DELIMITERS)) {
       const rule = name.length > 0 ? secretRule(name, { extensions: false }) : null;
       if (rule !== null) return message(context, 'secret', rule);

package/dist/guardrails/patch.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+/**
+ * Paths a Codex patch touches (spec aisac-engineering-extensions FR6, E6b).
+ * Codex sends an edit as `tool_name: "apply_patch"` with the whole patch text in
+ * `tool_input.command` and no `file_path` (measured on Codex 0.166.0), so the
+ * guardrails read the file names from the patch headers. Names only: the patch
+ * body is never interpreted.
+ */
+
+export const PATCH_TOOL = 'apply_patch';
+
+// `*** Add File: <path>`, `*** Update File: <path>`, `*** Delete File: <path>`
+// and `*** Move to: <path>` (the new name of an updated file).
+const HEADER = /^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/u;
+
+/**
+ * The paths named in a patch, in order and without repeats. Anything that is
+ * not a string, or has no header, names no path. There is no cap: the hook
+ * input is already bounded (1 MiB), and a cap would let a patch hide a secret
+ * file after the limit.
+ * @param {unknown} patch
+ * @returns {string[]}
+ */
+export function patchPaths(patch) {
+  if (typeof patch !== 'string' || patch.length === 0) return [];
+  /** @type {Set<string>} */
+  const paths = new Set();
+  for (const line of patch.split(/\r?\n/u)) {
+    const path = HEADER.exec(line)?.[1]?.trim();
+    if (path !== undefined && path.length > 0) paths.add(path);
+  }
+  return [...paths];
+}

package/dist/guardrails/run.mjs

@@ -1,20 +1,31 @@
 #!/usr/bin/env node
 // @ts-check
 /**
- * Guardrail dispatcher (spec aisac-engineering-extensions FR2, FR5): the
- * command the session plugin `aisac-guardrails` runs for each host event. One
- * process per event runs every enabled hook bound to it, so a tool call pays
- * for one Node start. Arguments come from the launcher; the event payload
- * comes from the host on stdin and is untrusted.
+ * Guardrail dispatcher (spec aisac-engineering-extensions FR2, FR5, FR6): the
+ * command the hosts run for each hook event.
+ * - Claude Code: the session plugin `aisac-guardrails` registers one command per
+ *   event, and that one process runs every enabled hook bound to it, so a tool
+ *   call pays for one Node start. The launcher passes the state folder, the
+ *   preferences file and the locale as arguments.
+ * - Codex (`--client codex`, E6b): one command per hook and event, byte-stable so
+ *   the user's review in `/hooks` holds. The enabled set, the locale, the state
+ *   folder and the preferences file come from GUARDRAILS_SESSION_ENV, which the
+ *   monitor put in the app-server's environment; without it the hook does
+ *   nothing. The project is the payload's `cwd`, never an inherited
+ *   CLAUDE_PROJECT_DIR, and a patch (`apply_patch`) is an edit of every file its
+ *   headers name.
+ * The event payload comes from the host on stdin and is untrusted.
  *
  * Exit 0 always, except exit 2 for a PreToolUse refusal (reason on stderr).
  * Any error lets the tool call run: a broken guard must not stop all work.
  */
 import { homedir } from 'node:os';
-import { isAbsolute } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { GUARDRAILS_SESSION_ENV, parseGuardrailsSession } from '../codex-hooks.mjs';
 import { hookById } from '../extensions-catalog.mjs';
 import { GUARDS } from './guards.mjs';
+import { PATCH_TOOL, patchPaths } from './patch.mjs';
 import {
   continuityReminder,
   docsReminder,
@@ -36,9 +47,18 @@ const EVENTS = new Set([
   'Stop',
 ]);
 const REFUSAL_EXIT_CODE = 2;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+const ARGUMENT_NAMES = ['--client', '--event', '--hooks', '--state', '--prefs', '--locale'];
+// Codex matches a patch with the edit tool names too (`Edit|Write` fires for
+// `apply_patch`, measured on 0.166.0), so the catalog's Claude matchers bind it.
+/** @type {Readonly<Record<string, readonly string[]>>} */
+const TOOL_ALIASES = Object.freeze({
+  [PATCH_TOOL]: Object.freeze([PATCH_TOOL, 'Edit', 'Write']),
+});
 
 /**
  * @typedef {object} RunOptions
+ * @property {'claude' | 'codex'} client
  * @property {import('../extensions-catalog.mjs').HookEvent} event
  * @property {string[]} hooks
  * @property {string} stateDir
@@ -46,41 +66,77 @@ const REFUSAL_EXIT_CODE = 2;
  * @property {'pt-BR' | 'en'} locale
  */
 
+/** Catalog ids bound to the event. @param {string[]} ids @param {string} event */
+function boundIds(ids, event) {
+  return ids.filter((id) => {
+    const entry = hookById(id);
+    return entry !== undefined && entry.bindings.some((binding) => binding.event === event);
+  });
+}
+
 /**
- * Strict launcher arguments; null when anything is off.
+ * Strict launcher arguments; null when anything is off. In Codex the enabled
+ * set and the paths come from the session value in the environment, and a hook
+ * the session did not enable is dropped.
  * @param {string[]} argv
+ * @param {NodeJS.ProcessEnv} [env]
  * @returns {RunOptions | null}
  */
-export function parseArguments(argv) {
+export function parseArguments(argv, env = process.env) {
   /** @type {Record<string, string>} */
   const values = {};
   for (let index = 0; index < argv.length; index += 2) {
     const name = argv[index] ?? '';
     const value = argv[index + 1];
-    if (
-      !['--event', '--hooks', '--state', '--prefs', '--locale'].includes(name) ||
-      value === undefined
-    )
+    if (!ARGUMENT_NAMES.includes(name) || value === undefined || Object.hasOwn(values, name))
       return null;
     values[name] = value;
   }
   const event = values['--event'] ?? '';
+  if (!EVENTS.has(event)) return null;
+  const typedEvent = /** @type {import('../extensions-catalog.mjs').HookEvent} */ (event);
+  const requested = (values['--hooks'] ?? '').split(',');
+  if (values['--client'] === 'codex') {
+    if (['--state', '--prefs', '--locale'].some((name) => Object.hasOwn(values, name))) return null;
+    const session = parseGuardrailsSession(env[GUARDRAILS_SESSION_ENV]);
+    if (session === null) return null;
+    return {
+      client: 'codex',
+      event: typedEvent,
+      hooks: boundIds(requested, event).filter((id) => session.hooks.includes(id)),
+      stateDir: session.stateDir,
+      prefsPath: session.prefsPath,
+      locale: session.locale,
+    };
+  }
+  if (values['--client'] !== undefined && values['--client'] !== 'claude') return null;
   const stateDir = values['--state'] ?? '';
   const prefsPath = values['--prefs'] ?? '';
-  if (!EVENTS.has(event) || !isAbsolute(stateDir) || !isAbsolute(prefsPath)) return null;
-  const hooks = (values['--hooks'] ?? '').split(',').filter((id) => {
-    const entry = hookById(id);
-    return entry !== undefined && entry.bindings.some((binding) => binding.event === event);
-  });
+  if (!isAbsolute(stateDir) || !isAbsolute(prefsPath)) return null;
   return {
-    event: /** @type {import('../extensions-catalog.mjs').HookEvent} */ (event),
-    hooks,
+    client: 'claude',
+    event: typedEvent,
+    hooks: boundIds(requested, event),
     stateDir,
     prefsPath,
     locale: values['--locale'] === 'pt-BR' ? 'pt-BR' : 'en',
   };
 }
 
+/**
+ * Codex's user config files: `~/.codex/config.toml`, and `$CODEX_HOME/config.toml`
+ * when CODEX_HOME is set. They hold the off switch of every Codex hook, so
+ * `secrets-guard` keeps the agent out of them (FR2.2, E6b).
+ * @param {NodeJS.ProcessEnv} env @param {string} home
+ */
+export function codexConfigPaths(env, home) {
+  const paths = [join(home, '.codex', 'config.toml')];
+  const codexHome = env.CODEX_HOME;
+  if (typeof codexHome === 'string' && isAbsolute(codexHome) && !CONTROL_CHARACTERS.test(codexHome))
+    paths.push(join(resolve(codexHome), 'config.toml'));
+  return [...new Set(paths)];
+}
+
 /** @returns {Promise<string | null>} */
 async function readInput() {
   /** @type {Buffer[]} */
@@ -97,13 +153,24 @@ async function readInput() {
 
 /** Does a hook's binding for this event accept the tool or source? @param {string} id @param {string} event @param {string} subject */
 function bound(id, event, subject) {
+  const names = TOOL_ALIASES[subject] ?? [subject];
   return (hookById(id)?.bindings ?? []).some(
     (binding) =>
       binding.event === event &&
-      (binding.matcher === undefined || binding.matcher.split('|').includes(subject)),
+      (binding.matcher === undefined ||
+        binding.matcher.split('|').some((name) => names.includes(name))),
   );
 }
 
+/**
+ * The files a tool call edits: `file_path`, or every path a Codex patch names.
+ * @param {string} tool @param {Record<string, unknown>} toolInput
+ * @returns {unknown[]}
+ */
+function editedFiles(tool, toolInput) {
+  return tool === PATCH_TOOL ? patchPaths(toolInput.command) : [toolInput.file_path];
+}
+
 /**
  * Run the enabled hooks for one event.
  * @param {RunOptions} options
@@ -111,18 +178,22 @@ function bound(id, event, subject) {
  * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
  */
 export async function dispatch(options, input) {
-  const envProject = process.env.CLAUDE_PROJECT_DIR;
+  // Codex adds no project variable: one in its environment was inherited from the
+  // user's shell (for example a Claude Code terminal), so Codex uses the payload cwd.
+  const envProject = options.client === 'codex' ? undefined : process.env.CLAUDE_PROJECT_DIR;
   const projectDir =
     typeof envProject === 'string' && isAbsolute(envProject)
       ? envProject
       : typeof input.cwd === 'string' && isAbsolute(input.cwd)
         ? input.cwd
         : process.cwd();
+  const home = homedir();
   const context = {
     projectDir,
     stateDir: options.stateDir,
     prefsPath: options.prefsPath,
-    home: homedir(),
+    codexConfigs: codexConfigPaths(process.env, home),
+    home,
     locale: options.locale,
   };
   const enabled = new Set(options.hooks);
@@ -143,15 +214,19 @@ export async function dispatch(options, input) {
     return quiet;
   }
   if (options.event === 'PostToolUse') {
-    const filePath = toolInput.file_path;
-    if (enabled.has('format-on-edit') && bound('format-on-edit', 'PostToolUse', tool))
-      await formatEdited(projectDir, filePath);
-    if (enabled.has('continuity-reminder') && bound('continuity-reminder', 'PostToolUse', tool))
-      await recordEdit(context, input.session_id, filePath);
-    const reminder =
-      enabled.has('docs-reminder') && bound('docs-reminder', 'PostToolUse', tool)
-        ? await docsReminder(context, input.session_id, filePath)
-        : '';
+    let reminder = '';
+    for (const filePath of editedFiles(tool, toolInput)) {
+      if (enabled.has('format-on-edit') && bound('format-on-edit', 'PostToolUse', tool))
+        await formatEdited(projectDir, filePath);
+      if (enabled.has('continuity-reminder') && bound('continuity-reminder', 'PostToolUse', tool))
+        await recordEdit(context, input.session_id, filePath);
+      if (
+        reminder.length === 0 &&
+        enabled.has('docs-reminder') &&
+        bound('docs-reminder', 'PostToolUse', tool)
+      )
+        reminder = await docsReminder(context, input.session_id, filePath);
+    }
     return reminder.length === 0
       ? quiet
       : {