instar 1.2.65 → 1.2.66

package/dist/core/installCodexHooks.d.ts

@@ -0,0 +1,52 @@
+/**
+ * installCodexHooks — wire instar's safety gates into a Codex CLI agent's
+ * native hook system, the Codex mirror of `installClaudeSettings`.
+ *
+ * Spec: docs/specs/codex-enforcement-hook-layer.md
+ *
+ * WHY: on Claude agents, instar's gates (external-operation, response-review,
+ * grounding, deferral, session-start, topic-context) are enforced via
+ * `.claude/settings.json` hooks. On Codex agents nothing enforced them — the
+ * gates were awareness-only. Codex CLI supports a Claude-compatible blocking
+ * hook system (verified: developers.openai.com/codex/hooks — PreToolUse can
+ * deny via `permissionDecision` or exit-2; events incl. SessionStart,
+ * PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop). This
+ * writes the gate registrations into Codex's discovery path.
+ *
+ * SCOPING (correctness-critical): writes the **per-project**
+ * `<projectDir>/.codex/hooks.json`, NOT the global `~/.codex/hooks.json`.
+ * The global root is shared with the operator's personal desktop Codex and
+ * every other Codex project on the machine — global enforcement hooks would
+ * intercept the operator's personal sessions. Per-project `.codex/` is a
+ * documented Codex discovery path and scopes the gates to this agent only.
+ *
+ * Invocation contract (Codex): the command receives the event JSON on stdin
+ * (no args), runs with the session cwd as working directory. We register
+ * absolute paths so discovery does not depend on cwd. The gate scripts'
+ * Codex-payload parsing is handled by the framework shim (spec P2); this
+ * module only writes the registrations.
+ *
+ * Idempotent + merge-safe: instar-owned entries are identified by a command
+ * path under `.instar/hooks/instar/` and replaced on every run; any
+ * user-added Codex hooks are preserved untouched.
+ */
+/** Marker that identifies an instar-owned hook command (for merge-safe replace). */
+export declare const INSTAR_HOOK_PATH_MARKER = ".instar/hooks/instar/";
+interface CodexHookHandler {
+    type: 'command';
+    command: string;
+    timeout?: number;
+}
+interface CodexHookGroup {
+    matcher?: string;
+    hooks: CodexHookHandler[];
+}
+/** Build the instar-owned hook groups for each Codex event, with absolute script paths. */
+export declare function buildInstarCodexHookGroups(projectDir: string): Record<string, CodexHookGroup[]>;
+/**
+ * Write/merge instar gate hooks into `<projectDir>/.codex/hooks.json`.
+ * Preserves any user-added hooks; replaces instar-owned entries.
+ */
+export declare function installCodexHooks(projectDir: string): string;
+export {};
+//# sourceMappingURL=installCodexHooks.d.ts.map

package/dist/core/installCodexHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installCodexHooks.d.ts","sourceRoot":"","sources":["../../src/core/installCodexHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,UAAU,gBAAgB;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAMD,2FAA2F;AAC3F,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CA4ClC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAwB5D"}

package/dist/core/installCodexHooks.js

