portable-agent-layer 0.63.0 → 0.63.2

package/assets/templates/hooks.copilot.json

@@ -4,33 +4,39 @@
     "sessionStart": [
       {
         "type": "command",
-        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts",
+        "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
       }
     ],
     "userPromptSubmitted": [
       {
         "type": "command",
-        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts",
+        "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
       }
     ],
     "preToolUse": [
       {
         "type": "command",
-        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts",
+        "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
       },
       {
         "type": "command",
-        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts",
+        "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
       },
       {
         "type": "command",
-        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts",
+        "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
       }
     ],
     "agentStop": [
       {
         "type": "command",
-        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+        "bash": "PAL_AGENT=copilot bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts",
+        "powershell": "$env:PAL_AGENT='copilot'; bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
       }
     ]
   }

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.0",
+  "version": "0.63.2",
   "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";
@@ -80,6 +80,20 @@ function checkTool(cmd: string, versionArgs: string[] = ["--version"]): ToolChec
   return { name: cmd, available: false };
 }
 
+/**
+ * Copilot ships as a VS Code extension as well as a CLI, and the extension puts
+ * no `copilot` binary on PATH — but both read hooks, skills and agents out of
+ * ~/.copilot. Fall back to that directory so PAL's copilot checks still run.
+ */
+function checkCopilot(): ToolCheck {
+  const cli = checkTool("copilot", ["version"]);
+  if (cli.available) return cli;
+  if (existsSync(platform.copilotDir())) {
+    return { name: "copilot", available: true, version: "~/.copilot (no CLI on PATH)" };
+  }
+  return cli;
+}
+
 function detectAgent(): string | null {
   if (checkTool("claude").available) return "claude";
   if (checkTool("opencode").available) return "opencode";
@@ -443,13 +457,18 @@ function checkCopilotInstructionsPresent(): boolean {
 
 // ── Install integrity (Tier 2 doctor checks) ──
 
-/** Recursively collect every `command` or `bash` field value in a hook-config JSON. */
+/** Hook-config keys that carry a shell command: cross-platform and per-shell variants. */
+function isHookCommandField(key: string): boolean {
+  return key === "command" || key === "bash" || key === "powershell";
+}
+
+/** Recursively collect every command-carrying field value in a hook-config JSON. */
 function extractAllHookCommands(obj: unknown, out: string[] = []): string[] {
   if (Array.isArray(obj)) {
     for (const item of obj) extractAllHookCommands(item, out);
   } else if (obj && typeof obj === "object") {
     for (const [k, v] of Object.entries(obj)) {
-      if ((k === "command" || k === "bash") && typeof v === "string") {
+      if (isHookCommandField(k) && typeof v === "string") {
         out.push(v);
       } else {
         extractAllHookCommands(v, out);
@@ -466,14 +485,27 @@ interface HookPrefixCheck {
   firstMissing?: string;
 }
 
-/** Verify every command in an installed hook file starts with `PAL_AGENT=<agent>`. */
+/**
+ * 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.includes(`--agent=${agentName}`)
+  );
+}
+
+/** 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 prefix = `PAL_AGENT=${agentName} `;
-    const missing = commands.filter((c) => !c.startsWith(prefix));
+    const missing = commands.filter((c) => !declaresAgent(c, agentName));
     return {
       ok: commands.length > 0 && missing.length === 0,
       total: commands.length,
@@ -701,7 +733,7 @@ function doctor(silent = false): DoctorResult {
   const claude = checkTool("claude");
   const opencode = checkTool("opencode");
   const cursor = checkTool("cursor");
-  const copilot = checkTool("copilot", ["version"]);
+  const copilot = checkCopilot();
   const codex = checkTool("codex");
   const rtk = checkTool("rtk");
   const hasAgent =
@@ -902,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}…`);
@@ -1058,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();
 
@@ -1066,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");
   }
 
@@ -1084,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`
       );
     }
   }
@@ -1112,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");
@@ -1122,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");
@@ -1152,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.");
 }
 
@@ -1377,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);
   }