@evo-dev/evodev 0.0.1-alpha → 0.0.1-alpha.2

package/dist/plugins/evodev/hooks/hooks.json

@@ -1,12 +1,12 @@
 {
-  "description": "EvoDev routes Claude Code lifecycle events through evodev hook runtime for Task Contract, workflow, policy, and evidence control.",
+  "description": "EvoDev observes Claude Code lifecycle events through evodev hook runtime for local trace and action-required advisories.",
   "hooks": {
     "SessionStart": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -29,7 +29,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -53,7 +53,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -65,7 +65,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -76,7 +76,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -88,7 +88,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -99,7 +99,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -110,7 +110,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -121,7 +121,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -132,7 +132,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -143,7 +143,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -154,7 +154,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -165,7 +165,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -176,7 +176,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 30
           }
         ]
@@ -187,7 +187,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NODE_PATH=\"$(dirname \"$(bun pm bin -g)\")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}\" bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun run hooks/runtime.ts hook runtime --target claude",
             "timeout": 5
           }
         ]

package/dist/plugins/evodev/hooks/hooks.ts

@@ -1,16 +1,31 @@
+import type { Dirent } from "node:fs";
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
+  CANONICAL_HOOK_EVENT_TYPES,
   type CanonicalHookEventType,
   type HookEventV1,
   type HookInputEventType,
   normalizeHookEvent,
 } from "@evo-dev/core";
-import { type ClaudePaths, resolveClaudePaths } from "./paths.ts";
+import {
+  type ClaudePaths,
+  type CodexPaths,
+  resolveClaudePaths,
+  resolveCodexPaths,
+} from "./paths.ts";
 
 export interface ClaudeHookInstallDryRunInput {
   homeDir: string;
   paths?: ClaudePaths;
 }
 
