portable-agent-layer 0.85.24 → 0.86.0

package/README.md

@@ -137,6 +137,12 @@ PAL routes inference through the host agent's subscription CLI by default. API k
 | `PAL_GEMINI_API_KEY` | For YouTube video analysis and web search skill |
 | `PAL_XAI_API_KEY` | For Grok real-time research skill (X/web search) |
 | `PAL_PERPLEXITY_API_KEY` | For Perplexity deep research skill |
+| `PAL_FYZZ_API_KEY` | For the Fyzz Chat skill |
+| `PAL_FYZZ_BASE_URL` | Fyzz Chat server for that skill (default: `http://localhost:3000`) |
+
+### `~/.pal/.env`
+
+Agents launched from a desktop app never read your shell profile, so the hooks they spawn cannot see variables exported there. PAL's background inference and the skills shipped with PAL also read `~/.pal/.env`, one `KEY=value` per line (`export KEY=value` works too); a variable already set in the environment wins. Put `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`) and the API keys above there; `pal cli doctor` warns about any of the API keys above still set in your shell. Personal skills made with `create-skill` never receive the file. It stays on this machine: `pal cli export` never includes it.
 
 ### Path overrides
 
@@ -225,7 +231,7 @@ Your setup should be able to travel with you.
 ## Features
 
 - **Cross-platform**: works on Windows, macOS, and Linux
-- **Cross-agent**: full support for Claude Code, opencode, Cursor, GitHub Copilot, and Codex (Codex still lacks subagents)
+- **Cross-agent**: full support for Claude Code, opencode, Cursor, GitHub Copilot, and Codex
 - **Subscription-first inference**: background inference routes through whichever subscription CLI is active — no API key needed by default
 - **Portable knowledge**: export and import accumulated knowledge
 - **A morning screen, not a dashboard**: `pal cli server` ranks your projects *and* your written goals in one urgent/important grid. Urgency is read off the files — blockers, an unfinished handoff, a date in a next step, an important thing gone quiet. Importance comes from one fact per project: whether it serves a goal you wrote down, is a way the work could pay, or is kept for its own sake. PAL guesses that once at session stop; you correct it on the page or with `project.ts serves <name> goal|revenue|fun`, and the correction survives every later guess

package/assets/agents/gemini-researcher.md

@@ -29,7 +29,7 @@ pal cli skill run deep-research gemini-search -- "<query>"
 ```
 
 - If it returns results → **continue using Gemini Search** for remaining queries
-- If it errors about `PAL_GEMINI_API_KEY` → **fall back to WebSearch/WebFetch** for all queries using the fallback methodology below
+- If it errors about `PAL_GEMINI_API_KEY` → **fall back to WebSearch/WebFetch** for all queries using the fallback methodology below, and **set a flag** to include the fallback footnote in your output
 
 The tool has a built-in academic system prompt that prioritizes scholarly sources, but you should still craft queries to target academic content:
 - Include author names, paper titles, or venue names when known
@@ -83,5 +83,5 @@ If you fell back to WebSearch because the Gemini API was unavailable, you MUST a
 
 ```markdown
 ---
