baldart 4.87.0 → 4.88.1

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.88.1] - 2026-07-01
+
+**`baldart update` backfills hooks on the aligned/self-heal path too.** The "already up to date" branch of `update` reconciled newly-shipped payload (agents / skills / workflows / output-styles + root primitives) but did **not** backfill hooks. Same gap class the payload reconcile already fixed: a consumer who framework-updated with an **older CLI** (before a given hook shipped — e.g. the v4.88.0 Codex hooks) and then aligned the CLI would hit the "already current" early-exit and **never get the hooks registered** (recoverable only via `doctor`). Now the aligned path registers both Claude (`.claude/settings.json`) and — when `tools.enabled ∋ codex` — Codex (`.codex/hooks.json`) hooks, **idempotently and additively**: SILENT when nothing is missing, drift left to `doctor` (never prompts on the self-heal path), non-fatal on any hiccup. The `--json` payload gains `backfilled_hooks`. **PATCH** — robustness fix, no behavior change on a healthy install. Codex parity: adapter-generated (the same registrar). No new config key.
+
+### Changed
+
+- **`src/commands/update.js`** — the aligned "already up to date" branch now backfills missing Claude + Codex hooks (silent when none missing) and reports `backfilled_hooks` in `--json`.
+
+## [4.88.0] - 2026-07-01
+
+**Native Codex hooks — BALDART now manages `.codex/hooks.json` in parallel with `.claude/settings.json` (Codex-parity foundation, S1–S3).** Kicks off a phased program to make BALDART **universally tool-agnostic**: everything it ships must work natively on both Claude Code and Codex. Two governance rules are now binding on all future development (CLAUDE.md § "Cross-tool parity discipline"): (1) every NEW tool/surface is first checked for native Codex compatibility (portable / adapter-generated / inline-fallback / N/A, outcome recorded in the CHANGELOG); (2) every change travels in parallel across Codex and Claude in the same change. This release delivers the **hook foundation**:
+
+- **S1 — hook registry split (no behavior change).** `src/utils/hooks.js` is split into a runtime-neutral registry (`hooks/registry.js`, one entry per logical hook with per-runtime bindings) + a Claude renderer (`hooks/claude.js`, `.claude/settings.json`); `hooks.js` becomes a thin compatibility shim. Verified **byte-identical** to the pre-split module across 7 fixtures (getStatus / verifyAll / registerAll keep+replace / unregisterAll + the written settings.json).
+- **S2 — Codex hook registrar.** New `hooks/codex.js` renderer manages `.codex/hooks.json` (same schema as Claude, verified against the OpenAI Codex hooks spec, CLI 0.142.5). `CodexAdapter.supportsHooks()` is now `true`. Two hooks ship on Codex: `framework-edit-gate` (PreToolUse; the SAME script made `apply_patch`-aware, **fail-open on parse doubt**) and `agent-discovery-info` (SessionStart; the SAME script with `--runtime codex` → inspects `.codex/agents/*.toml`). Two are deliberately **not bound on Codex** with documented rationale + compensating mechanism: `agent-discovery-gate` (no observable Agent tool → the `/new`+`/prd` Codex preflight) and `overlay-telemetry` (no reliable Read event). Ownership is matched by a command **marker** (Codex entries carry no `id`); registration is **additive** (preserves Graphify + user hooks). **Hook trust is never faked** — BALDART writes `.codex/hooks.json` but never `~/.codex/config.toml`; `add`/`update` surface that Codex asks for one-time approval, and `doctor` reports presence and trust **separately** (untrusted-only is not a failure).
+- **S3 — cross-tool delegation docs.** `skills-mapping.md` reframed for portable (Claude + Codex) skills, citing `AGENTS.md` as the delegation SSOT (the domain-ownership core — code→coder / UI→ui-expert, no-silent-fallback — already landed cross-tool in the AGENTS.md primitive), forward-referencing the Codex preflight, and noting that non-BALDART feature-entry skills (e.g. `nf`) must not drive BALDART backlog execution.
+
+**MINOR** — additive capability (native Codex hook management). **Codex parity: adapter-generated** (one registry SSOT + a Codex renderer; the two edit/session hook scripts are single-source dual-runtime). **No new `baldart.config.yml` key** (rides on `tools.enabled` containing `codex`) → the schema-change propagation rule does NOT apply. **Must-measure-first (ships safe-by-default):** one live Codex hook fire + the trust-approval flow remain to confirm on a real Codex consumer — the gate fails open, registration is additive, and trust is never faked, so S2 cannot break a consumer even before that confirmation. Authoritative design: [`framework/docs/CODEX-HOOKS.md`](framework/docs/CODEX-HOOKS.md).
+
+### Added
+
+- **`src/utils/hooks/registry.js`** — runtime-neutral hook set with per-runtime bindings (`runtimes.claude` / `runtimes.codex`) + `defsFor(runtime)`.
+- **`src/utils/hooks/claude.js`** — the Claude Code renderer (`.claude/settings.json`).
+- **`src/utils/hooks/codex.js`** — the Codex renderer (`.codex/hooks.json`) with additive register/verify/unregister/status/drift + a `~/.codex/config.toml` trust probe.
+- **`framework/docs/CODEX-HOOKS.md`** — authoritative design + parity table + must-measure-first.
+
+### Changed
+
+- **`src/utils/hooks.js`** — now a thin compatibility shim re-exporting the Claude renderer (historical `require('../utils/hooks')` surface preserved, byte-identical).
+- **`src/utils/tool-adapters/{codex,claude}.js`** — `supportsHooks()` (Codex `false`→`true`) + `hookTargetPath()`.
+- **`framework/.claude/hooks/framework-edit-gate.js`** — runtime-aware: parses the Codex `apply_patch` envelope (fail-open); Claude Edit/Write/MultiEdit/NotebookEdit path byte-unchanged.
+- **`framework/.claude/hooks/agent-discovery-info.sh`** — accepts `--runtime codex` → inspects `.codex/agents/*.toml`.
+- **`src/commands/{add,update,doctor}.js`** — register/backfill/report Codex hooks gated on `tools.enabled ∋ codex`; doctor reports presence and trust separately.
+- **`framework/agents/skills-mapping.md`** — cross-tool framing + delegation SSOT note (cites `AGENTS.md`, `CODEX-HOOKS.md`).
+- **`framework/docs/CODEX-AGENTS.md`** — cross-ref to `CODEX-HOOKS.md`.
+- **`CLAUDE.md`** — new "Cross-tool parity discipline" + "Codex-native hooks" conventions; fixed the stale "hooks remain Claude-only" line.
+
 ## [4.87.0] - 2026-07-01
 
 **Plan-review gate promoted to the cross-tool SSOT (AGENTS.md primitive `1.3.0`).** The "have the plan reviewed by `plan-auditor` + `doc-reviewer` before presenting it" rule lived only in the `CLAUDE.md` stub's Plan Mode — so Codex never ran it. Now that both agents exist on Codex (transpiled to `.codex/agents/`), the tool-agnostic principle is promoted into `AGENTS.md`: **MUST have any non-trivial plan reviewed by `plan-auditor` + `doc-reviewer` (in parallel), fold in their feedback, note the review gate in the plan, and present the ALREADY-reviewed plan — never a raw one.** The Claude-only `EnterPlanMode`/`ExitPlanMode` mechanics stay in `CLAUDE.md`; `AGENTS.md` carries the principle so both tools honor it.

