brainclaw 1.16.0 → 1.18.0

package/dist/commands/mcp-write-coordination.js

@@ -20,12 +20,14 @@ import { appendAuditEntry } from '../core/audit.js';
 import { nowISO } from '../core/ids.js';
 import { validateMcpField } from '../core/input-validation.js';
 import { generateCandidateIdWithLabel, saveCandidate } from '../core/candidates.js';
+import { validateLoopProjectResolution } from '../core/loops/project-resolution.js';
 import { ackMessage, getThread, hasActiveAssignment, sendMessage } from '../core/messaging.js';
 import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatcher.js';
 import { CoordinateRequestSchema } from '../core/facade-schema.js';
 import { buildInvokeCommand, getCapabilityProfile, getSpawnableAgents, resolveModel, validateAgentForDispatch, } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
+import { prepareTurnOwnedReviewDispatch, turnOwnedReviewEnabled } from '../core/review-loop-turn-dispatch.js';
 import { createAssignment, generateAssignmentId, patchAssignmentMessageId, transitionAssignment, } from '../core/assignments.js';
 import { createToolErrorResponse, toolResponse, } from './mcp-contract.js';
 import { handleMcpReadToolCall } from './mcp-read-handlers.js';
@@ -228,11 +230,13 @@ export function handleBclawSendMessage(args, ctx) {
         }, cwd);
         appendAuditEntry({ actor: resolved.identity.agent_name, actor_id: resolved.identity.agent_id, action: 'create', item_id: result.id, item_type: 'message', scope: to }, cwd);
         const threadInfo = threadId ? ` thread:${threadId}` : '';
+        const warningLine = result.warning ? `\n⚠ ${result.warning}` : '';
         return {
             response: toolResponse({
-                content: [{ type: 'text', text: `✔ Message sent: [${result.shortLabel}] ${msgType} → ${to}${threadInfo}` }],
+                content: [{ type: 'text', text: `✔ Message sent: [${result.shortLabel}] ${msgType} → ${to}${threadInfo}${warningLine}` }],
                 message_id: result.id,
                 thread_id: threadId,
+                ...(result.warning ? { warning: result.warning } : {}),
             }),
         };
     }
