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

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
       : {

package/dist/guardrails-plugin.mjs

@@ -6,11 +6,18 @@
  * Node executable plus the dispatcher inside the installed package; nothing
  * comes from the server (ADR-0048).
  */
-import { access, mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, realpath, writeFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
 import { hookById } from './extensions-catalog.mjs';
 import { enabledHookIds, preferencesPath, readPreferences } from './extensions-preferences.mjs';
 import { readStoredLocale, resolvePackLocale } from './engineering-pack.mjs';
+import {
+  codexHookConfigArgs,
+  codexHooksLine,
+  codexHooksValue,
+  summarizeCodexHooks,
+} from './codex-hooks.mjs';
+import { readCodexHookList } from './codex-permissions.mjs';
 
 export const GUARDRAILS_PLUGIN_NAME = 'aisac-guardrails';
 const PLUGIN_VERSION = '1.0.0';
@@ -147,3 +154,54 @@ export async function prepareGuardrails(input) {
     line: `AISAC Engineering: ${enabled.length} guardrail${enabled.length === 1 ? '' : 's'} on (aisac hooks to change them).`,
   };
 }
+
+/**
+ * What Codex reports for the AISAC hooks the user has on, read with Codex's own
+ * `hooks/list` for the exact flags the monitor passes (spec FR6, E6b). Null when
+ * no Codex hook is enabled or the package lacks the dispatcher; `summary` is null
+ * when the listing failed.
+ * @param {{ root: string, packageRoot: string, executable: string, cwd: string, profile: string | undefined, environment: NodeJS.ProcessEnv }} input
+ * @param {{ listHooks?: typeof readCodexHookList }} [dependencies]
+ * @returns {Promise<{ enabled: string[], summary: import('./codex-hooks.mjs').CodexHooksSummary | null } | null>}
+ */
+export async function readCodexGuardrails(input, dependencies = {}) {
+  const listHooks = dependencies.listHooks ?? readCodexHookList;
+  const enabled = enabledHookIds(await readPreferences(input.root)).filter(
+    (id) => hookById(id)?.clients.includes('codex') === true,
+  );
+  if (enabled.length === 0) return null;
+  // The monitor resolves the same file from its own folder; both use the real path.
+  const dispatcher = await realpath(join(input.packageRoot, DISPATCHER)).catch(() => null);
+  if (dispatcher === null || !safeAbsolute(dispatcher) || !safeAbsolute(process.execPath))
+    return null;
+  const paths = { node: process.execPath, dispatcher };
+  const summary = await listHooks({
+    executable: input.executable,
+    cwd: input.cwd,
+    profile: input.profile,
+    environment: input.environment,
+    configArgs: codexHookConfigArgs(paths),
+  }).then(
+    (listed) => summarizeCodexHooks(listed, paths, enabled),
+    () => null,
+  );
+  return { enabled, summary };
+}
+
+/**
+ * The guardrails for a licensed Codex launch: the value the launcher hands the
+ * monitor, and the launch line. The line comes from `hooks/list`, so a guardrail
+ * that waits for the user's review in `/hooks` is never called on.
+ * @param {{ root: string, packageRoot: string, executable: string, cwd: string, profile: string | undefined, environment: NodeJS.ProcessEnv }} input
+ * @param {{ listHooks?: typeof readCodexHookList }} [dependencies]
+ * @returns {Promise<{ value: string, line: string } | null>}
+ */
+export async function prepareCodexGuardrails(input, dependencies = {}) {
+  const read = await readCodexGuardrails(input, dependencies);
+  if (read === null) return null;
+  const locale = resolvePackLocale(await readStoredLocale(input.root));
+  return {
+    value: codexHooksValue(read.enabled, locale),
+    line: codexHooksLine(read.enabled.length, read.summary),
+  };
+}

package/dist/launch.mjs

@@ -18,7 +18,8 @@ import {
   sweepStaleLaunches,
   writeLaunchMarker,
 } from './engineering-pack.mjs';
-import { prepareGuardrails } from './guardrails-plugin.mjs';
+import { prepareCodexGuardrails, prepareGuardrails } from './guardrails-plugin.mjs';
+import { CODEX_HOOKS_ENV, GUARDRAILS_SESSION_ENV, supportsCodexHooks } from './codex-hooks.mjs';
 import {
   CODEX_MCP_ENV,
   claudeDenyRules,
@@ -149,6 +150,8 @@ function childEnvironment(root) {
   delete environment[CODEX_ENGINEERING_ENV];
   delete environment[CODEX_ENGINEERING_SKILLS_ROOT_ENV];
   delete environment[CODEX_MCP_ENV];
+  delete environment[CODEX_HOOKS_ENV];
+  delete environment[GUARDRAILS_SESSION_ENV];
   environment.AIBRAIN_STATE_DIR = resolve(root);
   return environment;
 }
@@ -451,6 +454,7 @@ export async function readSessionServers(root, client, environment) {
  * @property {typeof prepareEngineeringPack} [preparePack] AISAC Engineering pack loader (E4b)
  * @property {typeof prepareGuardrails} [prepareGuardrails] Guardrail hooks plugin writer (E6a)
  * @property {typeof readSessionServers} [readSessionServers] MCP catalog servers to load (E6c)
+ * @property {typeof prepareCodexGuardrails} [prepareCodexGuardrails] Codex guardrail hooks (E6b)
  */
 
 /**
@@ -675,6 +679,7 @@ export async function launchClaude(config, root, args, dependencies = {}) {
 export async function launchCodex(config, root, args, dependencies = {}) {
   const preparePack = dependencies.preparePack ?? prepareEngineeringPack;
   const readServers = dependencies.readSessionServers ?? readSessionServers;
+  const writeCodexGuardrails = dependencies.prepareCodexGuardrails ?? prepareCodexGuardrails;
   const validated = assertConfig(config);
   assertCodexArgs(args);
   const captureLockPlatform = captureLockPlatformCheck();
@@ -744,6 +749,22 @@ export async function launchCodex(config, root, args, dependencies = {}) {
       process.stderr.write(`${line}\n`);
     if (servers !== null && servers.ready.length > 0)
       environment[CODEX_MCP_ENV] = JSON.stringify(servers.ready.map((entry) => entry.id));
+    // Guardrail hooks need the same license and a Codex measured with them
+    // (0.166.0+); like the pack they never block the launch (spec extensions FR6).
+    const guardrails = supportsCodexHooks(compatibility.version)
+      ? await writeCodexGuardrails({
+          root,
+          packageRoot,
+          executable,
+          cwd: launchPlan.effectiveCwd,
+          profile: launchPlan.profile,
+          environment,
+        }).catch(() => null)
+      : null;
+    if (guardrails !== null) {
+      environment[CODEX_HOOKS_ENV] = guardrails.value;
+      process.stderr.write(`${guardrails.line}\n`);
+    }
   }
   environment.AI_BRAIN_MCP_SERVER = MCP_ALIAS;
   environment.CODEX_BIN = executable;