@@ -0,0 +1,113 @@
+/**
+ * installCodexHooks — wire instar's safety gates into a Codex CLI agent's
+ * native hook system, the Codex mirror of `installClaudeSettings`.
+ *
+ * Spec: docs/specs/codex-enforcement-hook-layer.md
+ *
+ * WHY: on Claude agents, instar's gates (external-operation, response-review,
+ * grounding, deferral, session-start, topic-context) are enforced via
+ * `.claude/settings.json` hooks. On Codex agents nothing enforced them — the
+ * gates were awareness-only. Codex CLI supports a Claude-compatible blocking
+ * hook system (verified: developers.openai.com/codex/hooks — PreToolUse can
+ * deny via `permissionDecision` or exit-2; events incl. SessionStart,
+ * PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop). This
+ * writes the gate registrations into Codex's discovery path.
+ *
+ * SCOPING (correctness-critical): writes the **per-project**
+ * `<projectDir>/.codex/hooks.json`, NOT the global `~/.codex/hooks.json`.
+ * The global root is shared with the operator's personal desktop Codex and
+ * every other Codex project on the machine — global enforcement hooks would
+ * intercept the operator's personal sessions. Per-project `.codex/` is a
+ * documented Codex discovery path and scopes the gates to this agent only.
+ *
+ * Invocation contract (Codex): the command receives the event JSON on stdin
+ * (no args), runs with the session cwd as working directory. We register
+ * absolute paths so discovery does not depend on cwd. The gate scripts'
+ * Codex-payload parsing is handled by the framework shim (spec P2); this
+ * module only writes the registrations.
+ *
+ * Idempotent + merge-safe: instar-owned entries are identified by a command
+ * path under `.instar/hooks/instar/` and replaced on every run; any
+ * user-added Codex hooks are preserved untouched.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Marker that identifies an instar-owned hook command (for merge-safe replace). */
+export const INSTAR_HOOK_PATH_MARKER = '.instar/hooks/instar/';
+/** Build the instar-owned hook groups for each Codex event, with absolute script paths. */
+export function buildInstarCodexHookGroups(projectDir) {
+    const node = (script) => ({
+        type: 'command',
+        command: `node ${path.join(projectDir, INSTAR_HOOK_PATH_MARKER, script)}`,
+        timeout: 5000,
+    });
+    const sh = (script) => ({
+        type: 'command',
+        command: `bash ${path.join(projectDir, INSTAR_HOOK_PATH_MARKER, script)}`,
+        timeout: 5000,
+    });
+    return {
+        // Pre-action gate. matcher '.*' = all tool calls (Codex treats the matcher as
+        // a regex against the tool name; a bare '*' is an invalid quantifier that
+        // matches NOTHING, so the gate silently never fires — '.*' is required.
+        // Verified live 2026-05-24: with '.*', dangerous-command-guard fires on Codex's
+        // exec_command tool and blocks `rm -rf /`; with '*'/'' it did not fire at all).
+        // Each script classifies and decides: dangerous-command-guard covers Codex's
+        // native shell/exec_command (the main destructive surface); external-operation-gate
+        // covers mcp__* tools; grounding-before-messaging gates messaging commands. All
+        // read the command from Codex's stdin payload — Codex's exec_command puts it in
+        // tool_input.cmd (Claude uses tool_input.command); the scripts shim arg→stdin and
+        // accept both field names.
+        PreToolUse: [
+            { matcher: '.*', hooks: [sh('dangerous-command-guard.sh'), node('external-operation-gate.js'), sh('grounding-before-messaging.sh')] },
+        ],
+        // Codex-only checkpoint. Routes to the same gate; the trust system
+        // auto-decides (allow/deny) with NO human prompt so autonomy is preserved.
+        PermissionRequest: [
+            { matcher: '.*', hooks: [node('external-operation-gate.js')] },
+        ],
+        // End-of-turn review: coherence/tone + deferral detection.
+        Stop: [
+            { matcher: '', hooks: [{ ...node('response-review.js'), timeout: 10000 }, node('deferral-detector.js')] },
+        ],
+        // Identity/context injection.
+        SessionStart: [
+            { matcher: '', hooks: [sh('session-start.sh')] },
+        ],
+        UserPromptSubmit: [
+            { matcher: '', hooks: [sh('telegram-topic-context.sh')] },
+        ],
+    };
+}
+function groupIsInstarOwned(group) {
+    return (group.hooks ?? []).some((h) => typeof h.command === 'string' && h.command.includes(INSTAR_HOOK_PATH_MARKER));
+}
+/**
+ * Write/merge instar gate hooks into `<projectDir>/.codex/hooks.json`.
+ * Preserves any user-added hooks; replaces instar-owned entries.
+ */
+export function installCodexHooks(projectDir) {
+    const codexDir = path.join(projectDir, '.codex');
+    fs.mkdirSync(codexDir, { recursive: true });
+    const hooksPath = path.join(codexDir, 'hooks.json');
+    let config = {};
+    if (fs.existsSync(hooksPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object')
+                config = parsed;
+        }
+        catch {
+            // Corrupted — start fresh rather than block install.
+        }
+    }
+    const hooks = (config.hooks ??= {});
+    const desired = buildInstarCodexHookGroups(projectDir);
+    for (const [event, instarGroups] of Object.entries(desired)) {
+        const userGroups = (hooks[event] ?? []).filter((g) => !groupIsInstarOwned(g));
+        hooks[event] = [...userGroups, ...instarGroups];
+    }
+    fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2) + '\n');
+    return hooksPath;
+}
+//# sourceMappingURL=installCodexHooks.js.map