@@ -270,7 +274,7 @@ export function handleBclawAckMessage(args, ctx) {
     }
 }
 export async function handleBclawCoordinate(args, ctx) {
-    const { cwd, connectionSessionId, currentModel } = ctx;
+    const { cwd, connectionSessionId, currentModel, effectiveScope } = ctx;
     const startMs = Date.now();
     const parseResult = CoordinateRequestSchema.safeParse(args);
     if (!parseResult.success) {
@@ -356,6 +360,35 @@ export async function handleBclawCoordinate(args, ctx) {
         warnings.push(`cross-project dispatch (project='${req.project}') — auto-spawn disabled; the target agent picks up the brief async via its own bclaw_work.`);
     }
     const effectiveAutoExecute = isCrossProject ? false : req.autoExecute;
+    // pln#521 P1 — project resolution gate. A review loop written into the wrong
+    // store is worse than one that never opened: candidate, claim, assignment and
+    // loop all persist where nobody is watching, and the reviewer spawns against
+    // the wrong repo (DGX misroute). So when this store can host several projects
+    // and NONE was selected, refuse here — before the pre-flight spawn and before
+    // the first write — instead of silently defaulting to cwd. Explicit `project`,
+    // a session switch, or an active-project pointer all count as a choice; ref /
+    // scope / path never do (B3 rejected, art_e29e88878209). Scoped to the failing
+    // path (review + open_loop): every other intent keeps its routing untouched.
+    let projectResolution;
+    if (req.intent === 'review' && req.open_loop === true) {
+        // Resolve from `cwd`, not `dispatchCwd`: an explicit project name is
+        // resolvable from the SOURCE store (its links / store chain), which is
+        // exactly what produced dispatchCwd above. Re-resolving from the target
+        // could fail for a link whose name differs from the target's project_name.
+        const resolution = validateLoopProjectResolution({
+            cwd,
+            projectArg: req.project,
+            activeSource: effectiveScope?.active_source,
+        });
+        if (!resolution.ok) {
+            return {
+                response: createToolErrorResponse(resolution.code, resolution.message, {
+                    candidates: resolution.candidates,
+                }),
+            };
+        }
+        projectResolution = resolution;
+    }
     // can_30c295b4 / trp#371 Tier 2 — scope-aware dirty-working-tree guard.
     // Intents that spawn a worktree worker from HEAD can review/edit stale code,
     // so they are guarded; consult/summarize (no worktree) are not. pln#626
@@ -403,7 +436,7 @@ export async function handleBclawCoordinate(args, ctx) {
     /** Run E2E execution phase on prepared delivery entries. Returns overall execution status. */
     const runCoordinateExecution = async (prepared, opts) => {
         let overall = 'inbox_only';
-        for (const { entry, invoke, worktreePath } of prepared) {
+        for (const { entry, invoke, worktreePath, turnEcho } of prepared) {
             const execResult = await attemptExecution(invoke, {
                 agent: entry.agent,
                 autoExecute: opts.autoExecute,
@@ -414,6 +447,8 @@ export async function handleBclawCoordinate(args, ctx) {
                 dispatcherAgentId: opts.senderAgentId,
                 cwd: opts.cwd,
                 requireWorktree: true, // pln#531: never spawn a worker in the integration repo
+                turnEcho, // pln#630 — turn-owned reviewer (initial dispatch): the ack-wrapper writes the
+                // turn-keyed completion sentinel. undefined for every non-turn-owned entry.
             });
             entry.execution_status = execResult.execution_status;
             // pln#626 Phase 1 — carry the machine-readable reason (+ failure_kind) to
@@ -436,7 +471,23 @@ export async function handleBclawCoordinate(args, ctx) {
             // emit three identical context-free warnings (pln#626 Phase 1 R5).
             if (execResult.error)
                 opts.warnings.push(`${entry.agent}: ${execResult.error}`);
-            if (entry.assignment_id && entry.claim_id) {
+            if (turnEcho) {
+                // pln#630 risk #1 — a turn-owned reviewer's run was ALREADY created (`created`) by
+                // prepareTurnOwnedReviewDispatch. Do NOT mint a second run here (double-mint). Transition
+                // the deterministic run → running on a real spawn (mirrors dispatchReviewLoopTurn); leave
+                // it `created` otherwise so the no-sentinel legacy fallback (turnOwnedLaneEvidence) + the
+                // pre-run lease reconciler govern it. Non-turn-owned entries take the unchanged else-branch.
+                if (execResult.execution_status === 'delivered_and_started') {
+                    try {
+                        transitionAgentRun(turnEcho.run_id, 'running', {
+                            actor: opts.senderAgent, actor_id: opts.senderAgentId, pid: execResult.pid,
+                            status_reason: 'turn-owned reviewer spawned by coordinator',
+                        }, opts.cwd);
+                    }
+                    catch { /* best-effort — the reconciler converges if this races */ }
+                }
+            }
+            else if (entry.assignment_id && entry.claim_id) {
                 if (execResult.failure_kind === 'spawn_no_handshake') {
                     try {
                         const run = createAgentRun({
@@ -969,38 +1020,82 @@ export async function handleBclawCoordinate(args, ctx) {
                             id: claimResult.claimId,
                         });
                         let reviewAssignmentId;
-                        try {
-                            const preId = generateAssignmentId(dispatchCwd);
-                            const assignment = createAssignment({
-                                id: preId.id,
-                                short_label: preId.short_label,
-                                claim_id: claimResult.claimId,
+                        let reviewTurnEcho;
+                        // pln#630 — turn-own the INITIAL reviewer dispatch (same default + kill-switch as the
+                        // fix cycle). Skipped for cross-project reviews (no local worktree/sentinel → they never
+                        // spawn here). WON: prepare minted the DETERMINISTIC assignment + run + turn()-bound the
+                        // slot, so we reuse prep.assignmentId for the brief/message/linkage below and carry the
+                        // turnEcho so the ack-wrapper writes the turn-keyed sentinel. DENIED: the exactly-once
+                        // fence says this dispatch is NOT the spawner — do NOT spawn, do NOT fall back to legacy
+                        // (that is the double-spawn hole), and do NOT release the (possibly shared) claim; leave
+                        // the slot for reconcile/self-heal. LEGACY: the unchanged inline mint runs.
+                        let usedTurnOwned = false;
+                        if (turnOwnedReviewEnabled() && !req.project) {
+                            const prep = prepareTurnOwnedReviewDispatch({
+                                loopId: loop.id,
+                                slotId: slot.slot_id,
                                 agent: slot.agent ?? '',
-                                dispatcher_agent: senderAgent,
-                                dispatcher_session_id: connectionSessionId,
-                                scope: reviewScope,
+                                agentId: slot.agent_id,
+                                phase: 'findings',
+                                task: req.task,
                                 description: reviewDescription,
-                                tags: ['coordinate', 'review', 'loop'],
-                            }, dispatchCwd);
-                            reviewAssignmentId = assignment.id;
-                            out.artifacts.push({ type: 'assignment', id: assignment.id });
+                                scope: reviewScope,
+                                claimId: claimResult.claimId,
+                                worktreePath: claimResult.worktreePath,
+                                dispatcherAgent: senderAgent,
+                                dispatcherAgentId: senderAgentId,
+                                sessionId: connectionSessionId,
+                                isReviewer: true,
+                                cwd: dispatchCwd,
+                            });
+                            if (prep.kind === 'won') {
+                                reviewAssignmentId = prep.assignmentId; // deterministic — harvest correlates on it
+                                reviewTurnEcho = { turn_id: prep.turnId, run_id: prep.runId, nonce: prep.nonce };
+                                out.artifacts.push({ type: 'assignment', id: prep.assignmentId });
+                                usedTurnOwned = true; // prepare already created the assignment + run + bound the slot
+                            }
+                            else if (prep.kind === 'denied') {
+                                out.partial = true;
+                                out.warnings.push(`open_loop: turn-owned reviewer dispatch denied for slot ${slot.slot_id} (${prep.reason}); not spawning — slot left for reconcile/self-heal`);
+                                continue; // MUST NOT spawn AND MUST NOT legacy-fallback beside a live reservation
+                            }
+                            // prep.kind === 'legacy' (pre-identity failure) → fall through to the inline mint.
                         }
-                        catch (asgErr) {
-                            out.warnings.push(`Review assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
+                        if (!usedTurnOwned) {
+                            try {
+                                const preId = generateAssignmentId(dispatchCwd);
+                                const assignment = createAssignment({
+                                    id: preId.id,
+                                    short_label: preId.short_label,
+                                    claim_id: claimResult.claimId,
+                                    agent: slot.agent ?? '',
+                                    dispatcher_agent: senderAgent,
+                                    dispatcher_session_id: connectionSessionId,
+                                    scope: reviewScope,
+                                    description: reviewDescription,
+                                    tags: ['coordinate', 'review', 'loop'],
+                                }, dispatchCwd);
+                                reviewAssignmentId = assignment.id;
+                                out.artifacts.push({ type: 'assignment', id: assignment.id });
+                            }
+                            catch (asgErr) {
+                                out.warnings.push(`Review assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
+                            }
+                            // pln#628 Focus 4B (BLOCKING 2) — assign the slot NOW that the
+                            // claim/assignment exist, binding their ids onto the slot so the
+                            // harvest close resolves this exact reviewer by assignment_id. Runs
+                            // even if assignment creation failed (undefined id → the harvest
+                            // falls back to the legacy agent match for this one slot). (For the
+                            // turn-owned WON path, prepare already turn()-bound the slot.)
+                            turn({
+                                id: loop.id,
+                                slot_id: slot.slot_id,
+                                actor: creatorActor,
+                                input: req.task,
+                                assignment_id: reviewAssignmentId,
+                                claim_id: claimResult.claimId,
+                            }, dispatchCwd);
                         }
-                        // pln#628 Focus 4B (BLOCKING 2) — assign the slot NOW that the
-                        // claim/assignment exist, binding their ids onto the slot so the
-                        // harvest close resolves this exact reviewer by assignment_id. Runs
-                        // even if assignment creation failed (undefined id → the harvest
-                        // falls back to the legacy agent match for this one slot).
-                        turn({
-                            id: loop.id,
-                            slot_id: slot.slot_id,
-                            actor: creatorActor,
-                            input: req.task,
-                            assignment_id: reviewAssignmentId,
-                            claim_id: claimResult.claimId,
-                        }, dispatchCwd);
                         const reviewBrief = buildCoordinateBrief(slot.agent ?? '', reviewDescription + reviewVerdictBriefSuffix, {
                             claimId: claimResult.claimId,
                             scope: reviewScope,
@@ -1045,6 +1140,7 @@ export async function handleBclawCoordinate(args, ctx) {
                             entry: queued.entry,
                             invoke: queued.invoke,
                             worktreePath: claimResult.worktreePath,
+                            turnEcho: reviewTurnEcho,
                         });
                     }
                     catch (dispatchErr) {
@@ -1105,6 +1201,16 @@ export async function handleBclawCoordinate(args, ctx) {
         result = {
             candidate_id: output.candidateId,
             selected_targets: resolvedAgents,
+            // pln#521 P1 (B4) — echo the routing decision so an operator can see WHERE
+            // the loop landed without reverse-engineering cwd and store state. Present
+            // for open_loop reviews (the gated path); the reasoning behind the decision
+            // ships as `_resolution_trace` on dispatch_status, not here.
+            ...(projectResolution
+                ? {
+                    project_cwd: projectResolution.project_cwd,
+                    ...(projectResolution.project_name ? { project_name: projectResolution.project_name } : {}),
+                }
+                : {}),
             // pln#626 Phase 1 (review rework) — expose the reviewer delivery entries
             // so review is as honest as assign/reroute: each entry's execution_reason
             // (set by runCoordinateExecution) feeds the top-level derivation, so a
@@ -1550,12 +1656,6 @@ export async function handleBclawCoordinate(args, ctx) {
                             slotRole: slot.role,
                             memoryProvider: provider,
                         });
-                        turn({
-                            id: loopId,
-                            slot_id: slot.slot_id,
-                            actor: creatorActor,
-                            input: briefResult.text,
-                        }, dispatchCwd);
                         // pln#626 Phase 2 (Option B) — spawn the critic as a worktree-isolated
                         // worker, mirroring the intent=assign / review chain. Each critic gets
                         // its OWN claim + worktree (scope is unique per slot) so parallel
@@ -1605,6 +1705,23 @@ export async function handleBclawCoordinate(args, ctx) {
                             catch (asgErr) {
                                 warnings.push(`ideate assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
                             }
+                            // pln#629 — bind the slot to its claim/assignment NOW that both
+                            // exist (mirrors the review path, pln#628 BLOCKING 2). The turn()
+                            // used to fire BEFORE the assignment was created, leaving
+                            // slot.assignment_id undefined: bclaw_loop get's reconcile then
+                            // skipped the critic slot (loops-handlers.ts `if (!assignmentId)
+                            // continue`) and dispatch_status(lop_) resolved no assignment, so
+                            // ideate loops could never be reconciled (trp_dfe0b941 /
+                            // trp_2187b340 / trp_1de94516). Runs even if assignment creation
+                            // failed (undefined id → legacy agent-match fallback, as review).
+                            turn({
+                                id: loopId,
+                                slot_id: slot.slot_id,
+                                actor: creatorActor,
+                                input: briefResult.text,
+                                assignment_id: criticAssignmentId,
+                                claim_id: claimResult.claimId,
+                            }, dispatchCwd);
                             // pln#626 Phase 2 — the critique-only contract must reach the
                             // DELIVERED brief, not just the claim record: buildCoordinateBrief
                             // wraps this in a worker envelope, so prepend the constraint + the
@@ -1806,7 +1923,9 @@ export async function handleBclawLoop(args, ctx) {
     }
     // pln#562 step 4 — dispatching a turn hands work to another agent; gate
     // it at the same trust bar as the other dispatch surfaces.
-    if (args?.intent === 'turn' && args?.dispatch === true) {
+    // pln#632 — `bind` also SPAWNS real workers (it dispatches the loop's linked
+    // sequence), so it is gated at the same 'trusted' bar as turn-dispatch / coordinate.
+    if ((args?.intent === 'turn' && args?.dispatch === true) || args?.intent === 'bind') {
         const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'trusted', cwd, connectionSessionId);
         if (resolved.error) {
             return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
@@ -1814,7 +1933,7 @@ export async function handleBclawLoop(args, ctx) {
     }
     const { handleBclawLoop: runLoopIntent } = await import('./loops-handlers.js');
     const targetCwd = resolveProjectCwd(args?.project, cwd);
-    const result = runLoopIntent({ args: args, cwd: targetCwd });
+    const result = await runLoopIntent({ args: args, cwd: targetCwd, sessionId: connectionSessionId });
     return {
         response: toolResponse({
             content: [{ type: 'text', text: result.summary }],

package/dist/commands/mcp.js

@@ -27,7 +27,7 @@ import { switchProject } from './switch.js';
 import { assessBootstrapNeed, resolveEmptyMemoryRecommendation } from '../core/setup-flow.js';
 import { WorkRequestSchema } from '../core/facade-schema.js';
 import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.js';
-import { sweepDeadPidRunningAgentRunsAtRead } from '../core/agentrun-reconciler.js';
+import { sweepDeadPidRunningAgentRunsAtRead, sweepTurnOwnedPreRunLeaseAtRead } from '../core/agentrun-reconciler.js';
 import { bumpActiveAssignmentHeartbeat } from '../core/assignments.js';
 import { handleBclawAckMessage, handleBclawCoordinate, handleBclawDispatch, handleBclawLoop, handleBclawSendMessage, } from './mcp-write-coordination.js';
 import { ensureTrust, resolveMutationIdentity, explicitSessionIdFromEnv, projectInfoForCwd, scopeMetadataForTarget, } from './mcp-write-support.js';
@@ -1556,7 +1556,10 @@ async function _executeMcpToolCallInner(payload) {
             };
         }
         if (name === 'bclaw_coordinate') {
-            return await handleBclawCoordinate(args, { cwd, connectionSessionId, currentModel });
+            // pln#521 P1 — scopeInfo carries WHICH selector produced `cwd`, which the
+            // review open_loop project gate needs to distinguish a chosen project
+            // from the bare cwd fallback.
+            return await handleBclawCoordinate(args, { cwd, connectionSessionId, currentModel, effectiveScope: scopeInfo });
         }
         if (name === 'bclaw_loop') {
             return await handleBclawLoop(args, { cwd, connectionSessionId });
@@ -1871,6 +1874,12 @@ export async function executeMcpToolCall(payload) {
             sweepDeadPidRunningAgentRunsAtRead(cwd);
         }
         catch { /* best-effort */ }
+        // pln#630 PR2c-lease: converge turn-owned runs still `created`/`launching`
+        // on their dispatch/launch lease (inert until live turn-owned dispatch).
+        try {
+            sweepTurnOwnedPreRunLeaseAtRead(cwd);
+        }
+        catch { /* best-effort */ }
     }
     // ── Delegate to inner handler ───────────────────────────────────────────────
     const outcome = await _executeMcpToolCallInner({

package/dist/core/agent-capability.js

@@ -159,10 +159,15 @@ const PROFILES = {
     // blocker.
     codex: {
         name: 'codex', category: 'code-agent', workflowModel: 'task-based',
-        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        // hooks: Codex gained a native lifecycle hook surface (SessionStart /
+        // UserPromptSubmit / Stop / PreToolUse / … via .codex/hooks.json or [hooks]
+        // in config.toml; developers.openai.com/codex/hooks, verified 2026-07 —
+        // trp_fe75dafc). brainclaw writes .codex/hooks.json (ensureCodexHooks),
+        // giving Codex the same session-lifecycle wiring as Claude Code.
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
         instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'A',
         role_capabilities: ['execute', 'review'],
-        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
         max_concurrent_tasks: 5,
         // pln#475: prefer stdin_pipe to avoid Windows cmd.exe arg-parsing breaking
         // long prompts. codex.cmd resolves through cmd shell, where embedded

package/dist/core/agent-files.js

@@ -314,6 +314,7 @@ const ANTIGRAVITY_MCP_RELATIVE_PATH = '.gemini/antigravity/mcp_config.json';
 const ANTIGRAVITY_HOOKS_RELATIVE_PATH = '.gemini/antigravity/hooks.json';
 const CURSOR_HOOKS_RELATIVE_PATH = '.cursor/hooks.json';
 const COPILOT_HOOKS_RELATIVE_PATH = '.github/copilot/hooks.json';
+const CODEX_HOOKS_RELATIVE_PATH = '.codex/hooks.json';
 const OPENCLAW_MCP_RELATIVE_PATH = '.openclaw/mcp.json';
 const VSCODE_EXTENSIONS_RELATIVE_PATH = '.vscode/extensions.json';
 const UNIVERSAL_SKILL_RELATIVE_PATH = '.agents/skills/brainclaw/SKILL.md';
@@ -1686,7 +1687,10 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         '\n[mcp_servers.brainclaw]',
         `command = "${normalizedCommand}"`,
         `args = [${normalizedArgs.map(a => `"${a}"`).join(', ')}]`,
-        'startup_timeout_ms = 20000',
+        // Codex renamed this field to `_sec` (developers.openai.com/codex/extend/mcp;
+        // the docs note "uses _sec, not _ms"). The old `startup_timeout_ms` is an
+        // unrecognized key → Codex silently falls back to its default startup timeout.
+        'startup_timeout_sec = 20',
         '',
         '[mcp_servers.brainclaw.env]',
         'BRAINCLAW_AGENT = "codex"',
@@ -2115,6 +2119,53 @@ export function ensureAntigravityHooks(homeDir) {
         relativePath: ANTIGRAVITY_HOOKS_RELATIVE_PATH,
     };
 }
+/**
+ * Writes `.codex/hooks.json` — Codex CLI's native lifecycle hooks config
+ * (project scope). Codex gained a full hook surface (developers.openai.com/codex/hooks,
+ * verified 2026-07 — trp_fe75dafc); this wires brainclaw's session lifecycle to it,
+ * mirroring the Claude Code / Antigravity hook writers.
+ *
+ * Events (PascalCase, per the Codex schema): `SessionStart` loads shared context,
+ * `UserPromptSubmit` surfaces the context diff, `Stop` runs session-end cleanup.
+ * File shape: `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type": "command", "command": "…" } ] } ] } }`
+ * — the top-level `hooks` wrapper + per-entry `hooks` array (`matcher: ""` = match all).
+ *
+ * brainclaw OWNS these three event arrays (overwrite, not merge) — the same
+ * contract as the Cursor / Antigravity `hooks.json` writers. This is
+ * unconditionally idempotent regardless of how the CLI path resolves, with no
+ * cross-upgrade pile-up. It deliberately does NOT use command-recognition to
+ * preserve user entries within these events: recognizing brainclaw's own hook
+ * path-independently requires matching bare CLI subcommands, which over-matches
+ * legitimate user hooks that merely pass `session-start`/etc. as an argument
+ * (Codex review of #94, round 2). Other events the user defines are untouched
+ * (only these three keys are set).
+ */
+export function ensureCodexHooks(cwd) {
+    const filePath = path.join(cwd, CODEX_HOOKS_RELATIVE_PATH);
+    const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Codex session hooks', filePath, CODEX_HOOKS_RELATIVE_PATH);
+    }
+    const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
+    const sessionStartCmd = buildHookCommand(['session-start', '--include-context']);
+    const contextDiffCmd = buildHookCommand(['context-diff']);
+    const sessionEndCmd = buildHookCommand(['session-end', '--auto-release', '--reflect', '--reflect-handoff', '--dispatch-review']);
+    hooks.SessionStart = [buildCommandHookEntry(sessionStartCmd)];
+    hooks.UserPromptSubmit = [buildCommandHookEntry(contextDiffCmd)];
+    hooks.Stop = [buildCommandHookEntry(sessionEndCmd)];
+    const { created, updated } = writeJsonFileIfChanged(filePath, {
+        ...existing,
+        hooks,
+    });
+    return {
+        kind: 'rule',
+        label: 'Codex session hooks',
+        created,
+        updated,
+        filePath,
+        relativePath: CODEX_HOOKS_RELATIVE_PATH,
+    };
+}
 /**
  * Writes `.github/copilot/hooks.json` — GitHub Copilot's native hooks config.
  * Events: sessionStart, userPromptSubmitted, sessionEnd (camelCase).
@@ -2284,7 +2335,7 @@ export const AGENT_WIRING_REGISTRY = {
             writeProtocolSkills,
         ],
         userWriters: [(ctx) => ensureCodexMcpConfig(ctx.homeDir, ctx.env)],
-        hookWriters: [],
+        hookWriters: [(ctx) => ensureCodexHooks(ctx.cwd)],
     },
     continue: {
         workspaceWriters: [(ctx) => ensureContinueMcpConfig(ctx.cwd)],

package/dist/core/agent-integrations.js

@@ -61,6 +61,7 @@ const DEFAULT_SURFACES = {
     'codex': [
         { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
         { kind: 'mcp', location: 'machine', path: '.codex/config.toml' },
+        { kind: 'hook', location: 'workspace', path: '.codex/hooks.json' },
         { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'opencode': [