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

package/README.md

@@ -41,6 +41,12 @@ Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
   them from inside a session.
 - **Code:** it ships in this package and runs locally. Nothing comes from the
   server.
+- **Codex (0.166.0 or later):** licensed `aisac codex` sessions get the same hooks
+  from session flags. Codex runs them only after you approve the AISAC hooks once
+  in `/hooks`, and you can switch each one off there too. The launch line says how
+  many are on and how many wait for that review; `aisac doctor` reports the same
+  under `extensions.codexHooks`. A new Node path (for example after an nvm or
+  Homebrew upgrade) changes the hook commands, so Codex asks for the review again.
 
 Licensed sessions of `aisac claude` and `aisac codex` can also load reviewed MCP
 servers: `github` (read-only, token in `GITHUB_PERSONAL_ACCESS_TOKEN`), `supabase`

package/dist/claude-observation.mjs

@@ -16,7 +16,7 @@ export const MAX_LOG_FILES = 3;
 const LOCK_WAIT_MS = 250;
 const LOCK_STALE_MS = 30_000;
 const ADMISSION_MS = 60 * 60 * 1000;
-export const ADAPTER_VERSION = '0.4.0-beta.12';
+export const ADAPTER_VERSION = '0.4.0-beta.13';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);

package/dist/cli.mjs