+export interface CodexHookInstallDryRunInput {
+  homeDir: string;
+  paths?: CodexPaths;
+}
+
 export interface ClaudeHookInstallDryRunPlan {
   target: "claude";
   settingsPath: string;
@@ -20,7 +35,27 @@ export interface ClaudeHookInstallDryRunPlan {
     reason: string;
   }>;
   warnings: string[];
-  blockers: string[];
+  advisories: string[];
+}
+
+export interface CodexHookInstallDryRunPlan {
+  target: "codex";
+  configPath: string;
+  plannedWrites: Array<{
+    action: "merge-with-backup" | "create";
+    targetPath: string;
+    reason: string;
+  }>;
+  warnings: string[];
+  advisories: string[];
+}
+
+export interface HookInstallResult {
+  target: "claude" | "codex";
+  targetPath: string;
+  backupPath: string | null;
+  changed: boolean;
+  warnings: string[];
 }
 
 export interface ClaudeHookCommand {
@@ -44,9 +79,21 @@ export interface CodexHookConfig {
 }
 
 export const CLAUDE_HOOK_RUNTIME_COMMAND =
-  'NODE_PATH="$(dirname "$(bun pm bin -g)")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}" bun run "${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts" hook runtime --target claude';
-export const CODEX_HOOK_RUNTIME_COMMAND =
-  'NODE_PATH="$(dirname "$(bun pm bin -g)")/install/global/node_modules${NODE_PATH:+:$NODE_PATH}" bun run "${PLUGIN_ROOT}/hooks/runtime.ts" hook runtime --target codex';
+  'cd "${CLAUDE_PLUGIN_ROOT}" && bun run hooks/runtime.ts hook runtime --target claude';
+export const DEFAULT_CLAUDE_PLUGIN_SELECTOR = "evodev@evo-dev";
+export const CODEX_HOOK_RUNTIME_COMMAND = [
+  "sh -lc '",
+  'root="${PLUGIN_ROOT:-}"; ',
+  'if [ -z "$root" ]; then ',
+  'for candidate in "$HOME/.codex/plugins/cache/evodev/evodev"/* "$HOME/.codex/plugins/evodev"; do ',
+  'if [ -f "$candidate/hooks/runtime.ts" ]; then root="$candidate"; break; fi; ',
+  "done; ",
+  "fi; ",
+  'if [ -z "$root" ] || [ ! -f "$root/hooks/runtime.ts" ]; then exit 0; fi; ',
+  'cd "$root" && bun run hooks/runtime.ts hook runtime --target codex || exit 0',
+  "'",
+].join("");
+const CODEX_FEATURE_FLAGS = ["plugins", "plugin_hooks", "hooks"] as const;
 const CLAUDE_TOOL_EVENTS = new Set<CanonicalHookEventType>([
   "PreToolUse",
   "PermissionRequest",
@@ -94,6 +141,10 @@ const CODEX_EVENT_MATCHERS: Partial<Record<CanonicalHookEventType, string>> = {
   SubagentStop: "*",
   Stop: "*",
 };
+const RUNTIME_HOOK_EVENT_TYPES = [...CANONICAL_HOOK_EVENT_TYPES, "AgentStop"] as const;
+const RUNTIME_HOOK_EVENT_TYPE_BY_KEY = new Map<string, HookInputEventType>(
+  RUNTIME_HOOK_EVENT_TYPES.map((type) => [normalizeRuntimeHookEventName(type), type]),
+);
 
 export function planClaudeHookInstallDryRun(
   input: ClaudeHookInstallDryRunInput,
@@ -107,17 +158,173 @@ export function planClaudeHookInstallDryRun(
         action: "merge-with-backup",
         targetPath: paths.settingsPath,
         reason:
-          "dry-run only: would add disabled EvoDev user-level hooks after future confirmation; no file is written",
+          "would add or replace EvoDev-managed user-level hook entries without touching user-owned hooks",
       },
     ],
-    warnings: [
-      "Hooks remain disabled by default.",
-      "Project .claude, .codex, CLAUDE.md, and AGENTS.md are never targeted by this dry-run.",
+    warnings: ["Project .claude, .codex, CLAUDE.md, and AGENTS.md are not targeted."],
+    advisories: [],
+  };
+}
+
+export function planCodexHookInstallDryRun(
+  input: CodexHookInstallDryRunInput,
+): CodexHookInstallDryRunPlan {
+  const paths = input.paths ?? resolveCodexPaths({ homeDir: input.homeDir });
+  return {
+    target: "codex",
+    configPath: paths.configPath,
+    plannedWrites: [
+      {
+        action: "merge-with-backup",
+        targetPath: paths.configPath,
+        reason:
+          "would enable missing Codex plugin hook feature flags while preserving explicit user-owned false values",
+      },
     ],
-    blockers: [],
+    warnings: ["Codex hook definitions are supplied by the EvoDev Codex plugin manifest."],
+    advisories: [],
   };
 }
 
+export async function installClaudeHooks(input: {
+  homeDir: string;
+  paths?: ClaudePaths;
+  now?: string;
+  pluginSelector?: string;
+}): Promise<HookInstallResult> {
+  const paths = input.paths ?? resolveClaudePaths({ homeDir: input.homeDir });
+  const existing = await readTextIfExists(paths.settingsPath);
+  const runtimeCommand = await resolveClaudeUserHookRuntimeCommand({
+    paths,
+    pluginSelector: input.pluginSelector ?? DEFAULT_CLAUDE_PLUGIN_SELECTOR,
+  });
+  const next = mergeClaudeSettingsHooks(existing, createClaudeHookConfig(runtimeCommand).hooks);
+  return writeMergedConfig({
+    target: "claude",
+    path: paths.settingsPath,
+    existing,
+    next,
+    now: input.now,
+    warnings: [],
+  });
+}
+
+async function resolveClaudeUserHookRuntimeCommand(input: {
+  paths: ClaudePaths;
+  pluginSelector: string;
+}): Promise<string> {
+  const runtimePath =
+    (await resolveInstalledClaudePluginRuntimePath(input)) ?? (await resolveLocalRuntimePath());
+  const pluginRoot = dirname(dirname(runtimePath));
+  return `cd ${shellQuote(pluginRoot)} && bun run hooks/runtime.ts hook runtime --target claude`;
+}
+
+async function resolveInstalledClaudePluginRuntimePath(input: {
+  paths: ClaudePaths;
+  pluginSelector: string;
+}): Promise<string | null> {
+  const marketplaceName = extractMarketplaceNameFromSelector(input.pluginSelector);
+  const pluginName = extractPluginNameFromSelector(input.pluginSelector);
+  if (marketplaceName === null || pluginName === null) return null;
+  if (!isSafePluginCacheSegment(marketplaceName) || !isSafePluginCacheSegment(pluginName)) {
+    return null;
+  }
+
+  const cacheRoot = join(input.paths.claudeDir, "plugins", "cache", marketplaceName, pluginName);
+  let entries: Dirent[];
+  try {
+    entries = await readdir(cacheRoot, { withFileTypes: true });
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+
+  const candidates = (
+    await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) => {
+          const runtimePath = join(cacheRoot, entry.name, "hooks", "runtime.ts");
+          try {
+            const runtimeStat = await stat(runtimePath);
+            return runtimeStat.isFile()
+              ? { path: runtimePath, mtimeMs: runtimeStat.mtimeMs }
+              : null;
+          } catch (error) {
+            if (isNotFoundError(error)) return null;
+            throw error;
+          }
+        }),
+    )
+  ).filter((candidate): candidate is { path: string; mtimeMs: number } => candidate !== null);
+
+  if (candidates.length === 0) return null;
+  candidates.sort(
+    (left, right) => right.mtimeMs - left.mtimeMs || right.path.localeCompare(left.path),
+  );
+  return candidates[0].path;
+}
+
+function extractMarketplaceNameFromSelector(selector: string): string | null {
+  const separator = selector.lastIndexOf("@");
+  if (separator <= 0 || separator === selector.length - 1) return null;
+  const marketplaceName = selector.slice(separator + 1).trim();
+  return marketplaceName === "" ? null : marketplaceName;
+}
+
+function extractPluginNameFromSelector(selector: string): string | null {
+  const separator = selector.lastIndexOf("@");
+  const pluginName = (separator <= 0 ? selector : selector.slice(0, separator)).trim();
+  return pluginName === "" ? null : pluginName;
+}
+
+function isSafePluginCacheSegment(segment: string): boolean {
+  return /^[A-Za-z0-9._-]+$/.test(segment) && segment !== "." && segment !== "..";
+}
+
+async function resolveLocalRuntimePath(): Promise<string> {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(currentDir, "runtime.ts"),
+    join(currentDir, "plugins", "evodev", "hooks", "runtime.ts"),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const candidateStat = await stat(candidate);
+      if (candidateStat.isFile()) return candidate;
+    } catch (error) {
+      if (isNotFoundError(error)) continue;
+      throw error;
+    }
+  }
+
+  throw new Error(
+    `Cannot resolve Claude user-level hook runtime path. Checked: ${candidates.join(", ")}`,
+  );
+}
+
+export async function installCodexHooks(input: {
+  homeDir: string;
+  paths?: CodexPaths;
+  now?: string;
+}): Promise<HookInstallResult> {
+  const paths = input.paths ?? resolveCodexPaths({ homeDir: input.homeDir });
+  const existing = await readTextIfExists(paths.configPath);
+  const merged = mergeCodexFeatureFlags(existing);
+  return writeMergedConfig({
+    target: "codex",
+    path: paths.configPath,
+    existing,
+    next: merged.content,
+    now: input.now,
+    warnings: [
+      "Codex hook definitions are loaded from the installed EvoDev Codex plugin.",
+      ...merged.warnings,
+    ],
+  });
+}
+
 export function normalizeClaudeHookPayload(input: {
   type: HookInputEventType;
   payload: Record<string, unknown>;
@@ -136,12 +343,11 @@ export function normalizeClaudeRuntimeHookPayload(input: {
   payload: Record<string, unknown>;
   receivedAt?: string;
 }): HookEventV1 {
-  const type = input.payload.hook_event_name ?? input.payload.hookEventName;
-  if (typeof type !== "string" || type.trim() === "") {
-    throw new Error("Claude hook payload is missing hook_event_name.");
-  }
   return normalizeClaudeHookPayload({
-    type: type as HookInputEventType,
+    type: readRuntimeHookEventType(
+      input.payload.hook_event_name ?? input.payload.hookEventName,
+      "Claude",
+    ),
     payload: input.payload,
     receivedAt: input.receivedAt,
   });
@@ -165,21 +371,34 @@ export function normalizeCodexRuntimeHookPayload(input: {
   payload: Record<string, unknown>;
   receivedAt?: string;
 }): HookEventV1 {
-  const type =
-    input.payload.hook_event_name ??
-    input.payload.hookEventName ??
-    input.payload.event ??
-    input.payload.name;
-  if (typeof type !== "string" || type.trim() === "") {
-    throw new Error("Codex hook payload is missing hook_event_name.");
-  }
   return normalizeCodexHookPayload({
-    type: type as HookInputEventType,
+    type: readRuntimeHookEventType(
+      input.payload.hook_event_name ??
+        input.payload.hookEventName ??
+        input.payload.event ??
+        input.payload.name,
+      "Codex",
+    ),
     payload: input.payload,
     receivedAt: input.receivedAt,
   });
 }
 
+function readRuntimeHookEventType(value: unknown, target: "Claude" | "Codex"): HookInputEventType {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${target} hook payload is missing hook_event_name.`);
+  }
+  const normalized = RUNTIME_HOOK_EVENT_TYPE_BY_KEY.get(normalizeRuntimeHookEventName(value));
+  if (normalized === undefined) {
+    throw new Error(`Unsupported hook event type: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeRuntimeHookEventName(value: string): string {
+  return value.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+}
+
 export function createClaudeHookConfig(
   command: string = CLAUDE_HOOK_RUNTIME_COMMAND,
 ): ClaudeHookConfig {
@@ -194,7 +413,7 @@ export function createClaudeHookConfig(
   }
   return {
     description:
-      "EvoDev routes Claude Code lifecycle events through evodev hook runtime for Task Contract, workflow, policy, and evidence control.",
+      "EvoDev observes Claude Code lifecycle events through evodev hook runtime for local trace and action-required advisories.",
     hooks,
   };
 }
@@ -215,3 +434,176 @@ export function createCodexHookConfig(
   }
   return { hooks };
 }
+
+async function readTextIfExists(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+}
+
+async function writeMergedConfig(input: {
+  target: "claude" | "codex";
+  path: string;
+  existing: string | null;
+  next: string;
+  now?: string;
+  warnings: string[];
+}): Promise<HookInstallResult> {
+  if (input.existing === input.next) {
+    return {
+      target: input.target,
+      targetPath: input.path,
+      backupPath: null,
+      changed: false,
+      warnings: input.warnings,
+    };
+  }
+
+  await mkdir(dirname(input.path), { recursive: true });
+  let backupPath: string | null = null;
+  if (input.existing !== null && (await fileExists(input.path))) {
+    backupPath = `${input.path}.evodev-${backupTimestamp(input.now)}.bak`;
+    await copyFile(input.path, backupPath);
+  }
+  await writeFile(input.path, input.next, "utf8");
+  return {
+    target: input.target,
+    targetPath: input.path,
+    backupPath,
+    changed: true,
+    warnings: input.warnings,
+  };
+}
+
+function mergeClaudeSettingsHooks(
+  existing: string | null,
+  evodevHooks: ClaudeHookConfig["hooks"],
+): string {
+  const settings = parseJsonConfig(existing, "Claude settings");
+  const currentHooks = isRecord(settings.hooks) ? settings.hooks : {};
+  const nextHooks: Record<string, unknown> = { ...currentHooks };
+
+  for (const [eventName, groups] of Object.entries(evodevHooks)) {
+    const existingGroups = Array.isArray(currentHooks[eventName]) ? currentHooks[eventName] : [];
+    nextHooks[eventName] = [
+      ...existingGroups.filter((group) => !isEvoDevHookGroup(group, "claude")),
+      ...(groups ?? []),
+    ];
+  }
+
+  return `${JSON.stringify({ ...settings, hooks: nextHooks }, null, 2)}\n`;
+}
+
+function parseJsonConfig(existing: string | null, label: string): Record<string, unknown> {
+  if (existing === null || existing.trim() === "") return {};
+  const parsed = JSON.parse(existing) as unknown;
+  if (!isRecord(parsed)) throw new Error(`${label} must be a JSON object.`);
+  return parsed;
+}
+
+function isEvoDevHookGroup(group: unknown, target: "claude" | "codex"): boolean {
+  if (!isRecord(group) || !Array.isArray(group.hooks)) return false;
+  return group.hooks.some((hook) => {
+    if (!isRecord(hook) || typeof hook.command !== "string") return false;
+    return hook.command.includes(`hook runtime --target ${target}`);
+  });
+}
+
+function mergeCodexFeatureFlags(existing: string | null): { content: string; warnings: string[] } {
+  const source = existing ?? "";
+  const lines = source === "" ? [] : source.replace(/\n$/, "").split("\n");
+  const section = findTomlSection(lines, "features");
+  if (section === null) {
+    const prefix = lines.length === 0 ? [] : [...lines, ""];
+    return {
+      content: [
+        ...prefix,
+        "[features]",
+        ...CODEX_FEATURE_FLAGS.map((flag) => `${flag} = true`),
+        "",
+      ].join("\n"),
+      warnings: [],
+    };
+  }
+
+  const nextLines = [...lines];
+  const seen = new Set<string>();
+  const preservedFalseFlags: string[] = [];
+  for (let index = section.start + 1; index < section.end; index += 1) {
+    const match = nextLines[index]?.match(/^(\s*)([A-Za-z0-9_-]+)(\s*=\s*)(.*)$/);
+    if (match === null) continue;
+    const key = match[2];
+    if ((CODEX_FEATURE_FLAGS as readonly string[]).includes(key)) {
+      seen.add(key);
+      if (isTomlBooleanFalse(match[4])) {
+        preservedFalseFlags.push(key);
+      } else {
+        nextLines[index] = `${match[1]}${key}${match[3]}true`;
+      }
+    }
+  }
+
+  const missing = CODEX_FEATURE_FLAGS.filter((flag) => !seen.has(flag));
+  nextLines.splice(section.end, 0, ...missing.map((flag) => `${flag} = true`));
+  return {
+    content: `${nextLines.join("\n")}\n`,
+    warnings:
+      preservedFalseFlags.length === 0
+        ? []
+        : [
+            `Explicitly disabled Codex feature flags were preserved: ${preservedFalseFlags.join(", ")}.`,
+          ],
+  };
+}
+
+function isTomlBooleanFalse(value: string): boolean {
+  return /^false(?:\s*(?:#.*)?)?$/i.test(value.trim());
+}
+
+function findTomlSection(lines: string[], name: string): { start: number; end: number } | null {
+  const header = `[${name}]`;
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^\s*\[[^\]]+\]\s*$/.test(lines[index] ?? "")) {
+      end = index;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+function backupTimestamp(value?: string): string {
+  const source = value ?? new Date().toISOString();
+  return source.replace(/[^0-9A-Za-z]/g, "").slice(0, 20) || "now";
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch (error) {
+    if (isNotFoundError(error)) return false;
+    throw error;
+  }
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}