portable-agent-layer 0.63.1 → 0.63.3

package/assets/templates/hooks.vscode.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=vscode"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=vscode"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=vscode"
+      },
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=vscode"
+      },
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=vscode"
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=vscode"
+      }
+    ]
+  }
+}

package/package.json

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

package/src/cli/index.ts

@@ -37,7 +37,7 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
 import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
-import { palHome, palPkg, platform } from "../hooks/lib/paths";
+import { palHome, palPkg, paths, platform } from "../hooks/lib/paths";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
 import { checkPendingMigrations } from "./migrate";
@@ -485,21 +485,27 @@ interface HookPrefixCheck {
   firstMissing?: string;
 }
 
-/** True when a hook command sets PAL_AGENT up front, in POSIX or PowerShell syntax. */
-function setsAgentEnvPrefix(cmd: string, agentName: string): boolean {
+/**
+ * True when a hook command names its agent, by env prefix or by argv flag.
+ *
+ * An env prefix only parses in one shell family, so hook configs whose host
+ * shell is unknown declare the agent with a shell-agnostic `--agent=` flag.
+ */
+function declaresAgent(cmd: string, agentName: string): boolean {
   return (
     cmd.startsWith(`PAL_AGENT=${agentName} `) ||
-    cmd.startsWith(`$env:PAL_AGENT='${agentName}'; `)
+    cmd.startsWith(`$env:PAL_AGENT='${agentName}'; `) ||
+    cmd.includes(`--agent=${agentName}`)
   );
 }
 
-/** Verify every command in an installed hook file sets `PAL_AGENT=<agent>` first. */
+/** Verify every command in an installed hook file names `<agent>` as its agent. */
 function checkAgentHookPrefix(filePath: string, agentName: string): HookPrefixCheck {
   if (!existsSync(filePath)) return { ok: false, total: 0, missing: 0 };
   try {
     const data = JSON.parse(readFileSync(filePath, "utf-8"));
     const commands = extractAllHookCommands(data.hooks ?? data);
-    const missing = commands.filter((c) => !setsAgentEnvPrefix(c, agentName));
+    const missing = commands.filter((c) => !declaresAgent(c, agentName));
     return {
       ok: commands.length > 0 && missing.length === 0,
       total: commands.length,
@@ -928,12 +934,12 @@ function doctor(silent = false): DoctorResult {
     ): void => {
       const r = checkAgentHookPrefix(filePath, agentName);
       if (r.ok) {
-        ok(`${agentName}: PAL_AGENT=${agentName} on all ${r.total} hook commands`);
+        ok(`${agentName}: declared on all ${r.total} hook commands`);
       } else if (r.total === 0) {
         fail(`${agentName}: hook file missing or unreadable at ${filePath}`);
       } else {
         fail(
-          `${agentName}: ${r.missing}/${r.total} hook commands missing PAL_AGENT=${agentName} prefix (run '${installCmd}')`
+          `${agentName}: ${r.missing}/${r.total} hook commands do not declare ${agentName} (run '${installCmd}')`
         );
         if (r.firstMissing) {
           log.warn(`    First offender: ${r.firstMissing}…`);
@@ -1084,6 +1090,10 @@ async function init(args: string[]) {
   log.info(`Creating PAL home at ${home}`);
   mkdirSync(resolve(home, "telos"), { recursive: true });
   mkdirSync(resolve(home, "memory"), { recursive: true });
+  // Scaffolded here, not left to generateSkillIndex: that returns early when
+  // ~/.pal/skills is absent, so an init that installs no skills would leave
+  // every writer of memory/state with nowhere to write.
+  mkdirSync(resolve(home, "memory", "state"), { recursive: true });
 
   scaffoldTelos();
 
@@ -1092,16 +1102,23 @@ async function init(args: string[]) {
   await install(targets);
 }
 
+/**
+ * Run a setup subprocess, showing its output only when it fails.
+ *
+ * These are idempotent and usually report "no changes", so their banners are
+ * pure noise on a re-install — but the moment one fails, the reason it gives
+ * is the only thing that explains the warning.
+ */
+function runQuietly(cmd: string, args: string[], cwd: string): number | null {
+  const r = spawnSync(cmd, args, { cwd, encoding: "utf-8", shell: true });
+  if (r.status !== 0) process.stderr.write((r.stdout ?? "") + (r.stderr ?? ""));
+  return r.status;
+}
+
 async function install(targets: Targets) {
   // Ensure dependencies are installed
   const pkg = palPkg();
-  log.info("Installing dependencies...");
-  const deps = spawnSync("bun", ["install", "--frozen-lockfile"], {
-    cwd: pkg,
-    stdio: "inherit",
-    shell: true,
-  });
-  if (deps.status !== 0) {
+  if (runQuietly("bun", ["install", "--frozen-lockfile"], pkg) !== 0) {
     log.warn("bun install failed — continuing anyway, but hooks may not work");
   }
 
@@ -1110,15 +1127,10 @@ async function install(targets: Targets) {
   // (used by tests to avoid a ~150MB download on every run).
   // Uses `bun x` (not `bunx`) for Windows compatibility — bunx resolves unreliably under cmd.exe.
   if (process.env.PAL_SKIP_BROWSER_INSTALL !== "1") {
-    log.info("Installing Playwright Chromium...");
-    const pw = spawnSync("bun", ["x", "playwright", "install", "chromium"], {
-      cwd: pkg,
-      stdio: "inherit",
-      shell: true,
-    });
-    if (pw.status !== 0) {
+    const pw = runQuietly("bun", ["x", "playwright", "install", "chromium"], pkg);
+    if (pw !== 0) {
       log.warn(
-        `playwright install chromium failed (exit ${pw.status}) — create-pdf and consulting-report skills won't work. Retry manually: bun x playwright install chromium`
+        `playwright install chromium failed (exit ${pw}) — create-pdf and consulting-report skills won't work. Retry manually: bun x playwright install chromium`
       );
     }
   }
@@ -1138,7 +1150,8 @@ async function install(targets: Targets) {
   }
 
   // Scaffold TELOS + PAL settings, then prompt for missing identity
-  const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
+  const { scaffoldTelos, scaffoldPalSettings, copyPalDocs, generateSkillIndex } =
+    await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
   const { promptTelos } = await import("./setup-telos");
   const { promptAttribution } = await import("./setup-attribution");
@@ -1148,6 +1161,13 @@ async function install(targets: Targets) {
   await promptTelos();
   await promptAttribution();
 
+  // Shared, target-independent state. Every target installer used to repeat these
+  // identical calls; AGENTS.md in particular must exist before any target symlinks
+  // to it, so it runs once here rather than once per target.
+  const { regenerateIfNeeded } = await import("../hooks/lib/claude-md");
+  const palDocsCount = copyPalDocs();
+  regenerateIfNeeded();
+
   if (targets.claude) {
     console.log("━━━ Claude Code ━━━");
     await import("../targets/claude/install");
@@ -1178,6 +1198,16 @@ async function install(targets: Targets) {
     console.log("");
   }
 
+  // The rest of the shared work reads what the installers just wrote: the index
+  // walks ~/.pal/skills, and the digests land in ~/.cursor/rules and
+  // ~/.copilot/instructions, which are skipped when the agent's home is absent.
+  const { writeContextDigests } = await import("../hooks/handlers/context-digests");
+  const indexedSkills = generateSkillIndex();
+  writeContextDigests();
+  log.success(
+    `Shared: ${indexedSkills} skills indexed · ${palDocsCount} docs → ~/.pal/docs/ · AGENTS.md + context digests written`
+  );
+
   log.success("Done. Existing config was preserved — only new entries were added.");
 }
 
@@ -1403,7 +1433,9 @@ async function update() {
 function cliDebug(args: string[]) {
   const stateDir = resolve(palHome(), "memory", "state");
   const flagFile = resolve(stateDir, "debug-enabled");
-  const logFile = resolve(stateDir, "debug.log");
+  // Must match log.ts's logFile() — reporting a different path sends anyone
+  // debugging a hook to an empty file.
+  const logFile = resolve(paths.debug(), "debug.log");
   const sub = args[0];
   if (sub === "on") {
     mkdirSync(stateDir, { recursive: true });

package/src/hooks/SecurityValidator.ts

@@ -1,34 +1,81 @@
 /**
  * Hook: PreToolUse — Guards against dangerous commands.
- * Returns JSON { decision: "block", reason: "..." } to block, or exits silently to allow.
+ * Emits the current agent's deny response to block, or exits silently to allow.
  *
  * Fail-open design: if anything goes wrong, the command is allowed through.
  */
 
-import { blockResponse } from "./lib/agent";
+import { blockResponse, normalizeToolUse } from "./lib/agent";
+import { logDebug } from "./lib/log";
 import { checkBashCommand, checkFilePath } from "./lib/security";
 import { readStdinJSON } from "./lib/stdin";
 
-// preToolUse shape (Claude Code + Cursor + Codex)
-interface ToolUseInput {
-  tool_name: string;
-  hook_event_name?: string; // Codex includes this in all hook inputs
-  tool_input: {
-    command?: string;
-    file_path?: string;
-  };
-}
-
-// beforeShellExecution shape (Cursor only) — flat, no tool_name wrapper
+// beforeShellExecution shape (Cursor only) — flat, no tool-name wrapper
 interface ShellExecInput {
   command: string;
   sandbox?: boolean;
 }
 
-type SecurityInput = ToolUseInput | ShellExecInput;
+type SecurityInput = Record<string, unknown> | ShellExecInput;
 
 function isShellExec(input: SecurityInput): input is ShellExecInput {
-  return !("tool_name" in input) && "command" in input;
+  return !("tool_name" in input) && !("toolName" in input) && "command" in input;
+}
+
+// A name this list misses is a command this hook waves through, so both sets mirror
+// the tool names VS Code's own Copilot build ships in its shell and edit tool sets.
+const SHELL_TOOLS = [
+  "bash",
+  "shell",
+  "powershell",
+  "local_shell",
+  "runinterminal",
+  "run_in_terminal",
+  "terminal",
+  "execute_command",
+];
+
+const FILE_WRITE_TOOLS = [
+  "write",
+  "edit",
+  "multiedit",
+  "write_file",
+  "apply_patch",
+  "applypatch",
+  "create",
+  "create_file",
+  "createfile",
+  "str_replace",
+  "str_replace_editor",
+  "insert",
+  "insert_edit_into_file",
+  "replace_string_in_file",
+  "multi_replace_string_in_file",
+  "replacestring",
+  "edit_notebook_file",
+  "notebookedit",
+];
+
+/** First of `keys` present as a non-empty string — agents disagree on argument spelling. */
+function firstStringArg(
+  args: Record<string, unknown>,
+  keys: string[]
+): string | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/** Tool names that run a shell command, across every agent's naming. */
+function runsShellCommand(toolName: string): boolean {
+  return SHELL_TOOLS.includes(toolName.toLowerCase());
+}
+
+/** Tool names that write to a file, across every agent's naming. */
+function writesFile(toolName: string): boolean {
+  return FILE_WRITE_TOOLS.includes(toolName.toLowerCase());
 }
 
 try {
@@ -44,31 +91,35 @@ try {
     process.exit(0);
   }
 
-  const hookEventName = input.hook_event_name;
+  const toolUse = normalizeToolUse(input);
+  if (!toolUse) process.exit(0);
 
-  // preToolUse — Claude: "Bash", Cursor: "Shell", Codex: "shell"
-  const isBash =
-    input.tool_name === "Bash" ||
-    input.tool_name === "Shell" ||
-    input.tool_name === "shell";
-  const isFileWrite =
-    input.tool_name === "Write" ||
-    input.tool_name === "Edit" ||
-    input.tool_name === "write_file" ||
-    input.tool_name === "apply_patch";
+  // Each agent names its shell/write tools differently; log the real name so an
+  // unrecognized one shows up here instead of silently skipping the check.
+  logDebug(
+    "SecurityValidator",
+    `toolName=${toolUse.toolName} args=${Object.keys(toolUse.toolInput).join(",")}`
+  );
 
-  if (isBash && input.tool_input.command) {
-    const reason = checkBashCommand(input.tool_input.command);
+  const command = firstStringArg(toolUse.toolInput, ["command", "commandLine", "script"]);
+  if (runsShellCommand(toolUse.toolName) && typeof command === "string") {
+    const reason = checkBashCommand(command);
+    const verdict = reason ? `BLOCK(${reason})` : "ALLOW";
+    // "No output" from a downstream tool is indistinguishable between "denied,
+    // never ran" and "ran, produced nothing" — logging the verdict here, next
+    // to the literal command, is what actually tells the two apart.
+    logDebug("SecurityValidator", `bashVerdict=${verdict} command=${command}`);
     if (reason) {
-      process.stdout.write(blockResponse(`Blocked: ${reason}`, hookEventName));
+      process.stdout.write(blockResponse(`Blocked: ${reason}`, toolUse.hookEventName));
       process.exit(0);
     }
   }
 
-  if (isFileWrite && input.tool_input.file_path) {
-    const reason = checkFilePath(input.tool_input.file_path);
+  const filePath = firstStringArg(toolUse.toolInput, ["file_path", "filePath", "path"]);
+  if (writesFile(toolUse.toolName) && typeof filePath === "string") {
+    const reason = checkFilePath(filePath);
     if (reason) {
-      process.stdout.write(blockResponse(reason, hookEventName));
+      process.stdout.write(blockResponse(reason, toolUse.hookEventName));
       process.exit(0);
     }
   }

package/src/hooks/SkillGuard.ts

@@ -9,29 +9,25 @@
  * Fail-open: on any error, the skill is allowed through.
  */
 
-import { blockResponse } from "./lib/agent";
+import { blockResponse, normalizeToolUse } from "./lib/agent";
 import { readStdinJSON } from "./lib/stdin";
 
 const BLOCKED_SKILLS = ["keybindings-help"];
 
-interface SkillInput {
-  tool_name: string;
-  tool_input: {
-    skill?: string;
-  };
-}
-
 try {
-  const input = await readStdinJSON<SkillInput>();
-  if (!input) process.exit(0);
+  const toolUse = normalizeToolUse(await readStdinJSON());
+  if (!toolUse) process.exit(0);
 
-  const skill = (input.tool_input?.skill || "").toLowerCase().trim();
+  const skill = String(toolUse.toolInput.skill ?? "")
+    .toLowerCase()
+    .trim();
 
   if (BLOCKED_SKILLS.includes(skill)) {
     process.stdout.write(
       blockResponse(
         'BLOCKED: "keybindings-help" is a known false-positive triggered by position bias. ' +
-          "The user did NOT ask about keybindings. Continue with their ACTUAL request."
+          "The user did NOT ask about keybindings. Continue with their ACTUAL request.",
+        toolUse.hookEventName
       )
     );
   }

package/src/hooks/StopOrchestrator.ts

@@ -7,7 +7,7 @@
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
-import { isCodex, isCursor } from "./lib/agent";
+import { blockResponse, isCodex, isCursor } from "./lib/agent";
 import { logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
@@ -29,8 +29,10 @@ interface StopHookInput {
 
 // Check README sync before anything else — may block the session
 try {
+  // A block carrying no reason stops the turn without telling the model why, so it
+  // is worth less than not blocking at all — require the reason to raise one.
   const decision = checkReadmeSync();
-  if (decision.decision === "block") {
+  if (decision.decision === "block" && decision.reason) {
     if (isCursor()) {
       // Cursor stop hook: followup_message auto-sends to the agent
       process.stdout.write(JSON.stringify({ followup_message: decision.reason }));
@@ -38,8 +40,9 @@ try {
       // Codex stop hook: additionalContext re-queues as next prompt
       process.stdout.write(JSON.stringify({ additionalContext: decision.reason }));
     } else {
-      // Claude Code: block decision
-      process.stdout.write(JSON.stringify(decision));
+      // Claude Code, the Copilot CLI and VS Code's own Copilot each read a
+      // different stop-block shape; VS Code ignores the top-level keys entirely.
+      process.stdout.write(blockResponse(decision.reason, "Stop"));
     }
     process.exit(0);
   }

package/src/hooks/handlers/inject-retrieval.ts

@@ -3,8 +3,8 @@
  *
  * Called from UserPromptOrchestrator. Reads the retrieval index, ranks the prompt
  * against the corpus, prints a `<system-reminder>` block to stdout (Claude Code
- * prepends UserPromptSubmit hook stdout to the prompt). Fail-closed: any error or
- * timeout produces empty output, never blocks the prompt.
+ * prepends UserPromptSubmit hook stdout to the prompt). Fail-closed: any error
+ * produces empty output, never blocks the prompt.
  */
 
 import { isCodex, isCursor } from "../lib/agent";
@@ -14,21 +14,25 @@ import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
 import { getSteeringReminder } from "../lib/steering";
 
-const TIMEOUT_MS = 250;
+const BUDGET_MS = 250;
 
-function withTimeout<T>(work: () => T, ms: number): Promise<T | null> {
-  return new Promise((resolve) => {
-    const timer = setTimeout(() => resolve(null), ms);
-    try {
-      const result = work();
-      clearTimeout(timer);
-      resolve(result);
-    } catch (err) {
-      clearTimeout(timer);
-      logError("inject-retrieval", err);
-      resolve(null);
+/** Run sync work on the prompt path, containing any throw. A synchronous call cannot
+ *  be preempted on a single thread, so the budget is measured and logged, never
+ *  enforced — an overrun still returns its result rather than being discarded.
+ *  @lintignore exported for test/inject-retrieval.test.ts */
+export function withinBudget<T>(work: () => T, ms: number): T | null {
+  const started = performance.now();
+  try {
+    return work();
+  } catch (err) {
+    logError("inject-retrieval", err);
+    return null;
+  } finally {
+    const elapsed = performance.now() - started;
+    if (elapsed > ms) {
+      logDebug("inject-retrieval", `over budget: ${elapsed.toFixed(0)}ms > ${ms}ms`);
     }
-  });
+  }
 }
 
 /** Returns the retrieval reminder string, or null if nothing to inject. @lintignore dynamically imported by opencode plugin */
@@ -36,11 +40,11 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
   if (!prompt?.trim()) return null;
   if (!isEnabled("learningInjection")) return null;
 
-  const result = await withTimeout(() => {
+  const result = withinBudget(() => {
     const index = ensureIndex();
     if (index.corpusSize === 0) return null;
     return runRetrieval(prompt, index, process.cwd());
-  }, TIMEOUT_MS);
+  }, BUDGET_MS);
 
   if (!result?.reminder) return null;
 

package/src/hooks/lib/agent.ts

@@ -11,7 +11,7 @@
  * vars are used as secondary fallbacks for environments that forward them.
  */
 
-export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode";
+export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode" | "vscode";
 
 const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
   "claude",
@@ -19,14 +19,33 @@ const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
   "codex",
   "copilot",
   "opencode",
+  "vscode",
 ]);
 
+function agentFromEnv(): AgentType | undefined {
+  const explicit = process.env.PAL_AGENT;
+  return explicit && KNOWN_AGENTS.has(explicit as AgentType)
+    ? (explicit as AgentType)
+    : undefined;
+}
+
+/**
+ * `--agent=<name>` on the hook's own command line.
+ *
+ * An `PAL_AGENT=x cmd` prefix is POSIX-only and an `$env:PAL_AGENT='x'; cmd`
+ * prefix is PowerShell-only, so a hook config that guesses the host's shell
+ * wrong fails before the hook ever runs. An argv flag is shell-agnostic.
+ */
+function agentFromArgv(): AgentType | undefined {
+  const flag = process.argv.find((a) => a.startsWith("--agent="));
+  const value = flag?.slice("--agent=".length);
+  return value && KNOWN_AGENTS.has(value as AgentType) ? (value as AgentType) : undefined;
+}
+
 /** Detect which agent is currently running PAL. Defaults to "claude". */
 export function getActiveAgent(): AgentType {
-  const explicit = process.env.PAL_AGENT;
-  if (explicit && KNOWN_AGENTS.has(explicit as AgentType)) {
-    return explicit as AgentType;
-  }
+  const declared = agentFromArgv() ?? agentFromEnv();
+  if (declared) return declared;
   if (process.env.CURSOR_VERSION) return "cursor";
   if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
   return "claude";
@@ -37,17 +56,96 @@ export const isCursor = () => getActiveAgent() === "cursor";
 export const isCodex = () => getActiveAgent() === "codex";
 export const isCopilot = () => getActiveAgent() === "copilot";
 export const isOpencode = () => getActiveAgent() === "opencode";
+const isVscode = () => getActiveAgent() === "vscode";
+
+/** Normalized preToolUse request — one shape for every agent's payload. */
+export interface ToolUseRequest {
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  hookEventName?: string;
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  return values.find((v): v is string => typeof v === "string" && v.length > 0);
+}
+
+function firstObject(...values: unknown[]): Record<string, unknown> | undefined {
+  return values.find(
+    (v): v is Record<string, unknown> => typeof v === "object" && v !== null
+  );
+}
+
+/**
+ * Normalize a preToolUse payload across agents.
+ *
+ * Claude Code, Cursor, Codex — and Copilot's VS Code-compatible mode — send
+ * snake_case `tool_name` + `tool_input`. Copilot's native CLI payload sends
+ * camelCase `toolName` + `toolArgs`. A hook reading only one shape matches
+ * nothing on the other, which for a security hook silently means "allow".
+ */
+export function normalizeToolUse(raw: unknown): ToolUseRequest | null {
+  const payload = firstObject(raw);
+  if (!payload) return null;
+  const toolName = firstString(payload.tool_name, payload.toolName);
+  if (!toolName) return null;
+  return {
+    toolName,
+    toolInput: firstObject(payload.tool_input, payload.toolArgs, payload.toolInput) ?? {},
+    hookEventName: firstString(payload.hook_event_name, payload.hookEventName),
+  };
+}
 
 /**
  * Format a "block this action" response for the current agent.
- * Claude Code:       { decision: "block", reason }
- * Cursor preToolUse: { permission: "deny", user_message }
- * Codex PreToolUse:  { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }
+ * Claude Code / VS Code: both spellings at once — see claudeBlock below
+ * Cursor preToolUse:     { permission: "deny", user_message }
+ * Copilot preToolUse:    { permissionDecision: "deny", permissionDecisionReason }
+ * Copilot agentStop:     { decision: "block", reason }
+ * Codex PreToolUse:      { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }
+ *
+ * A stop event denies the whole turn, not one tool call, so it carries a
+ * decision rather than a permission — callers must name the event to get it.
  */
+function isStopEvent(hookEventName?: string): boolean {
+  return hookEventName === "Stop" || hookEventName === "agentStop";
+}
+
+/**
+ * One payload both Claude Code and VS Code's own Copilot build accept.
+ *
+ * VS Code reads every decision from inside hookSpecificOutput and ignores the
+ * top-level keys; Claude Code reads the top-level keys and ignores the extra
+ * object (verified against `claude -p`: a turn carrying both is still blocked).
+ * Since VS Code also executes the hooks registered in ~/.claude/settings.json,
+ * carrying both spellings here is what lets one registration serve both — a
+ * second VS Code-specific hooks file made every event run twice.
+ */
+function claudeBlock(reason: string, hookEventName?: string): string {
+  return JSON.stringify({
+    decision: "block",
+    reason,
+    hookSpecificOutput: isStopEvent(hookEventName)
+      ? { hookEventName: "Stop", decision: "block", reason }
+      : {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: reason,
+        },
+  });
+}
+
 export function blockResponse(reason: string, hookEventName?: string): string {
   if (isCursor()) {
     return JSON.stringify({ permission: "deny", user_message: reason });
   }
+  if (isCopilot()) {
+    return isStopEvent(hookEventName)
+      ? JSON.stringify({ decision: "block", reason })
+      : JSON.stringify({
+          permissionDecision: "deny",
+          permissionDecisionReason: reason,
+        });
+  }
   if (isCodex() && hookEventName === "PreToolUse") {
     return JSON.stringify({
       hookSpecificOutput: {
@@ -57,5 +155,11 @@ export function blockResponse(reason: string, hookEventName?: string): string {
       },
     });
   }
+  // Only the surfaces that share ~/.claude/settings.json need both spellings.
+  // Handing the extra key to codex or opencode would be a shape they never
+  // asked to parse, for a duplication problem they don't have.
+  if (isClaude() || isVscode()) {
+    return claudeBlock(reason, hookEventName);
+  }
   return JSON.stringify({ decision: "block", reason });
 }

package/src/hooks/lib/security.ts

@@ -5,6 +5,77 @@
 
 import { lstatSync } from "node:fs";
 
+// PowerShell aliases rm, rmdir, del, erase, rd and ri all to Remove-Item, and
+// cmd ships its own rd and del — so the verb alone never says which shell ran it.
+const WIN_DELETE_VERB = "(?:remove-item|rmdir|erase|del|rd|rm|ri)";
+
+// -r through -Recurse all bind in PowerShell; cmd's rd/del spell it /s.
+const WIN_RECURSE_FLAG = String.raw`(?:-(?:r(?:e(?:c(?:u(?:r(?:se?)?)?)?)?)?f?|fr)|/s)\b`;
+
+/**
+ * A whole root, not a directory inside one. The trailing lookahead is the part
+ * that matters: without it `C:\` prefix-matches `C:\Users\rico\dist` and every
+ * ordinary recursive delete on Windows gets blocked.
+ */
+const WIN_ROOT_TARGET = String.raw`["']?(?:[a-z]:[\\/]?\*?|\\\\|~|\$home|\$env:userprofile|\$env:systemdrive)["']?(?=["'\s;,)]|$)`;
+
+const WIN_DOWNLOAD = "(?:iwr|irm|curl|wget|invoke-webrequest|invoke-restmethod)";
+const WIN_EVAL = "(?:iex|invoke-expression)";
+
+/**
+ * Something is about to be run, rather than merely named. `format` and
+ * `diskpart` are bare enough to collide with ordinary text — a PR title reading
+ * `fix: format C: handling` or `rg 'diskpart' docs/` are not disk operations.
+ * The optional wrapper keeps `powershell -c "format C:"` in scope.
+ */
+const SHELL_WRAPPER = String.raw`(?:(?:sudo|powershell(?:\.exe)?|pwsh|cmd(?:\.exe)?)\s+(?:[-/]\w+\s+)*)?`;
+const COMMAND_POSITION = String.raw`(?:^|[|;&\n({])\s*${SHELL_WRAPPER}["']?`;
+
+/**
+ * Start-Process/runas/gsudo hand the target to a flag (-FilePath, -ArgumentList)
+ * or a positional slot after other flags, in either order — COMMAND_POSITION's
+ * fixed wrapper-then-verb shape can't follow that. Since nobody launches a
+ * process via Start-Process to hold a PR title, an elevation wrapper anywhere in
+ * the command is itself enough license to drop the position anchor entirely.
+ */
+/**
+ * Both lookaheads stop at |, ; and & so they cannot reach across a command
+ * boundary — otherwise `rm -r build; echo C:\` reads as a root delete.
+ */
+const WIN_ROOT_DELETE = new RegExp(
+  String.raw`${COMMAND_POSITION}${WIN_DELETE_VERB}\b(?=[^|;&\n]*\s${WIN_RECURSE_FLAG})(?=[^|;&\n]*\s${WIN_ROOT_TARGET})`,
+  "i"
+);
+
+const WIN_FORMAT_COMMAND = new RegExp(
+  String.raw`${COMMAND_POSITION}format(?:\s+["']?[a-z]:|-volume\b)`,
+  "i"
+);
+const WIN_DISKPART_COMMAND = new RegExp(String.raw`${COMMAND_POSITION}diskpart\b`, "i");
+
+/**
+ * Start-Process/runas/gsudo hand the target to a flag (-FilePath, -ArgumentList)
+ * or a positional slot after other flags, in either order — COMMAND_POSITION's
+ * fixed wrapper-then-verb shape can't follow that, and a single combined regex
+ * can't either: a lookahead only sees forward from the verb, so it misses
+ * `Start-Process -Verb RunAs -FilePath diskpart` where the wrapper comes first.
+ * Two independent whole-string checks (wrapper present, threat present anywhere)
+ * sidestep the ordering problem entirely. Nobody launches a process via
+ * Start-Process to hold a PR title, so no position anchor is needed here.
+ */
+const WIN_ELEVATION_WRAPPER = /\b(?:start-process|runas|gsudo)\b/i;
+const WIN_ELEVATED_THREATS: [RegExp, string][] = [
+  [
+    new RegExp(
+      String.raw`\b${WIN_DELETE_VERB}\b(?=[^|;&\n]*\s${WIN_RECURSE_FLAG})(?=[^|;&\n]*\s${WIN_ROOT_TARGET})`,
+      "i"
+    ),
+    "Recursive delete of a drive root or home",
+  ],
+  [/\bformat(?:\s+["']?[a-z]:|-volume\b)/i, "Disk format"],
+  [/\bdiskpart\b/i, "Disk partitioning"],
+];
+
 /** Dangerous command patterns — always blocked */
 const BLOCKED_COMMANDS: [RegExp, string][] = [
   [/rm\s+-rf\s+[/~]/, "Recursive delete of root or home"],
@@ -15,6 +86,20 @@ const BLOCKED_COMMANDS: [RegExp, string][] = [
   [/:\(\)\{\s*:\|:&\s*\};:/, "Fork bomb"],
   [/curl.*\|\s*(?:ba)?sh/, "Pipe to shell"],
   [/wget.*\|\s*(?:ba)?sh/, "Pipe to shell"],
+  [WIN_ROOT_DELETE, "Recursive delete of a drive root or home"],
+  [WIN_FORMAT_COMMAND, "Disk format"],
+  [WIN_DISKPART_COMMAND, "Disk partitioning"],
+  [
+    new RegExp(String.raw`\b${WIN_DOWNLOAD}\b[^|\n]*\|\s*${WIN_EVAL}\b`, "i"),
+    "Pipe to shell",
+  ],
+  [
+    new RegExp(
+      String.raw`\b${WIN_EVAL}\b[^|\n]*(?:downloadstring|downloadfile|new-object\s+(?:system\.)?net\.webclient|\b${WIN_DOWNLOAD}\b)`,
+      "i"
+    ),
+    "Download and execute",
+  ],
 ];
 
 /** Hook-managed files — single source of truth */
@@ -99,6 +184,11 @@ export function checkBashCommand(cmd: string): string | null {
   for (const [pattern, reason] of BLOCKED_COMMANDS) {
     if (pattern.test(cmd)) return reason;
   }
+  if (WIN_ELEVATION_WRAPPER.test(cmd)) {
+    for (const [pattern, reason] of WIN_ELEVATED_THREATS) {
+      if (pattern.test(cmd)) return reason;
+    }
+  }
   // If command references a managed file in a managed root path, block unless read-only.
   // The filename must appear IN the same path as the managed root (e.g. .pal/.../file.json).
   const segments = cmd.split(/[|;&&]/).map((s) => s.trim());

package/src/hooks/lib/transcript.ts

@@ -20,9 +20,42 @@ export function parseMessages(raw: string): Message[] {
   }
 }
 
+function claudeCodeEntryText(msg: { content?: unknown }): string {
+  if (typeof msg.content === "string") return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .filter((c: { type: string }) => c.type === "text")
+      .map((c: { text: string }) => c.text)
+      .join(" ");
+  }
+  return "";
+}
+
+// Claude Code tags transcript lines `type: "user"|"assistant"` with the text
+// under `message.content`. VS Code Copilot's own event log instead uses
+// `type: "user.message"|"assistant.message"` with a flat `data.content`
+// string — two shapes sharing one transcript_path contract across agents.
+function parseTranscriptEntry(entry: {
+  type?: string;
+  message?: { content?: unknown };
+  data?: { content?: unknown };
+}): Message | null {
+  if (entry.type === "user" || entry.type === "assistant") {
+    const text = claudeCodeEntryText(entry.message ?? {});
+    return text ? { role: entry.type, content: text } : null;
+  }
+  if (entry.type === "user.message" || entry.type === "assistant.message") {
+    const text = entry.data?.content;
+    const role = entry.type === "user.message" ? "user" : "assistant";
+    return typeof text === "string" && text ? { role, content: text } : null;
+  }
+  return null;
+}
+
 /**
- * Read a Claude Code transcript JSONL file and extract user/assistant messages.
- * Each line is a JSON object; we extract entries with type "user" or "assistant".
+ * Read an agent transcript JSONL file and extract user/assistant messages.
+ * Supports Claude Code's `{type:"user"|"assistant", message:{content}}` shape
+ * and VS Code Copilot's `{type:"user.message"|"assistant.message", data:{content}}` shape.
  */
 export function readTranscriptFile(path: string): Message[] {
   try {
@@ -32,22 +65,8 @@ export function readTranscriptFile(path: string): Message[] {
     for (const line of content.split("\n")) {
       if (!line.trim()) continue;
       try {
-        const entry = JSON.parse(line);
-        if (entry.type === "user" || entry.type === "assistant") {
-          const msg = entry.message ?? {};
-          let text = "";
-          if (typeof msg.content === "string") {
-            text = msg.content;
-          } else if (Array.isArray(msg.content)) {
-            text = msg.content
-              .filter((c: { type: string }) => c.type === "text")
-              .map((c: { text: string }) => c.text)
-              .join(" ");
-          }
-          if (text) {
-            messages.push({ role: entry.type, content: text });
-          }
-        }
+        const parsed = parseTranscriptEntry(JSON.parse(line));
+        if (parsed) messages.push(parsed);
       } catch {
         /* skip malformed lines */
       }

package/src/targets/claude/install.ts

@@ -6,25 +6,21 @@
 
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
 import { identity, raw as readPalSettings } from "../../hooks/lib/settings";
 import {
   addStatuslineConfig,
   applyAttribution,
   copyAgents,
-  copyPalDocs,
   copySkills,
   copyStatusline,
   countAgents,
   countMd,
   countSkills,
-  generateSkillIndex,
   loadSettingsTemplate,
   log,
   mergeSettings,
   readJson,
-  scaffoldPalSettings,
   writeJson,
 } from "../lib";
 
@@ -68,7 +64,6 @@ log.success("Merged PAL settings into settings.json");
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
 copySkills(skillsDir);
-generateSkillIndex();
 
 // --- Copy agents ---
 copyAgents();
@@ -76,19 +71,6 @@ copyAgents();
 // --- Copy statusline script ---
 copyStatusline();
 
-// --- Copy PAL system docs ---
-const palDocsCount = copyPalDocs();
-log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
-
-// --- Scaffold PAL settings ---
-scaffoldPalSettings();
-
-// --- Generate ~/.claude/AGENTS.md and symlink ~/.claude/CLAUDE.md → AGENTS.md ---
-regenerateIfNeeded();
-log.success("Generated ~/.config/opencode/AGENTS.md (→ ~/.claude/CLAUDE.md symlink)");
-
-log.success("Claude Code installation complete");
-console.log("");
-log.info(`Skills: ${countSkills()}`);
-log.info(`Agents: ${countAgents()}`);
-log.info(`TELOS: ${countMd(resolve(palHome(), "telos"))} files`);
+log.success(
+  `${countSkills()} skills · ${countAgents()} agents · ${countMd(resolve(palHome(), "telos"))} TELOS files · CLAUDE.md → AGENTS.md`
+);

package/src/targets/codex/install.ts

@@ -12,20 +12,17 @@ import {
   writeFileSync,
 } from "node:fs";
 import { resolve } from "node:path";
-import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
   addCodexStatuslineConfig,
   copySkills,
   countSkills,
-  generateSkillIndex,
   loadCodexHooksTemplate,
   loadCodexRulesTemplate,
   log,
   mergeCodexHooks,
   mergeCodexRules,
   readJson,
-  scaffoldPalSettings,
   writeJson,
 } from "../lib";
 
@@ -86,7 +83,7 @@ const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
 const merged = mergeCodexHooks(existing, template);
 
 writeJson(HOOKS_FILE, merged);
-log.success("Merged PAL hooks into ~/.codex/hooks.json");
+log.success(`Merged PAL hooks into ${HOOKS_FILE}`);
 
 // --- Merge allowlist rules ---
 mkdirSync(resolve(CODEX_DIR, "rules"), { recursive: true });
@@ -102,21 +99,9 @@ log.success("Merged PAL allowlist rules into ~/.codex/rules/default.rules");
 // --- Symlink skills to ~/.codex/skills/ ---
 const codexSkillsDir = resolve(CODEX_DIR, "skills");
 copySkills(codexSkillsDir);
-generateSkillIndex();
-
-// --- Scaffold PAL settings ---
-scaffoldPalSettings();
-
-// --- Generate / verify AGENTS.md symlink ---
-regenerateIfNeeded();
-log.success("Ensured AGENTS.md symlink at ~/.codex/AGENTS.md");
+log.success(`${countSkills()} skills → ~/.codex/skills/`);
 
 // --- Enable hooks in config.toml ---
 const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
 enableCodexHooks(CONFIG_FILE);
 enableCodexStatusline(CONFIG_FILE);
-
-log.success("Codex installation complete");
-console.log("");
-log.info(`Skills: ${countSkills()}`);
-log.info(`Hooks: ${HOOKS_FILE}`);

package/src/targets/copilot/install.ts

@@ -5,21 +5,16 @@
  * Enables ~/.copilot/instructions in VS Code chat.instructionsFilesLocations.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { writeContextDigests } from "../../hooks/handlers/context-digests";
-import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
   copyAgentsForCopilot,
-  copyPalDocs,
   copySkills,
   countSkills,
-  generateSkillIndex,
   loadCopilotHooksTemplate,
   log,
   readJson,
-  scaffoldPalSettings,
   vscodeSettingsFile,
   writeJson,
 } from "../lib";
@@ -28,6 +23,7 @@ const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const COPILOT_DIR = platform.copilotDir();
 const HOOKS_DIR = resolve(COPILOT_DIR, "hooks");
 const HOOKS_FILE = resolve(HOOKS_DIR, "pal-hooks.json");
+const VSCODE_HOOKS_FILE = resolve(HOOKS_DIR, "pal-vscode-hooks.json");
 
 // --- Ensure dirs ---
 mkdirSync(HOOKS_DIR, { recursive: true });
@@ -37,34 +33,24 @@ const template = loadCopilotHooksTemplate(assets.copilotHooksTemplate(), PKG_ROO
 writeFileSync(HOOKS_FILE, `${JSON.stringify(template, null, 2)}\n`, "utf-8");
 log.success(`Written hooks to ${HOOKS_FILE}`);
 
+// --- Retire the separate VS Code hooks file ---
+// VS Code's own Copilot build already executes the PascalCase hooks in
+// ~/.claude/settings.json, so registering the same events here too ran every
+// hook twice per turn. One dual-shape block payload (see lib/agent.ts) now
+// serves both surfaces from that single registration.
+if (existsSync(VSCODE_HOOKS_FILE)) {
+  unlinkSync(VSCODE_HOOKS_FILE);
+  log.success("Removed pal-vscode-hooks.json (VS Code runs the Claude hooks)");
+}
+
 // --- Install skills ---
 const copilotSkillsDir = resolve(COPILOT_DIR, "skills");
 copySkills(copilotSkillsDir);
-generateSkillIndex();
-log.success("Installed skills to ~/.copilot/skills/");
 
 // --- Install agents ---
 const copilotAgentsDir = resolve(COPILOT_DIR, "agents");
 const agentCount = copyAgentsForCopilot(copilotAgentsDir);
-if (agentCount > 0) log.success(`Installed ${agentCount} agents to ~/.copilot/agents/`);
-
-// --- Copy PAL docs ---
-const palDocsCount = copyPalDocs();
-log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
-
-// --- Scaffold PAL settings ---
-scaffoldPalSettings();
-
-// --- Generate AGENTS.md ---
-regenerateIfNeeded();
-log.success("Generated AGENTS.md");
-
-// --- Write ~/.copilot/instructions/pal-*.instructions.md ---
-mkdirSync(resolve(COPILOT_DIR, "instructions"), { recursive: true });
-writeContextDigests();
-log.success(
-  "Written ~/.copilot/instructions/pal-self-model + pal-wisdom + pal-opinions.instructions.md"
-);
+log.success(`${countSkills()} skills · ${agentCount} agents → ~/.copilot/`);
 
 // --- Enable ~/.copilot/instructions in VS Code settings ---
 const vsSettingsPath = vscodeSettingsFile();
@@ -90,8 +76,3 @@ if (vsSettingsPath) {
 } else {
   log.warn(`Could not detect VS Code settings path — ${manualHint}`);
 }
-
-log.success("Copilot installation complete");
-console.log("");
-log.info(`Skills: ${countSkills()}`);
-log.info(`Hooks: ${HOOKS_FILE}`);

package/src/targets/copilot/uninstall.ts

@@ -20,16 +20,22 @@ import {
 
 const COPILOT_DIR = platform.copilotDir();
 const HOOKS_FILE = resolve(COPILOT_DIR, "hooks", "pal-hooks.json");
+const VSCODE_HOOKS_FILE = resolve(COPILOT_DIR, "hooks", "pal-vscode-hooks.json");
 
-// --- Remove hooks file ---
-if (existsSync(HOOKS_FILE)) {
-  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
-  unlinkSync(HOOKS_FILE);
-  log.success("Removed pal-hooks.json");
-} else {
-  log.info("No pal-hooks.json found, nothing to do");
+// --- Remove hooks files ---
+function removeHooksFile(path: string, label: string): void {
+  if (!existsSync(path)) {
+    log.info(`No ${label} found, nothing to do`);
+    return;
+  }
+  copyFileSync(path, `${path}.bak.${Date.now()}`);
+  unlinkSync(path);
+  log.success(`Removed ${label}`);
 }
 
+removeHooksFile(HOOKS_FILE, "pal-hooks.json");
+removeHooksFile(VSCODE_HOOKS_FILE, "pal-vscode-hooks.json");
+
 // --- Remove skill symlinks ---
 const copilotSkillsDir = resolve(COPILOT_DIR, "skills");
 const removed = removeSkills(copilotSkillsDir);

package/src/targets/cursor/install.ts

@@ -6,22 +6,17 @@
 
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { writeContextDigests } from "../../hooks/handlers/context-digests";
-import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
   addStatuslineConfig,
   copyAgentsForCursor,
-  copyPalDocs,
   copySkills,
   copyStatusline,
   countSkills,
-  generateSkillIndex,
   loadCursorHooksTemplate,
   log,
   mergeCursorHooks,
   readJson,
-  scaffoldPalSettings,
   writeJson,
 } from "../lib";
 
@@ -45,24 +40,16 @@ const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
 const merged = mergeCursorHooks(existing, template);
 
 writeJson(HOOKS_FILE, merged);
-log.success("Merged PAL hooks into hooks.json");
+log.success(`Merged PAL hooks into ${HOOKS_FILE}`);
 
 // --- Symlink skills to ~/.cursor/skills/ ---
 const cursorSkillsDir = resolve(CURSOR_DIR, "skills");
 copySkills(cursorSkillsDir);
-generateSkillIndex();
 
 // --- Copy agents to ~/.cursor/agents/ ---
 const cursorAgentsDir = resolve(CURSOR_DIR, "agents");
 const agentCount = copyAgentsForCursor(cursorAgentsDir);
-if (agentCount > 0) log.success(`Installed ${agentCount} agents to ~/.cursor/agents/`);
-
-// --- Copy PAL system docs ---
-const palDocsCount = copyPalDocs();
-log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
-
-// --- Scaffold PAL settings ---
-scaffoldPalSettings();
+log.success(`${countSkills()} skills · ${agentCount} agents → ~/.cursor/`);
 
 // --- Statusline script + cli-config.json statusLine ---
 copyStatusline("cursor");
@@ -77,21 +64,6 @@ const cliConfig = readJson<Record<string, unknown>>(CLI_CONFIG, {});
 writeJson(CLI_CONFIG, addStatuslineConfig(cliConfig, "cursor"));
 log.success("Merged statusLine into cli-config.json");
 
-// --- Generate AGENTS.md ---
-regenerateIfNeeded();
-log.success("Generated AGENTS.md");
-
-// --- Write ~/.cursor/rules/pal-*.mdc ---
-mkdirSync(resolve(CURSOR_DIR, "rules"), { recursive: true });
-writeContextDigests();
-log.success(
-  "Written ~/.cursor/rules/pal-self-model.mdc + pal-wisdom.mdc + pal-opinions.mdc"
-);
-
-log.success("Cursor installation complete");
-console.log("");
-log.info(`Skills: ${countSkills()}`);
-log.info(`Hooks: ${HOOKS_FILE}`);
 log.info(
   "Note: Cursor tool matchers may need tuning — verify hook behavior after first use"
 );

package/src/targets/lib.ts

@@ -741,6 +741,23 @@ export function removePalDocs(): void {
 
 const PAL_SKILLS_DIR = resolve(palHome(), "skills");
 
+/**
+ * Run one step of a bulk install, naming it only when it fails.
+ *
+ * Installs handle dozens of skills and agents; a line each buries the paths,
+ * backups and warnings that a reader actually has to act on. Returning false
+ * instead of throwing also keeps one unlinkable skill from aborting the rest.
+ */
+function reportOnlyOnFailure(label: string, install: () => void): boolean {
+  try {
+    install();
+    return true;
+  } catch (e) {
+    log.warn(`Could not install ${label} — ${(e as Error).message}`);
+    return false;
+  }
+}
+
 /**
  * Install PAL skills by symlinking:
  *   ~/.pal/skills/<name> → <repo>/assets/skills/<name>  (source of truth)
@@ -762,16 +779,15 @@ export function copySkills(claudeSkillsDir: string): number {
     const srcDir = resolve(skillsDir, name);
     if (!existsSync(resolve(srcDir, "SKILL.md"))) continue;
 
-    // ~/.pal/skills/<name> → <repo>/assets/skills/<name>
     const palLink = resolve(PAL_SKILLS_DIR, name);
-    ensureSymlink(palLink, srcDir, linkType);
-
-    // ~/.claude/skills/<name> → ~/.pal/skills/<name>
     const claudeLink = resolve(claudeSkillsDir, name);
-    ensureSymlink(claudeLink, palLink, linkType);
-
-    log.info(`Linked skill: ${name}`);
-    count++;
+    const linked = reportOnlyOnFailure(`skill ${name}`, () => {
+      // ~/.pal/skills/<name> → <repo>/assets/skills/<name>
+      ensureSymlink(palLink, srcDir, linkType);
+      // ~/.claude/skills/<name> → ~/.pal/skills/<name>
+      ensureSymlink(claudeLink, palLink, linkType);
+    });
+    if (linked) count++;
   }
 
   // ~/.agents/skills/ → ~/.pal/skills/
@@ -1000,14 +1016,16 @@ function installAgents(targetDir: string, platform: AgentPlatform): number {
   let count = 0;
 
   for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-    const content = readFileSync(resolve(agentsDir, file), "utf-8");
-    writeFileSync(
-      resolve(targetDir, file),
-      extractAgentForPlatform(content, platform),
-      "utf-8"
-    );
-    log.info(`Installed ${platform} agent: ${file.replace(/\.md$/, "")}`);
-    count++;
+    const name = file.replace(/\.md$/, "");
+    const installed = reportOnlyOnFailure(`${platform} agent ${name}`, () => {
+      const content = readFileSync(resolve(agentsDir, file), "utf-8");
+      writeFileSync(
+        resolve(targetDir, file),
+        extractAgentForPlatform(content, platform),
+        "utf-8"
+      );
+    });
+    if (installed) count++;
   }
   return count;
 }
@@ -1375,7 +1393,6 @@ export function generateSkillIndex(): number {
   const stateDir = resolve(palHome(), "memory", "state");
   mkdirSync(stateDir, { recursive: true });
   writeJson(resolve(stateDir, "skill-index.json"), index);
-  log.info(`Skill index: ${index.totalSkills} skills indexed`);
 
   return index.totalSkills;
 }

package/src/targets/opencode/install.ts

@@ -12,18 +12,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { resolve } from "node:path";
-import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { palPkg, platform } from "../../hooks/lib/paths";
 import { getSemiStaticSources } from "../../hooks/lib/semi-static";
-import {
-  copyAgentsForOpencode,
-  copyPalDocs,
-  copySkills,
-  countSkills,
-  generateSkillIndex,
-  log,
-  writeJson,
-} from "../lib";
+import { copyAgentsForOpencode, copySkills, countSkills, log, writeJson } from "../lib";
 
 const PKG_ROOT = palPkg();
 const OC_GLOBAL_DIR = platform.opencodeDir();
@@ -55,7 +46,6 @@ if (!existsSync(pkgPath)) {
 
 try {
   Bun.spawnSync(["bun", "install", "--silent"], { cwd: OC_PLUGINS_DIR });
-  log.success("Installed plugin dependencies");
 } catch {
   log.warn(`Could not install plugin deps — run 'bun install' in ${OC_PLUGINS_DIR}`);
 }
@@ -63,22 +53,13 @@ try {
 // --- 3. Install skills into ~/.pal/skills/ ---
 const claudeSkillsDir = resolve(platform.claudeDir(), "skills");
 copySkills(claudeSkillsDir);
-generateSkillIndex();
-log.success("Installed skills to ~/.pal/skills/");
 
 // --- 4. Install agents into ~/.config/opencode/agents/ ---
 const ocAgentsDir = resolve(OC_GLOBAL_DIR, "agents");
-copyAgentsForOpencode(ocAgentsDir);
-
-// --- 5. Copy PAL system docs ---
-const palDocsCount = copyPalDocs();
-log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
-
-// --- 6. Generate ~/.config/opencode/AGENTS.md ---
-regenerateIfNeeded();
-log.success("Generated ~/.config/opencode/AGENTS.md");
+const agentCount = copyAgentsForOpencode(ocAgentsDir);
+log.success(`${countSkills()} skills · ${agentCount} agents → ~/.config/opencode/`);
 
-// --- 7. Add semi-static digest files to instructions[] in config.json ---
+// --- 5. Add semi-static digest files to instructions[] in config.json ---
 const configPath = resolve(OC_GLOBAL_DIR, "config.json");
 const staticFiles = getSemiStaticSources().map((s) => s.path);
 let ocConfig: Record<string, unknown> = {};
@@ -94,11 +75,3 @@ const existingInstructions = Array.isArray(ocConfig.instructions)
   : [];
 ocConfig.instructions = [...new Set([...existingInstructions, ...staticFiles])];
 writeFileSync(configPath, `${JSON.stringify(ocConfig, null, 2)}\n`, "utf-8");
-log.success(
-  `Updated config.json: ${(ocConfig.instructions as string[]).length} instructions`
-);
-
-log.success("opencode installation complete");
-console.log("");
-log.info(`Plugin: ${pluginDst}`);
-log.info(`Skills: ${countSkills()} (native via ~/.pal/skills/)`);