@danielblomma/cortex-mcp 2.0.12 → 2.0.14

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

package/scaffold/mcp/src/cli/govern.ts

@@ -8,6 +8,7 @@ import {
   renameSync,
   unlinkSync,
   rmSync,
+  chmodSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
 import { platform, hostname } from "node:os";
@@ -58,6 +59,30 @@ export type FetchedConfig = {
   frameworks: Array<{ id: string; version: string }>;
 };
 
+type CodexHookCommand = {
+  type: "command";
+  command: string;
+  timeout?: number;
+  statusMessage?: string;
+};
+
+type CodexHookHandler = {
+  matcher?: string;
+  hooks: CodexHookCommand[];
+};
+
+type CodexHookHandlersByEvent = Record<string, CodexHookHandler[]>;
+
+const SUPPORTED_CODEX_HOOK_EVENTS = new Set([
+  "SessionStart",
+  "SessionEnd",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "UserPromptSubmit",
+  "Stop",
+]);
+
 export function getManagedSettingsPath(cli: GovernCli, os: NodeJS.Platform): string {
   const path = DEFAULT_PATHS[cli]?.[os];
   if (!path) {
@@ -93,11 +118,159 @@ function tomlArray(values: unknown[]): string {
   return `[${items.join(", ")}]`;
 }
 
-export function buildCodexRequirementsToml(config: FetchedConfig): string {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeCodexHookCommand(raw: unknown): CodexHookCommand | null {
+  if (typeof raw === "string" && raw.trim()) {
+    return { type: "command", command: raw.trim() };
+  }
+  if (!isRecord(raw)) {
+    return null;
+  }
+  const command = typeof raw.command === "string" ? raw.command.trim() : "";
+  if (!command) {
+    return null;
+  }
+  const timeout = typeof raw.timeout === "number" && Number.isFinite(raw.timeout)
+    ? Math.trunc(raw.timeout)
+    : undefined;
+  const statusMessage = typeof raw.statusMessage === "string" && raw.statusMessage.trim()
+    ? raw.statusMessage
+    : undefined;
+  return {
+    type: "command",
+    command,
+    ...(timeout !== undefined ? { timeout } : {}),
+    ...(statusMessage ? { statusMessage } : {}),
+  };
+}
+
+function normalizeCodexHookCommands(raw: unknown): CodexHookCommand[] {
+  if (Array.isArray(raw)) {
+    return raw
+      .map((entry) => normalizeCodexHookCommand(entry))
+      .filter((entry): entry is CodexHookCommand => entry !== null);
+  }
+  const single = normalizeCodexHookCommand(raw);
+  return single ? [single] : [];
+}
+
+function normalizeCodexHookHandlers(raw: unknown): CodexHookHandler[] {
+  const entries = Array.isArray(raw) ? raw : [raw];
+  const normalized: CodexHookHandler[] = [];
+
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      normalized.push({ hooks: [{ type: "command", command: entry }] });
+      continue;
+    }
+    if (!isRecord(entry)) {
+      continue;
+    }
+
+    const matcher = typeof entry.matcher === "string" && entry.matcher.trim()
+      ? entry.matcher
+      : undefined;
+
+    if (Array.isArray(entry.hooks) || typeof entry.hooks === "string" || isRecord(entry.hooks)) {
+      const hooks = normalizeCodexHookCommands(entry.hooks);
+      if (hooks.length > 0) {
+        normalized.push({ ...(matcher ? { matcher } : {}), hooks });
+      }
+      continue;
+    }
+
+    const shorthand = normalizeCodexHookCommand(entry);
+    if (shorthand) {
+      normalized.push({
+        ...(matcher ? { matcher } : {}),
+        hooks: [shorthand],
+      });
+    }
+  }
+
+  return normalized;
+}
+
+function normalizeCodexHooks(managedSettings: Record<string, unknown>): CodexHookHandlersByEvent {
+  const hooksRoot = managedSettings.hooks;
+  if (!isRecord(hooksRoot)) {
+    return {};
+  }
+
+  const normalized: CodexHookHandlersByEvent = {};
+  for (const [eventName, rawHandlers] of Object.entries(hooksRoot)) {
+    if (!SUPPORTED_CODEX_HOOK_EVENTS.has(eventName)) {
+      continue;
+    }
+    const handlers = normalizeCodexHookHandlers(rawHandlers);
+    if (handlers.length > 0) {
+      normalized[eventName] = handlers;
+    }
+  }
+  return normalized;
+}
+
+function codexManagedHooksDir(requirementsPath: string): string {
+  return join(dirname(requirementsPath), "hooks");
+}
+
+function shellQuotedCommandPath(filePath: string): string {
+  return `"${filePath.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function managedCodexHookWrapperContent(hookName: string): string {
+  return [
+    "#!/bin/sh",
+    "set -eu",
+    'CORTEX="${CORTEX_BIN:-cortex}"',
+    `exec "$CORTEX" hook ${hookName} "$@"`,
+    "",
+  ].join("\n");
+}
+
+function materializeCodexManagedHooks(
+  requirementsPath: string,
+  managedSettings: Record<string, unknown>,
+): { managedHookDir: string | null; hooksByEvent: CodexHookHandlersByEvent } {
+  const hooksByEvent = normalizeCodexHooks(managedSettings);
+  const eventNames = Object.keys(hooksByEvent);
+  if (eventNames.length === 0) {
+    return { managedHookDir: null, hooksByEvent };
+  }
+
+  const managedHookDir = codexManagedHooksDir(requirementsPath);
+  mkdirSync(managedHookDir, { recursive: true });
+
+  for (const handlers of Object.values(hooksByEvent)) {
+    for (const handler of handlers) {
+      for (const hook of handler.hooks) {
+        const match = hook.command.match(/^cortex hook ([a-z0-9-]+)$/);
+        if (!match) {
+          continue;
+        }
+        const hookName = match[1];
+        const wrapperPath = join(managedHookDir, `${hookName}.sh`);
+        writeAtomic(wrapperPath, managedCodexHookWrapperContent(hookName), 0o755);
+        hook.command = shellQuotedCommandPath(wrapperPath);
+      }
+    }
+  }
+
+  return { managedHookDir, hooksByEvent };
+}
+
+export function buildCodexRequirementsToml(
+  config: FetchedConfig,
+  options: { managedHookDir?: string | null; hooksByEvent?: CodexHookHandlersByEvent } = {},
+): string {
   const denyRead = config.deny_rules
     .map((r) => r.pattern)
     .filter((p) => /^(Edit|Read|Write)\(/.test(p))
     .map((p) => p.replace(/^[A-Za-z]+\(/, "").replace(/\)$/, ""));
+  const hooksByEvent = options.hooksByEvent ?? normalizeCodexHooks(config.managed_settings);
   const lines: string[] = [
     "# Cortex govern — codex requirements (Phase 3 of PLAN.govern-mode.md).",
     "# Admin-enforced upper bounds. Users cannot weaken these via ~/.codex/config.toml.",
@@ -112,13 +285,48 @@ export function buildCodexRequirementsToml(config: FetchedConfig): string {
     "codex_hooks = true",
     "",
   ];
+
+  const eventNames = Object.keys(hooksByEvent);
+  if (eventNames.length > 0) {
+    lines.push("[hooks]");
+    if (options.managedHookDir) {
+      lines.push(`managed_dir = ${tomlString(options.managedHookDir)}`);
+    }
+    lines.push("");
+
+    for (const eventName of eventNames) {
+      for (const handler of hooksByEvent[eventName]) {
+        lines.push(`[[hooks.${eventName}]]`);
+        if (handler.matcher) {
+          lines.push(`matcher = ${tomlString(handler.matcher)}`);
+        }
+        for (const hook of handler.hooks) {
+          lines.push("");
+          lines.push(`[[hooks.${eventName}.hooks]]`);
+          lines.push(`type = ${tomlString(hook.type)}`);
+          lines.push(`command = ${tomlString(hook.command)}`);
+          if (hook.timeout !== undefined) {
+            lines.push(`timeout = ${hook.timeout}`);
+          }
+          if (hook.statusMessage) {
+            lines.push(`statusMessage = ${tomlString(hook.statusMessage)}`);
+          }
+        }
+        lines.push("");
+      }
+    }
+  }
+
   return lines.join("\n");
 }
 
-function writeAtomic(filePath: string, content: string): void {
+function writeAtomic(filePath: string, content: string, mode?: number): void {
   mkdirSync(dirname(filePath), { recursive: true });
   const tmp = `${filePath}.tmp.${randomUUID()}`;
   writeFileSync(tmp, content, "utf8");
+  if (mode !== undefined) {
+    chmodSync(tmp, mode);
+  }
   renameSync(tmp, filePath);
 }
 
@@ -303,10 +511,15 @@ export async function runGovernInstall(
       };
     }
 
+    const codexManagedHooks =
+      cli === "codex"
+        ? materializeCodexManagedHooks(path, merged.managed_settings)
+        : { managedHookDir: null, hooksByEvent: {} };
+
     const content =
       cli === "claude"
         ? JSON.stringify(merged.managed_settings, null, 2) + "\n"
-        : buildCodexRequirementsToml(merged);
+        : buildCodexRequirementsToml(merged, codexManagedHooks);
 
     try {
       writeAtomic(path, content);

package/scaffold/mcp/src/daemon/protocol.ts

@@ -82,6 +82,8 @@ export type HeartbeatPayload = {
   cli: "claude" | "codex" | "copilot";
   hook:
     | "PreToolUse"
+    | "PostToolUse"
+    | "PermissionRequest"
     | "UserPromptSubmit"
     | "SessionStart"
     | "SessionEnd"

package/scaffold/mcp/src/daemon/skill-sync-checker.ts

@@ -46,6 +46,7 @@ type ManifestEntry = {
 };
 
 type LocalSkillRecord = {
+  cli: SkillCli;
   scope: string;
   updated_at: string;
   path: string;
@@ -88,7 +89,29 @@ function readState(): LocalSkillsState {
   if (!existsSync(path)) return { skills: {} };
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8")) as LocalSkillsState;
-    return { skills: parsed.skills ?? {}, last_synced_at: parsed.last_synced_at };
+    const normalizedSkills: Record<string, LocalSkillRecord> = {};
+    for (const [key, record] of Object.entries(parsed.skills ?? {})) {
+      if (!record || typeof record !== "object") continue;
+      const inferredCli =
+        record.path?.includes("/.codex/skills/")
+          ? "codex"
+          : "claude";
+      const cli =
+        record.cli === "codex" || record.cli === "claude"
+          ? record.cli
+          : inferredCli;
+      const normalizedKey = key.includes(":") ? key : `${cli}:${key}`;
+      normalizedSkills[normalizedKey] = {
+        cli,
+        scope: String(record.scope ?? "global"),
+        updated_at: String(record.updated_at ?? ""),
+        path: String(record.path ?? ""),
+      };
+    }
+    return {
+      skills: normalizedSkills,
+      last_synced_at: parsed.last_synced_at,
+    };
   } catch {
     return { skills: {} };
   }
@@ -103,19 +126,22 @@ function writeState(state: LocalSkillsState): void {
 }
 
 /**
- * Resolve the on-disk SKILL.md path for a skill. Global skills live under
- * ~/.claude/skills (Claude Code's user-scope skills directory); cli:codex
- * skills live under ~/.codex/skills. cli:claude scope is treated as
- * Claude-only and lands in ~/.claude/skills.
+ * Resolve the on-disk SKILL.md path for a skill install target. Global
+ * skills are installed once per CLI, so the destination root depends on the
+ * active sync target rather than just the stored scope.
  */
-function skillFilePath(scope: string, name: string): string {
+function skillFilePath(cli: SkillCli, name: string): string {
   const root =
-    scope === "cli:codex"
+    cli === "codex"
       ? join(homedir(), ".codex", "skills")
       : join(homedir(), ".claude", "skills");
   return join(root, name, "SKILL.md");
 }
 
+function stateSkillKey(cli: SkillCli, name: string): string {
+  return `${cli}:${name}`;
+}
+
 function shouldSyncForCli(scope: string, cli: SkillCli): boolean {
   if (scope === "global") return true;
   return scope === `cli:${cli}`;
@@ -222,7 +248,8 @@ export async function runSkillSyncForCli(
 
   // Detect adds + changes
   for (const entry of relevantManifest) {
-    const local = state.skills[entry.name];
+    const skillKey = stateSkillKey(cli, entry.name);
+    const local = state.skills[skillKey];
     const isNew = !local;
     const isChanged =
       Boolean(local) &&
@@ -243,7 +270,7 @@ export async function runSkillSyncForCli(
       };
     }
 
-    const path = skillFilePath(entry.scope, entry.name);
+    const path = skillFilePath(cli, entry.name);
     try {
       writeSkillFile(path, body);
     } catch (err) {
@@ -257,7 +284,8 @@ export async function runSkillSyncForCli(
       };
     }
 
-    state.skills[entry.name] = {
+    state.skills[skillKey] = {
+      cli,
       scope: entry.scope,
       updated_at: entry.updated_at,
       path,
@@ -269,7 +297,10 @@ export async function runSkillSyncForCli(
   // dropped (or disabled). We only consider state entries whose scope
   // matches this cli, so we don't accidentally remove the other CLI's
   // skills when running a per-cli tick.
-  for (const [name, record] of Object.entries(state.skills)) {
+  for (const [skillKey, record] of Object.entries(state.skills)) {
+    if (record.cli !== cli) continue;
+    const [, name] = skillKey.split(":", 2);
+    if (!name) continue;
     if (!shouldSyncForCli(record.scope, cli)) continue;
     if (remoteByName.has(name)) continue;
     try {
@@ -277,7 +308,7 @@ export async function runSkillSyncForCli(
     } catch {
       // best-effort; if unlink fails the next tick will retry
     }
-    delete state.skills[name];
+    delete state.skills[skillKey];
     removed.push(name);
   }
 

package/scaffold/mcp/src/hooks/permission-request.ts

@@ -0,0 +1,126 @@
+import { call } from "../daemon/client.js";
+import type {
+  AuditLogPayload,
+  AuditLogResult,
+  PolicyCheckPayload,
+  PolicyCheckResult,
+} from "../daemon/protocol.js";
+import { evaluateToolCall } from "../core/workflow/enforcement.js";
+import {
+  ensureDaemon,
+  isEnterpriseProject,
+  normalizeToolCall,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+  sendHeartbeat,
+  serializeForAudit,
+  getStringField,
+} from "./shared.js";
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw);
+  const normalized = normalizeToolCall(input);
+  const enterprise = isEnterpriseProject(normalized.cwd);
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  if (normalized.sessionId) {
+    void sendHeartbeat({
+      cli: "codex",
+      hook: "PermissionRequest",
+      session_id: normalized.sessionId,
+      cwd: normalized.cwd,
+    });
+  }
+
+  const activeTaskId = process.env.CORTEX_ACTIVE_TASK_ID?.trim();
+  if (activeTaskId) {
+    try {
+      const verdict = evaluateToolCall({
+        cwd: normalized.cwd,
+        taskId: activeTaskId,
+        call: { toolName: normalized.toolName, toolInput: normalized.toolInput },
+      });
+      if (!verdict.allowed) {
+        process.stderr.write(`[cortex] Permission denied by workflow: ${verdict.reason}\n`);
+        process.exit(2);
+      }
+    } catch (err) {
+      process.stderr.write(
+        `[cortex] permission capability evaluation failed (${
+          err instanceof Error ? err.message : String(err)
+        }); deferring to policy.check\n`,
+      );
+    }
+  }
+
+  const policyPayload: PolicyCheckPayload = {
+    tool: normalized.toolName,
+    cwd: normalized.cwd,
+    input: normalized.toolInput,
+  };
+  const policyRes = await call<PolicyCheckResult>("policy.check", policyPayload, {
+    timeoutMs: 5000,
+  });
+
+  const approvalReason = getStringField(input, ["reason", "permission_reason", "permissionReason"]);
+  const auditPayload: AuditLogPayload = {
+    cwd: normalized.cwd,
+    entry: {
+      timestamp: new Date().toISOString(),
+      tool: "permission.request",
+      input: {
+        tool_name: normalized.toolName,
+        command: normalized.toolInput.command ?? null,
+        prefix_rule: normalized.toolInput.prefix_rule ?? null,
+        sandbox_permissions: normalized.toolInput.sandbox_permissions ?? null,
+      },
+      event_type: "session",
+      evidence_level: "diagnostic",
+      resource_type: "approval_request",
+      session_id: normalized.sessionId,
+      metadata: {
+        tool_name: normalized.toolName,
+        reason: approvalReason ?? null,
+        command_preview: serializeForAudit(normalized.toolInput.command),
+      },
+      ...(policyRes.ok && !policyRes.result.allow
+        ? {
+            status: "error" as const,
+          }
+        : {}),
+    },
+  };
+  void call<AuditLogResult>("audit.log", auditPayload, { timeoutMs: 3000 });
+
+  if (policyRes.ok) {
+    if (policyRes.result.allow) {
+      process.exit(0);
+    }
+    process.stderr.write(
+      `[cortex] Permission denied by policy: ${policyRes.result.reason ?? "unspecified"}\n`,
+    );
+    process.exit(2);
+  }
+
+  if (enterprise) {
+    process.stderr.write(
+      `[cortex] Enterprise daemon unreachable (${policyRes.error}). Denying permission per fail-closed policy.\n`,
+    );
+    process.exit(2);
+  }
+
+  process.stderr.write(
+    `[cortex] Daemon unreachable (${policyRes.error}). Allowing permission request (community mode).\n`,
+  );
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `[cortex permission-request] error: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(0);
+});

package/scaffold/mcp/src/hooks/post-tool-use.ts

@@ -0,0 +1,156 @@
+import { call } from "../daemon/client.js";
+import type {
+  AuditLogPayload,
+  AuditLogResult,
+  PolicyCheckPayload,
+  PolicyCheckResult,
+} from "../daemon/protocol.js";
+import { evaluateToolCall } from "../core/workflow/enforcement.js";
+import {
+  ensureDaemon,
+  getBooleanField,
+  getNumberField,
+  getRecordField,
+  getStringField,
+  isEnterpriseProject,
+  normalizeToolCall,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+  sendHeartbeat,
+  serializeForAudit,
+} from "./shared.js";
+
+function extractToolOutput(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const record =
+    getRecordField(input, ["tool_output", "toolOutput", "tool_result", "toolResult", "result"]) ??
+    {};
+
+  const outputText = getStringField(input, ["output", "stdout", "stderr"]);
+  if (outputText && record.output === undefined) {
+    record.output = outputText;
+  }
+
+  const success = getBooleanField(input, ["success"]);
+  if (success !== undefined && record.success === undefined) {
+    record.success = success;
+  }
+
+  const exitCode = getNumberField(input, ["exit_code", "exitCode"]);
+  if (exitCode !== undefined && record.exit_code === undefined) {
+    record.exit_code = exitCode;
+  }
+
+  return record;
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw);
+  const normalized = normalizeToolCall(input);
+  const enterprise = isEnterpriseProject(normalized.cwd);
+  const toolOutput = extractToolOutput(input);
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  if (normalized.sessionId) {
+    void sendHeartbeat({
+      cli: "codex",
+      hook: "PostToolUse",
+      session_id: normalized.sessionId,
+      cwd: normalized.cwd,
+    });
+  }
+
+  const success =
+    getBooleanField(input, ["success"]) ??
+    (typeof toolOutput.exit_code === "number" ? toolOutput.exit_code === 0 : undefined);
+  const durationMs = getNumberField(input, ["duration_ms", "durationMs"]);
+
+  const auditPayload: AuditLogPayload = {
+    cwd: normalized.cwd,
+    entry: {
+      timestamp: new Date().toISOString(),
+      tool: normalized.toolName,
+      input: normalized.toolInput,
+      event_type: "tool",
+      evidence_level: "diagnostic",
+      resource_type: "tool_result",
+      session_id: normalized.sessionId,
+      ...(durationMs !== undefined ? { duration_ms: durationMs } : {}),
+      ...(success !== undefined
+        ? { status: success ? ("success" as const) : ("error" as const) }
+        : {}),
+      metadata: {
+        hook: "PostToolUse",
+        tool_output_preview: serializeForAudit(toolOutput),
+      },
+    },
+  };
+  void call<AuditLogResult>("audit.log", auditPayload, { timeoutMs: 3000 });
+
+  const activeTaskId = process.env.CORTEX_ACTIVE_TASK_ID?.trim();
+  if (activeTaskId) {
+    try {
+      const verdict = evaluateToolCall({
+        cwd: normalized.cwd,
+        taskId: activeTaskId,
+        call: { toolName: normalized.toolName, toolInput: normalized.toolInput },
+      });
+      if (!verdict.allowed) {
+        process.stderr.write(`[cortex] Blocked after tool execution: ${verdict.reason}\n`);
+        process.exit(2);
+      }
+    } catch (err) {
+      process.stderr.write(
+        `[cortex] post-tool capability evaluation failed (${
+          err instanceof Error ? err.message : String(err)
+        }); deferring to policy.check\n`,
+      );
+    }
+  }
+
+  if (Object.keys(toolOutput).length === 0) {
+    process.exit(0);
+  }
+
+  const policyPayload: PolicyCheckPayload = {
+    tool: `${normalized.toolName}.result`,
+    cwd: normalized.cwd,
+    input: toolOutput,
+  };
+  const policyRes = await call<PolicyCheckResult>("policy.check", policyPayload, {
+    timeoutMs: 5000,
+  });
+
+  if (policyRes.ok) {
+    if (policyRes.result.allow) {
+      process.exit(0);
+    }
+    process.stderr.write(
+      `[cortex] Blocked after tool execution by policy: ${policyRes.result.reason ?? "unspecified"}\n`,
+    );
+    process.exit(2);
+  }
+
+  if (enterprise) {
+    process.stderr.write(
+      `[cortex] Enterprise daemon unreachable (${policyRes.error}). Blocking continuation per fail-closed policy.\n`,
+    );
+    process.exit(2);
+  }
+
+  process.stderr.write(
+    `[cortex] Daemon unreachable (${policyRes.error}). Allowing continuation (community mode).\n`,
+  );
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `[cortex post-tool-use] error: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(0);
+});

package/scaffold/mcp/src/hooks/shared.ts

@@ -20,6 +20,13 @@ export type HookInput = {
   [key: string]: unknown;
 };
 
+export type NormalizedToolCall = {
+  cwd: string;
+  sessionId?: string;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+};
+
 export async function readStdin(): Promise<string> {
   return new Promise((resolve) => {
     let data = "";
@@ -42,6 +49,106 @@ export function parseInput(raw: string): HookInput {
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function getStringField(
+  input: Record<string, unknown>,
+  keys: string[],
+): string | undefined {
+  for (const key of keys) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return undefined;
+}
+
+export function getNumberField(
+  input: Record<string, unknown>,
+  keys: string[],
+): number | undefined {
+  for (const key of keys) {
+    const value = input[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+export function getBooleanField(
+  input: Record<string, unknown>,
+  keys: string[],
+): boolean | undefined {
+  for (const key of keys) {
+    const value = input[key];
+    if (typeof value === "boolean") return value;
+  }
+  return undefined;
+}
+
+export function getRecordField(
+  input: Record<string, unknown>,
+  keys: string[],
+): Record<string, unknown> | undefined {
+  for (const key of keys) {
+    const value = input[key];
+    if (isRecord(value)) return value;
+  }
+  return undefined;
+}
+
+export function normalizeToolInput(value: unknown): Record<string, unknown> {
+  if (isRecord(value)) return value;
+  return {};
+}
+
+export function normalizeToolCall(input: HookInput): NormalizedToolCall {
+  const cwd = getStringField(input, ["cwd", "working_directory", "workingDirectory"]) ?? process.cwd();
+  const sessionId = getStringField(input, ["session_id", "sessionId"]);
+  const toolName =
+    getStringField(input, ["tool_name", "toolName", "tool"]) ??
+    (typeof input.command === "string" ? "Bash" : "unknown");
+  const toolInput =
+    getRecordField(input, ["tool_input", "toolInput", "tool_args", "toolArgs", "input", "args"]) ??
+    {};
+
+  if (typeof input.command === "string" && toolInput.command === undefined) {
+    toolInput.command = input.command;
+  }
+  if (Array.isArray(input.prefix_rule) && toolInput.prefix_rule === undefined) {
+    toolInput.prefix_rule = input.prefix_rule;
+  }
+  if (
+    typeof input.sandbox_permissions === "string" &&
+    toolInput.sandbox_permissions === undefined
+  ) {
+    toolInput.sandbox_permissions = input.sandbox_permissions;
+  }
+
+  return {
+    cwd,
+    ...(sessionId ? { sessionId } : {}),
+    toolName,
+    toolInput,
+  };
+}
+
+export function serializeForAudit(value: unknown, maxLen = 1200): string | undefined {
+  if (value === undefined) return undefined;
+  const raw =
+    typeof value === "string"
+      ? value
+      : (() => {
+          try {
+            return JSON.stringify(value);
+          } catch {
+            return String(value);
+          }
+        })();
+  if (!raw) return undefined;
+  return raw.length <= maxLen ? raw : `${raw.slice(0, maxLen)}...`;
+}
+
 /**
  * Detect whether the current project is running enterprise mode.
  * Lightweight YAML peek — we don't want to load the full config parser

package/scaffold/mcp/tests/govern-install.test.mjs

@@ -109,7 +109,39 @@ test("install --cli codex writes requirements.toml with sandbox bounds", async (
     "GET /api/v1/govern/config": (req, res) => {
       const config = {
         cli: "codex",
-        managed_settings: {},
+        managed_settings: {
+          hooks: {
+            PreToolUse: [
+              {
+                matcher: "Edit|Write|Bash|MultiEdit",
+                command: "cortex hook pre-tool-use",
+                statusMessage: "Checking Cortex policy",
+                timeout: 30,
+              },
+            ],
+            PostToolUse: [
+              {
+                command: "cortex hook post-tool-use",
+              },
+            ],
+            PermissionRequest: [
+              {
+                command: "cortex hook permission-request",
+              },
+            ],
+            SessionStart: [
+              {
+                matcher: "startup|resume|clear",
+                command: "cortex hook session-start",
+              },
+            ],
+            SessionEnd: [
+              {
+                command: "cortex hook session-end",
+              },
+            ],
+          },
+        },
         deny_rules: [
           { pattern: "Edit(~/.codex/config.toml)", source_frameworks: ["iso27001"] },
         ],
@@ -124,7 +156,8 @@ test("install --cli codex writes requirements.toml with sandbox bounds", async (
   });
 
   const { root } = makeProject({ apiKey: "ent_test_key_12345678", baseUrl });
-  const codexPath = path.join(root, "fake-codex-requirements.toml");
+  const codexDir = path.join(root, "fake managed codex");
+  const codexPath = path.join(codexDir, "requirements.toml");
   try {
     const result = await runGovernInstall({
       cli: "codex",
@@ -138,6 +171,40 @@ test("install --cli codex writes requirements.toml with sandbox bounds", async (
     assert.match(toml, /allowed_sandbox_modes = \["read-only", "workspace-write"\]/);
     assert.match(toml, /\[permissions\.filesystem\]/);
     assert.match(toml, /deny_read = \["~\/.codex\/config\.toml"\]/);
+    assert.match(toml, /\[hooks\]/);
+    assert.match(toml, /managed_dir = ".+fake managed codex\/hooks"/);
+    assert.match(toml, /\[\[hooks\.PreToolUse\]\]/);
+    assert.match(toml, /matcher = "Edit\|Write\|Bash\|MultiEdit"/);
+    assert.match(toml, /command = "\\".+fake managed codex\/hooks\/pre-tool-use\.sh\\""/);
+    assert.match(toml, /\[\[hooks\.PostToolUse\]\]/);
+    assert.match(toml, /command = "\\".+fake managed codex\/hooks\/post-tool-use\.sh\\""/);
+    assert.match(toml, /\[\[hooks\.PermissionRequest\]\]/);
+    assert.match(toml, /command = "\\".+fake managed codex\/hooks\/permission-request\.sh\\""/);
+    assert.match(toml, /\[\[hooks\.SessionStart\]\]/);
+    assert.match(toml, /command = "\\".+fake managed codex\/hooks\/session-start\.sh\\""/);
+    assert.match(toml, /\[\[hooks\.SessionEnd\]\]/);
+    assert.match(toml, /command = "\\".+fake managed codex\/hooks\/session-end\.sh\\""/);
+
+    const preToolUseWrapper = path.join(codexDir, "hooks", "pre-tool-use.sh");
+    const postToolUseWrapper = path.join(codexDir, "hooks", "post-tool-use.sh");
+    const permissionRequestWrapper = path.join(codexDir, "hooks", "permission-request.sh");
+    const sessionStartWrapper = path.join(codexDir, "hooks", "session-start.sh");
+    const sessionEndWrapper = path.join(codexDir, "hooks", "session-end.sh");
+    assert.equal(fs.existsSync(preToolUseWrapper), true);
+    assert.equal(fs.existsSync(postToolUseWrapper), true);
+    assert.equal(fs.existsSync(permissionRequestWrapper), true);
+    assert.equal(fs.existsSync(sessionStartWrapper), true);
+    assert.equal(fs.existsSync(sessionEndWrapper), true);
+    const preToolUseContents = fs.readFileSync(preToolUseWrapper, "utf8");
+    assert.match(preToolUseContents, /exec "\$CORTEX" hook pre-tool-use "\$@"/);
+    const postToolUseContents = fs.readFileSync(postToolUseWrapper, "utf8");
+    assert.match(postToolUseContents, /exec "\$CORTEX" hook post-tool-use "\$@"/);
+    const permissionRequestContents = fs.readFileSync(permissionRequestWrapper, "utf8");
+    assert.match(permissionRequestContents, /exec "\$CORTEX" hook permission-request "\$@"/);
+    const sessionEndContents = fs.readFileSync(sessionEndWrapper, "utf8");
+    assert.match(sessionEndContents, /exec "\$CORTEX" hook session-end "\$@"/);
+    const mode = fs.statSync(preToolUseWrapper).mode & 0o777;
+    assert.equal(mode, 0o755);
   } finally {
     server.close();
     fs.rmSync(root, { recursive: true, force: true });

package/scaffold/mcp/tests/govern.test.mjs

@@ -1,5 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
 
 import { getManagedSettingsPath, buildCodexRequirementsToml } from "../dist/cli/govern.js";
 
@@ -34,7 +35,33 @@ test("getManagedSettingsPath: throws on unsupported cli (copilot has no managed
 test("buildCodexRequirementsToml: emits sandbox + approval upper bounds", () => {
   const config = {
     cli: "codex",
-    managed_settings: {},
+    managed_settings: {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: "Edit|Write|Bash|MultiEdit",
+            command: '"/Library/Application Support/Codex/hooks/pre-tool-use.sh"',
+            statusMessage: "Checking Cortex policy",
+            timeout: 30,
+          },
+        ],
+        PostToolUse: [
+          {
+            command: '"/Library/Application Support/Codex/hooks/post-tool-use.sh"',
+          },
+        ],
+        PermissionRequest: [
+          {
+            command: '"/Library/Application Support/Codex/hooks/permission-request.sh"',
+          },
+        ],
+        SessionEnd: [
+          {
+            command: "cortex hook session-end",
+          },
+        ],
+      },
+    },
     deny_rules: [
       { pattern: "Edit(~/.codex/config.toml)", source_frameworks: ["iso27001"] },
       { pattern: "Bash(curl *)", source_frameworks: ["iso27001"] },
@@ -42,11 +69,26 @@ test("buildCodexRequirementsToml: emits sandbox + approval upper bounds", () =>
     tamper_config: { heartbeat_interval_seconds: 60, missing_threshold_seconds: 300 },
     frameworks: [{ id: "iso27001", version: "0.1.0" }],
   };
-  const toml = buildCodexRequirementsToml(config);
+  const toml = buildCodexRequirementsToml(config, {
+    managedHookDir: "/Library/Application Support/Codex/hooks",
+  });
   assert.match(toml, /allowed_sandbox_modes = \["read-only", "workspace-write"\]/);
   assert.match(toml, /allowed_approval_policies = \["untrusted", "on-request"\]/);
   assert.match(toml, /\[permissions\.filesystem\]/);
   assert.match(toml, /deny_read = \["~\/.codex\/config\.toml"\]/);
+  assert.match(toml, /\[hooks\]/);
+  assert.match(toml, /managed_dir = "\/Library\/Application Support\/Codex\/hooks"/);
+  assert.match(toml, /\[\[hooks\.PreToolUse\]\]/);
+  assert.match(toml, /matcher = "Edit\|Write\|Bash\|MultiEdit"/);
+  assert.match(toml, /command = "\\"\/Library\/Application Support\/Codex\/hooks\/pre-tool-use\.sh\\""/);
+  assert.match(toml, /\[\[hooks\.PostToolUse\]\]/);
+  assert.match(toml, /command = "\\"\/Library\/Application Support\/Codex\/hooks\/post-tool-use\.sh\\""/);
+  assert.match(toml, /\[\[hooks\.PermissionRequest\]\]/);
+  assert.match(toml, /command = "\\"\/Library\/Application Support\/Codex\/hooks\/permission-request\.sh\\""/);
+  assert.match(toml, /statusMessage = "Checking Cortex policy"/);
+  assert.match(toml, /timeout = 30/);
+  assert.match(toml, /\[\[hooks\.SessionEnd\]\]/);
+  assert.match(toml, /command = "cortex hook session-end"/);
   // Bash(...) patterns should not appear in deny_read (filesystem only)
   assert.doesNotMatch(toml, /curl/);
 });
@@ -72,3 +114,34 @@ test("buildCodexRequirementsToml: escapes quotes in patterns", () => {
   });
   assert.match(toml, /\\"quote\\"/);
 });
+
+test("buildCodexRequirementsToml: emits managed hook paths under the provided directory", () => {
+  const managedHookDir = path.join("/tmp", "Codex Hooks");
+  const toml = buildCodexRequirementsToml({
+    cli: "codex",
+    managed_settings: {
+      hooks: {
+        SessionStart: [
+          {
+            matcher: "startup|resume|clear",
+            hooks: [
+              {
+                type: "command",
+                command: `"${path.join(managedHookDir, "session-start.sh")}"`,
+              },
+            ],
+          },
+        ],
+      },
+    },
+    deny_rules: [],
+    tamper_config: { heartbeat_interval_seconds: 60, missing_threshold_seconds: 300 },
+    frameworks: [],
+  }, {
+    managedHookDir,
+  });
+  assert.match(toml, /managed_dir = "\/tmp\/Codex Hooks"/);
+  assert.match(toml, /\[\[hooks\.SessionStart\]\]/);
+  assert.match(toml, /matcher = "startup\|resume\|clear"/);
+  assert.match(toml, /command = "\\"\/tmp\/Codex Hooks\/session-start\.sh\\""/);
+});