package/dist/core/installCodexHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installCodexHooks.js","sourceRoot":"","sources":["../../src/core/installCodexHooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.65",
+  "version": "1.2.66",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-25T01:39:18.241Z",
-  "instarVersion": "1.2.65",
+  "generatedAt": "2026-05-25T01:54:04.610Z",
+  "instarVersion": "1.2.66",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1472,7 +1472,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "298dee6bf9314642a3fbb90885a9e2c6aa8e944ffbd4209219481c5c6fd14df7",
+      "contentHash": "12706baa0f474d541a3d47fb6548a02e988727c7b150ac6ac351adaed4480e19",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.2.66.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — Codex safety hooks now actually fire
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**Fix: on Codex (codex-cli) agents, the PreToolUse safety guard now actually fires
+and blocks dangerous commands. Previously it was registered but silently never ran.**
+
+Two mismatches between how instar wrote the Codex hook config and how Codex actually
+invokes hooks:
+
+1. **Invalid tool-call matcher.** `installCodexHooks` emitted `matcher: "*"`. Codex
+   treats the matcher as a regex against the tool name, and a bare `*` is an invalid
+   quantifier that matches nothing — so the gate never fired. Session-level hooks
+   (SessionStart, UserPromptSubmit) fired fine because they aren't tool-matched, which
+   masked the problem. Changed to `".*"` (match all tool calls).
+2. **Wrong command field.** Codex's shell tool is `exec_command` and puts the command
+   in `tool_input.cmd`; the guard's stdin shim only read `tool_input.command` (Claude's
+   shape), so even once it fired it saw an empty command. The shim now reads either.
+
+Claude agents are unaffected — their existing argument path is unchanged and still tested.
+
+## What to Tell Your User
+
+If I'm running on the Codex engine, my safety guard that blocks catastrophic commands —
+things like wiping a disk — now genuinely stops them before they run. Until this fix the
+guard was installed but never actually triggered on Codex, so dangerous shell commands
+could slip through. Nothing changes if I'm running on Claude; this only closes the gap on
+the Codex side.
+
+## Summary of New Capabilities
+
+No new user-facing capabilities — this is a correctness fix to the existing Codex
+enforcement-hook layer. Codex agents that update will have a working PreToolUse safety
+gate (dangerous-command guard + external-operation gate + grounding check) where before it
+was inert. Existing Codex agents receive it on update via PostUpdateMigrator (matcher +
+stdin-shim fixes ship through both the init and update paths).
+
+## Evidence
+
+**Live reproduction (real Codex engine, not a simulation).** Regenerated a Codex test
+agent's hooks from freshly-built source via the real `refreshHooksAndSettings` path (no
+hand-editing, no debug instrumentation), launched real interactive Codex v0.133.0, and told
+it to run `echo 'rm -rf /'`.
+
+- **Before the fix:** identical setup — Codex ran the command unblocked; the guard never
+  fired (debug trace empty).
+- **After the fix:** Codex displayed `• PreToolUse hook (blocked) — BLOCKED: Catastrophic
+  command detected: rm -rf /` and did not execute it. First confirmed firing of the Codex
+  enforcement guard in the real engine.
+
+**Regression coverage:** the integration test now uses Codex's verified payload shape
+(`tool_name: exec_command`, `tool_input.cmd`) — it would have failed before the shim fix —
+plus a Claude-stdin case; a unit test asserts the matcher is `".*"`, not `"*"`. Full Codex
+hook suite: 19 green. `tsc` clean.