@@ -40,8 +40,10 @@ import {
 import { extensionsSummary, hooksCommand, mcpCommand } from './extensions-cli.mjs';
 import { sessionServers } from './mcp-servers.mjs';
 import { anyFormatter } from './guardrails/format.mjs';
+import { readCodexGuardrails } from './guardrails-plugin.mjs';
+import { codexHooksStatus, supportsCodexHooks } from './codex-hooks.mjs';
 
-const VERSION = '0.4.0-beta.12';
+const VERSION = '0.4.0-beta.13';
 // The command is `aisac`; `aibrain` is an alias installed from the same entry.
 const COMMAND = 'aisac';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
@@ -65,7 +67,7 @@ function usage() {
     'AISAC Engineering: `aisac claude` and `aisac codex` (Codex 0.164+) load the licensed method; setup --lang pt-BR|en picks its language (before the first setup it runs the full setup); setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
   );
   console.log(
-    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` session.',
+    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` or `aisac codex` session.',
   );
   console.log(
     'MCP catalog: `aisac mcp` lists the reviewed servers (GitHub, Supabase, Vercel, Playwright, Context7); `aisac mcp enable|disable <id>...`, `aisac mcp reset`, `aisac mcp info <id>` and `aisac mcp login <id>` (Codex) change or explain the next session.',
@@ -601,8 +603,48 @@ async function setup(args) {
   if (line !== null) console.log(line);
 }
 
-/** Extension state plus whether `format-on-edit` has a formatter in this folder (FR8). */
-async function doctorExtensions() {
+/**
+ * Whether Codex runs the AISAC hooks the user has on, from Codex's own
+ * `hooks/list` in this folder (FR6, FR8, E6b). No session starts, and Codex
+ * writes no config or trust record. Codex is not asked when the last launch had
+ * no license, because the launcher then hands Codex no hook.
+ * @param {{ executable: string | null, version: string | null | undefined, licensed: boolean }} codex
+ */
+async function doctorCodexHooks({ executable, version, licensed }) {
+  if (executable === null) return { status: 'codex_not_found' };
+  if (!supportsCodexHooks(version)) return { status: 'codex_version_unsupported' };
+  if (!licensed) return { status: 'not_licensed' };
+  const read = await readCodexGuardrails({
+    root: stateRoot(),
+    packageRoot: PACKAGE_ROOT,
+    executable,
+    cwd: process.cwd(),
+    profile: undefined,
+    environment: process.env,
+  }).catch(() => undefined);
+  if (read === undefined) return { status: 'list_failed' };
+  if (read === null) return { status: 'none_enabled' };
+  const { summary } = read;
+  if (summary === null) return { status: 'list_failed' };
+  const status = codexHooksStatus(summary);
+  return {
+    status,
+    handlers: summary.handlers,
+    review: summary.review,
+    off: summary.off,
+    missing: summary.missing,
+    ...(summary.review.length > 0
+      ? { remedy: 'Run aisac codex, open /hooks and approve the AISAC hooks.' }
+      : {}),
+  };
+}
+
+/**
+ * Extension state plus whether `format-on-edit` has a formatter in this folder,
+ * and whether Codex runs the hooks (FR8).
+ * @param {{ executable: string | null, version: string | null | undefined }} codex
+ */
+async function doctorExtensions(codex) {
   const summary = await extensionsSummary(stateRoot());
   // A token server is skipped at launch when its variable is unset (names only).
   const mcpMissingEnv = sessionServers(summary.mcp, 'claude', process.env).missingEnv.map(
@@ -613,7 +655,9 @@ async function doctorExtensions() {
     : (await anyFormatter(process.cwd()))
       ? 'ready'
       : 'no_formatter_found';
-  return { ...summary, formatOnEdit, mcpMissingEnv };
+  const licensed = (await readLastLaunch(stateRoot()))?.state === 'loaded';
+  const codexHooks = await doctorCodexHooks({ ...codex, licensed });
+  return { ...summary, formatOnEdit, mcpMissingEnv, codexHooks };
 }
 
 /** @param {boolean} json */
@@ -710,7 +754,10 @@ async function doctor(json) {
     },
     engineering,
     engineeringPack: await engineeringPackState(),
-    extensions: await doctorExtensions(),
+    extensions: await doctorExtensions({
+      executable: native.codex,
+      version: codexCompatibility?.version,
+    }),
     paidOrPilot: probe?.ok
       ? 'provider_free_probe_ok; paid entitlement or pilot invitation remains server-enforced'
       : config

package/dist/codex-hooks.mjs

@@ -0,0 +1,411 @@
+// @ts-check
+/**
+ * AISAC guardrails in Codex (spec aisac-engineering-extensions FR6, E6b).
+ *
+ * Codex loads session-flag hooks as `untrusted`. The user approves them once in
+ * `/hooks`, and Codex keys that approval, and the off switch, by position
+ * (`<event>:<group>:<handler>`) and command line (measured on 0.166.0). So:
+ * - the launch emits every catalog hook, in CODEX_HOOK_POSITIONS order, each with
+ *   a byte-stable command: the Node executable, the dispatcher, the event and the
+ *   hook id. No launch directory, version, locale or random value goes in it;
+ * - what changes per launch (the enabled hooks, the locale, the launch's state
+ *   folder, the preferences file) reaches the hook process through the
+ *   app-server's environment, which Codex hook processes inherit (measured on
+ *   0.166.0), as one JSON value in GUARDRAILS_SESSION_ENV.
+ * The launcher hands the monitor CODEX_HOOKS_ENV (enabled ids and locale). The
+ * monitor validates it against its own catalog and builds the flags and the
+ * session value itself, so the variable can never inject a command or a path.
+ * This module imports only the catalog and the TOML helper, so the monitor stays
+ * small.
+ */
+import { isAbsolute, join, resolve } from 'node:path';
+import { CODEX_HOOK_POSITIONS, HOOK_CATALOG, hookById } from './extensions-catalog.mjs';
+import { tomlBasicString } from './codex-engineering.mjs';
+
+/** Launcher to monitor: the enabled hook ids and the locale. */
+export const CODEX_HOOKS_ENV = 'AISAC_EXTENSIONS_CODEX_HOOKS';
+/** Monitor to hook processes, through the app-server's environment. */
+export const GUARDRAILS_SESSION_ENV = 'AISAC_GUARDRAILS_SESSION';
+const SCHEMA_VERSION = 1;
+// Same names as the Claude session plugin (guardrails-plugin.mjs) and the
+// preferences module (EXTENSIONS_FILE); a test keeps them equal.
+const STATE_DIRECTORY = 'guardrails-state';
+const PREFERENCES_FILE = 'extensions.json';
+const MAX_VALUE_BYTES = 8 * 1024;
+const MAX_PATH_LENGTH = 4096;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+const LOCALES = /** @type {const} */ (['pt-BR', 'en']);
+/** First Codex release whose hooks were measured with real turns (spike part 2). */
+const MIN_CODEX_HOOKS_VERSION = /** @type {const} */ ([0, 166, 0]);
+/** @type {Readonly<Record<string, number>>} */
+const TIMEOUT_SECONDS = Object.freeze({
+  PreToolUse: 5,
+  PostToolUse: 5,
+  UserPromptSubmit: 5,
+  Stop: 5,
+  SessionStart: 10,
+  PreCompact: 10,
+});
+// Codex reports camelCase event names in hooks/list.
+/** @type {Readonly<Record<string, string>>} */
+const LISTED_EVENT = Object.freeze({
+  PreToolUse: 'preToolUse',
+  PostToolUse: 'postToolUse',
+  UserPromptSubmit: 'userPromptSubmit',
+  SessionStart: 'sessionStart',
+  PreCompact: 'preCompact',
+  Stop: 'stop',
+});
+
+/** @typedef {import('./extensions-catalog.mjs').HookEvent} HookEvent */
+/** @typedef {'pt-BR' | 'en'} HookLocale */
+/** @typedef {{ node: string, dispatcher: string }} HookCommandPaths */
+/** @typedef {{ schemaVersion: 1, hooks: string[], locale: HookLocale }} CodexHooksValue */
+/**
+ * @typedef {object} GuardrailsSession
+ * @property {1} schemaVersion
+ * @property {string[]} hooks The hooks the user had on when the session started.
+ * @property {HookLocale} locale
+ * @property {string} stateDir The launch's guardrail state folder, deleted on exit.
+ * @property {string} prefsPath The preferences file (FR2.2).
+ */
+/**
+ * @typedef {object} CodexHookHandler
+ * @property {HookEvent} event
+ * @property {string} id
+ * @property {string | undefined} matcher
+ * @property {string} command
+ * @property {number} timeout
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is string} */
+function isCleanAbsolutePath(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_PATH_LENGTH &&
+    !CONTROL_CHARACTERS.test(value) &&
+    isAbsolute(value) &&
+    resolve(value) === value
+  );
+}
+
+/** @param {unknown} value @returns {value is HookLocale} */
+function isLocale(value) {
+  return typeof value === 'string' && LOCALES.includes(/** @type {HookLocale} */ (value));
+}
+
+/** POSIX single-quote quoting for the shell that runs the hook command. @param {string} value */
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** Ids that are Codex catalog hooks, in catalog order, without repeats. @param {unknown} ids */
+function codexHookIds(ids) {
+  if (!Array.isArray(ids)) return null;
+  const wanted = new Set(ids);
+  if (ids.length !== wanted.size) return null;
+  for (const id of wanted)
+    if (typeof id !== 'string' || hookById(id)?.clients.includes('codex') !== true) return null;
+  return HOOK_CATALOG.map((entry) => entry.id).filter((id) => wanted.has(id));
+}
+
+/**
+ * Whether this Codex version gets the guardrails. A null or malformed version
+ * never does.
+ * @param {string | null | undefined} version
+ */
+export function supportsCodexHooks(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version ?? '');
+  if (match === null) return false;
+  const parts = match.slice(1).map(Number);
+  for (let index = 0; index < MIN_CODEX_HOOKS_VERSION.length; index += 1) {
+    const part = /** @type {number} */ (parts[index]);
+    const minimum = MIN_CODEX_HOOKS_VERSION[index] ?? 0;
+    if (part !== minimum) return part > minimum;
+  }
+  return true;
+}
+
+/** The catalog matcher of a hook's binding for one event. @param {string} id @param {string} event */
+function bindingMatcher(id, event) {
+  return hookById(id)?.bindings.find((binding) => binding.event === event)?.matcher;
+}
+
+/**
+ * The byte-stable command of one Codex hook.
+ * @param {HookCommandPaths} paths @param {string} event @param {string} id
+ */
+export function codexHookCommand(paths, event, id) {
+  if (!isCleanAbsolutePath(paths.node) || !isCleanAbsolutePath(paths.dispatcher))
+    throw new Error('codex_hooks_path');
+  return [
+    shellQuote(paths.node),
+    shellQuote(paths.dispatcher),
+    '--client',
+    'codex',
+    '--event',
+    event,
+    '--hooks',
+    id,
+  ].join(' ');
+}
+
+/**
+ * Every Codex hook handler, in position order: one matcher group per hook, so
+ * the user can switch each one off in `/hooks`.
+ * @param {HookCommandPaths} paths
+ * @returns {CodexHookHandler[]}
+ */
+export function codexHookHandlers(paths) {
+  return Object.entries(CODEX_HOOK_POSITIONS).flatMap(([event, ids]) =>
+    ids.map((id) => ({
+      event: /** @type {HookEvent} */ (event),
+      id,
+      matcher: bindingMatcher(id, event),
+      command: codexHookCommand(paths, event, id),
+      timeout: TIMEOUT_SECONDS[event] ?? 5,
+    })),
+  );
+}
+
+/**
+ * Session-only `-c` flags for the owned app-server, one per event.
+ * @param {HookCommandPaths} paths
+ * @returns {string[]}
+ */
+export function codexHookConfigArgs(paths) {
+  /** @type {Map<string, string[]>} */
+  const groups = new Map();
+  for (const handler of codexHookHandlers(paths)) {
+    const matcher =
+      handler.matcher === undefined ? '' : `matcher=${tomlBasicString(handler.matcher)},`;
+    const group = `{${matcher}hooks=[{type="command",command=${tomlBasicString(handler.command)},timeout=${handler.timeout}}]}`;
+    groups.set(handler.event, [...(groups.get(handler.event) ?? []), group]);
+  }
+  return [...groups].flatMap(([event, list]) => ['-c', `hooks.${event}=[${list.join(',')}]`]);
+}
+
+/**
+ * The launcher's value for the monitor. Ids that are not Codex catalog hooks
+ * are dropped.
+ * @param {string[]} hooks @param {HookLocale} locale
+ */
+export function codexHooksValue(hooks, locale) {
+  const ids = codexHookIds([
+    ...new Set(hooks.filter((id) => hookById(id)?.clients.includes('codex') === true)),
+  ]);
+  return JSON.stringify({
+    schemaVersion: SCHEMA_VERSION,
+    hooks: ids ?? [],
+    locale: isLocale(locale) ? locale : 'en',
+  });
+}
+
+/**
+ * Parse the monitor's value; null when absent or when no hook is on.
+ * @param {string | undefined} raw
+ * @returns {CodexHooksValue | null}
+ */
+export function parseCodexHooks(raw) {
+  if (raw === undefined || raw === '') return null;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_VALUE_BYTES) throw new Error('codex_hooks_too_large');
+  /** @type {unknown} */
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('codex_hooks_invalid');
+  }
+  if (
+    !isRecord(value) ||
+    Object.keys(value).sort().join(',') !== 'hooks,locale,schemaVersion' ||
+    value.schemaVersion !== SCHEMA_VERSION ||
+    !isLocale(value.locale)
+  )
+    throw new Error('codex_hooks_invalid');
+  const hooks = codexHookIds(value.hooks);
+  if (hooks === null) throw new Error('codex_hooks_invalid');
+  return hooks.length === 0 ? null : { schemaVersion: SCHEMA_VERSION, hooks, locale: value.locale };
+}
+
+/**
+ * The value the hook processes read, built by the monitor: the launcher's
+ * choices plus the launch's own state folder (deleted with the launch on exit)
+ * and the preferences file of the state root the pack was checked against.
+ * @param {CodexHooksValue} value
+ * @param {{ launchDirectory: string, stateRoot: string }} paths
+ */
+export function guardrailsSessionValue(value, paths) {
+  const parsed = parseGuardrailsSession(
+    JSON.stringify({
+      schemaVersion: SCHEMA_VERSION,
+      hooks: value.hooks,
+      locale: value.locale,
+      stateDir: join(paths.launchDirectory, STATE_DIRECTORY),
+      prefsPath: join(resolve(paths.stateRoot), PREFERENCES_FILE),
+    }),
+  );
+  if (parsed === null) throw new Error('codex_hooks_session_invalid');
+  return JSON.stringify(parsed);
+}
+
+/**
+ * Parse the session value inside a hook process; null when absent or invalid,
+ * so the hook does nothing.
+ * @param {string | undefined} raw
+ * @returns {GuardrailsSession | null}
+ */
+export function parseGuardrailsSession(raw) {
+  if (raw === undefined || raw === '' || Buffer.byteLength(raw, 'utf8') > MAX_VALUE_BYTES)
+    return null;
+  /** @type {unknown} */
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (
+    !isRecord(value) ||
+    Object.keys(value).sort().join(',') !== 'hooks,locale,prefsPath,schemaVersion,stateDir' ||
+    value.schemaVersion !== SCHEMA_VERSION ||
+    !isLocale(value.locale) ||
+    !isCleanAbsolutePath(value.stateDir) ||
+    !isCleanAbsolutePath(value.prefsPath)
+  )
+    return null;
+  const hooks = codexHookIds(value.hooks);
+  if (hooks === null) return null;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    hooks,
+    locale: value.locale,
+    stateDir: value.stateDir,
+    prefsPath: value.prefsPath,
+  };
+}
+
+/**
+ * @typedef {object} CodexHooksSummary
+ * @property {{ total: number, trusted: number, untrusted: number, modified: number, disabled: number, missing: number }} handlers
+ *   Every AISAC hook Codex was given, by what `hooks/list` reports.
+ * @property {string[]} on Enabled guardrails whose hooks are all trusted and on.
+ * @property {string[]} review Enabled guardrails with a hook that waits for review in `/hooks`.
+ * @property {string[]} off Enabled guardrails switched off in Codex (`/hooks` or config.toml).
+ * @property {string[]} missing Enabled guardrails Codex did not load.
+ */
+
+/**
+ * What `hooks/list` says about the AISAC hooks. A guardrail counts as on only
+ * when every one of its hooks is trusted and enabled (spec FR6: an untrusted
+ * guardrail is never reported as on).
+ * @param {unknown} listed The `hooks/list` result.
+ * @param {HookCommandPaths} paths
+ * @param {string[]} enabled The guardrails the user has on.
+ * @returns {CodexHooksSummary}
+ */
+export function summarizeCodexHooks(listed, paths, enabled) {
+  const rows = (isRecord(listed) && Array.isArray(listed.data) ? listed.data : []).flatMap(
+    (entry) => (isRecord(entry) && Array.isArray(entry.hooks) ? entry.hooks : []),
+  );
+  /** @type {Map<string, Record<string, unknown>>} */
+  const byCommand = new Map();
+  for (const row of rows)
+    if (isRecord(row) && row.source === 'sessionFlags' && typeof row.command === 'string')
+      byCommand.set(`${String(row.eventName)}\u0000${row.command}`, row);
+  const handlers = codexHookHandlers(paths);
+  const counts = {
+    total: handlers.length,
+    trusted: 0,
+    untrusted: 0,
+    modified: 0,
+    disabled: 0,
+    missing: 0,
+  };
+  /** @type {Map<string, 'on' | 'review' | 'off' | 'missing'>} */
+  const states = new Map();
+  const rank = { on: 0, off: 1, review: 2, missing: 3 };
+  for (const handler of handlers) {
+    const row = byCommand.get(`${LISTED_EVENT[handler.event]}\u0000${handler.command}`);
+    /** @type {'on' | 'review' | 'off' | 'missing'} */
+    let state;
+    if (row === undefined) {
+      counts.missing += 1;
+      state = 'missing';
+    } else if (row.trustStatus === 'untrusted' || row.trustStatus === 'modified') {
+      counts[row.trustStatus] += 1;
+      state = 'review';
+    } else if (row.trustStatus !== 'trusted' && row.trustStatus !== 'managed') {
+      counts.untrusted += 1;
+      state = 'review';
+    } else if (row.enabled === false) {
+      counts.trusted += 1;
+      counts.disabled += 1;
+      state = 'off';
+    } else {
+      counts.trusted += 1;
+      state = 'on';
+    }
+    const previous = states.get(handler.id);
+    if (previous === undefined || rank[state] > rank[previous]) states.set(handler.id, state);
+  }
+  const ids =
+    codexHookIds([
+      ...new Set(enabled.filter((id) => hookById(id)?.clients.includes('codex') === true)),
+    ]) ?? [];
+  return {
+    handlers: counts,
+    on: ids.filter((id) => states.get(id) === 'on'),
+    review: ids.filter((id) => states.get(id) === 'review'),
+    off: ids.filter((id) => states.get(id) === 'off'),
+    missing: ids.filter((id) => states.get(id) === 'missing'),
+  };
+}
+
+/**
+ * The doctor's one-word state for the AISAC hooks in Codex, worst first: a
+ * guardrail waiting for review outranks one Codex did not load, which outranks
+ * one switched off in Codex.
+ * @param {CodexHooksSummary} summary
+ * @returns {'needs_review' | 'not_loaded' | 'off_in_codex' | 'on'}
+ */
+export function codexHooksStatus(summary) {
+  if (summary.review.length > 0) return 'needs_review';
+  if (summary.missing.length > 0) return 'not_loaded';
+  if (summary.off.length > 0) return 'off_in_codex';
+  return 'on';
+}
+
+/** @param {number} count */
+function guardrails(count) {
+  return `${count} guardrail${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * The launch line for Codex. With no summary (the listing failed), it says the
+ * guardrails were handed to Codex and names the review, never "on".
+ * @param {number} enabledCount
+ * @param {CodexHooksSummary | null} summary
+ */
+export function codexHooksLine(enabledCount, summary) {
+  const change = '(aisac hooks to change them)';
+  if (summary === null)
+    return `AISAC Engineering: ${guardrails(enabledCount)} loaded for Codex; Codex runs them only after you approve the AISAC hooks once in /hooks ${change}.`;
+  const total =
+    summary.on.length + summary.review.length + summary.off.length + summary.missing.length;
+  if (summary.on.length === total) return `AISAC Engineering: ${guardrails(total)} on ${change}.`;
+  const parts = [`AISAC Engineering: ${summary.on.length} of ${guardrails(total)} on`];
+  if (summary.review.length > 0)
+    parts.push(
+      `${summary.review.length} wait for your review: open /hooks in Codex and approve the AISAC hooks`,
+    );
+  if (summary.off.length > 0) parts.push(`${summary.off.length} switched off in Codex (/hooks)`);
+  if (summary.missing.length > 0) parts.push(`${summary.missing.length} not loaded by Codex`);
+  return `${parts.join('; ')} ${change}.`;
+}

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]);