instar 1.2.65 → 1.2.67

package/dist/core/codexCapabilities.d.ts

@@ -0,0 +1,31 @@
+/**
+ * codexCapabilities — runtime feature detection for the Codex CLI.
+ *
+ * Codex's flag surface changes across versions, and instar agents run whatever
+ * codex the operator has installed (0.130 → 0.133+ all observed). Rather than
+ * track a version matrix, we probe the binary's `--help` once per binary path
+ * and cache the answer. Builders gate version-specific flags on these probes so
+ * an older codex never receives a flag it would reject (which would fail the
+ * whole launch).
+ */
+/**
+ * Whether `<binaryPath>` accepts `--dangerously-bypass-hook-trust`.
+ *
+ * The flag was added in codex 0.133 ("Run enabled hooks without requiring
+ * persisted hook trust for this invocation") and is ABSENT in 0.131/0.130.
+ * instar launches codex with this flag so its OWN safety hooks
+ * (installCodexHooks) run automatically with no interactive "trust these hooks?"
+ * prompt — which would otherwise freeze an unattended/autonomous session. It is
+ * safe-by-construction here: instar both writes the hooks and owns the launch
+ * command, so there is no untrusted third-party hook to guard against, and the
+ * agent cannot strip a flag from a launch it doesn't construct.
+ *
+ * Fails closed: any probe error (missing binary, timeout, non-zero exit) returns
+ * false, so an undetectable/older codex simply omits the flag. The hooks still
+ * block dangerous actions in that case — they just sit behind codex's interactive
+ * trust prompt rather than running unprompted.
+ */
+export declare function codexSupportsHookTrustBypass(binaryPath: string): boolean;
+/** Test-only: clear the memoization cache so a probe re-runs. */
+export declare function __resetCodexCapabilityCache(): void;
+//# sourceMappingURL=codexCapabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codexCapabilities.d.ts","sourceRoot":"","sources":["../../src/core/codexCapabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAiBxE;AAED,iEAAiE;AACjE,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/core/codexCapabilities.js