package/upgrades/side-effects/codex-enforcement-hooks-p1.md

@@ -0,0 +1,32 @@
+# Side-Effects Review: Codex enforcement hooks — P1 (installCodexHooks writer + tests)
+
+## Change
+New module `src/core/installCodexHooks.ts` + `tests/unit/installCodexHooks.test.ts` (6 tests). The module writes/merges instar's safety-gate registrations into a Codex agent's per-project `<projectDir>/.codex/hooks.json`, mapping the existing gate scripts (`external-operation-gate.js`, `grounding-before-messaging.sh`, `response-review.js`, `deferral-detector.js`, `session-start.sh`, `telegram-topic-context.sh`) to Codex's verified hook events (PreToolUse, PermissionRequest, Stop, SessionStart, UserPromptSubmit), using the verified Codex hooks.json schema.
+
+## Scope of effect (this commit)
+- **Capability-only, NOT yet wired.** This commit adds the writer + tests; it is NOT yet invoked from the init/refresh path (that is P1b, with a wiring-integrity test). So there is **no runtime behavior change** until the wiring lands — the function is inert until called.
+- When wired, it writes a single file: `<projectDir>/.codex/hooks.json`. Nothing else.
+
+## Scoping (correctness-critical)
+- Writes the **per-project** `.codex/hooks.json`, never the global `~/.codex/`. The global root is shared with the operator's personal desktop Codex and every other Codex project — global hooks would intercept the operator's personal sessions. Per-project scoping confines the gates to this agent's project dir. Unit-tested (asserts the path is not under `~/.codex`).
+
+## Merge-safety
+- Instar-owned entries are identified by command path containing `.instar/hooks/instar/`. On re-run, instar groups are replaced; any user-added Codex hooks are preserved verbatim. Idempotent (re-run yields identical file). Both behaviors unit-tested.
+
+## Signal vs Authority
+- The writer carries no runtime authority. The hooks it registers are low-context triggers that route to the server-side authority gates (`/operations/evaluate`, `/review/evaluate`). The writer just emits config; nothing in it decides allow/deny.
+
+## Over/under-block, abstraction
+- N/A — config writer, not a gate. The registered gates are the existing, unchanged authorities. No new decision boundary introduced here.
+
+## Migration parity
+- Not in this commit. `migrateCodexHooks()` (P3) will backfill existing Codex agents. Tracked in the spec phase plan; not deferred-and-forgotten.
+
+## Rollback
+- Trivial: delete the two files. No deployed effect (unwired). Once wired, removing the instar entries from `.codex/hooks.json` is a clean revert with no data migration.
+
+## Tests
+- 6 unit tests: per-project location (not global), all five events with the verified schema, absolute cwd-independent script paths, idempotency, user-hook preservation + instar replace, pure builder. All passing; tsc clean.
+
+## Publish
+- Feature branch `echo/codex-enforcement-hooks`. Not shipped; no separate publish.

package/upgrades/side-effects/codex-enforcement-hooks-p1b.md