package/VERSION

@@ -1 +1 @@
-4.87.0
+4.88.1

package/framework/.claude/hooks/agent-discovery-info.sh

@@ -34,6 +34,20 @@
 set -u
 exec 2>/dev/null  # silence stderr; we are not user-visible
 
+# --- runtime selection ----------------------------------------------------
+# Default is Claude (inspects .claude/agents/<name>.md symlinks). Codex passes
+# `--runtime codex`, which inspects the generated .codex/agents/<name>.toml
+# files instead — Codex custom agents are transpiled TOML, never symlinks, so
+# the Claude-specific "degraded regular-file" concept does not apply there.
+RUNTIME="claude"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --runtime) RUNTIME="${2:-claude}"; shift 2 ;;
+    --runtime=*) RUNTIME="${1#*=}"; shift ;;
+    *) shift ;;
+  esac
+done
+
 # --- read envelope --------------------------------------------------------
 
 INPUT=""
@@ -58,7 +72,13 @@ cd "$CWD" 2>/dev/null || exit 0
 # --- locate the framework agent directory --------------------------------
 
 FRAMEWORK_AGENTS_DIR=".framework/framework/.claude/agents"
-CONSUMER_AGENTS_DIR=".claude/agents"
+if [ "$RUNTIME" = "codex" ]; then
+  CONSUMER_AGENTS_DIR=".codex/agents"
+  CONSUMER_AGENT_EXT="toml"
+else
+  CONSUMER_AGENTS_DIR=".claude/agents"
+  CONSUMER_AGENT_EXT="md"
+fi
 
 [ -d "$FRAMEWORK_AGENTS_DIR" ] || exit 0  # consumer not installed — silent.
 
