portable-agent-layer 0.85.23 → 0.86.0

package/src/hooks/lib/frontmatter.ts

@@ -10,23 +10,36 @@ interface Parsed<T = Record<string, string>> {
   body: string;
 }
 
-const DELIMITER = /^---\s*$/m;
+const DELIMITER = /^---[ \t]*$/m;
+
+interface FrontmatterSplit {
+  leading: string;
+  frontmatter: string;
+  body: string;
+}
+
+/**
+ * Split text at its first two `---` lines. The body keeps every character after
+ * the closing delimiter, so later `---` rules and the lines around them survive.
+ */
+export function splitFrontmatter(content: string): FrontmatterSplit | null {
+  const parts = content.split(DELIMITER);
+  if (parts.length < 3) return null;
+  return { leading: parts[0], frontmatter: parts[1], body: parts.slice(2).join("---") };
+}
 
 /**
  * Parse frontmatter from a markdown string.
  * Returns typed meta + body. If no frontmatter found, meta is empty and body is the full content.
  */
 export function parse<T = Record<string, string>>(content: string): Parsed<T> {
-  const parts = content.split(DELIMITER);
-
-  // Need at least 3 parts: before --- | frontmatter | after ---
-  // parts[0] should be empty (content starts with ---)
-  if (parts.length < 3 || parts[0].trim() !== "") {
+  const split = splitFrontmatter(content);
+  if (!split || split.leading.trim() !== "") {
     return { meta: {} as T, body: content };
   }
 
-  const rawMeta = parts[1];
-  const body = parts.slice(2).join("---").trim();
+  const rawMeta = split.frontmatter;
+  const body = split.body.trim();
 
   const meta: Record<string, unknown> = {};
   for (const line of rawMeta.split("\n")) {

package/src/hooks/lib/inference.ts

@@ -32,37 +32,58 @@ import {
   isOpencode,
 } from "./agent";
 import { logDebug, logError } from "./log";
-import { HAIKU_MODEL } from "./models";
-import { writeInstructionFreeConfig } from "./opencode-config";
+import {
+  type FixedModelRoute,
+  type InferenceTier,
+  inferenceModel,
+  isFixedModelRoute,
+} from "./models";
+import { opencodeTierModel, writeInstructionFreeConfig } from "./opencode-config";
+import { withPalEnv } from "./pal-env";
 import { buildSpawnGuardEnv, getInferenceDepth, SPAWN_GUARD_ENV } from "./spawn-guard";
 import { findBinaryOnPath } from "./which";
 
 export function hasApiKey(): boolean {
-  return !!process.env.PAL_ANTHROPIC_API_KEY;
+  return !!withPalEnv().PAL_ANTHROPIC_API_KEY;
 }
 
 export function hasOpenAiKey(): boolean {
-  return !!process.env.PAL_OPENAI_API_KEY;
+  return !!withPalEnv().PAL_OPENAI_API_KEY;
+}
+
+type InferenceRoute =
+  | FixedModelRoute
+  | "opencode-spawn"
+  | "copilot-spawn"
+  | "cursor-spawn"
+  | "disabled"
+  | "none";
+
+interface RoutePreview {
+  agent: string;
+  route: InferenceRoute;
+  reason: string;
+}
+
+function modelFor(route: FixedModelRoute, opts: InferenceOptions): string {
+  return inferenceModel(route, opts.tier);
+}
+
+function smallModelOf(route: InferenceRoute): string | undefined {
+  if (route === "opencode-spawn") return opencodeTierModel("small") ?? undefined;
+  return isFixedModelRoute(route) ? inferenceModel(route, "small") : undefined;
 }
 
 /**
  * Preview what `inference()` would do RIGHT NOW given current env + binaries.
  * Pure diagnostic — never spawns or fetches. Used by `pal cli doctor`.
  */
-export function previewInferenceRoute(): {
-  agent: string;
-  route:
-    | "claude-spawn"
-    | "codex-spawn"
-    | "openai-api"
-    | "opencode-spawn"
-    | "copilot-spawn"
-    | "cursor-spawn"
-    | "anthropic-api"
-    | "disabled"
-    | "none";
-  reason: string;
-} {
+export function previewInferenceRoute(): RoutePreview & { model?: string } {
+  const preview = previewRoute();
+  return { ...preview, model: smallModelOf(preview.route) };
+}
+
+function previewRoute(): RoutePreview {
   const agent = getActiveAgent();
   if (process.env.PAL_INFERENCE_DISABLED === "1") {
     return {
@@ -115,7 +136,8 @@ export function canInfer(): boolean {
 interface InferenceOptions {
   system?: string;
   user: string;
-  model?: string;
+  /** Model size; the active route maps it to that provider's model. Default "small". */
+  tier?: InferenceTier;
   maxTokens?: number;
   timeout?: number;
   /** JSON schema for structured output — guarantees valid JSON matching the schema */
@@ -129,6 +151,8 @@ interface InferenceOptions {
 interface InferenceResult {
   success: boolean;
   output?: string;
+  /** First line of a failed CLI's error output. */
+  error?: string;
   usage?: { inputTokens: number; outputTokens: number };
 }
 
@@ -152,7 +176,7 @@ export async function inference(opts: InferenceOptions): Promise<InferenceResult
     if (bin) {
       logDebug(
         "inference",
-        `${tag} route=claude-spawn agent=${agent} model=${opts.model ?? HAIKU_MODEL}`
+        `${tag} route=claude-spawn agent=${agent} model=${modelFor("claude-spawn", opts)}`
       );
       return inferenceViaClaudeSpawn(bin, opts);
     }
@@ -269,7 +293,7 @@ export function buildClaudeArgs(
   const args = [
     "--print",
     "--model",
-    opts.model ?? HAIKU_MODEL,
+    modelFor("claude-spawn", opts),
     "--tools",
     "",
     "--output-format",
@@ -281,6 +305,27 @@ export function buildClaudeArgs(
   return args;
 }
 
+type ClaudeAuthMode = "token" | "native";
+
+function claudeAuthMode(): ClaudeAuthMode {
+  return withPalEnv().CLAUDE_CODE_OAUTH_TOKEN ? "token" : "native";
+}
+
+/** Lines logged before spawns were tagged came from the native login. */
+export function loggedClaudeAuthMode(message: string): ClaudeAuthMode {
+  return /\bauth=token\b/.test(message) ? "token" : "native";
+}
+
+/** https://code.claude.com/docs/en/authentication#authentication-precedence */
+const WITHOUT_KEYS_OUTRANKING_TOKEN = {
+  ANTHROPIC_API_KEY: undefined,
+  ANTHROPIC_AUTH_TOKEN: undefined,
+};
+
+function credentialOverridesFor(mode: ClaudeAuthMode) {
+  return mode === "token" ? WITHOUT_KEYS_OUTRANKING_TOKEN : {};
+}
+
 /**
  * Claude keeps a real system prompt, unlike the other agents, so the system text
  * reaches it through --system-prompt-file rather than --system-prompt. Only the
@@ -294,16 +339,22 @@ async function inferenceViaClaudeSpawn(
   bin: string,
   opts: InferenceOptions
 ): Promise<InferenceResult> {
+  const mode = claudeAuthMode();
+  const spawnClaude = (args: string[]) =>
+    inferenceViaCliSpawn(bin, args, opts.user, opts, undefined, {
+      env: credentialOverridesFor(mode),
+      logTag: `auth=${mode}`,
+    });
   const system = opts.jsonSchema
     ? injectJsonSchemaInstruction(opts.system ?? "", opts.jsonSchema)
     : opts.system;
-  if (!system) return inferenceViaCliSpawn(bin, buildClaudeArgs(opts), opts.user, opts);
+  if (!system) return spawnClaude(buildClaudeArgs(opts));
 
   const dir = await mkdtemp(join(tmpdir(), "pal-system-"));
   try {
     const file = join(dir, "system-prompt.md");
     await writeFile(file, system, "utf-8");
-    return await inferenceViaCliSpawn(bin, buildClaudeArgs(opts, file), opts.user, opts);
+    return await spawnClaude(buildClaudeArgs(opts, file));
   } finally {
     await rm(dir, { recursive: true, force: true });
   }
@@ -327,9 +378,11 @@ async function inferenceViaClaudeSpawn(
  * given, so this costs nothing on POSIX and is the only thing that works on
  * Windows. Do not move the prompt back into argv.
  */
-export function buildCodexArgs(_opts: InferenceOptions): string[] {
+export function buildCodexArgs(opts: InferenceOptions): string[] {
   return [
     "exec",
+    "-m",
+    modelFor("codex-spawn", opts),
     "--color",
     "never",
     "--skip-git-repo-check",
@@ -357,8 +410,9 @@ export function buildCodexArgs(_opts: InferenceOptions): string[] {
  * element does not survive cmd.exe on Windows. Provider/model is left unset so
  * opencode uses the user's configured default.
  */
-export function buildOpencodeArgs(_opts: InferenceOptions): string[] {
-  return ["run", "--pure", "--format", "json"];
+export function buildOpencodeArgs(opts: InferenceOptions): string[] {
+  const model = opencodeTierModel(opts.tier ?? "small");
+  return ["run", "--pure", "--format", "json", ...(model ? ["-m", model] : [])];
 }
 
 // Without its own AGENTS.md, opencode falls back to ~/.claude/CLAUDE.md, and it
@@ -520,6 +574,13 @@ export function parseJsonFromOutput(output: string): unknown | null {
   return null;
 }
 
+function firstLine(text: string): string | undefined {
+  return text
+    .split("\n")
+    .find((line) => line.trim())
+    ?.trim();
+}
+
 interface RawSpawnResult {
   code: number | null;
   stdout: string;
@@ -620,7 +681,8 @@ async function singleCliAttempt(
 
 interface SpawnPlace {
   cwd?: string;
-  env?: Record<string, string>;
+  env?: Record<string, string | undefined>;
+  logTag?: string;
 }
 
 /**
@@ -637,11 +699,13 @@ async function inferenceViaCliSpawn(
   place: SpawnPlace = {}
 ): Promise<InferenceResult> {
   const timeout = opts.timeout ?? 15000;
-  const env = { ...buildSpawnGuardEnv(process.env), ...place.env };
+  const env = { ...buildSpawnGuardEnv(withPalEnv(process.env)), ...place.env };
   const started = Date.now();
   const caller = opts.caller ?? "anonymous";
   const session = opts.sessionId ?? "-";
-  const tag = `caller=${caller} sessionId=${session}`;
+  const tag = [`caller=${caller}`, `sessionId=${session}`, place.logTag]
+    .filter(Boolean)
+    .join(" ");
   // Friendly name for logs — strip path + extension so cross-platform diffs
   // (e.g. C:\…\claude.cmd vs /usr/local/bin/claude) read the same in debug.log.
   const binaryName = basename(binary).replace(/\.(cmd|bat|exe|com)$/i, "");
@@ -685,7 +749,7 @@ async function inferenceViaCliSpawn(
       "inference:spawn",
       `${tag} exited=${attempt.code} binary=${binaryName} argv=${JSON.stringify(args)} stderr(${attempt.stderr.length})=${attempt.stderr.slice(0, 300)} stdout(${attempt.stdout.length})=${attempt.stdout.slice(0, 300)}`
     );
-    return finish({ success: false });
+    return finish({ success: false, error: firstLine(attempt.stderr || attempt.stdout) });
   }
   const rawText = attempt.stdout.trim();
   if (!rawText) return finish({ success: false });
@@ -713,24 +777,17 @@ async function inferenceViaCliSpawn(
 // ─────────────────────────────────────────────────────────────────────────────
 
 async function inferenceViaApi(opts: InferenceOptions): Promise<InferenceResult> {
-  const apiKey = process.env.PAL_ANTHROPIC_API_KEY;
+  const apiKey = withPalEnv().PAL_ANTHROPIC_API_KEY;
   if (!apiKey) return { success: false };
 
-  const {
-    system,
-    user,
-    model = HAIKU_MODEL,
-    maxTokens = 200,
-    timeout = 5000,
-    jsonSchema,
-  } = opts;
+  const { system, user, maxTokens = 200, timeout = 5000, jsonSchema } = opts;
 
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
 
     const body: Record<string, unknown> = {
-      model,
+      model: modelFor("anthropic-api", opts),
       max_tokens: maxTokens,
       messages: [{ role: "user", content: user }],
     };
@@ -787,20 +844,11 @@ async function inferenceViaApi(opts: InferenceOptions): Promise<InferenceResult>
 // structured-output schema for JSON-mode callers.
 // ─────────────────────────────────────────────────────────────────────────────
 
-const OPENAI_DEFAULT_MODEL = "gpt-5.4-mini";
-
 async function inferenceViaOpenAiApi(opts: InferenceOptions): Promise<InferenceResult> {
-  const apiKey = process.env.PAL_OPENAI_API_KEY;
+  const apiKey = withPalEnv().PAL_OPENAI_API_KEY;
   if (!apiKey) return { success: false };
 
-  const {
-    system,
-    user,
-    model = OPENAI_DEFAULT_MODEL,
-    maxTokens = 500,
-    timeout = 15000,
-    jsonSchema,
-  } = opts;
+  const { system, user, maxTokens = 500, timeout = 15000, jsonSchema } = opts;
 
   try {
     const controller = new AbortController();
@@ -811,7 +859,7 @@ async function inferenceViaOpenAiApi(opts: InferenceOptions): Promise<InferenceR
     messages.push({ role: "user", content: user });
 
     const body: Record<string, unknown> = {
-      model,
+      model: modelFor("openai-api", opts),
       max_tokens: maxTokens,
       messages,
     };

package/src/hooks/lib/log.ts

@@ -72,6 +72,8 @@ export interface HookErrorGroup {
   count: number;
   last: string;
   lastAt: number;
+  /** The newest error's whole message, for tags `last` trims away. */
+  lastMessage?: string;
 }
 
 interface LoggedError {
@@ -97,8 +99,11 @@ function readAllLogs(): string {
     .join("\n");
 }
 
+const LOGGED_LINE = /^\[(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})\] /;
+const ERROR_LINE = new RegExp(`${LOGGED_LINE.source}ERROR `);
+
 function loggedAt(line: string): number {
-  const match = /^\[(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})\]/.exec(line);
+  const match = LOGGED_LINE.exec(line);
   return match ? Date.parse(`${match[1]}T${match[2]}Z`) : 0;
 }
 
@@ -114,7 +119,8 @@ function groupBySource(errors: LoggedError[]): HookErrorGroup[] {
     const source = /^([^:]+):/.exec(message)?.[1] ?? "unknown";
     const group = groups.get(source) ?? { source, count: 0, last: "", lastAt: 0 };
     group.count++;
-    group.last = whatTheAgentSaid(message.slice(source.length + 1).trim()).slice(0, 120);
+    group.lastMessage = message.slice(source.length + 1).trim();
+    group.last = whatTheAgentSaid(group.lastMessage).slice(0, 120);
     group.lastAt = at;
     groups.set(source, group);
   }
@@ -125,10 +131,10 @@ export function recentHookErrors(now: number = Date.now()): HookErrorGroup[] {
   try {
     const recent = readAllLogs()
       .split("\n")
-      .filter((line) => line.includes("] ERROR ") && loggedAt(line) > now - DAY_MS)
+      .filter((line) => ERROR_LINE.test(line) && loggedAt(line) > now - DAY_MS)
       .map((line) => ({
         at: loggedAt(line),
-        message: line.replace(/^\[.*?\] ERROR /, ""),
+        message: line.replace(ERROR_LINE, ""),
       }));
     return groupBySource(recent);
   } catch {

package/src/hooks/lib/models.ts

@@ -8,6 +8,40 @@ export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
 export const SONNET_MODEL = "claude-sonnet-5";
 export const FABLE_MODEL = "claude-fable-5";
 
+export type InferenceTier = "small" | "medium";
+
+export type FixedModelRoute =
+  | "claude-spawn"
+  | "anthropic-api"
+  | "codex-spawn"
+  | "openai-api";
+
+const ANTHROPIC_MODELS = { small: HAIKU_MODEL, medium: SONNET_MODEL };
+const OPENAI_MODELS = { small: "gpt-6-luna", medium: "gpt-6-sol" };
+
+/**
+ * opencode's models come from the user's own config (opencodeTierModel). Copilot and
+ * Cursor are absent on purpose: which named models they accept depends on the user's
+ * plan, and a free plan refuses every one but Auto.
+ */
+const INFERENCE_MODELS: Record<FixedModelRoute, Record<InferenceTier, string>> = {
+  "claude-spawn": ANTHROPIC_MODELS,
+  "anthropic-api": ANTHROPIC_MODELS,
+  "codex-spawn": OPENAI_MODELS,
+  "openai-api": OPENAI_MODELS,
+};
+
+export function isFixedModelRoute(route: string): route is FixedModelRoute {
+  return Object.hasOwn(INFERENCE_MODELS, route);
+}
+
+export function inferenceModel(
+  route: FixedModelRoute,
+  tier: InferenceTier = "small"
+): string {
+  return INFERENCE_MODELS[route][tier];
+}
+
 /**
  * Per-agent flagship model used to AUTHOR new skills (via `create-skill`).
  *

package/src/hooks/lib/opencode-config.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import type { InferenceTier } from "./models";
 import { platform } from "./paths";
 
 const GLOBAL_CONFIG_FILES = ["config.json", "opencode.json", "opencode.jsonc"];
@@ -17,19 +18,29 @@ function readConfig(name: string): OpencodeConfig | null {
   }
 }
 
-function pinnedModel(config: OpencodeConfig | null): string | null {
-  return typeof config?.model === "string" && config.model ? config.model : null;
+function pinnedModel(config: OpencodeConfig | null, key = "model"): string | null {
+  const value = config?.[key];
+  return typeof value === "string" && value ? value : null;
 }
 
-/** Without a pinned model, `opencode run` falls back to whatever was last picked in the TUI. */
-export function opencodeBackgroundModel(): string | null {
+function firstPinned(key: string): string | null {
   for (const name of GLOBAL_CONFIG_FILES) {
-    const model = pinnedModel(readConfig(name));
+    const model = pinnedModel(readConfig(name), key);
     if (model) return model;
   }
   return null;
 }
 
+/** Without a pinned model, `opencode run` falls back to whatever was last picked in the TUI. */
+export function opencodeBackgroundModel(): string | null {
+  return firstPinned("model");
+}
+
+export function opencodeTierModel(tier: InferenceTier): string | null {
+  const small = tier === "small" ? firstPinned("small_model") : null;
+  return small ?? opencodeBackgroundModel();
+}
+
 function withoutInstructions(config: OpencodeConfig): OpencodeConfig {
   const { instructions: _, ...rest } = config;
   return rest;

package/src/hooks/lib/pal-env.ts

@@ -0,0 +1,51 @@
+/**
+ * Credentials PAL reads from ~/.pal/.env. A variable already set in the
+ * environment wins; the file fills the gaps. Agents launched from a desktop
+ * app never read a shell profile, so hooks they spawn see only this file.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+type Env = Record<string, string | undefined>;
+
+export function palEnvPath(): string {
+  return resolve(palHome(), ".env");
+}
+
+function withoutExportPrefix(line: string): string {
+  return line.startsWith("export ") ? line.slice("export ".length).trimStart() : line;
+}
+
+function unquoted(value: string): string {
+  return value.replace(/^["']|["']$/g, "");
+}
+
+export function parsePalEnv(content: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const raw of content.split("\n")) {
+    const line = withoutExportPrefix(raw.trim());
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    values[line.slice(0, eq).trim()] = unquoted(line.slice(eq + 1).trim());
+  }
+  return values;
+}
+
+export function readPalEnvFile(): Record<string, string> {
+  try {
+    return parsePalEnv(readFileSync(palEnvPath(), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function withPalEnv(env: Env = process.env): Env {
+  const merged: Env = { ...env };
+  for (const [key, value] of Object.entries(readPalEnvFile())) {
+    if (!merged[key]) merged[key] = value;
+  }
+  return merged;
+}

package/src/hooks/lib/paths.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 
 /**
  * Turn a path string that came from outside — argv, a flag, an env override, a
@@ -36,6 +36,12 @@ export function namesAPath(input: string): boolean {
   return input.startsWith("~") || input.includes("/") || input.includes("\\");
 }
 
+/** Compared as paths, not strings — a separator differs by platform. */
+export function isInside(parent: string, target: string): boolean {
+  const rel = relative(parent, target);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
 /** An env override names a path the same way a flag does, so it gets the same treatment. */
 function envPath(name: string, fallback: string): string {
   const override = process.env[name];

package/src/targets/agent-render.ts

@@ -0,0 +1,103 @@
+/**
+ * Renders one merged subagent definition into the file each agent reads:
+ * Markdown with that platform's frontmatter, or a Codex agent-role TOML.
+ */
+
+import {
+  type AgentDefinition,
+  type AgentPlatform,
+  parseAgentDefinition,
+} from "../hooks/lib/agent-definition";
+
+const CODEX_OWNED_KEYS = new Set(["name", "description", "developer_instructions"]);
+
+export function agentFileName(stem: string, platform: AgentPlatform): string {
+  return `${stem}.${platform === "codex" ? "toml" : "md"}`;
+}
+
+export function renderAgentForPlatform(content: string, platform: AgentPlatform): string {
+  const definition = parseAgentDefinition(content);
+  if (platform === "codex") return renderCodexAgent(definition);
+  if (!definition.hasFrontmatter) return content;
+  const frontmatter = [...definition.global, ...(definition.platforms[platform] ?? [])];
+  return `---\n${frontmatter.join("\n")}\n---${definition.body}`;
+}
+
+function renderCodexAgent(definition: AgentDefinition): string {
+  if (!definition.hasFrontmatter)
+    throw new Error("no frontmatter to build a Codex agent from");
+  const { name, description, ...unmapped } = yamlMapping(
+    definition.global,
+    "frontmatter"
+  );
+  rejectUnmappedGlobals(Object.keys(unmapped));
+  const overrides = Object.entries(
+    yamlMapping(definition.platforms.codex ?? [], "codex block")
+  );
+  const instructions = `${definition.body.trim()}\n`;
+  const lines = [
+    `name = ${tomlString(requiredText(name, "name"))}`,
+    `description = ${tomlString(requiredText(description, "description"))}`,
+    ...overrides.map(
+      ([key, value]) => `${tomlKey(key)} = ${codexOverrideValue(key, value)}`
+    ),
+    `developer_instructions = ${tomlText(instructions)}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function yamlMapping(lines: string[], where: string): Record<string, unknown> {
+  if (lines.length === 0) return {};
+  const parsed = Bun.YAML.parse(lines.join("\n"));
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`the ${where} is not a YAML mapping`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function rejectUnmappedGlobals(keys: string[]): void {
+  if (keys.length === 0) return;
+  throw new Error(
+    `Codex has no field for global ${keys.join(", ")}; move it into a platform block`
+  );
+}
+
+function requiredText(value: unknown, field: string): string {
+  if (typeof value === "string" && value.trim()) return value;
+  throw new Error(`Codex needs a non-empty ${field}`);
+}
+
+function codexOverrideValue(key: string, value: unknown): string {
+  if (CODEX_OWNED_KEYS.has(key)) {
+    throw new Error(
+      `codex.${key} is built from the shared definition and cannot be overridden`
+    );
+  }
+  if (typeof value === "string") return tomlString(value);
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return `[${value.map(tomlString).join(", ")}]`;
+  }
+  throw new Error(`codex.${key} must be a string, number, boolean or list of strings`);
+}
+
+function tomlKey(key: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
+}
+
+function tomlString(value: string): string {
+  return JSON.stringify(value).replaceAll("\u007f", String.raw`\u007f`);
+}
+
+function tomlText(text: string): string {
+  return fitsLiteralString(text) ? `'''\n${text}'''` : tomlString(text);
+}
+
+function fitsLiteralString(text: string): boolean {
+  if (text.includes("'''")) return false;
+  return Array.from(text).every((char) => {
+    const code = char.charCodeAt(0);
+    return char === "\t" || char === "\n" || (code >= 0x20 && code !== 0x7f);
+  });
+}

package/src/targets/codex/install.ts

@@ -1,7 +1,7 @@
 /**
  * PAL — Codex target installer
  * Merges PAL hooks into ~/.codex/hooks.json (never overwrites user hooks).
- * Symlinks skills. Ensures AGENTS.md symlink via regenerateIfNeeded().
+ * Symlinks skills, renders agents to TOML. Ensures AGENTS.md symlink via regenerateIfNeeded().
  */
 
 import {
@@ -15,6 +15,7 @@ import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
   addCodexStatuslineConfig,
+  copyAgentsForCodex,
   copySkills,
   countSkills,
   loadCodexHooksTemplate,
@@ -101,6 +102,10 @@ const codexSkillsDir = resolve(CODEX_DIR, "skills");
 copySkills(codexSkillsDir);
 log.success(`${countSkills()} skills → ~/.codex/skills/`);
 
+// --- Render agents to ~/.codex/agents/ ---
+const agentCount = copyAgentsForCodex(resolve(CODEX_DIR, "agents"));
+log.success(`${agentCount} agents → ~/.codex/agents/`);
+
 // --- Enable hooks in config.toml ---
 const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
 enableCodexHooks(CONFIG_FILE);