@@ -0,0 +1,29 @@
+# Side-Effects Review: Codex enforcement hooks — P1b (wire installCodexHooks into init/refresh)
+
+## Change
+`src/commands/init.ts`: `refreshHooksAndSettings()` now calls `installCodexHooks(projectDir)` gated on `enabledFrameworks.includes('codex-cli')`, mirroring the existing `claudeEnabled → installClaudeSettings` block. Plus a wiring-integrity test (`tests/unit/codex-hooks-wiring.test.ts`).
+
+`refreshHooksAndSettings` is the single path that both `instar init` (line ~1097) and the update path invoke — so this one call site covers BOTH new and existing codex agents.
+
+## Runtime behavior change
+- Codex-cli agents now get `<projectDir>/.codex/hooks.json` written on init AND on every update/refresh. Claude-only agents are unaffected (gated). Both verified by the wiring-integrity test (codex → file created with instar gates; claude-only → no file; both → file created).
+
+## Sequencing risk (IMPORTANT — captured, not deferred-and-forgotten)
+- The wiring registers the existing gate scripts (`external-operation-gate.js`, `response-review.js`, etc.) into Codex's hook events. Those scripts currently parse **Claude's** hook stdin payload; the **Codex-payload shim is P2**. So on a *live* Codex session, the scripts could misbehave (parse errors → potentially an erroneous exit-2 block) until P2 lands.
+- **Why this is safe now:** this is a feature branch, NOT deployed. codey runs the released v1.2.53, which does not carry this wiring. No live codex agent has these hooks yet.
+- **Hard sequencing constraint for the build:** **P2 (gate-script Codex-payload shim) MUST land before the P6 deploy.** The phase plan already orders P2 → P6; this review makes the constraint explicit. Do not deploy P1 wiring without P2.
+
+## Signal vs Authority
+- Unchanged from P1: the hooks route to the server-side authority gates; the wiring just ensures they're registered for codex agents. No new authority.
+
+## Migration parity
+- `instar init` + update both flow through `refreshHooksAndSettings`, so existing codex agents get the wiring on their next update. (A dedicated `migrateCodexHooks` / always-overwrite-instar-owned hardening is P3.)
+
+## Rollback
+- Remove the `codexEnabled` block in `refreshHooksAndSettings` + the import. No deployed effect (branch-only).
+
+## Tests
+- Wiring-integrity: 3 tests (codex → wired, claude-only → not wired, both → wired). Plus the P1a unit suite (6). tsc + lint clean.
+
+## Publish
+- Feature branch. Not shipped.

package/upgrades/side-effects/codex-enforcement-hooks-p2.md

@@ -0,0 +1,36 @@
+# Side-Effects Review: Codex enforcement hooks — P2 (shell-gate works under Codex)
+
+## Change
+Closes the gap from §4.2d (as-wired-in-P1, Codex's native shell/exec/apply_patch would have passed UNGATED).
+1. **stdin shim** for the two arg-reading safety scripts so they read `tool_input.command` from Codex's stdin JSON when no positional arg is present (Claude's `$1` path unchanged):
+   - `dangerous-command-guard.sh` — both source copies kept consistent: `PostUpdateMigrator.getDangerousCommandGuard()` (always-overwrite/migration canonical) AND the inline duplicate in `init.ts`.
+   - `grounding-before-messaging.sh` — `PostUpdateMigrator.getGroundingBeforeMessaging()` (canonical, used by migration + init).
+2. **Mapping fix:** added `dangerous-command-guard.sh` to `installCodexHooks` `buildInstarCodexHookGroups()` PreToolUse group (coupled with the shim — mapping without shim would be the false-install trap).
+
+## Why
+`external-operation-gate.js` only gates `mcp__*` tools (exits 0 otherwise). Codex's destructive class is native `shell`/`exec`/`apply_patch`, which Claude gates via `dangerous-command-guard` on the Bash matcher. P1 omitted that gate from the Codex mapping, and the script couldn't read Codex's input anyway. Both fixed.
+
+## Over/under-block
+- The blocked catastrophic patterns are identical to Claude's (`rm -rf /`, `mkfs.`, `dd if=`, fork-bomb, etc.) — no Codex-specific over-block. Empty/garbage stdin → INPUT empty → no match → pass (no false-block); tested.
+
+## Signal vs Authority
+- `dangerous-command-guard` is a deterministic low-context guard on catastrophic patterns + a config safety-level gate; nuanced authority remains the server-side gate. Adding it to Codex mirrors Claude's posture — no new authority.
+
+## Near-silence
+- Blocks write the reason to **stderr** (the agent sees it), never a user message. No notification spam.
+
+## Migration parity
+- The scripts are always-overwritten on migration (getDangerousCommandGuard / getGroundingBeforeMessaging), so existing Codex agents get the shim on update; the mapping runs via refreshHooksAndSettings (P1b) on init + update.
+
+## Rollback
+- Revert the 3 shim insertions + the one mapping-line addition. No data migration.
+
+## Tests (real, no mocks)
+- Unit: 9 (incl. new assertion that dangerous-command-guard is in the Codex PreToolUse mapping).
+- **Integration (the proof): 5** — generates the REAL script via refreshHooksAndSettings, then: BLOCKS `rm -rf /` via Codex stdin/no-arg (exit 2), PASSES benign via stdin, still BLOCKS via Claude arg path (regression), no false-block on garbage stdin.
+
+## Sequencing
+- Satisfies the P2 hard-constraint (shell gating works under Codex) before any P6 deploy. Remaining: PermissionRequest exit-2 confirmation (P4), the live codey E2E (P5).
+
+## Publish
+- Feature branch. Not shipped.

