portable-agent-layer 0.84.2 → 0.84.4

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -263,7 +263,7 @@ Every agent's turns are measured and its replies filed under the session id the
 | Cursor | `beforeSubmitPrompt` → `additional_context`, undocumented | `afterAgentResponse` `text` (`AgentResponse.ts`) |
 | Copilot CLI | `userPromptTransformed` → `modifiedTransformedPrompt` (`PromptTransformed.ts`) | `agentStop` transcript |
 
-The Copilot CLI drops what its `userPromptSubmitted` hook returns, so that hook only measures the turn and parks the context; `userPromptTransformed` fires next and appends it to the prompt the model receives. It also writes the reply to the `agentStop` transcript only after that hook returns, so a stop whose transcript still ends on the user's message hands off to a detached `StopDeferred.ts`, which waits for the reply before running the stop handlers. Cursor documents no context field on `beforeSubmitPrompt`, so PAL offers `additional_context` there but logs no interaction hint as sent until it is shown to reach the model; its documented context channel is session start. `test/agent-turns.test.ts` holds each agent to this table.
+The Copilot CLI drops what its `userPromptSubmitted` hook returns, so that hook only measures the turn and parks the context; `userPromptTransformed` fires next and appends it to the prompt the model receives. It also writes the reply to the `agentStop` transcript only after that hook returns, so a stop whose transcript still ends on the user's message hands off to a detached `StopDeferred.ts`, which waits for the reply before running the stop handlers. Cursor documents no context field on `beforeSubmitPrompt`, so PAL offers `additional_context` there but logs no interaction hint as sent until it is shown to reach the model; its documented context channel is session start. cursor-agent also runs every hook in `~/.claude/settings.json`, so when PAL's own Cursor hooks are installed, the copy registered with `--agent=claude` exits at once (`lib/cursor-shadow.ts`) and each Cursor event runs PAL once. `test/agent-turns.test.ts` holds each agent to this table.
 
 ### Design Principles
 

package/package.json

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

package/src/hooks/CompactRecover.ts

@@ -14,12 +14,14 @@ import {
   isConsumable,
   type SavedExchange,
 } from "./lib/compact-recall";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logDebug, logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
 // Recursion guard — spawned subprocesses don't compact, so nothing to recover.
 if (isPalSpawnedInference()) process.exit(0);
+if (duplicatesCursorHooks()) process.exit(0);
 
 interface SessionStartInput {
   session_id?: string;

package/src/hooks/LedgerCommit.ts

@@ -10,10 +10,13 @@
  * Silent and fail-open, for the same reason as its other half.
  */
 
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { commitApplied, ledgeredCalls } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
+if (duplicatesCursorHooks()) process.exit(0);
+
 try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);

package/src/hooks/LedgerSnapshot.ts

@@ -10,10 +10,13 @@
  * that could block an edit would be a worse thing than a ledger with a gap.
  */
 
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { ledgeredCalls, snapshotCall } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
+if (duplicatesCursorHooks()) process.exit(0);
+
 try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);

package/src/hooks/LedgerUnapplied.ts

@@ -20,11 +20,14 @@
  * Silent and fail-open, for the same reason as the other halves.
  */
 
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { reapStalePending } from "./lib/ledger";
 import { commitUnapplied, ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
+if (duplicatesCursorHooks()) process.exit(0);
+
 try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);

package/src/hooks/LoadContext.ts