@@ -79,12 +99,15 @@ while IFS= read -r f; do
   [ -z "$f" ] && continue
   name="$(basename "$f" .md)"
   [ "$name" = "REGISTRY" ] && continue
-  target="$CONSUMER_AGENTS_DIR/${name}.md"
+  target="$CONSUMER_AGENTS_DIR/${name}.${CONSUMER_AGENT_EXT}"
   # `test -e` returns false for broken symlinks too — exactly what we want.
   if [ ! -e "$target" ]; then
     if [ -z "$MISSING" ]; then MISSING="$name"; else MISSING="$MISSING, $name"; fi
     continue
   fi
+  # Codex agents are generated TOML regular files — that IS the healthy state,
+  # so the degraded-regular-file check below applies to Claude only.
+  [ "$RUNTIME" = "codex" ] && continue
   # File exists. If it's a symlink → CC discovery sees it, healthy.
   # If it's a regular file with the baldart-generated marker → degraded
   # state (legacy overlay layout before v3.27.0).
@@ -107,7 +130,11 @@ escape_json() {
 
 MSG=""
 if [ -n "$MISSING" ]; then
-  MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+  if [ "$RUNTIME" = "codex" ]; then
+    MSG="BALDART expects the following custom agents to be spawnable by name in this Codex session, but their generated definitions are missing from .codex/agents/ (expected <name>.toml): ${MISSING}. Do NOT silently substitute a generic agent for these — per AGENTS.md the run must stop with the missing-agent remediation. Run \`npx baldart update\` (regenerates the TOML from the .md source) or \`npx baldart doctor\`, then restart this session."
+  else
+    MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+  fi
 fi
 if [ -n "$DEGRADED" ]; then
   DEG_MSG="BALDART detected overlay-merged agents stored in the legacy pre-v3.27.0 layout (regular files in .claude/agents/ with the baldart-generated marker): ${DEGRADED}. Claude Code upstream bug #20931 silently skips regular files at session-start discovery, so calling Agent with one of these subagent_type values will fail with InputValidationError even though the file is on disk. Run \`npx baldart update\` to migrate to the v3.27.0+ symlink-indirection layout (the file is moved to .baldart/generated/<kind>s/<name>.md and .claude/agents/<name>.md becomes a symlink to it), then restart this session."

package/framework/.claude/hooks/framework-edit-gate.js

@@ -1,21 +1,29 @@
 #!/usr/bin/env node
 /**
- * framework-edit-gate — Claude Code PreToolUse hook.
+ * framework-edit-gate — cross-tool PreToolUse hook (Claude Code + Codex).
  *
- * Intercepts Edit / Write / MultiEdit calls whose target resolves (via
- * symlink) to a path inside `.framework/` — i.e. the BALDART subtree that
- * flows upstream via `baldart push`. Runs the contamination scanner on the
- * new content and blocks the call with an informative `reason` if any
- * project-specific tokens are present (Neo-Brutalism, merchant, fidelity,
- * Recharts, hardcoded paths, etc.).
+ * Intercepts file-edit calls whose target resolves (via symlink) to a path
+ * inside `.framework/` — i.e. the BALDART subtree that flows upstream via
+ * `baldart push`. Runs the contamination scanner on the new content and blocks
+ * the call with an informative `reason` if any project-specific tokens are
+ * present (Neo-Brutalism, merchant, fidelity, Recharts, hardcoded paths, etc.).
  *
- * Effect: Claude sees the block reason and either reformulates the content
+ * Runtime-aware payloads:
+ *   - Claude Code: `Edit` / `Write` / `MultiEdit` / `NotebookEdit`, each with a
+ *     single `file_path` + new content.
+ *   - Codex: `apply_patch`, whose input is the OpenAI patch envelope covering
+ *     one or more files; `handleApplyPatch` parses it (fail-open on any doubt).
+ * The deny format (`hookSpecificOutput.permissionDecision`) is identical for
+ * both runtimes.
+ *
+ * Effect: the agent sees the block reason and either reformulates the content
  * generically (referencing `${paths.X}` / `identity.X`) or moves the change
- * into `.baldart/overlays/<skill>.md`. Project-specific tokens never reach
- * the framework subtree silently.
+ * into `.baldart/overlays/<skill>.md`. Project-specific tokens never reach the
+ * framework subtree silently.
  *
- * Registration: see src/utils/hooks.js — `baldart add` and `baldart update`
- * auto-register this hook in the consumer's `.claude/settings.json`.
+ * Registration: see src/utils/hooks/registry.js — `baldart add` and
+ * `baldart update` auto-register this hook in the consumer's
+ * `.claude/settings.json` (Claude) and/or `.codex/hooks.json` (Codex).
  *
  * Fail-safe contract: this hook MUST NOT block legitimate work. If anything
  * unexpected happens (missing scanner, parse error, IO error), it exits 0
@@ -150,12 +158,138 @@ function blockReason(realPath, decisions, blockings) {
   ].join('\n');
 }
 
+// Structural marker that identifies a BALDART-generated file (agent/command
+// generated from base + overlay). Hoisted to module scope so both the Claude
+// single-file path and the Codex apply_patch path can reuse it. The regex
+// requires kind=…name=…overlay_sha= so a mere string-literal mention of the
+// marker (e.g. in this hook, overlay-merger.js) is not a false positive.
+const GENERATED_MARKER_RE =
+  /<!-- baldart-generated:[\s\S]{0,400}?kind=\S+[\s\S]{0,400}?name=\S+[\s\S]{0,400}?overlay_sha=\S+/;
+
+// Emit a deny decision in the shape both Claude Code and Codex accept
+// (`hookSpecificOutput.permissionDecision`), falling back to the legacy
+// exit-2 + stderr convention if stdout is unavailable. Never returns.
+function emitDeny(reason) {
+  try {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }));
+  } catch (_) {
+    process.stderr.write(reason + '\n');
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+// --- Codex apply_patch support -------------------------------------------
+//
+// Codex normalizes file edits to a single `apply_patch` tool whose input is the
+// OpenAI patch envelope (`*** Begin Patch` / `*** Add File:` / `*** Update File:`
+// / `*** Delete File:` / `+added` / `-removed`). The field carrying the patch
+// text is not guaranteed by the spec, so we probe the common shapes and, on any
+// doubt, fail OPEN (return no targets → the caller exits 0). This gate is a
+// safety net; a missed edit is caught later by the `baldart push` scanner, but
+// a FALSE block would disrupt legitimate work — so uncertainty always fails open.
+
+function extractPatchText(toolInput) {
+  if (!toolInput) return '';
+  if (typeof toolInput === 'string') return toolInput;
+  for (const key of ['input', 'patch', 'content', 'text', 'diff', 'apply_patch']) {
+    if (typeof toolInput[key] === 'string' && toolInput[key].includes('*** ')) return toolInput[key];
+  }
+  // Last resort: any string value that looks like a patch envelope.
+  for (const v of Object.values(toolInput)) {
+    if (typeof v === 'string' && v.includes('*** Begin Patch')) return v;
+  }
+  return '';
+}
+
+// Parse the patch text into per-file `{ path, added }` targets. `added` is the
+// concatenation of inserted lines (leading `+` stripped) for that file.
+function collectApplyPatchTargets(toolInput) {
+  const text = extractPatchText(toolInput);
+  if (!text) return [];
+  const targets = [];
+  let cur = null;
+  const fileHdr = /^\*\*\* (Add|Update|Delete) File: (.+?)\s*$/;
+  for (const line of text.split('\n')) {
+    const m = line.match(fileHdr);
+    if (m) {
+      if (cur) targets.push(cur);
+      cur = { path: m[2], added: [] };
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith('*** ')) { targets.push(cur); cur = null; continue; } // End Patch / next marker
+    if (line.startsWith('+') && !line.startsWith('+++')) cur.added.push(line.slice(1));
+  }
+  if (cur) targets.push(cur);
+  return targets.map((t) => ({ path: t.path, added: t.added.join('\n') }));
+}
+
+// Codex PreToolUse(apply_patch) handler — the multi-file analogue of the Claude
+// single-file flow below. Reuses the same generated-file guard and the same
+// `.framework/` contamination scan. Fail-safe throughout.
+function handleApplyPatch(input) {
+  let targets;
+  try { targets = collectApplyPatchTargets(input.tool_input); }
+  catch (_) { safeExit(); }
+  if (!targets || targets.length === 0) safeExit();
+
+  for (const t of targets) {
+    if (!t.path) continue;
+
+    // Guard 1: overwriting a BALDART-generated file without retaining the marker.
+    try {
+      if (fs.existsSync(t.path)) {
+        const head = fs.readFileSync(t.path, 'utf8').slice(0, 5000);
+        if (GENERATED_MARKER_RE.test(head) && !GENERATED_MARKER_RE.test(t.added)) {
+          emitDeny(
+            `Cannot edit BALDART-generated file (${t.path}).\n` +
+            `This file is auto-generated by \`npx baldart update\` from a base ` +
+            `framework file plus an overlay. Manual edits will be overwritten.\n\n` +
+            `To customise: edit the corresponding overlay under .baldart/overlays/ ` +
+            `(or create it if absent), then re-run \`npx baldart update\`.`);
+        }
+      }
+    } catch (_) { /* fail-safe */ }
+
+    // Guard 2: contamination inside the .framework/ subtree.
+    const realPath = resolveReal(t.path);
+    if (!realPath) continue;
+    if (realPath.includes(`${path.sep}.baldart${path.sep}overlays${path.sep}`)) continue;
+    const frameworkRoot = findFrameworkRoot(realPath);
+    if (!frameworkRoot) continue;
+    if (!t.added) continue;
+    const scanner = loadScanner(frameworkRoot);
+    if (!scanner) continue;
+    let findings;
+    try {
+      const r = scanner.scan(t.added);
+      if (r.optedOut) continue;
+      findings = r.findings || [];
+    } catch (_) { continue; }
+    const decisions = findings.filter((f) => f.severity === 'requires-decision');
+    const blockings = findings.filter((f) => f.severity === 'block');
+    if (decisions.length === 0 && blockings.length === 0) continue;
+    emitDeny(blockReason(realPath, decisions, blockings));
+  }
+
+  safeExit();
+}
+
 function main() {
   const raw = readStdin();
   const input = parseInput(raw);
   if (!input) safeExit();
 
   const toolName = input.tool_name;
+  // Codex routes all file edits through `apply_patch`; handle that shape first.
+  if (toolName === 'apply_patch') return handleApplyPatch(input);
   if (!['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(toolName)) safeExit();
 
   const filePath = input.tool_input && input.tool_input.file_path;
@@ -170,8 +304,7 @@ function main() {
   // regex (requires kind=…name=…overlay_sha=…) avoids false-positives on
   // framework source files that mention the marker as a string literal
   // (e.g. this hook itself, agent-discovery-info.sh, overlay-merger.js).
-  const GENERATED_MARKER_RE =
-    /<!-- baldart-generated:[\s\S]{0,400}?kind=\S+[\s\S]{0,400}?name=\S+[\s\S]{0,400}?overlay_sha=\S+/;
+  // GENERATED_MARKER_RE is defined at module scope (shared with handleApplyPatch).
   try {
     const fs = require('fs');
     if (fs.existsSync(filePath)) {

package/framework/agents/skills-mapping.md

@@ -2,7 +2,11 @@
 
 ## Purpose
 
-Map Claude Code skills to project domains and provide guidance on when to use each skill.
+Map the framework's **portable skills** (Claude Code + Codex) to project domains
+and provide guidance on when to use each skill. The same skill source under
+`framework/.claude/skills/<x>/` is installed for every enabled tool — Claude
+reads it from `.claude/skills/<x>`, Codex from `.agents/skills/<x>` — so skill
+selection is runtime-agnostic; only the invocation mechanics differ.
 
 ## Scope
 
@@ -29,6 +33,31 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > (noted per entry). When the flag is `false` the skill REFUSES — do not route to
 > it; resolve the gate first (e.g. `/design-system-init` for `has_design_system`).
 
+### Cross-tool delegation (SSOT: `AGENTS.md`)
+
+Skill selection is portable, but **who does the work** is governed cross-tool by
+`AGENTS.md` § Non-negotiables — the single SSOT (read by Claude Code and Codex
+alike), not restated here:
+
+- Understand-before-implement (`codebase-architect` first), plan-review gate,
+  and **domain delegation — code/logic/tests → `coder`, UI → `ui-expert`** —
+  hold on both runtimes. The invocation differs only mechanically: Claude uses
+  the Task tool (`subagent_type`), Codex spawns the custom agent **by name**
+  from `.codex/agents/<name>.toml`.
+- **No silent fallback.** If a named agent is missing or an invocation returns
+  empty, STOP and report — never improvise a generic agent. On Claude this is
+  also guarded by the `agent-discovery-gate` hook; on Codex, where agents are
+  spawned by name (no observable Agent tool), the guarantee is enforced by the
+  `/new` + `/prd` **Codex preflight** (validates `.codex/agents/<name>.toml`
+  before spawning) — see [`CODEX-HOOKS.md`](../docs/CODEX-HOOKS.md).
+- Branch/worktree creation is the orchestrator's job (`/nw`, `/new`), **never**
+  an implementer agent's — same rule on both runtimes.
+
+**Non-BALDART feature-entry skills** (e.g. the OpenAI-curated `nf`) describe
+their own delegation model with non-BALDART agent names and must **not** be used
+to drive BALDART backlog execution — route backlog work through `/prd` + `/new`,
+which enforce the contract above.
+
 ## Core Development Skills
 
 ### prd

package/framework/docs/CODEX-AGENTS.md

@@ -2,6 +2,10 @@
 
 > **Status:** shipped in v4.80.0. Claude + Codex. No new `baldart.config.yml` key —
 > rides on `tools.enabled` containing `codex`.
+>
+> **Related:** Codex also has a native **hook** surface, managed by BALDART in
+> `.codex/hooks.json` — see [`CODEX-HOOKS.md`](CODEX-HOOKS.md). This doc covers
+> agents (transpiled TOML); that one covers hooks.
 
 ## The problem this fixes
 

package/framework/docs/CODEX-HOOKS.md

@@ -0,0 +1,142 @@
+# Codex Hooks
+
+BALDART manages **native Codex hooks** in `.codex/hooks.json`, in parallel with
+the Claude Code hooks it has always managed in `.claude/settings.json`. This is
+the Codex half of the cross-tool hook parity delivered by the Codex-parity
+foundation (slice S2). It is **additive** — Claude hook behavior is unchanged.
+
+> Authoritative for agents: **read [`CODEX-AGENTS.md`](CODEX-AGENTS.md)** for the
+> agent-transpilation story and this file for hooks. The runtime-neutral hook
+> **set** lives in one place: [`src/utils/hooks/registry.js`](../../src/utils/hooks/registry.js).
+
+## Why this exists
+
+Codex now has a native hook surface using the **same JSON schema as Claude
+Code** (verified against the OpenAI Codex hooks spec, CLI 0.142.5):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Edit|Write|apply_patch",
+        "hooks": [ { "type": "command", "command": "node …/framework-edit-gate.js" } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "bash …/agent-discovery-info.sh --runtime codex" } ] }
+    ]
+  }
+}
+```
+
+Before S2, `CodexAdapter.supportsHooks()` returned `false` and the hook
+registrar was Claude-only, so a Codex consumer got **none** of BALDART's hook
+protections (framework-contamination gate, agent-discovery signal). Now they do.
+
+## Architecture — one registry, two renderers
+
+```
+src/utils/hooks/
+  registry.js   ← runtime-neutral hook SET (one entry per logical hook,
+                   with per-runtime bindings under `runtimes.claude` / `runtimes.codex`)
+  claude.js     ← Claude renderer  → .claude/settings.json
+  codex.js      ← Codex renderer   → .codex/hooks.json
+src/utils/hooks.js   ← compatibility shim → re-exports claude.js
+```
+
+A logical hook declares an identity (`id`, `order`, `purpose`) and a binding
+per runtime that can express it. `defsFor('claude')` / `defsFor('codex')`
+project the registry onto each renderer. A hook with no binding for a runtime is
+simply not registered there.
+
+### Key differences the Codex renderer handles
+
+| Concern | Claude Code | Codex |
+|---|---|---|
+| Settings file | `.claude/settings.json` (many keys) | `.codex/hooks.json` (hooks only) |
+| Schema | `hooks[event][].{matcher, hooks:[{type,command}]}` | **identical** |
+| Per-entry `id` | yes (BALDART stamps + matches by `id`) | **no** — Codex addresses by position, trusts by content hash, and rejects unknown fields. Ownership is matched by a **command substring `marker`**, and entries carry **no `id`**. |
+| Edit tool | `Edit` / `Write` / `MultiEdit` / `NotebookEdit` (has `file_path`) | `apply_patch` (patch envelope; matcher also accepts `Edit\|Write`) |
+| Session context | `SessionStart` (inject `additionalContext`) | `SessionStart` (same) |
+| Deny format | `hookSpecificOutput.permissionDecision:"deny"` or exit 2 | **identical** |
+| Trust | none | **hook trust**: a new/changed hook is skipped until the user approves it; recorded in `~/.codex/config.toml`. |
+
+## The hooks and their Codex status
+
+| BALDART hook | Claude | Codex | Rationale |
+|---|---|---|---|
+| `baldart-framework-edit-gate` | `PreToolUse` on `Edit\|Write\|MultiEdit\|NotebookEdit` | **`PreToolUse` on `Edit\|Write\|apply_patch`** | Same script, made runtime-aware: it parses the Codex `apply_patch` envelope (`handleApplyPatch`) and scans added lines. **Fail-open on any parse doubt** — a missed edit is caught later by the `baldart push` scanner, but a false block would disrupt work. |
+| `baldart-agent-discovery-info` | `SessionStart` | **`SessionStart --runtime codex`** | Same script, told to inspect `.codex/agents/<name>.toml` (generated TOML) instead of `.claude/agents/<name>.md` (symlinks). Injects `additionalContext` only. |
+| `baldart-agent-discovery-gate` | `PreToolUse` on `Agent` | **not bound (deferred)** | Codex spawns subagents by name, not via an observable `Agent` PreToolUse tool; its `SubagentStart` event is session-scoped with unconfirmed deny semantics. The no-silent-fallback guarantee is enforced Codex-side by the **skill preflight** (the `/new` + `/prd` Codex runtime modules validate `.codex/agents/<name>.toml` before spawning). |
+| `baldart-overlay-telemetry` | `PostToolUse` on `Read` | **not bound (unsupported)** | Codex exposes no reliable file-`Read` tool event to hook on. Overlay-load telemetry stays Claude-only (observation-only, no functional impact). |
+
+The two deferred/unsupported hooks satisfy acceptance criterion 12 of the
+porting report: every unsupported hook is explicitly documented with a
+compensating mechanism (preflight for the gate; N/A for telemetry).
+
+## Hook trust — BALDART never fakes it
+
+Codex records trust against a hook's content; a new or changed hook is
+**inactive until the user approves it once** (or the session is run with
+`--dangerously-bypass-hook-trust`, which BALDART never does). The approval is
+stored in `~/.codex/config.toml`:
+
+```toml
+[hooks.state."/abs/path/.codex/hooks.json:pre_tool_use:0:0"]
+trusted_hash = "sha256:…"
+```
+
+BALDART **writes `.codex/hooks.json` but never `config.toml`** — faking trust
+would defeat the security model. Instead:
+
+- `add` / `update` register the hooks and **tell the user** that Codex will
+  prompt for approval on the next session ("until approved, they stay inactive").
+- `doctor` reports **presence and trust separately**: `Codex hooks: 2/2
+  registered & trusted`, or `2/2 registered, 2 untrusted` with a
+  `• untrusted: … (approve once on the next Codex session)` line. Untrusted-only
+  is **not** a failure (it needs an interactive step BALDART cannot perform).
+
+The trust probe reads `config.toml` and checks whether a `trusted_hash` entry
+exists for each hook's position key (`<hooks.json abspath>:<event_snake>:<i>:<j>`).
+It reports *presence of a trust entry*, not hash currency (Codex's hash
+algorithm is unspecified).
+
+## Lifecycle wiring
+
+- **`baldart add`** — after Claude hook registration, if `codex` ∈ enabled
+  tools, register the Codex hooks (additive) and surface the trust nudge. The
+  post-flight is **non-fatal** for Codex (a missing Codex hook warns + points to
+  `doctor`; it does not fail the install the way a missing Claude hook does).
+- **`baldart update`** — backfills Codex hooks for consumers that predate S2,
+  idempotently, preserving foreign entries.
+- **`baldart doctor`** — probes `.codex/hooks.json`, offers
+  `register-codex-hooks` (missing) and `reconcile-codex-hooks-drift` (drift)
+  actions, and reports trust state.
+
+## Additivity guarantee
+
+The Codex renderer only ever touches entries whose command carries a BALDART
+`marker`. Foreign hooks — notably a project's **Graphify** `graphify hook-check`
+entry, or any user-authored hook — are preserved verbatim, in place. `.codex/
+hooks.json` is never rewritten wholesale.
+
+## Must-measure-first
+
+The Codex hook schema, events, deny format, and trust key format were verified
+against the OpenAI Codex hooks spec and the real local `.codex/hooks.json` +
+`config.toml`. The renderer, the `apply_patch` gate, and the trust probe are
+unit-tested. What remains to confirm on a **live Codex consumer**:
+
+1. one BALDART Codex hook actually **fires** in a real Codex session, and
+2. the **trust-approval prompt** flow behaves as documented.
+
+Both fail safe: the gate fails open, registration is additive, and trust is
+never faked — so shipping S2 cannot break a Codex consumer even before the live
+confirmation. Report findings back into this doc.
+
+## Adding or changing a hook
+
+Edit exactly one place — [`src/utils/hooks/registry.js`](../../src/utils/hooks/registry.js):
+add a neutral entry with the `runtimes.claude` and/or `runtimes.codex` binding.
+The renderers, `add`/`update`/`doctor` wiring, and `doctor` reporting pick it up
+automatically. Per the cross-tool parity discipline, a new hook MUST state its
+Codex binding (or an explicit rationale for having none).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.87.0",
+  "version": "4.88.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/add.js

@@ -226,6 +226,35 @@ async function add(repo, options) {
       UI.warning(`Hook registration skipped: ${err.message}`);
     }
 
+    // Codex hooks (S2) — register the framework-edit-gate (PreToolUse/apply_patch)
+    // + agent-discovery-info (SessionStart) hooks into .codex/hooks.json when
+    // Codex is an enabled tool. Additive (preserves Graphify + user entries),
+    // never fakes hook trust — Codex asks the user to approve them on the next
+    // session; we surface that here so the inactivity is expected, not a bug.
+    if (Array.isArray(enabledTools) && enabledTools.includes('codex')) {
+      try {
+        const CodexHooks = require('../utils/hooks/codex');
+        const res = await CodexHooks.registerAll(process.cwd(), {
+          onDrift: CodexHooks.createDriftPrompt(UI, { autoYes: nonInteractive }),
+        });
+        if (res.malformed) {
+          UI.warning('.codex/hooks.json is malformed; skipped Codex hook registration. Run `npx baldart doctor` after fixing it.');
+        } else {
+          for (const r of res.results) {
+            if (r.status === 'created') UI.success(`Registered Codex hook \`${r.id}\` in .codex/hooks.json`);
+            else if (r.status === 'drift-replaced') UI.success(`Replaced drifted Codex hook \`${r.id}\` (was: ${r.previousCommand})`);
+            else if (r.status === 'drift-kept') UI.info(`Kept user-customized Codex hook \`${r.id}\` as-is.`);
+          }
+          const verify = CodexHooks.verifyAll(process.cwd());
+          if (verify.untrusted && verify.untrusted.length) {
+            UI.info(`Codex will prompt you to approve ${verify.untrusted.length} new hook(s) on the next session (hook trust): ${verify.untrusted.join(', ')}. Until approved they stay inactive.`);
+          }
+        }
+      } catch (err) {
+        UI.warning(`Codex hook registration skipped: ${err.message}`);
+      }
+    }
+
     // Configure Git aliases
     UI.section('Configuring Git Aliases');
 
@@ -343,6 +372,22 @@ async function add(repo, options) {
       process.exit(1);
     }
 
+    // Codex hook post-flight — non-fatal (Codex is a secondary target and hook
+    // trust is an interactive step BALDART cannot complete during install). A
+    // MISSING Codex hook is surfaced as a warning + a doctor pointer, but it
+    // does not fail the install the way a missing Claude hook does.
+    if (Array.isArray(enabledTools) && enabledTools.includes('codex')) {
+      try {
+        const CodexHooks = require('../utils/hooks/codex');
+        const cv = CodexHooks.verifyAll(process.cwd());
+        if (cv.malformed) {
+          UI.warning('.codex/hooks.json is malformed — Codex hooks unverifiable. Run `npx baldart doctor`.');
+        } else if (!cv.ok) {
+          UI.warning(`Codex hooks missing: ${cv.missing.join(', ')}. Run \`npx baldart doctor\` to repair.`);
+        }
+      } catch (_) { /* non-fatal */ }
+    }
+
     // Success summary
     UI.header('✓ INSTALLATION COMPLETE');