portable-agent-layer 0.85.24 → 0.86.0

package/src/hooks/lib/inference.ts

@@ -39,15 +39,16 @@ import {
   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 =
@@ -304,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
@@ -317,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 });
   }
@@ -653,7 +681,8 @@ async function singleCliAttempt(
 
 interface SpawnPlace {
   cwd?: string;
-  env?: Record<string, string>;
+  env?: Record<string, string | undefined>;
+  logTag?: string;
 }
 
 /**
@@ -670,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, "");
@@ -746,7 +777,7 @@ 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, maxTokens = 200, timeout = 5000, jsonSchema } = opts;
@@ -814,7 +845,7 @@ async function inferenceViaApi(opts: InferenceOptions): Promise<InferenceResult>
 // ─────────────────────────────────────────────────────────────────────────────
 
 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, maxTokens = 500, timeout = 15000, jsonSchema } = opts;

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/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);

package/src/targets/codex/uninstall.ts

@@ -1,7 +1,7 @@
 /**
  * PAL — Codex uninstaller
  * Removes only PAL-owned hooks from ~/.codex/hooks.json. Preserves user hooks.
- * Removes PAL skill symlinks.
+ * Removes PAL skill symlinks and PAL agents.
  */
 
 import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -11,6 +11,7 @@ import {
   loadCodexHooksTemplate,
   log,
   readJson,
+  removeAgentsFromCodex,
   removeCodexStatuslineConfig,
   removeSkills,
   unmergeCodexHooks,
@@ -87,6 +88,12 @@ if (removed.length > 0) {
   log.info("No PAL skills found");
 }
 
+// --- Remove PAL agents ---
+const removedAgents = removeAgentsFromCodex(resolve(CODEX_DIR, "agents"));
+if (removedAgents.length > 0) {
+  log.success(`Removed ${removedAgents.length} agent(s): ${removedAgents.join(", ")}`);
+}
+
 // --- Disable hooks in config.toml ---
 const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
 disableCodexHooks(CONFIG_FILE);

package/src/targets/lib.ts

@@ -18,8 +18,10 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { AGENT_PLATFORMS, type AgentPlatform } from "../hooks/lib/agent-definition";
 import { assets, palHome, platform } from "../hooks/lib/paths";
 import { declaredTriggers } from "../hooks/lib/skill-triggers";
+import { agentFileName, renderAgentForPlatform } from "./agent-render";
 
 // --- Colored logging ---
 
@@ -993,7 +995,7 @@ export function removeSkills(claudeSkillsDir: string): string[] {
 
 // --- Agents ---
 
-const claudeAgentsDir = () => resolve(platform.claudeDir(), "agents");
+const claudeAgentsDir = () => nativeAgentsDir("claude");
 
 /**
  * Install PAL agent definitions into ~/.claude/agents/.
@@ -1031,81 +1033,28 @@ export function countAgents(): number {
   }
 }
 
-// --- Agent platform extraction ---
+// --- Agent platform rendering ---
 
-const AGENT_PLATFORMS = ["claude", "opencode", "cursor", "copilot"] as const;
-type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
-
-/**
- * Extract a platform-specific agent file from the unified agent format.
- *
- * Each agent .md defines platform blocks at the top level:
- *   claude:     → fields for Claude Code
- *   opencode:   → fields for opencode
- *   cursor:     → fields for Cursor
- *
- * Global fields (name, description) are always included.
- * The target platform block is un-indented and merged into the root.
- * All other platform blocks are stripped.
- */
-function extractAgentForPlatform(content: string, platform: AgentPlatform): string {
-  const parts = content.split(/^---\s*$/m);
-  if (parts.length < 3) return content;
-
-  const frontmatter = parts[1];
-  const body = parts.slice(2).join("---");
-
-  const globalLines: string[] = [];
-  const platformLines: Record<AgentPlatform, string[]> = {
-    claude: [],
-    opencode: [],
-    cursor: [],
-    copilot: [],
-  };
-  let currentPlatform: AgentPlatform | null = null;
-
-  for (const line of frontmatter.split("\n")) {
-    if (!line.trim()) continue;
-
-    const platformMatch = new RegExp(/^(claude|opencode|cursor|copilot):\s*$/).exec(line);
-    if (platformMatch) {
-      currentPlatform = platformMatch[1] as AgentPlatform;
-      continue;
-    }
-
-    if (currentPlatform) {
-      if (new RegExp(/^ {2}/).exec(line)) {
-        platformLines[currentPlatform].push(line.slice(2)); // un-indent one level
-        continue;
-      }
-      currentPlatform = null; // end of platform block
-    }
-
-    globalLines.push(line);
-  }
-
-  const newFrontmatter = [...globalLines, ...platformLines[platform]]
-    .filter((l) => l.trim())
-    .join("\n");
+const shippedAgentStems = () =>
+  readdirSync(assets.agents())
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""));
 
-  return `---\n${newFrontmatter}\n---\n${body}`;
-}
+const shippedAgentSource = (stem: string) =>
+  readFileSync(resolve(assets.agents(), `${stem}.md`), "utf-8");
 
 /** Install agents for a platform into a target directory. Always overwrites. */
 function installAgents(targetDir: string, platform: AgentPlatform): number {
-  const agentsDir = assets.agents();
-  if (!existsSync(agentsDir)) return 0;
+  if (!existsSync(assets.agents())) return 0;
 
   mkdirSync(targetDir, { recursive: true });
   let count = 0;
 
-  for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-    const name = file.replace(/\.md$/, "");
-    const installed = reportOnlyOnFailure(`${platform} agent ${name}`, () => {
-      const content = readFileSync(resolve(agentsDir, file), "utf-8");
+  for (const stem of shippedAgentStems()) {
+    const installed = reportOnlyOnFailure(`${platform} agent ${stem}`, () => {
       writeFileSync(
-        resolve(targetDir, file),
-        extractAgentForPlatform(content, platform),
+        resolve(targetDir, agentFileName(stem, platform)),
+        renderAgentForPlatform(shippedAgentSource(stem), platform),
         "utf-8"
       );
     });
@@ -1114,18 +1063,31 @@ function installAgents(targetDir: string, platform: AgentPlatform): number {
   return count;
 }
 
+/** Shipped agents in targetDir that differ from what installAgents would write there. */
+export function staleShippedAgents(targetDir: string, agent: AgentPlatform): string[] {
+  if (!existsSync(assets.agents())) return [];
+  const isStale = (stem: string) => {
+    const installed = resolve(targetDir, agentFileName(stem, agent));
+    return (
+      !existsSync(installed) ||
+      readFileSync(installed, "utf-8") !==
+        renderAgentForPlatform(shippedAgentSource(stem), agent)
+    );
+  };
+  return shippedAgentStems().filter(isStale).sort();
+}
+
 /** Remove PAL agents from a directory. */
-function uninstallAgents(targetDir: string, label: string): string[] {
-  const agentsDir = assets.agents();
-  if (!existsSync(agentsDir)) return [];
+function uninstallAgents(targetDir: string, platform: AgentPlatform): string[] {
+  if (!existsSync(assets.agents())) return [];
 
   const removed: string[] = [];
-  for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-    const dst = resolve(targetDir, file);
+  for (const stem of shippedAgentStems()) {
+    const dst = resolve(targetDir, agentFileName(stem, platform));
     if (existsSync(dst)) {
       unlinkSync(dst);
-      removed.push(file.replace(/\.md$/, ""));
-      log.detail(`Removed ${label} agent: ${file.replace(/\.md$/, "")}`);
+      removed.push(stem);
+      log.detail(`Removed ${platform} agent: ${stem}`);
     }
   }
   return removed;
@@ -1147,6 +1109,10 @@ export function copyAgentsForCopilot(copilotAgentsDir: string): number {
   return installAgents(copilotAgentsDir, "copilot");
 }
 
+export function copyAgentsForCodex(codexAgentsDir: string): number {
+  return installAgents(codexAgentsDir, "codex");
+}
+
 export function removeAgentsFromCursor(cursorAgentsDir: string): string[] {
   return uninstallAgents(cursorAgentsDir, "cursor");
 }
@@ -1155,6 +1121,10 @@ export function removeAgentsFromCopilot(copilotAgentsDir: string): string[] {
   return uninstallAgents(copilotAgentsDir, "copilot");
 }
 
+export function removeAgentsFromCodex(codexAgentsDir: string): string[] {
+  return uninstallAgents(codexAgentsDir, "codex");
+}
+
 // --- Personal subagents (user-authored, under ~/.pal/agents/) ---
 
 /**
@@ -1169,12 +1139,19 @@ const palAgentsStore = () => resolve(palHome(), "agents");
  * exists (mirrors linkPersonalSkill's per-agent gate).
  */
 function personalSubagentTargets(): { agent: AgentPlatform; dir: string }[] {
-  return [
-    { agent: "claude", dir: resolve(platform.claudeDir(), "agents") },
-    { agent: "opencode", dir: resolve(platform.opencodeDir(), "agents") },
-    { agent: "cursor", dir: resolve(platform.cursorDir(), "agents") },
-    { agent: "copilot", dir: resolve(platform.copilotDir(), "agents") },
-  ];
+  return AGENT_PLATFORMS.map((agent) => ({ agent, dir: nativeAgentsDir(agent) }));
+}
+
+/** The directory each agent reads its subagent definitions from. */
+export function nativeAgentsDir(agent: AgentPlatform): string {
+  const home = {
+    claude: platform.claudeDir,
+    opencode: platform.opencodeDir,
+    cursor: platform.cursorDir,
+    copilot: platform.copilotDir,
+    codex: platform.codexDir,
+  }[agent];
+  return resolve(home(), "agents");
 }
 
 /** Names of the subagents PAL ships (assets/agents/*.md). */
@@ -1215,17 +1192,23 @@ export function installPersonalSubagent(name: string): string[] {
     );
   }
   const content = readFileSync(src, "utf-8");
-  const installed: string[] = [];
-  for (const { agent, dir } of personalSubagentTargets()) {
-    if (!existsSync(dir)) continue; // agent not installed
-    writeFileSync(
-      resolve(dir, `${name}.md`),
-      extractAgentForPlatform(content, agent),
-      "utf-8"
-    );
-    installed.push(agent);
+  const renders = personalSubagentTargets()
+    .filter(({ dir }) => existsSync(dir))
+    .map(({ agent, dir }) => ({
+      agent,
+      file: resolve(dir, agentFileName(name, agent)),
+      text: renderForPersonalSubagent(content, agent),
+    }));
+  for (const { file, text } of renders) writeFileSync(file, text, "utf-8");
+  return renders.map(({ agent }) => agent);
+}
+
+function renderForPersonalSubagent(content: string, agent: AgentPlatform): string {
+  try {
+    return renderAgentForPlatform(content, agent);
+  } catch (e) {
+    throw new Error(`Cannot build the ${agent} subagent: ${(e as Error).message}`);
   }
-  return installed;
 }
 
 /** Load and resolve the Copilot hooks template, substituting PKG_ROOT */

package/src/tools/control-room/static.ts

@@ -6,7 +6,8 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
+import { isInside } from "../../hooks/lib/paths";
 
 const UI_DIST = resolve(import.meta.dir, "ui", "dist");
 
@@ -57,12 +58,6 @@ export function indexHtml(): Response {
  */
 export function staticAsset(pathname: string): Response | null {
   const target = resolve(UI_DIST, `.${pathname}`);
-  if (!isInsideDist(target)) return null;
+  if (!isInside(UI_DIST, target)) return null;
   return existsSync(target) ? new Response(Bun.file(target)) : null;
 }
-
-/** Compared as paths, not strings — a separator differs by platform. */
-function isInsideDist(target: string): boolean {
-  const rel = relative(UI_DIST, target);
-  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
-}