@@ -14,6 +14,7 @@ import { getActiveAgent } from "./lib/agent";
 import { autoUpdateOnStart } from "./lib/auto-update";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logContextSnapshot, logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
 import {
@@ -29,7 +30,7 @@ import { readStdinJSON } from "./lib/stdin";
 // Recursion guard — when this process is a PAL-spawned inference subprocess,
 // skip all context loading so we don't trigger another inference call.
 if (isPalSpawnedInference()) process.exit(0);
-
+if (duplicatesCursorHooks()) process.exit(0);
 if (isSubagentSession(process.env)) {
   logDebug("LoadContext", "Subagent session — skipping context loading");
   process.exit(0);

package/src/hooks/PreCompactPersist.ts

@@ -15,6 +15,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { persistLastExchange } from "./handlers/persist-last-exchange";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logDebug, logError } from "./lib/log";
 import { paths } from "./lib/paths";
 import { sessionDir } from "./lib/session-dir";
@@ -24,6 +25,7 @@ import { readTranscriptFile } from "./lib/transcript";
 
 // Recursion guard — spawned subprocesses don't compact, so nothing to persist.
 if (isPalSpawnedInference()) process.exit(0);
+if (duplicatesCursorHooks()) process.exit(0);
 
 interface PreCompactInput {
   session_id?: string;

package/src/hooks/RtkWrap.ts

@@ -17,8 +17,11 @@
  */
 
 import { getActiveAgent } from "./lib/agent";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { findBinaryOnPath } from "./lib/which";
 
+if (duplicatesCursorHooks()) process.exit(0);
+
 const RTK_HOOK_SUBCOMMAND: Partial<Record<ReturnType<typeof getActiveAgent>, string>> = {
   claude: "claude",
   cursor: "cursor",

package/src/hooks/SecurityValidator.ts

@@ -8,11 +8,14 @@
  */
 
 import { blockResponse } from "./lib/agent";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { recordBlocked } from "./lib/ledger";
 import { logError } from "./lib/log";
 import { decideRefusal, type SecurityInput } from "./lib/security-gate";
 import { readStdinJSON } from "./lib/stdin";
 
+if (duplicatesCursorHooks()) process.exit(0);
+
 try {
   const input = await readStdinJSON<SecurityInput>();
   if (!input) process.exit(0);

package/src/hooks/SessionClose.ts

@@ -11,11 +11,13 @@
  */
 
 import { autoUpdateOnClose } from "./lib/auto-update";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
 if (isPalSpawnedInference()) process.exit(0);
+if (duplicatesCursorHooks()) process.exit(0);
 
 try {
   const input = await readStdinJSON<{ reason?: string }>();

package/src/hooks/SkillGuard.ts

@@ -10,8 +10,11 @@
  */
 
 import { blockResponse, normalizeToolUse } from "./lib/agent";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { readStdinJSON } from "./lib/stdin";
 
+if (duplicatesCursorHooks()) process.exit(0);
+
 const BLOCKED_SKILLS = ["keybindings-help"];
 
 try {

package/src/hooks/StopOrchestrator.ts

@@ -7,6 +7,7 @@
 
 import { checkReadmeSync } from "./handlers/readme-sync";
 import { blockResponse, isCodex, isCursor } from "./lib/agent";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
@@ -15,6 +16,7 @@ import { type StopTurnPayload, stopTurn } from "./lib/stop";
 // Recursion guard — spawned inference subprocesses must not record session
 // learning, ratings, or handoffs from their throwaway transcript.
 if (isPalSpawnedInference()) process.exit(0);
+if (duplicatesCursorHooks()) process.exit(0);
 
 // Check README sync before anything else — may block the session
 try {

package/src/hooks/UserPromptOrchestrator.ts

@@ -10,6 +10,7 @@
 import { injectPromptContext } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { type HookTurnPayload, hookSessionId } from "./lib/hook-turn";
 import { logDebug, logError, logPromptSnapshot } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
@@ -18,6 +19,7 @@ import { readStdinJSON } from "./lib/stdin";
 // Recursion guard — the "prompt" inside a spawned inference is the dispatcher's
 // payload, not a real user message. Skip rating capture, session naming, etc.
 if (isPalSpawnedInference()) process.exit(0);
+if (duplicatesCursorHooks()) process.exit(0);
 
 interface PromptSubmitInput extends HookTurnPayload {
   prompt: string;

package/src/hooks/lib/agent.ts

@@ -41,7 +41,7 @@ function agentFromEnv(): AgentType | undefined {
  * 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 {
+export 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;
@@ -52,7 +52,7 @@ function agentFromArgv(): AgentType | undefined {
  * nothing and appears on no other surface, but it is not the primary signal —
  * it is absent from the session env that hook children inherit.
  */
-function inCursorAgent(): boolean {
+export function inCursorAgent(): boolean {
   return Boolean(
     process.env.CURSOR_AGENT ??
       process.env.CURSOR_VERSION ??

package/src/hooks/lib/cursor-shadow.ts

@@ -0,0 +1,31 @@
+/**
+ * cursor-agent runs every hook in ~/.claude/settings.json next to its own
+ * ~/.cursor/hooks.json. With PAL registered in both, each Cursor prompt ran PAL
+ * twice, so the copy started from the Claude config stands down.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { agentFromArgv, inCursorAgent } from "./agent";
+import { platform } from "./paths";
+
+const PAL_HOOK = /\/src\/hooks\/\w+\.ts\b/;
+
+function cursorRunsPalHooks(): boolean {
+  try {
+    return PAL_HOOK.test(
+      readFileSync(resolve(platform.cursorDir(), "hooks.json"), "utf-8")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isClaudeRegistrationInCursor(): boolean {
+  return agentFromArgv() === "claude" && inCursorAgent();
+}
+
+/** True for the Claude-config copy of a hook that Cursor's own PAL hooks also run. */
+export function duplicatesCursorHooks(): boolean {
+  return isClaudeRegistrationInCursor() && cursorRunsPalHooks();
+}

package/src/targets/copilot/install.ts

@@ -14,10 +14,9 @@ import {
   countSkills,
   loadCopilotHooksTemplate,
   log,
-  readJson,
   vscodeSettingsFile,
-  writeJson,
 } from "../lib";
+import { enableCopilotInstructions } from "../vscode-settings";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const COPILOT_DIR = platform.copilotDir();
@@ -58,18 +57,15 @@ const manualHint =
   'Add manually: { "chat.instructionsFilesLocations": { "~/.copilot/instructions": true } }';
 if (vsSettingsPath) {
   try {
-    const settings = readJson<Record<string, unknown>>(vsSettingsPath, {});
-    const existing =
-      typeof settings["chat.instructionsFilesLocations"] === "object" &&
-      settings["chat.instructionsFilesLocations"] !== null
-        ? (settings["chat.instructionsFilesLocations"] as Record<string, unknown>)
-        : {};
-    settings["chat.instructionsFilesLocations"] = {
-      ...existing,
-      "~/.copilot/instructions": true,
-    };
-    writeJson(vsSettingsPath, settings);
-    log.success("Enabled ~/.copilot/instructions in VS Code settings");
+    const outcome = enableCopilotInstructions(vsSettingsPath);
+    if (outcome === "enabled")
+      log.success("Enabled ~/.copilot/instructions in VS Code settings");
+    if (outcome === "needs-manual-edit")
+      log.warn(
+        `VS Code settings aren't plain JSON, so PAL left them untouched — ${manualHint}`
+      );
+    if (outcome === "vscode-never-launched")
+      log.info("Skipped VS Code settings — VS Code has not been launched yet");
   } catch {
     log.warn(`Could not update VS Code settings — ${manualHint}`);
   }

package/src/targets/vscode-settings.ts

@@ -0,0 +1,56 @@
+/**
+ * VS Code's settings.json is JSONC. PAL rewrites it only when it parses as
+ * strict JSON, because a rewrite would drop the user's comments.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { writeJson } from "./lib";
+
+const LOCATIONS_KEY = "chat.instructionsFilesLocations";
+const COPILOT_INSTRUCTIONS = "~/.copilot/instructions";
+
+type Settings = Record<string, unknown>;
+
+type InstructionsOutcome =
+  | "enabled"
+  | "already-enabled"
+  | "needs-manual-edit"
+  | "vscode-never-launched";
+
+function parsed(raw: string, parse: (text: string) => unknown): Settings | null {
+  try {
+    const value = parse(raw);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? (value as Settings)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function locationsOf(settings: Settings): Settings {
+  const locations = settings[LOCATIONS_KEY];
+  return typeof locations === "object" && locations !== null
+    ? (locations as Settings)
+    : {};
+}
+
+function writeEnabled(settingsPath: string, settings: Settings): InstructionsOutcome {
+  writeJson(settingsPath, {
+    ...settings,
+    [LOCATIONS_KEY]: { ...locationsOf(settings), [COPILOT_INSTRUCTIONS]: true },
+  });
+  return "enabled";
+}
+
+export function enableCopilotInstructions(settingsPath: string): InstructionsOutcome {
+  if (!existsSync(dirname(settingsPath))) return "vscode-never-launched";
+  if (!existsSync(settingsPath)) return writeEnabled(settingsPath, {});
+  const raw = readFileSync(settingsPath, "utf-8");
+  const settings = parsed(raw, Bun.JSONC.parse);
+  if (settings && locationsOf(settings)[COPILOT_INSTRUCTIONS] === true)
+    return "already-enabled";
+  const strict = parsed(raw, JSON.parse);
+  return strict ? writeEnabled(settingsPath, strict) : "needs-manual-edit";
+}