-> **Note:** This research used WebSearch fallback instead of Gemini Search. The `PAL_GEMINI_API_KEY` environment variable is not set. To enable Gemini-grounded search, set the key: `export PAL_GEMINI_API_KEY=...` (get one at https://aistudio.google.com/apikey)
+> **Tell the user:** This research used WebSearch fallback instead of Gemini Search. The `PAL_GEMINI_API_KEY` environment variable is not set. To enable Gemini-grounded search, add `PAL_GEMINI_API_KEY=...` to `~/.pal/.env` (get one at https://aistudio.google.com/apikey)
 ```

package/assets/agents/grok-researcher.md

@@ -52,7 +52,7 @@ If the grok-search tool fails (missing `PAL_XAI_API_KEY` or API error), fall bac
 1. **Search** using WebSearch with time-sensitive queries — prepend "2026" or "latest" or "today" to queries
 2. **Prioritize** news sources, social media aggregators, and live blogs
 3. **Fetch** the most recent results with WebFetch to extract detail
-4. **Note** in your output that you used the fallback path (no Grok API access)
+4. **Set a flag** to include the fallback footnote in your output
 
 ## Methodology
 
@@ -105,5 +105,5 @@ If you fell back to WebSearch because the Grok API was unavailable, you MUST app
 
 ```markdown
 ---
-> **Note:** This research used WebSearch fallback instead of Grok Search. The `PAL_XAI_API_KEY` environment variable is not set. To enable Grok real-time search, set the key: `export PAL_XAI_API_KEY=...` (get one at https://console.x.ai/)
+> **Tell the user:** This research used WebSearch fallback instead of Grok Search. The `PAL_XAI_API_KEY` environment variable is not set. To enable Grok real-time search, add `PAL_XAI_API_KEY=...` to `~/.pal/.env` (get one at https://console.x.ai/)
 ```

package/assets/agents/perplexity-researcher.md

@@ -77,5 +77,5 @@ If you fell back to WebSearch because the Perplexity API was unavailable, you MU
 
 ```markdown
 ---
-> **Note:** This research used WebSearch fallback instead of Perplexity Search. The `PAL_PERPLEXITY_API_KEY` environment variable is not set. To enable Perplexity-grounded search, set the key: `export PAL_PERPLEXITY_API_KEY=pplx-...` (get one at https://www.perplexity.ai/settings/api)
+> **Tell the user:** This research used WebSearch fallback instead of Perplexity Search. The `PAL_PERPLEXITY_API_KEY` environment variable is not set. To enable Perplexity-grounded search, add `PAL_PERPLEXITY_API_KEY=pplx-...` to `~/.pal/.env` (get one at https://www.perplexity.ai/settings/api)
 ```

package/assets/agents/subagent-author.md

@@ -29,7 +29,7 @@ You author a single new personal subagent for this user. You are handed a **suba
    cat ~/.pal/skills/create-subagent/authoring-guide.md
    ```
 2. Validate the name: lowercase-kebab, no spaces. It must not collide with an existing personal subagent (`pal cli subagent list`) or a shipped one. If it collides or is malformed, stop and report the conflict instead of overwriting.
-3. Write `~/.pal/agents/<name>.md` (create `~/.pal/agents/` if missing), populated per the guide's merged schema: global `name` + `description`, then only the platform blocks that matter (`claude:`, `opencode:`, `cursor:`, `copilot:`), then the system prompt body. Remember: `skills:` is Claude-only and preloads — for other agents, name intended skills in the body.
+3. Write `~/.pal/agents/<name>.md` (create `~/.pal/agents/` if missing), populated per the guide's merged schema: global `name` + `description`, then only the platform blocks that matter (`claude:`, `opencode:`, `cursor:`, `copilot:`, `codex:`), then the system prompt body. Remember: `skills:` is Claude-only and preloads — for other agents, name intended skills in the body.
 4. Install it into every installed agent:
    ```bash
    pal cli subagent link <name>

package/assets/skills/analyze-youtube/SKILL.md

@@ -44,4 +44,4 @@ Follow the user's request. Common tasks:
 - For long videos, consider asking a focused question via `--prompt` rather than a full analysis
 - Gemini sees both visuals and audio — mention on-screen content (slides, code, diagrams) when relevant
 - Quote speakers verbatim when the user asks about specific statements
-- If the tool reports a missing API key, tell the user to get one at https://aistudio.google.com/apikey and set `PAL_GEMINI_API_KEY` in their shell profile or PAL settings
+- If the tool reports a missing API key, tell the user to get one at https://aistudio.google.com/apikey and add `PAL_GEMINI_API_KEY=...` to `~/.pal/.env`

package/assets/skills/analyze-youtube/tools/youtube-analyze.ts

@@ -29,6 +29,7 @@ function loadApiKey(): string {
   if (!key) {
     console.error("Error: PAL_GEMINI_API_KEY environment variable is not set.");
     console.error("Get a free key at https://aistudio.google.com/apikey");
+    console.error("and add it to ~/.pal/.env as PAL_GEMINI_API_KEY=...");
     process.exit(1);
   }
   return key;

package/assets/skills/create-subagent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-subagent
 license: MIT
-description: "Create a user-scoped subagent for every installed agent (Claude Code, opencode, Cursor, Copilot) from one merged definition, then install and run the doctor on it. Use when the user asks to create a subagent, add a custom agent, delegate a role to a specialized agent, or \"make a subagent that…\"."
+description: "Create a user-scoped subagent for every installed agent (Claude Code, opencode, Cursor, Copilot, Codex) from one merged definition, then install and run the doctor on it. Use when the user asks to create a subagent, add a custom agent, delegate a role to a specialized agent, or \"make a subagent that…\"."
 argument-hint: <subagent name> <what it does + when to delegate>
 metadata:
   source: portable-agent-layer
@@ -38,7 +38,7 @@ cat ~/.pal/skills/create-subagent/authoring-guide.md
    cannot reasonably infer, then confirm your draft:
    - **model** — a flagship model or `inherit` the caller's model (can differ per agent).
    - **tools** — which tools it may use (a comma list for Claude/Copilot; a permission
-     map for opencode). Default: inherit all tools.
+     map for opencode; a `sandbox_mode` for Codex). Default: inherit all tools.
    - **skills** — skills to PRELOAD. Claude Code only; the other agents have no such
      field (see the guide). Record intended skills in the body for the others.
    - **system prompt** — the role and behavior. Draft it and confirm with the user.

package/assets/skills/create-subagent/authoring-guide.md

@@ -18,7 +18,9 @@ A personal subagent is stored once as `~/.pal/agents/<name>.md` with **merged
 multi-platform frontmatter**. On `pal cli subagent link <name>`, PAL splits it per
 platform and writes a native file into each installed agent's agents directory. Global
 fields (`name`, `description`) always ship; each platform block is un-indented into that
-agent's frontmatter and the other blocks are stripped.
+agent's frontmatter and the other blocks are stripped. Codex is the exception in format
+only: it gets `~/.codex/agents/<name>.toml`, with the body as `developer_instructions`
+and the `codex:` block's keys at the top level.
 
 ```markdown
 ---
@@ -44,6 +46,10 @@ cursor:
 copilot:
   model: inherit
   tools: read, edit             # comma list
+codex:
+  model: gpt-6-sol              # omit to inherit the parent session's model
+  model_reasoning_effort: high
+  sandbox_mode: read-only       # read-only | workspace-write | danger-full-access
 ---
 
 <system prompt — second-person instructions to the subagent>
@@ -67,6 +73,12 @@ with just `name` + `description` (a valid, minimal subagent).
   field — emitting one there is ignored. If a subagent should lean on specific skills on
   those agents, name them in the system prompt body instead.
 - **cursor** — `readonly` and `is_background` are booleans (`true`/`false`).
+- **codex** — every key is optional and inherits from the parent session when omitted.
+  Values must be strings, numbers, booleans or lists of strings. Codex has **no** `tools`
+  allow-list or `skills` list (both are config tables there, and a list makes Codex skip
+  the agent); restrict access with `sandbox_mode` and name skills in the body. The
+  global frontmatter may hold only `name` and `description`, because nothing else maps
+  to a Codex key.
 
 ## What makes a good subagent
 

package/assets/skills/deep-research/SKILL.md

@@ -92,6 +92,7 @@ After collecting agent results, synthesize into:
 4. **Conflicts** — where agents disagree, with both sides presented
 5. **Gaps** — what remains unknown or needs further investigation
 6. **Sources** — deduplicated list of verified URLs from all agents
+7. **Missing API keys** — only when a researcher ended with a WebSearch fallback footnote: tell the user which researcher ran without its API, which key it needs, where to get one, and to add it to `~/.pal/.env`. One line per missing key, never dropped from the synthesis
 
 Keep total output under 1500 words unless the user asks for more.
 

package/assets/skills/deep-research/tools/gemini-search.ts

@@ -53,6 +53,7 @@ function loadApiKey(): string {
   if (!key) {
     console.error("Error: PAL_GEMINI_API_KEY environment variable is not set.");
     console.error("Get an API key at https://aistudio.google.com/apikey");
+    console.error("and add it to ~/.pal/.env as PAL_GEMINI_API_KEY=...");
     process.exit(1);
   }
   return key;

package/assets/skills/deep-research/tools/grok-search.ts

@@ -49,6 +49,7 @@ function loadApiKey(): string {
   if (!key) {
     console.error("Error: PAL_XAI_API_KEY environment variable is not set.");
     console.error("Get an API key at https://console.x.ai/");
+    console.error("and add it to ~/.pal/.env as PAL_XAI_API_KEY=...");
     process.exit(1);
   }
   return key;

package/assets/skills/deep-research/tools/perplexity-search.ts

@@ -39,7 +39,7 @@ function loadApiKey(): string {
       "Error: PAL_PERPLEXITY_API_KEY environment variable is not set.\n" +
         "The Perplexity API could not be reached. The researcher agent should fall back to WebSearch.\n" +
         "To enable Perplexity search, get an API key at https://www.perplexity.ai/settings/api\n" +
-        "and set it: export PAL_PERPLEXITY_API_KEY=pplx-..."
+        "and add it to ~/.pal/.env as PAL_PERPLEXITY_API_KEY=pplx-..."
     );
     process.exit(1);
   }

package/assets/skills/fyzz-chat-api/SKILL.md

@@ -41,8 +41,8 @@ pal cli skill run fyzz-chat-api fyzz-api -- projects
 If the tool reports a missing API key:
 
 1. Ask the user to create one in Fyzz Chat → Settings → API Keys
-2. They should set `PAL_FYZZ_API_KEY` in their shell profile or in PAL's `settings.json` env section
-3. Optionally set `PAL_FYZZ_BASE_URL` (defaults to `http://localhost:3000`)
+2. They should add `PAL_FYZZ_API_KEY=...` to `~/.pal/.env`
+3. Optionally add `PAL_FYZZ_BASE_URL=...` there too (defaults to `http://localhost:3000`)
 
 ## Guidelines
 

package/assets/skills/fyzz-chat-api/tools/fyzz-api.ts

@@ -17,7 +17,7 @@ function loadApiKey(): string {
   const key = process.env.PAL_FYZZ_API_KEY;
   if (!key) {
     console.error("Error: PAL_FYZZ_API_KEY environment variable is not set.");
-    console.error("Set it in your shell profile or PAL settings.json env section.");
+    console.error("Add it to ~/.pal/.env as PAL_FYZZ_API_KEY=...");
     process.exit(1);
   }
   return key;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.85.24",
+  "version": "0.86.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/doctor/agents.ts

@@ -1,7 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
+import type { AgentPlatform } from "../../hooks/lib/agent-definition";
 import { palPkg, platform } from "../../hooks/lib/paths";
+import { nativeAgentsDir, staleShippedAgents } from "../../targets/lib";
 import { NO_SESSION_AGENT_MESSAGE } from "../session-agent";
 import { type Finding, type Fix, failing, optional, passed, warning } from "./finding";
 
@@ -274,6 +276,18 @@ function opencodePluginFindings(): Finding[] {
   return [passed("opencode.hooks", "opencode plugin installed and current")];
 }
 
+function subagentFinding(agent: AgentPlatform): Finding {
+  const label = LAYOUT[agent].label;
+  const stale = staleShippedAgents(nativeAgentsDir(agent), agent);
+  if (stale.length === 0)
+    return passed(`${agent}.subagents`, `${label}: subagents match this PAL version`);
+  return warning(
+    `${agent}.subagents`,
+    `${label}: installed subagents differ from this PAL version — ${stale.join(", ")}`,
+    reinstall(agent)
+  );
+}
+
 function countSkills(dir: string): number {
   if (!existsSync(dir)) return 0;
   return readdirSync(dir).filter((f) => existsSync(resolve(dir, f, "SKILL.md"))).length;
@@ -290,7 +304,8 @@ function oneAgentFindings(agent: AgentName): Finding[] {
   findings.push(
     ...(layout.hookFile
       ? hookFindings(agent, layout.hookFile())
-      : opencodePluginFindings())
+      : opencodePluginFindings()),
+    subagentFinding(agent)
   );
   if (layout.instructions) {
     const { file, name } = layout.instructions;

package/src/cli/doctor/health.ts

@@ -1,6 +1,8 @@
 import { resolve } from "node:path";
 import { cachedStatus, type UpdateCache } from "../../hooks/handlers/update-check";
+import { loggedClaudeAuthMode } from "../../hooks/lib/inference";
 import { type HookErrorGroup, recentHookErrors } from "../../hooks/lib/log";
+import { palEnvPath } from "../../hooks/lib/pal-env";
 import { palHome } from "../../hooks/lib/paths";
 import { checkPendingMigrations } from "../migrate";
 import { type Finding, failing, passed, warning } from "./finding";
@@ -13,7 +15,6 @@ interface PendingMigration {
 
 interface ErrorContext {
   now: number;
-  env: Record<string, string | undefined>;
 }
 
 const CLAUDE_LOGIN_EXPIRED = /Failed to authenticate/;
@@ -29,22 +30,22 @@ function claudeLoginExpiredFinding(
   context: ErrorContext
 ): Finding {
   const title = `Background calls to Claude could not log in — ${group.count} failed in the last 24h, last ${ago(group.lastAt, context.now)}: ${group.last}`;
-  if (context.env.CLAUDE_CODE_OAUTH_TOKEN)
+  if (loggedClaudeAuthMode(group.lastMessage ?? "") === "token")
     return warning(`hook-errors.${group.source}`, title, {
-      say: "CLAUDE_CODE_OAUTH_TOKEN is set — if these failures predate it, they clear 24h after the last one; if not, the token is invalid, so create a new one",
+      say: `CLAUDE_CODE_OAUTH_TOKEN was rejected — it expired or is invalid. Create a new one and replace it in ${palEnvPath()}`,
       command: "claude setup-token",
       external: true,
     });
   return failing(`hook-errors.${group.source}`, title, {
-    say: "Create a year-long token, then export it as CLAUDE_CODE_OAUTH_TOKEN in your shell profile",
-    command: "claude setup-token",
+    say: "Log the Claude CLI in again",
+    command: "claude auth login",
     external: true,
   });
 }
 
 export function hookErrorFindings(
   groups: HookErrorGroup[],
-  context: ErrorContext = { now: Date.now(), env: process.env }
+  context: ErrorContext = { now: Date.now() }
 ): Finding[] {
   if (groups.length === 0)
     return [passed("hook-errors", "No hook errors in the last 24h")];

package/src/cli/doctor/inference.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { previewInferenceRoute } from "../../hooks/lib/inference";
 import { opencodeBackgroundModel } from "../../hooks/lib/opencode-config";
+import { palEnvPath, readPalEnvFile } from "../../hooks/lib/pal-env";
 import { platform } from "../../hooks/lib/paths";
 import type { AgentName } from "./agents";
 import { type Finding, failing, optional, passed, warning } from "./finding";
@@ -14,14 +15,19 @@ const SUBPROCESS_ONLY = {
   PAL_INFERENCE_DISABLED: "every inference call fails",
 } as const;
 
-const API_KEYS = {
+const INFERENCE_KEYS = {
   PAL_ANTHROPIC_API_KEY: "fallback when the claude CLI cannot answer",
   PAL_OPENAI_API_KEY: "fallback when the codex CLI cannot answer",
-  PAL_GEMINI_API_KEY: "YouTube analysis and Gemini research",
-  PAL_XAI_API_KEY: "the Grok researcher",
-  PAL_PERPLEXITY_API_KEY: "the Perplexity researcher",
 } as const;
 
+const SKILL_KEYS = [
+  "PAL_GEMINI_API_KEY",
+  "PAL_XAI_API_KEY",
+  "PAL_PERPLEXITY_API_KEY",
+  "PAL_FYZZ_API_KEY",
+  "PAL_FYZZ_BASE_URL",
+] as const;
+
 function unsetCommand(name: string, os: NodeJS.Platform): string {
   return os === "win32" ? `Remove-Item Env:${name}` : `unset ${name}`;
 }
@@ -42,14 +48,85 @@ export function leakedEnvFindings(env: Env, os: NodeJS.Platform): Finding[] {
   );
 }
 
-export function apiKeyFindings(env: Env): Finding[] {
-  return Object.entries(API_KEYS).map(([name, unlocks]) =>
-    env[name]
-      ? passed(`key.${name}`, `${name} set`)
-      : optional(`key.${name}`, `${name} — ${unlocks}`, {
-          say: "set it in your shell profile",
-        })
+function shellKeyConsequence(shellValue: string, fileValue: string | undefined): string {
+  if (fileValue === undefined)
+    return "so agents launched outside a terminal never see it";
+  if (fileValue === shellValue) return `and duplicated in ${palEnvPath()}`;
+  return `and overrides the different value in ${palEnvPath()}`;
+}
+
+function shellKeyFinding(name: string, shellValue: string, fileValue?: string): Finding {
+  return warning(
+    `key.${name}`,
+    `${name} is set in your shell, ${shellKeyConsequence(shellValue, fileValue)}`,
+    {
+      say:
+        fileValue === undefined
+          ? `Move it to ${palEnvPath()} and remove it from your shell profile`
+          : "Remove it from your shell profile",
+    }
+  );
+}
+
+function keyFinding(
+  name: string,
+  shell: Env,
+  file: Record<string, string>,
+  ifUnset: () => Finding | null
+): Finding | null {
+  const shellValue = shell[name];
+  if (shellValue) return shellKeyFinding(name, shellValue, file[name]);
+  if (file[name]) return passed(`key.${name}`, `${name} set`);
+  return ifUnset();
+}
+
+export function apiKeyFindings(
+  shell: Env,
+  file: Record<string, string> = readPalEnvFile()
+): Finding[] {
+  const inference = Object.entries(INFERENCE_KEYS).map(([name, unlocks]) =>
+    keyFinding(name, shell, file, () =>
+      optional(`key.${name}`, `${name} — ${unlocks}`, {
+        say: `add it to ${palEnvPath()}`,
+      })
+    )
   );
+  const skills = SKILL_KEYS.map((name) => keyFinding(name, shell, file, () => null));
+  return [...inference, ...skills].filter((f): f is Finding => f !== null);
+}
+
+const OAUTH_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
+
+function isMalformedToken(value: string): boolean {
+  return value === "" || /[\s"']/.test(value);
+}
+
+/** Silent unless a token is set; it is optional, and the native login needs none of this. */
+export function oauthTokenFindings(
+  shell: Env,
+  file: Record<string, string> = readPalEnvFile()
+): Finding[] {
+  const shellToken = shell[OAUTH_TOKEN];
+  const fileToken = file[OAUTH_TOKEN];
+  if (shellToken === undefined && fileToken === undefined) return [];
+  const findings: Finding[] = [];
+  if ([shellToken, fileToken].some((t) => t !== undefined && isMalformedToken(t)))
+    findings.push(
+      warning("oauth.malformed", `${OAUTH_TOKEN} is empty or contains spaces or quotes`, {
+        say: `Paste the token from 'claude setup-token' as a bare value in ${palEnvPath()}`,
+      })
+    );
+  if (shellToken && fileToken && shellToken !== fileToken)
+    findings.push(
+      warning(
+        "oauth.shadowed",
+        `Your shell's ${OAUTH_TOKEN} differs from the one in ${palEnvPath()}, and the shell's wins`,
+        {
+          say: "Keep one copy: drop it from your shell, or have your shell read it from the file",
+        }
+      )
+    );
+  return findings.length > 0 ? findings : [passed("oauth", `${OAUTH_TOKEN} set`)];
 }
 
 type Preview = ReturnType<typeof previewInferenceRoute>;
@@ -131,5 +208,6 @@ export function inferenceFindings(agents: AgentName[]): Finding[] {
     ...(agents.includes("cursor") ? cursorFindings() : []),
     ...leakedEnvFindings(process.env, process.platform),
     ...apiKeyFindings(process.env),
+    ...oauthTokenFindings(process.env),
   ];
 }

package/src/cli/skill.ts

@@ -15,11 +15,12 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { getActiveAgent } from "../hooks/lib/agent";
 import { flagshipAuthorModel } from "../hooks/lib/models";
-import { palHome } from "../hooks/lib/paths";
+import { withPalEnv } from "../hooks/lib/pal-env";
+import { isInside, palHome, palPkg } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
 import {
   formatReport,
@@ -93,10 +94,17 @@ function runSkillTool(skill: string, tool: string, toolArgs: string[]): number {
   }
   const { status } = spawnSync("bun", [path, ...toolArgs], {
     stdio: "inherit",
+    env: isShippedTool(path) ? withPalEnv(process.env) : process.env,
   });
   return status ?? 1;
 }
 
+/** Real paths, so a personal skill symlinked from elsewhere never passes as shipped. */
+function isShippedTool(path: string): boolean {
+  const shipped = resolve(palPkg(), "assets", "skills");
+  return existsSync(shipped) && isInside(realpathSync(shipped), realpathSync(path));
+}
+
 export async function runSkill(args: string[]): Promise<number> {
   const [sub, name] = args;
 

package/src/hooks/lib/agent-definition.ts

@@ -0,0 +1,57 @@
+/**
+ * The merged multi-platform subagent format shared by assets/agents/*.md and
+ * ~/.pal/agents/*.md: global frontmatter lines, one indented block per platform,
+ * and a body that becomes the subagent's system prompt.
+ */
+
+import { splitFrontmatter } from "./frontmatter";
+
+export const AGENT_PLATFORMS = [
+  "claude",
+  "opencode",
+  "cursor",
+  "copilot",
+  "codex",
+] as const;
+export type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
+
+export interface AgentDefinition {
+  hasFrontmatter: boolean;
+  global: string[];
+  platforms: Partial<Record<AgentPlatform, string[]>>;
+  body: string;
+}
+
+const PLATFORM_BLOCK_HEADER = new RegExp(
+  String.raw`^(${AGENT_PLATFORMS.join("|")}):\s*$`
+);
+const BLOCK_INDENT = "  ";
+
+export function parseAgentDefinition(content: string): AgentDefinition {
+  const split = splitFrontmatter(content);
+  if (!split) {
+    return { hasFrontmatter: false, global: [], platforms: {}, body: content };
+  }
+
+  const global: string[] = [];
+  const platforms: Partial<Record<AgentPlatform, string[]>> = {};
+  let current: AgentPlatform | null = null;
+
+  for (const line of split.frontmatter.split("\n")) {
+    if (!line.trim()) continue;
+    const header = PLATFORM_BLOCK_HEADER.exec(line);
+    if (header) {
+      current = header[1] as AgentPlatform;
+      platforms[current] ??= [];
+      continue;
+    }
+    if (current && line.startsWith(BLOCK_INDENT)) {
+      platforms[current]?.push(line.slice(BLOCK_INDENT.length));
+      continue;
+    }
+    current = null;
+    global.push(line);
+  }
+
+  return { hasFrontmatter: true, global, platforms, body: split.body };
+}

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")) {