package/upgrades/side-effects/codex-enforcement-hooks-p3.md

@@ -0,0 +1,25 @@
+# Side-Effects Review: Codex enforcement hooks — P3 (migration parity)
+
+## Change
+`PostUpdateMigrator.migrateHooks()` now calls `installCodexHooks(this.config.projectDir)` gated on `getEnabledFrameworks().includes('codex-cli')`, writing the per-project `.codex/hooks.json` for existing Codex agents on update. + import.
+
+## Why (Migration Parity Standard — non-negotiable)
+`installCodexHooks` ran ONLY from init's `refreshHooksAndSettings` (verified: that function's sole caller is `init.ts`). Existing agents update via `PostUpdateMigrator`, which wrote the gate SCRIPTS (with the P2 shim) but NOT the `.codex/hooks.json` registration. So without this, an existing Codex agent would get the updated guard scripts yet never the registration that makes Codex fire them — "works for new agents only" = broken. This closes it.
+
+## Scope
+- On update, codex-cli agents get `.codex/hooks.json` written/refreshed (idempotent; preserves user-added Codex hooks via the command-path ownership check). Claude-only agents unaffected (gated). The referenced gate scripts are written earlier in the same `migrateHooks` pass.
+
+## Idempotency
+- Tested: repeated migration yields exactly one instar PreToolUse group (no accumulation).
+
+## Signal vs Authority / Over-block
+- Unchanged from P1/P2 — this only ensures the registration reaches existing agents. No new authority, no new block patterns.
+
+## Rollback
+- Revert the `migrateHooks` codex block + the import. No data migration.
+
+## Tests
+- 3 migration tests: codex-cli agent → `.codex/hooks.json` written (with dangerous-command-guard in PreToolUse); claude-only → not written; idempotent across repeated migrations. Full P1–P3 sweep: 17 green. tsc + lint clean.
+
+## Publish
+- Feature branch. Not shipped.

package/upgrades/side-effects/codex-enforcement-hooks-p5c.md