@@ -0,0 +1,56 @@
+/**
+ * codexCapabilities — runtime feature detection for the Codex CLI.
+ *
+ * Codex's flag surface changes across versions, and instar agents run whatever
+ * codex the operator has installed (0.130 → 0.133+ all observed). Rather than
+ * track a version matrix, we probe the binary's `--help` once per binary path
+ * and cache the answer. Builders gate version-specific flags on these probes so
+ * an older codex never receives a flag it would reject (which would fail the
+ * whole launch).
+ */
+import { execFileSync } from 'node:child_process';
+/** Memoized per binaryPath — `codex --help` is invoked at most once per path per process. */
+const hookTrustBypassCache = new Map();
+/**
+ * Whether `<binaryPath>` accepts `--dangerously-bypass-hook-trust`.
+ *
+ * The flag was added in codex 0.133 ("Run enabled hooks without requiring
+ * persisted hook trust for this invocation") and is ABSENT in 0.131/0.130.
+ * instar launches codex with this flag so its OWN safety hooks
+ * (installCodexHooks) run automatically with no interactive "trust these hooks?"
+ * prompt — which would otherwise freeze an unattended/autonomous session. It is
+ * safe-by-construction here: instar both writes the hooks and owns the launch
+ * command, so there is no untrusted third-party hook to guard against, and the
+ * agent cannot strip a flag from a launch it doesn't construct.
+ *
+ * Fails closed: any probe error (missing binary, timeout, non-zero exit) returns
+ * false, so an undetectable/older codex simply omits the flag. The hooks still
+ * block dangerous actions in that case — they just sit behind codex's interactive
+ * trust prompt rather than running unprompted.
+ */
+export function codexSupportsHookTrustBypass(binaryPath) {
+    if (!binaryPath)
+        return false;
+    const cached = hookTrustBypassCache.get(binaryPath);
+    if (cached !== undefined)
+        return cached;
+    let supported = false;
+    try {
+        const help = execFileSync(binaryPath, ['--help'], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        supported = help.includes('--dangerously-bypass-hook-trust');
+    }
+    catch {
+        supported = false;
+    }
+    hookTrustBypassCache.set(binaryPath, supported);
+    return supported;
+}
+/** Test-only: clear the memoization cache so a probe re-runs. */
+export function __resetCodexCapabilityCache() {
+    hookTrustBypassCache.clear();
+}
+//# sourceMappingURL=codexCapabilities.js.map

package/dist/core/codexCapabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codexCapabilities.js","sourceRoot":"","sources":["../../src/core/codexCapabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,6FAA6F;AAC7F,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,4BAA4B,CAAC,UAAkB;IAC7D,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9B,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,EAAE;YAChD,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC;QACH,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,iCAAiC,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,KAAK,CAAC;IACpB,CAAC;IACD,oBAAoB,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAChD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,2BAA2B;IACzC,oBAAoB,CAAC,KAAK,EAAE,CAAC;AAC/B,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"frameworkSessionLaunch.d.ts","sourceRoot":"","sources":["../../src/core/frameworkSessionLaunch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,qBAAqB,EAChC,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CA6BpB;AAmBD,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IAC1E;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAuGD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,wBAAwB,GAChC,qBAAqB,CAMvB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,YAAY,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC7C,GAAG,qBAAqB,CAExB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IAC1E;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3C;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzD;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAoFD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,qBAAqB,GAC7B,kBAAkB,CAMpB"}
+{"version":3,"file":"frameworkSessionLaunch.d.ts","sourceRoot":"","sources":["../../src/core/frameworkSessionLaunch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAG9E;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,qBAAqB,EAChC,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CA6BpB;AAmBD,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IAC1E;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AA8GD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,wBAAwB,GAChC,qBAAqB,CAMvB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,YAAY,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC7C,GAAG,qBAAqB,CAExB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IAC1E;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3C;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzD;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAyFD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,qBAAqB,GAC7B,kBAAkB,CAMpB"}

package/dist/core/frameworkSessionLaunch.js

@@ -12,6 +12,7 @@
  * `BUILDERS`. The exhaustiveness check in `buildInteractiveLaunch`
  * forces a compile error if a case is missed.
  */
+import { codexSupportsHookTrustBypass } from './codexCapabilities.js';
 /**
  * Map a generic tier or framework-specific name to the concrete model
  * string that should be passed to the framework's CLI. Pass-through for
@@ -155,6 +156,13 @@ const codexCliBuilder = (options) => {
     else {
         argv.push('--dangerously-bypass-approvals-and-sandbox');
     }
+    // Run instar's own safety hooks (installCodexHooks) without the interactive
+    // "trust these hooks?" prompt that would otherwise freeze an unattended
+    // session. Gated on a capability probe — codex <0.133 lacks the flag and would
+    // reject it. Safe-by-construction: instar writes the hooks and owns the launch.
+    if (codexSupportsHookTrustBypass(options.binaryPath)) {
+        argv.push('--dangerously-bypass-hook-trust');
+    }
     argv.push(...codexThreadlineMcpFlags(options.codexThreadlineMcp));
     return {
         argv,
@@ -255,6 +263,11 @@ const codexCliHeadlessBuilder = (options) => {
     else {
         argv.push('-s', 'workspace-write');
     }
+    // Run instar's own safety hooks without a persisted-trust requirement (same
+    // rationale as the interactive builder; capability-gated for codex <0.133).
+    if (codexSupportsHookTrustBypass(options.binaryPath)) {
+        argv.push('--dangerously-bypass-hook-trust');
+    }
     // -c overrides must precede the positional prompt in `codex exec`.
     argv.push(...codexThreadlineMcpFlags(options.codexThreadlineMcp));
     argv.push('-m', model, options.prompt);

package/dist/core/frameworkSessionLaunch.js.map

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

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.67",
   "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-25T02:30:22.480Z",
+  "instarVersion": "1.2.67",
   "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/1.2.67.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — Codex safety hooks run unprompted in autonomous sessions
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**Codex (codex-cli) agents now run instar's safety hooks without the interactive
+"trust these hooks?" prompt that would otherwise freeze an unattended session.**
+
+Codex requires a one-time review/trust of any command hook before it runs. In an
+interactive session that prompt blocks until answered — and it even offers a
+"continue without trusting (hooks won't run)" option, so an agent could decline its
+own guards. instar now launches codex with `--dangerously-bypass-hook-trust` (added
+in codex 0.133), which runs the already-vetted instar hooks with no prompt.
+
+This is safe-by-construction: instar both writes the hooks (`installCodexHooks`) and
+owns the launch command, so there's no untrusted third-party hook to guard against,
+and the agent can't strip a flag from a launch it doesn't construct. It's a per-agent
+launch setting — it touches nothing system-wide and does not affect the operator's own
+personal codex sessions (those still prompt normally).
+
+The flag is **capability-gated**: instar probes `codex --help` once per binary and only
+adds the flag when present. On codex <0.133 (which lacks the flag and would reject it),
+it's omitted and behaviour degrades to the safe-by-blocking trust-prompt path.
+
+## What to Tell Your User
+
+If I'm running on Codex without you watching, my safety guard now kicks in on its own
+instead of stopping to ask you "do you trust this guard?" first — a question that would
+have frozen me mid-task, and that technically let me wave my own guard off. Now the
+guard just runs. This only applies to how I launch Codex; when you use Codex yourself it
+behaves exactly as before.
+
+## Summary of New Capabilities
+
+No new user-facing capabilities — this completes the Codex enforcement-hook layer so its
+guards work in unattended/autonomous sessions, not just interactive ones where a human can
+answer the trust prompt. Internal: `codexCapabilities.codexSupportsHookTrustBypass()`
+(memoized feature probe) + both codex launch builders append the flag when supported.
+
+## Evidence
+
+**Live reproduction (real codex 0.133, no trust ever granted).** Launched interactive
+codex with `--dangerously-bypass-hook-trust` and a hook whose trust hash had been
+invalidated:
+
+- Codex launched **straight to the prompt — no "trust these hooks?" review** (banner:
+  `⚠ Enabled hooks may run without review for this invocation`).
+- Told it to run `echo 'rm -rf /'` — the guard fired and blocked it; codex itself reported
+  it was blocked for the catastrophic `rm -rf /` pattern, and the guard's debug trace
+  logged the fire. Before this, the same setup either blocked on the trust prompt or ran
+  unguarded.
+
+Also verified instar's builder emits the flag for the real codex binary, and the
+capability probe correctly omits it for a binary whose `--help` lacks it. Unit coverage:
+`codexCapabilities` (5) + `frameworkSessionLaunch` (+4). `tsc` clean.