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

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 advisory workflow suggestions.",
   "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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/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": "bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/runtime.ts\" hook runtime --target claude",
             "timeout": 5
           }
         ]

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

@@ -1,16 +1,28 @@
+import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import {
   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 +32,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 +76,10 @@ 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';
+  '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';
+  'bun run "${PLUGIN_ROOT}/hooks/runtime.ts" hook runtime --target codex';
+const CODEX_FEATURE_FLAGS = ["plugins", "plugin_hooks", "hooks"] as const;
 const CLAUDE_TOOL_EVENTS = new Set<CanonicalHookEventType>([
   "PreToolUse",
   "PermissionRequest",
@@ -107,17 +140,73 @@ 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;
+}): Promise<HookInstallResult> {
+  const paths = input.paths ?? resolveClaudePaths({ homeDir: input.homeDir });
+  const existing = await readTextIfExists(paths.settingsPath);
+  const next = mergeClaudeSettingsHooks(existing, createClaudeHookConfig().hooks);
+  return writeMergedConfig({
+    target: "claude",
+    path: paths.settingsPath,
+    existing,
+    next,
+    now: input.now,
+    warnings: [],
+  });
+}
+
+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>;
@@ -194,7 +283,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 advisory workflow suggestions.",
     hooks,
   };
 }
@@ -215,3 +304,172 @@ 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";
+}
+
+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);
+}

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

@@ -2,15 +2,21 @@ export {
   type CodexCommandResult,
   type CodexCommandRunner,
   type CodexPluginOptions,
+  type CodexSyncFileSystem,
   codexPlugin,
   createCodexPlugin,
 } from "./codex.ts";
 
 export { type ClaudeCommandResult, type ClaudeCommandRunner, detectClaudeCode } from "./detect.ts";
 export {
+  type CodexPaths,
+  type ResolveCodexPathsOptions,
   type ClaudePaths,
   type ResolveClaudePathsOptions,
+  assertSafeCodexAssetName,
   assertSafeClaudeAssetName,
+  resolveCodexAgentTargetPath,
+  resolveCodexPaths,
   resolveClaudeAgentTargetPath,
   resolveClaudePaths,
   resolveClaudeSkillTargetPath,
@@ -23,13 +29,19 @@ export {
   type ClaudeHookInstallDryRunInput,
   type ClaudeHookInstallDryRunPlan,
   type ClaudeHookMatcherGroup,
+  type CodexHookInstallDryRunInput,
+  type CodexHookInstallDryRunPlan,
   type CodexHookConfig,
+  type HookInstallResult,
   createCodexHookConfig,
   createClaudeHookConfig,
+  installClaudeHooks,
+  installCodexHooks,
   normalizeCodexHookPayload,
   normalizeCodexRuntimeHookPayload,
   normalizeClaudeHookPayload,
   normalizeClaudeRuntimeHookPayload,
+  planCodexHookInstallDryRun,
   planClaudeHookInstallDryRun,
 } from "./hooks.ts";
 export {
@@ -43,6 +55,9 @@ export {
 export {
   type ClaudeAgentTransformInput,
   type ClaudeAgentTransformResult,
+  type CodexAgentTransformInput,
+  type CodexAgentTransformResult,
+  transformCodexAgent,
   transformClaudeAgent,
 } from "./transform-agent.ts";
 export {

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

@@ -6,11 +6,24 @@ export interface ClaudePaths {
   agentsDir: string;
 }
 
+export interface CodexPaths {
+  homeDir: string;
+  codexDir: string;
+  configPath: string;
+  hooksPath: string;
+  agentsDir: string;
+}
+
 export interface ResolveClaudePathsOptions {
   homeDir: string;
   claudeDir?: string;
 }
 
+export interface ResolveCodexPathsOptions {
+  homeDir: string;
+  codexDir?: string;
+}
+
 export function resolveClaudePaths(options: ResolveClaudePathsOptions): ClaudePaths {
   const homeDir = stripTrailingSlash(options.homeDir);
   const claudeDir = stripTrailingSlash(options.claudeDir ?? `${homeDir}/.claude`);
@@ -24,6 +37,19 @@ export function resolveClaudePaths(options: ResolveClaudePathsOptions): ClaudePa
   };
 }
 
+export function resolveCodexPaths(options: ResolveCodexPathsOptions): CodexPaths {
+  const homeDir = stripTrailingSlash(options.homeDir);
+  const codexDir = stripTrailingSlash(options.codexDir ?? `${homeDir}/.codex`);
+
+  return {
+    homeDir,
+    codexDir,
+    configPath: `${codexDir}/config.toml`,
+    hooksPath: `${codexDir}/hooks.json`,
+    agentsDir: `${codexDir}/agents`,
+  };
+}
+
 export function resolveClaudeSkillTargetPath(skillName: string, paths: ClaudePaths): string {
   const safeSkillName = assertSafeClaudeAssetName(skillName, "skillName");
   return `${paths.skillsDir}/${safeSkillName}/SKILL.md`;
@@ -34,10 +60,27 @@ export function resolveClaudeAgentTargetPath(agentName: string, paths: ClaudePat
   return `${paths.agentsDir}/${safeAgentName}.md`;
 }
 
+export function resolveCodexAgentTargetPath(agentName: string, paths: CodexPaths): string {
+  const safeAgentName = assertSafeCodexAssetName(agentName, "agentName");
+  return `${paths.agentsDir}/${safeAgentName}.toml`;
+}
+
 export function assertSafeClaudeAssetName(name: string, label = "name"): string {
+  return assertSafeCodeAgentAssetName(name, "Claude", label);
+}
+
+export function assertSafeCodexAssetName(name: string, label = "name"): string {
+  return assertSafeCodeAgentAssetName(name, "Codex", label);
+}
+
+function assertSafeCodeAgentAssetName(
+  name: string,
+  target: "Claude" | "Codex",
+  label: string,
+): string {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name === "." || name === "..") {
     throw new Error(
-      `Invalid Claude asset ${label}: must be a single safe path segment using letters, numbers, dot, underscore, or hyphen`,
+      `Invalid ${target} asset ${label}: must be a single safe path segment using letters, numbers, dot, underscore, or hyphen`,
     );
   }