@@ -0,0 +1,38 @@
+# Side-Effects Review: Codex enforcement hooks — P5c (the guard actually fires)
+
+## Change
+Two source fixes that make the Codex PreToolUse gate actually fire on the real Codex engine (previously it was registered but silently never invoked):
+
+1. **`src/core/installCodexHooks.ts`** — PreToolUse + PermissionRequest matcher changed `'*'` → `'.*'`. Codex treats the matcher as a regex against the tool name; a bare `*` is an invalid quantifier (no preceding atom) that matches nothing, so the gate never fired. `.*` matches all tool calls.
+2. **`src/core/PostUpdateMigrator.ts`** (dangerous-command-guard + grounding-before-messaging generators) and **`src/commands/init.ts`** (inline dangerous-command-guard) — the stdin shim now reads `tool_input.command OR tool_input.cmd`. Codex's shell tool is `exec_command` and delivers the command in `tool_input.cmd`; Claude uses `tool_input.command`. The prior shim read only `command`, so even when fired against Codex it saw an empty string.
+
+## Why
+Live verification (host codex-cli v0.133.0, interactive, hooks trusted) showed SessionStart + UserPromptSubmit hooks fired but the PreToolUse dangerous-command-guard did NOT — even trusted. Diagnosing from the Codex session rollout log revealed the matcher was an invalid regex AND the command field name differed. The earlier P5b conclusion ("root cause = hook-trust model") was a red herring for the non-firing symptom: trust gates whether hooks run at all, but with trust granted the guard still failed to fire for these two reasons.
+
+## Scope / blast radius
+- Codex agents only in effect: `.codex/hooks.json` is written solely for `enabledFrameworks.includes('codex-cli')`. Claude-only agents are unaffected (the guard scripts gained a stdin fallback that is inert when `$1` is supplied — Claude's existing arg path is unchanged and still tested).
+- With matcher `.*`, all three PreToolUse hooks now fire on every Codex tool call. Verified non-harmful: `external-operation-gate.js` exits 0 for any non-`mcp__*` tool (so `exec_command` passes straight through); `grounding-before-messaging.sh` only blocks when the command matches its messaging regex; `dangerous-command-guard.sh` only blocks catastrophic/risky patterns. No false-block surface introduced.
+- The `cmd`-field fallback is additive: `command or cmd or ''`. Claude payloads (`command`) are read first and unchanged.
+
+## Signal vs Authority / over-block
+- Unchanged authority model: hooks remain low-context triggers that exit-2 on deterministic catastrophic patterns or route to the server-side gate. No new block patterns added; only the delivery (matcher + field) was corrected so existing patterns reach the guard.
+
+## Migration parity
+- Both the init generator (`init.ts`) and the update generator (`PostUpdateMigrator.ts`) carry the shim fix, so new AND existing Codex agents get the working guard. The matcher fix lives in `installCodexHooks.ts`, called from both `refreshHooksAndSettings` (init) and `migrateHooks` (update, P3).
+
+## Live proof (evidence bar)
+Regenerated codey's hooks from freshly-built source via the real `refreshHooksAndSettings` path (no hand-patch, no debug instrumentation), launched real interactive Codex 0.133, instructed it to run `echo 'rm -rf /'` → Codex displayed `• PreToolUse hook (blocked) — BLOCKED: Catastrophic command detected: rm -rf /` and did not execute it. First confirmed firing of the Codex enforcement guard in the real engine. Before the fix the identical setup ran the command unblocked.
+
+## Tests
+- `tests/integration/codex-dangerous-command-block.test.ts` rewritten to the verified Codex shape (`tool_name: 'exec_command'`, `tool_input: { cmd, yield_time_ms }`) — would have failed before the `cmd` shim; plus a Claude-stdin (`command`) case so both field paths are covered.
+- `tests/unit/installCodexHooks.test.ts` asserts `PreToolUse`/`PermissionRequest` matcher === `'.*'` (regression guard against the invalid `*`).
+- Full codex suite: 19 green (7 + 3 + 3 + 6). tsc clean.
+
+## Rollback
+- Revert the matcher to its prior value and drop the `cmd` fallback in the three generators. No data migration. (Rollback re-breaks Codex enforcement — not advised.)
+
+## Follow-on (tracked, NOT deferred-broken)
+- **P6a managed hooks**: trust remains a separate concern — even `--dangerously-bypass-hook-trust` still pops an interactive trust prompt + a model-upsell prompt (would freeze unattended autonomy), and a trust-gated hook lets the agent decline ("continue without trusting"), so it can disable its own guard. Managed hooks (run-by-policy, agent-can't-disable) fix both. Genuine design fork → paused for Justin's input. Does not block this correctness fix shipping.
+
+## Publish
+- Feature branch `echo/codex-enforcement-hooks`. Targets release v1.2.57 once P6 (awareness + crossreview) completes.