portable-agent-layer 0.84.3 → 0.84.5

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.3",
+  "version": "0.84.5",
   "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/hooks/lib/transcript.ts

@@ -31,15 +31,44 @@ function claudeCodeEntryText(msg: { content?: unknown }): string {
   return "";
 }
 
+interface CodexPayload {
+  role?: string;
+  content?: unknown;
+}
+
+const CODEX_INJECTED_CONTEXT = ["# AGENTS.md instructions", "<environment_context>"];
+
+function isCodexInjectedContext(text: string): boolean {
+  return CODEX_INJECTED_CONTEXT.some((prefix) => text.startsWith(prefix));
+}
+
+function codexTexts(content: unknown): string[] {
+  if (!Array.isArray(content)) return [];
+  return content
+    .map((part) => part?.text)
+    .filter((text): text is string => typeof text === "string" && text.length > 0);
+}
+
+function codexMessage(payload: CodexPayload | undefined): Message | null {
+  const role = payload?.role;
+  if (role !== "user" && role !== "assistant") return null;
+  const texts = codexTexts(payload?.content).filter(
+    (text) => !isCodexInjectedContext(text)
+  );
+  return texts.length > 0 ? { role, content: texts.join(" ") } : null;
+}
+
 // 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.
+// string. Codex nests each message as a `response_item` payload.
 function parseTranscriptEntry(entry: {
   type?: string;
   message?: { content?: unknown };
   data?: { content?: unknown };
+  payload?: CodexPayload;
 }): Message | null {
+  if (entry.type === "response_item") return codexMessage(entry.payload);
   if (entry.type === "user" || entry.type === "assistant") {
     const text = claudeCodeEntryText(entry.message ?? {});
     return text ? { role: entry.type, content: text } : null;
@@ -55,7 +84,8 @@ function parseTranscriptEntry(entry: {
 /**
  * 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.
+ * VS Code Copilot's `{type:"user.message"|"assistant.message", data:{content}}` shape,
+ * and Codex's `{type:"response_item", payload:{type:"message", role, content}}` shape.
  */
 export function readTranscriptFile(path: string): Message[] {
   try {