portable-agent-layer 0.67.0 → 0.68.0

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

@@ -2,7 +2,7 @@
 name: pal-analyze
 license: MIT
 description: "Run learning analysis — surface rating trends, recurring failure patterns, and graduation candidates. Use when learning analysis is due, or when the user asks about performance patterns, low ratings, or what to improve."
-argument-hint: [optional: --actionable for AI-generated recommendations]
+argument-hint: "[optional: --actionable for AI-generated recommendations]"
 metadata:
   source: portable-agent-layer
   triggers:

package/assets/skills/pal-reflect/SKILL.md

@@ -2,7 +2,7 @@
 name: pal-reflect
 license: MIT
 description: "Run relationship reflect — promote recurring behavioral observations into tracked opinions. Use when relationship reflect is due, or when the user asks to review what patterns have been observed."
-argument-hint: [optional: --dry-run to preview without writing]
+argument-hint: "[optional: --dry-run to preview without writing]"
 metadata:
   source: portable-agent-layer
   triggers:

package/assets/skills/projects/SKILL.md

@@ -2,7 +2,7 @@
 name: projects
 license: MIT
 description: "Project context management. PROACTIVE — use when the user references a project (by name or as \"this repo\", \"current work\"), asks to add/update/complete a project, says \"store under a named project\", \"track this\", \"what am I working on\", \"my projects\", \"my priorities\". Also triggered by ISC/ISA terminology — ISC stands for Ideal State Criteria, a project's verifiable done-conditions stored as `ISC-N:` lines in the Criteria section of its ISA.md spec. Phrases like \"ISC\", \"open/opening the ISC\", \"open ISCs\" (unfinished criteria), \"create/creating a ticket for a project\", \"new ticket\", or \"project ticket\" all map here: use `list-isc` to read them, `add-isc` to create one, `complete-isc`/`reopen-isc` to change status."
-argument-hint: [list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause]
+argument-hint: "[list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause]"
 metadata:
   source: portable-agent-layer
   triggers:

package/assets/skills/telos/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: telos
 description: "Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies."
-argument-hint: [area to view or update]
+argument-hint: "[area to view or update]"
 metadata:
   source: portable-agent-layer
   derived-from: https://github.com/danielmiessler/LifeOS

package/assets/templates/hooks.codex.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=codex"
           }
         ]
       }
@@ -15,7 +15,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=codex"
           }
         ]
       }
@@ -25,7 +25,21 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=codex"
+          },
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=codex"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=codex"
           }
         ]
       }
@@ -35,7 +49,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=codex bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=codex"
           }
         ]
       }

package/assets/templates/hooks.copilot.json

@@ -4,39 +4,58 @@
     "sessionStart": [
       {
         "type": "command",
-        "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"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=copilot"
       }
     ],
     "userPromptSubmitted": [
       {
         "type": "command",
-        "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"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=copilot"
       }
     ],
     "preToolUse": [
       {
         "type": "command",
-        "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"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=copilot"
       },
       {
         "type": "command",
-        "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"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=copilot"
       },
       {
         "type": "command",
-        "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"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=copilot"
+      },
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=copilot"
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=copilot"
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=copilot --event=postToolUseFailure",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=copilot --event=postToolUseFailure"
       }
     ],
     "agentStop": [
       {
         "type": "command",
-        "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"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=copilot"
       }
     ]
   }

package/assets/templates/hooks.cursor.json

@@ -4,39 +4,55 @@
     "sessionStart": [
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=cursor"
       }
     ],
     "beforeSubmitPrompt": [
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=cursor"
       }
     ],
     "preToolUse": [
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=cursor"
       },
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=cursor"
       },
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=cursor"
+      },
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=cursor"
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=cursor"
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=cursor"
       }
     ],
     "beforeShellExecution": [
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=cursor"
       }
     ],
     "stop": [
       {
         "type": "command",
-        "command": "PAL_AGENT=cursor bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=cursor"
       }
     ]
   }

package/assets/templates/settings.claude.json

@@ -69,7 +69,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LoadContext.ts --agent=claude"
           }
         ]
       },
@@ -78,7 +78,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/CompactRecover.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/CompactRecover.ts --agent=claude"
           }
         ]
       }
@@ -89,7 +89,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts --agent=claude"
           }
         ]
       }
@@ -100,7 +100,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/UserPromptOrchestrator.ts --agent=claude"
           }
         ]
       }
@@ -111,7 +111,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/SecurityValidator.ts --agent=claude"
           }
         ]
       },
@@ -120,7 +120,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/SkillGuard.ts --agent=claude"
           }
         ]
       },
@@ -129,7 +129,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts --agent=claude"
           }
         ]
       },
@@ -138,7 +138,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=claude"
           }
         ]
       }
@@ -149,7 +149,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=claude"
           }
         ]
       }
@@ -160,7 +160,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
           }
         ]
       }
@@ -171,7 +171,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
           }
         ]
       }
@@ -182,7 +182,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=claude"
           }
         ]
       }

package/package.json

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

package/src/cli/index.ts

@@ -469,7 +469,11 @@ function checkCodexHooksRegistered(): boolean {
 }
 
 function checkCopilotInstructionsPresent(): boolean {
-  return existsSync(resolve(platform.copilotDir(), "copilot-instructions.md"));
+  const instructionsDir = resolve(platform.copilotDir(), "instructions");
+  if (!existsSync(instructionsDir)) return false;
+  return readdirSync(instructionsDir).some(
+    (f) => f.startsWith("pal-") && f.endsWith(".instructions.md")
+  );
 }
 
 // ── Install integrity (Tier 2 doctor checks) ──
@@ -939,8 +943,8 @@ function doctor(silent = false): DoctorResult {
         ? ok("Copilot hooks registered")
         : fail("Copilot hooks — not registered (run 'pal cli install --copilot')");
       checkCopilotInstructionsPresent()
-        ? ok("copilot-instructions.md present")
-        : warn("copilot-instructions.md missing (run 'pal cli install --copilot')");
+        ? ok("Copilot instructions present")
+        : warn("Copilot instructions missing (written at first session stop)");
     }
     if (codex.available) {
       checkCodexHooksRegistered()

package/src/hooks/LedgerCommit.ts

@@ -10,9 +10,7 @@
  * Silent and fail-open, for the same reason as its other half.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { claimPending, reapStalePending, recordAction } from "./lib/ledger";
-import { ledgeredCall } from "./lib/ledger-hook";
+import { commitApplied, ledgeredCalls } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -20,24 +18,12 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  const call = ledgeredCall(input);
-  if (!call) process.exit(0);
-
-  // No snapshot means no before-state, and an entry claiming one it never had
-  // would be worse than the missing entry.
-  const pending = claimPending(call.toolUseId);
-  if (!pending) process.exit(0);
-
-  const entry = recordAction({
-    tool: pending.tool,
-    target: pending.target,
-    outcome: "applied",
-    before: pending.before,
-    after: existsSync(call.target) ? readFileSync(call.target, "utf-8") : null,
-  });
-
-  reapStalePending();
-  logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);
+  for (const call of ledgeredCalls(input)) {
+    const entry = commitApplied(call);
+    if (entry) {
+      logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);
+    }
+  }
 } catch {
   process.exit(0);
 }

package/src/hooks/LedgerSnapshot.ts

@@ -10,9 +10,7 @@
  * that could block an edit would be a worse thing than a ledger with a gap.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { savePending } from "./lib/ledger";
-import { ledgeredCall } from "./lib/ledger-hook";
+import { ledgeredCalls, snapshotCall } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -20,18 +18,13 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  const call = ledgeredCall(input);
-  if (!call) process.exit(0);
+  const calls = ledgeredCalls(input);
+  if (calls.length === 0) process.exit(0);
 
-  savePending({
-    ...call,
-    // Absent rather than empty: a file that does not exist yet is a creation,
-    // which is a different event from a write over an empty file.
-    before: existsSync(call.target) ? readFileSync(call.target, "utf-8") : null,
-    ts: new Date().toISOString(),
-  });
-
-  logDebug("LedgerSnapshot", `captured ${call.tool} ${call.toolUseId}`);
+  for (const call of calls) {
+    snapshotCall(call);
+    logDebug("LedgerSnapshot", `captured ${call.tool} ${call.toolUseId}`);
+  }
 } catch {
   process.exit(0);
 }

package/src/hooks/LedgerUnapplied.ts

@@ -27,7 +27,7 @@ import {
   reapStalePending,
   recordAction,
 } from "./lib/ledger";
-import { ledgeredCall, unappliedVerdictOf } from "./lib/ledger-hook";
+import { ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -45,23 +45,25 @@ try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
 
-  const call = ledgeredCall(input);
-  const verdict = call && unappliedVerdictOf(input);
-  if (!call || !verdict) process.exit(0);
+  const calls = ledgeredCalls(input);
+  const verdict = calls.length > 0 && unappliedVerdictOf(input);
+  if (!verdict) process.exit(0);
 
-  const entry = recordAction({
-    tool: call.tool,
-    target: call.target,
-    outcome: verdict.outcome,
-    before: beforeState(claimPending(call.toolUseId), call.target),
-    // Nothing landed. That is what this event means, and it is the difference
-    // between this entry and an applied one.
-    after: null,
-    reason: verdict.reason,
-  });
+  for (const call of calls) {
+    const entry = recordAction({
+      tool: call.tool,
+      target: call.target,
+      outcome: verdict.outcome,
+      before: beforeState(claimPending(call.toolUseId), call.target),
+      // Nothing landed. That is what this event means, and it is the difference
+      // between this entry and an applied one.
+      after: null,
+      reason: verdict.reason,
+    });
+    logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
+  }
 
   reapStalePending();
-  logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
 } catch {
   process.exit(0);
 }

package/src/hooks/LoadContext.ts

@@ -5,8 +5,9 @@
  * This hook injects dynamic context only: wisdom principles, relationship notes,
  * learning digest, signal trends, failure patterns, active work state.
  *
- * Copilot: sessionStart output is ignored by the runtime. Instead, we write the merged
- * context directly to ~/.copilot/copilot-instructions.md so it is picked up on load.
+ * Copilot: the CLI reads additionalContext from this hook's stdout, while
+ * ~/.copilot/instructions/ is read only by the VS Code extension. The merged
+ * context goes to both so either surface picks it up.
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -63,6 +64,7 @@ try {
         `---\napplyTo: "**"\n---\n\n${context}`,
         "utf-8"
       );
+      process.stdout.write(JSON.stringify({ additionalContext: context }));
     }
     logDebug(
       "LoadContext",

package/src/hooks/lib/actor.ts

@@ -15,7 +15,7 @@
  */
 
 import { resolve } from "node:path";
-import { type AgentType, getActiveAgent } from "./agent";
+import { type AgentType, declaredAgent } from "./agent";
 import {
   type IdentityBase,
   loadIdentity,
@@ -50,8 +50,8 @@ export interface RecordAttribution {
   machine: string;
   /** Which person caused it. */
   actor: string;
-  /** Which agent the actor was driving — claude, codex, cursor, copilot, opencode. */
-  runtime: AgentType;
+  /** Which agent the actor was driving, or "unknown" when none declared itself. */
+  runtime: AgentType | "unknown";
   /** Whether a human turn was behind the call. */
   authority: Authority;
 }
@@ -165,7 +165,7 @@ export function currentAttribution(): RecordAttribution {
   return {
     machine: loadMachine().id,
     actor: loadActor().id,
-    runtime: getActiveAgent(),
+    runtime: declaredAgent() ?? "unknown",
     authority: currentAuthority(),
   };
 }

package/src/hooks/lib/agent.ts

@@ -42,13 +42,20 @@ function agentFromArgv(): AgentType | undefined {
   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 declared = agentFromArgv() ?? agentFromEnv();
-  if (declared) return declared;
+function agentFromRuntimeEnv(): AgentType | undefined {
   if (process.env.CURSOR_VERSION) return "cursor";
   if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
-  return "claude";
+  return undefined;
+}
+
+/** The agent something actually said was running, or undefined if nothing did. */
+export function declaredAgent(): AgentType | undefined {
+  return agentFromArgv() ?? agentFromEnv() ?? agentFromRuntimeEnv();
+}
+
+/** Which agent's conventions to follow. Assumes "claude" when undeclared. */
+export function getActiveAgent(): AgentType {
+  return declaredAgent() ?? "claude";
 }
 
 export const isClaude = () => getActiveAgent() === "claude";
@@ -71,10 +78,27 @@ function firstString(...values: unknown[]): string | undefined {
 
 function firstObject(...values: unknown[]): Record<string, unknown> | undefined {
   return values.find(
-    (v): v is Record<string, unknown> => typeof v === "object" && v !== null
+    (v): v is Record<string, unknown> =>
+      typeof v === "object" && v !== null && !Array.isArray(v)
   );
 }
 
+/** Copilot's CLI sends toolArgs as JSON text where the others send an object. */
+function parsedObject(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    return firstObject(parsed);
+  } catch {
+    return undefined;
+  }
+}
+
+function toolInputOf(payload: Record<string, unknown>): Record<string, unknown> {
+  const candidates = [payload.tool_input, payload.toolArgs, payload.toolInput];
+  return firstObject(...candidates) ?? candidates.map(parsedObject).find(Boolean) ?? {};
+}
+
 /**
  * Normalize a preToolUse payload across agents.
  *
@@ -90,7 +114,7 @@ export function normalizeToolUse(raw: unknown): ToolUseRequest | null {
   if (!toolName) return null;
   return {
     toolName,
-    toolInput: firstObject(payload.tool_input, payload.toolArgs, payload.toolInput) ?? {},
+    toolInput: toolInputOf(payload),
     hookEventName: firstString(payload.hook_event_name, payload.hookEventName),
   };
 }

package/src/hooks/lib/ledger-hook.ts

@@ -6,8 +6,17 @@
  * tool the post-tool half ignores leaves a snapshot nothing ever claims.
  */
 
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { normalizeToolUse } from "./agent";
-import type { LedgerOutcome } from "./ledger";
+import {
+  claimPending,
+  type LedgerEntry,
+  type LedgerOutcome,
+  reapStalePending,
+  recordAction,
+  savePending,
+} from "./ledger";
 
 /**
  * Edits and writes, which carry their own target in the call. A shell command's
@@ -16,12 +25,39 @@ import type { LedgerOutcome } from "./ledger";
  *
  * Reads and searches are excluded because they are queries, not actions, and a
  * ledger that logs them buries the changes among them.
+ *
+ * The four beyond edit and write are Copilot's own names for the same act — its
+ * runtime groups them as its file-editing tools, and it sends the command as
+ * the tool name rather than as an argument.
+ */
+const LEDGERED_TOOLS = new Set([
+  "edit",
+  "write",
+  "create",
+  "insert",
+  "str_replace",
+  "str_replace_editor",
+]);
+
+/**
+ * Copilot's CLI also writes through a patch, and one call of that edits however
+ * many files the patch names. Its targets live in the patch body rather than in
+ * an argument, so it is filtered separately and read by patchedTargets.
+ */
+const PATCHING_TOOLS = new Set(["apply_patch", "applypatch"]);
+
+/**
+ * The editor tool that changes a file also reads one, under a command argument.
+ * A read recorded as an action would put queries back in a log of changes.
  */
-const LEDGERED_TOOLS = new Set(["edit", "write"]);
+const READING_COMMANDS = new Set(["view"]);
 
 /** Agents disagree on the spelling; the value is the same file either way. */
 const TARGET_KEYS = ["file_path", "filePath", "path"];
 
+/** Every header in the V4A patch format that names a file the patch changes. */
+const PATCHED_FILE_HEADER = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+
 export interface LedgeredCall {
   toolUseId: string;
   tool: string;
@@ -32,14 +68,104 @@ export interface LedgeredCall {
  * The one reading of a payload both halves share. Asking the same question in
  * two places is how they drift apart, and a drift here is silent: the pre-tool
  * half parks a snapshot the post-tool half never comes to claim.
+ *
+ * A list because a patch call changes a set of files, not one.
  */
-export function ledgeredCall(payload: Record<string, unknown>): LedgeredCall | null {
+export function ledgeredCalls(payload: Record<string, unknown>): LedgeredCall[] {
   const toolUse = normalizeToolUse(payload);
-  const toolUseId = toolUseIdOf(payload);
-  if (!toolUse || !toolUseId) return null;
+  if (!toolUse) return [];
+
+  const patched = patchedTargets(payload, toolUse.toolName);
+  if (patched.length > 0) return patchCalls(payload, toolUse.toolName, patched);
 
   const target = ledgeredTarget(toolUse.toolName, toolUse.toolInput);
-  return target ? { toolUseId, tool: toolUse.toolName, target } : null;
+  if (!target) return [];
+
+  const toolUseId = pairingKeyOf(payload, toolUse.toolName, target);
+  return toolUseId ? [{ toolUseId, tool: toolUse.toolName, target }] : [];
+}
+
+/**
+ * A patch changes several files under one tool call, so the call's own id
+ * cannot key its snapshots — all of them would collide on it and only one would
+ * ever be claimed. Naming the target in the key is what keeps them apart.
+ */
+function patchCalls(
+  payload: Record<string, unknown>,
+  tool: string,
+  targets: string[]
+): LedgeredCall[] {
+  const anchor = toolUseIdOf(payload) ?? sessionOf(payload);
+  if (!anchor) return [];
+  return targets.map((target) => ({
+    toolUseId: derivedPairingKey(anchor, tool, target),
+    tool,
+    target,
+  }));
+}
+
+/**
+ * The files a patch call changes, resolved against the directory the agent ran
+ * it in — a patch names them the way the agent typed them, which is relative.
+ */
+function patchedTargets(payload: Record<string, unknown>, toolName: string): string[] {
+  if (!PATCHING_TOOLS.has(toolName.toLowerCase())) return [];
+
+  const patch = patchBodyOf(payload);
+  if (!patch) return [];
+
+  const base = typeof payload.cwd === "string" ? payload.cwd : process.cwd();
+  return Array.from(patch.matchAll(PATCHED_FILE_HEADER), (match) =>
+    absoluteFrom(base, match[1].trim())
+  );
+}
+
+/** Its arguments are the patch itself, rather than JSON naming a file. */
+function patchBodyOf(payload: Record<string, unknown>): string | null {
+  const args = payload.toolArgs ?? payload.tool_input ?? payload.toolInput;
+  if (typeof args === "string") return args.length > 0 ? args : null;
+  return patchCommandOf(args);
+}
+
+/** Codex carries the patch under a command key instead of sending it as the arguments. */
+function patchCommandOf(args: unknown): string | null {
+  if (typeof args !== "object" || args === null || Array.isArray(args)) return null;
+  const command = (args as Record<string, unknown>).command;
+  return typeof command === "string" && command.length > 0 ? command : null;
+}
+
+function absoluteFrom(base: string, path: string): string {
+  return isAbsolute(path) ? path : resolve(base, path);
+}
+
+/**
+ * Copilot's CLI publishes no id for a tool invocation, so its two halves are
+ * paired on what both do carry. Session, tool and target identify the call
+ * uniquely as long as it does not overlap another write to the same file in
+ * the same session, which sequential tool use cannot produce.
+ */
+function derivedPairingKey(anchor: string, tool: string, target: string): string {
+  const digest = new Bun.CryptoHasher("sha256")
+    .update([anchor, tool, target].join(" "), "utf-8")
+    .digest("hex");
+  return `derived-${digest.slice(0, 32)}`;
+}
+
+function sessionOf(payload: Record<string, unknown>): string | null {
+  const session = payload.sessionId ?? payload.session_id;
+  return typeof session === "string" && session.length > 0 ? session : null;
+}
+
+function pairingKeyOf(
+  payload: Record<string, unknown>,
+  tool: string,
+  target: string
+): string | null {
+  const explicit = toolUseIdOf(payload);
+  if (explicit) return explicit;
+
+  const session = sessionOf(payload);
+  return session ? derivedPairingKey(session, tool, target) : null;
 }
 
 /**
@@ -50,16 +176,28 @@ export function ledgeredCall(payload: Record<string, unknown>): LedgeredCall | n
  * They carry the same fact under different keys, which is the whole reason this
  * mapping is written down in one place rather than read twice.
  */
-const UNAPPLIED_EVENTS: Record<string, { outcome: LedgerOutcome; reasonKey: string }> = {
-  PostToolUseFailure: { outcome: "failed", reasonKey: "error" },
-  PermissionDenied: { outcome: "denied", reasonKey: "reason" },
-};
+const UNAPPLIED_EVENTS: Record<string, { outcome: LedgerOutcome; reasonKeys: string[] }> =
+  {
+    PostToolUseFailure: { outcome: "failed", reasonKeys: ["error"] },
+    PermissionDenied: { outcome: "denied", reasonKeys: ["reason"] },
+    postToolUseFailure: { outcome: "failed", reasonKeys: ["error_message", "error"] },
+  };
+
+function deniedByFailureType(payload: Record<string, unknown>): boolean {
+  return payload.failure_type === "permission_denied";
+}
 
 export interface UnappliedVerdict {
   outcome: LedgerOutcome;
   reason?: string;
 }
 
+/** Copilot names the event nowhere in its payload, so its config says so on argv. */
+function eventFromArgv(): string | undefined {
+  const flag = process.argv.find((a) => a.startsWith("--event="));
+  return flag?.slice("--event=".length) || undefined;
+}
+
 /**
  * What became of a call, for the events that mean it did not land — or nothing
  * when the payload is some other event, so one hook can be registered on both
@@ -68,18 +206,43 @@ export interface UnappliedVerdict {
 export function unappliedVerdictOf(
   payload: Record<string, unknown>
 ): UnappliedVerdict | null {
-  const event = payload.hook_event_name ?? payload.hookEventName;
+  const event = payload.hook_event_name ?? payload.hookEventName ?? eventFromArgv();
   if (typeof event !== "string") return null;
 
   const mapping = UNAPPLIED_EVENTS[event];
   if (!mapping) return null;
 
-  const reason = payload[mapping.reasonKey];
-  // A reason the runtime did not send is left absent rather than invented: an
-  // entry that states a cause it does not have is worse than one that admits none.
-  return typeof reason === "string" && reason.length > 0
-    ? { outcome: mapping.outcome, reason }
-    : { outcome: mapping.outcome };
+  const outcome = deniedByFailureType(payload) ? "denied" : mapping.outcome;
+  const reason = mapping.reasonKeys
+    .map((key) => payload[key])
+    .find((value): value is string => typeof value === "string" && value.length > 0);
+  return reason ? { outcome, reason } : { outcome };
+}
+
+function contentsOf(path: string): string | null {
+  return existsSync(path) ? readFileSync(path, "utf-8") : null;
+}
+
+/** Park the target's current contents, the last moment they still exist. */
+export function snapshotCall(call: LedgeredCall): void {
+  savePending({ ...call, before: contentsOf(call.target), ts: new Date().toISOString() });
+}
+
+/** Pair a parked before-state with the result, or nothing if none was parked. */
+export function commitApplied(call: LedgeredCall): LedgerEntry | null {
+  const pending = claimPending(call.toolUseId);
+  if (!pending) return null;
+
+  const entry = recordAction({
+    tool: pending.tool,
+    target: pending.target,
+    outcome: "applied",
+    before: pending.before,
+    beforeState: pending.beforeState,
+    after: contentsOf(call.target),
+  });
+  reapStalePending();
+  return entry;
 }
 
 export function toolUseIdOf(payload: Record<string, unknown>): string | null {
@@ -90,6 +253,11 @@ export function toolUseIdOf(payload: Record<string, unknown>): string | null {
   return null;
 }
 
+function readsRatherThanChanges(toolInput: Record<string, unknown>): boolean {
+  const command = toolInput.command;
+  return typeof command === "string" && READING_COMMANDS.has(command);
+}
+
 /**
  * The absolute path this call will change, or nothing if the call is not one
  * the ledger records.
@@ -99,6 +267,7 @@ export function ledgeredTarget(
   toolInput: Record<string, unknown>
 ): string | null {
   if (!LEDGERED_TOOLS.has(toolName.toLowerCase())) return null;
+  if (readsRatherThanChanges(toolInput)) return null;
   for (const key of TARGET_KEYS) {
     const value = toolInput[key];
     if (typeof value === "string" && value.length > 0) return value;

package/src/hooks/lib/ledger.ts

@@ -35,6 +35,7 @@ import { calcPatch } from "fast-myers-diff";
 import { currentAttribution, type RecordAttribution } from "./actor";
 import { encodeAnchor } from "./anchor";
 import { ensureDir, paths } from "./paths";
+import { isSensitivePath } from "./sensitive-path";
 
 /**
  * What became of the action.
@@ -82,6 +83,8 @@ export interface LedgerDelta {
   hunks: LedgerHunk[];
   /** Set when the change itself was too large to keep. Its absence means the hunks are complete. */
   truncated?: boolean;
+  /** Set when the target is one whose contents the ledger never keeps. */
+  redacted?: boolean;
 }
 
 export interface LedgerEntry extends RecordAttribution {
@@ -111,8 +114,10 @@ export interface RecordActionInput {
   /** Absolute path of the file the action targeted. */
   target: string;
   outcome: LedgerOutcome;
-  /** Prior content; null for a file creation. */
+  /** Prior content; null for a file creation, and withheld for a sensitive target. */
   before: string | null;
+  /** Identity of the prior content, when the content itself was withheld. */
+  beforeState?: LedgerState;
   /** Resulting content; null when nothing landed. */
   after: string | null;
   reason?: string;
@@ -156,6 +161,13 @@ function toLines(content: string | null): string[] {
  * The change between two states, or nothing when there was no transition to
  * describe. An action that did not land has no delta — see LedgerEntry.delta.
  */
+const WITHHELD: LedgerDelta = { hunks: [], redacted: true };
+
+function deltaFor(input: RecordActionInput): LedgerDelta | undefined {
+  if (isSensitivePath(input.target)) return WITHHELD;
+  return deltaOf(input.before, input.after);
+}
+
 function deltaOf(before: string | null, after: string | null): LedgerDelta | undefined {
   if (after === null) return undefined;
 
@@ -180,7 +192,7 @@ function deltaOf(before: string | null, after: string | null): LedgerDelta | und
  * side of the ledger — a stored change is only evidence if it can be replayed.
  */
 export function applyDelta(before: string | null, delta: LedgerDelta): string | null {
-  if (delta.truncated) return null;
+  if (delta.truncated || delta.redacted) return null;
 
   const lines = toLines(before);
   const out: string[] = [];
@@ -230,7 +242,7 @@ function freeArchivePath(stamp: string): string {
  * being asked of it.
  */
 export function recordAction(input: RecordActionInput): LedgerEntry {
-  const delta = deltaOf(input.before, input.after);
+  const delta = deltaFor(input);
   const entry: LedgerEntry = {
     id: generateId(),
     ts: new Date().toISOString(),
@@ -238,7 +250,7 @@ export function recordAction(input: RecordActionInput): LedgerEntry {
     tool: input.tool,
     target: encodeAnchor(input.target),
     outcome: input.outcome,
-    before: stateOf(input.before),
+    before: input.beforeState ?? stateOf(input.before),
     after: stateOf(input.after),
     ...(delta ? { delta } : {}),
     ...(input.reason ? { reason: input.reason } : {}),
@@ -262,6 +274,7 @@ export interface PendingSnapshot {
   tool: string;
   target: string;
   before: string | null;
+  beforeState?: LedgerState;
   ts: string;
 }
 
@@ -281,8 +294,15 @@ function pendingPath(toolUseId: string): string {
   return resolve(pendingDir(), `${toolUseId.replace(/[^A-Za-z0-9_-]/g, "")}.json`);
 }
 
+function withheldWhenSensitive(snapshot: PendingSnapshot): PendingSnapshot {
+  if (snapshot.before === null || !isSensitivePath(snapshot.target)) return snapshot;
+  const state = stateOf(snapshot.before);
+  return { ...snapshot, before: null, ...(state ? { beforeState: state } : {}) };
+}
+
 export function savePending(snapshot: PendingSnapshot): void {
-  writeFileSync(pendingPath(snapshot.toolUseId), JSON.stringify(snapshot), "utf-8");
+  const withheld = withheldWhenSensitive(snapshot);
+  writeFileSync(pendingPath(withheld.toolUseId), JSON.stringify(withheld), "utf-8");
 }
 
 /**

package/src/hooks/lib/sensitive-path.ts

@@ -0,0 +1,117 @@
+/**
+ * Paths whose contents the ledger notes the change of but never keeps.
+ *
+ * The floor below is fixed in code rather than configured: a denylist a user can
+ * shrink is a suggestion, and settings may only add to this one. That direction
+ * also makes a malformed user pattern harmless — the worst it can do is redact
+ * something it did not need to.
+ */
+
+import { raw } from "./settings";
+
+const ENV_TEMPLATE_SUFFIXES = [".sample", ".example", ".template", ".dist", ".defaults"];
+
+/** Matched whole: `id_*` would catch `id_generator.ts`, `credentials*` a test file. */
+const SECRET_FILENAMES = new Set([
+  ".npmrc",
+  ".netrc",
+  "_netrc",
+  ".pgpass",
+  ".htpasswd",
+  ".envrc",
+  "credentials",
+  "id_rsa",
+  "id_dsa",
+  "id_ecdsa",
+  "id_ecdsa_sk",
+  "id_ed25519",
+  "id_ed25519_sk",
+]);
+
+const SECRET_EXTENSIONS = [
+  ".pem",
+  ".key",
+  ".p12",
+  ".pfx",
+  ".keystore",
+  ".jks",
+  ".asc",
+  ".gpg",
+  ".kdbx",
+];
+
+const SECRET_DIRECTORIES = new Set([
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".docker",
+  ".kube",
+  ".gcloud",
+  ".azure",
+]);
+
+const SECRET_DIRECTORY_PAIRS = [
+  [".config", "gh"],
+  [".config", "gcloud"],
+  [".local", "share/keyrings"],
+];
+
+function segmentsOf(path: string): string[] {
+  return path.split(/[/\\]/).filter(Boolean);
+}
+
+function isLiveDotenv(name: string): boolean {
+  if (name !== ".env" && !name.startsWith(".env.")) return false;
+  return !ENV_TEMPLATE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+function isSecretFilename(name: string): boolean {
+  return SECRET_FILENAMES.has(name);
+}
+
+function hasSecretExtension(name: string): boolean {
+  return SECRET_EXTENSIONS.some((ext) => name.toLowerCase().endsWith(ext));
+}
+
+function inSecretDirectory(dirs: string[]): boolean {
+  if (dirs.some((dir) => SECRET_DIRECTORIES.has(dir))) return true;
+  return SECRET_DIRECTORY_PAIRS.some(([parent, child]) =>
+    dirs.some(
+      (dir, i) =>
+        dir === parent &&
+        dirs
+          .slice(i + 1)
+          .join("/")
+          .startsWith(child)
+    )
+  );
+}
+
+function userPatterns(): string[] {
+  const configured = raw().ledger?.redactPaths;
+  if (!Array.isArray(configured)) return [];
+  return configured.filter(
+    (pattern) => typeof pattern === "string" && pattern.length > 0
+  );
+}
+
+function matchesUserPattern(path: string, name: string): boolean {
+  return userPatterns().some((pattern) => {
+    const glob = new Bun.Glob(pattern);
+    return glob.match(path) || glob.match(name);
+  });
+}
+
+/** Should this file's contents be withheld from the ledger? */
+export function isSensitivePath(path: string): boolean {
+  const segments = segmentsOf(path);
+  const name = segments.at(-1) ?? "";
+  const dirs = segments.slice(0, -1);
+  return (
+    inSecretDirectory(dirs) ||
+    isLiveDotenv(name) ||
+    isSecretFilename(name) ||
+    hasSecretExtension(name) ||
+    matchesUserPattern(path, name)
+  );
+}

package/src/hooks/lib/settings.ts

@@ -25,6 +25,11 @@ export interface PalSettingsData {
   dynamicContext?: Record<string, boolean>;
   /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
   attribution?: { enabled?: boolean; decided?: boolean };
+  /**
+   * Action-ledger user extension. `redactPaths` adds to the built-in set of
+   * paths whose contents are never stored; it cannot shrink it.
+   */
+  ledger?: { redactPaths?: string[] };
   /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
   steering?: {
     disable?: string[];

package/src/targets/lib.ts

@@ -472,7 +472,21 @@ export function unmergeCursorHooks(
 
 type CodexHookCommand = { type: string; command: string; timeout?: number };
 type CodexHookGroup = { matcher?: string; hooks: CodexHookCommand[] };
-type CodexHooks = { hooks?: Record<string, CodexHookGroup[]> };
+type CodexHooks = {
+  hooks?: Record<string, CodexHookGroup[]>;
+  description?: string;
+  version?: unknown;
+};
+
+/**
+ * Codex parses hooks.json strictly and accepts only `description` and `hooks`.
+ * A stale `version` makes it reject the whole file — every PAL hook silently
+ * stops — and merging preserves what it finds, so it must be dropped by name.
+ */
+function withoutRejectedFields(config: CodexHooks): CodexHooks {
+  const { version: _version, ...accepted } = config;
+  return accepted;
+}
 
 /**
  * Normalize a PAL hook command for cross-path deduplication.
@@ -542,7 +556,7 @@ function stripPalHooks(
 
 /** Merge PAL hooks into an existing Codex hooks.json. Deduplicates by canonical command path. */
 export function mergeCodexHooks(existing: CodexHooks, template: CodexHooks): CodexHooks {
-  const result: CodexHooks = { ...existing };
+  const result: CodexHooks = withoutRejectedFields(existing);
   if (!template.hooks) return result;
   result.hooks ??= {};
 
@@ -561,7 +575,7 @@ export function unmergeCodexHooks(
   existing: CodexHooks,
   template: CodexHooks
 ): CodexHooks {
-  const result: CodexHooks = { ...existing };
+  const result: CodexHooks = withoutRejectedFields(existing);
   if (!template.hooks || !result.hooks) return result;
 
   stripPalHooks(result.hooks, collectPalCanonical(template));

package/src/targets/opencode/plugin.ts

@@ -106,6 +106,14 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
   const { isPalSpawnedInference } =
     await lib<typeof import("../../hooks/lib/spawn-guard")>("spawn-guard.ts");
 
+  const { commitApplied, ledgeredTarget, snapshotCall } =
+    await lib<typeof import("../../hooks/lib/ledger-hook")>("ledger-hook.ts");
+
+  const ledgeredOpencodeCall = (tool: string, callID: string, args: unknown) => {
+    const target = ledgeredTarget(tool, (args ?? {}) as Record<string, unknown>);
+    return target ? { toolUseId: callID, tool, target } : null;
+  };
+
   return {
     // --- Per-message: Inject dynamic system reminder ---
     "experimental.chat.system.transform": async (_input, output) => {
@@ -213,6 +221,20 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
           throw new Error(`PAL Security: ${fileReason}`);
         }
       }
+
+      const call = ledgeredOpencodeCall(toolName, _input.callID, output.args);
+      if (call) snapshotCall(call);
+    },
+
+    "tool.execute.after": async (
+      input: { tool: string; sessionID: string; callID: string; args: unknown },
+      _output: { title: string; output: string; metadata: unknown }
+    ) => {
+      const call = ledgeredOpencodeCall(input.tool, input.callID, input.args);
+      if (!call) return;
+
+      const entry = commitApplied(call);
+      if (entry) logDebug("opencode:ledger", `recorded ${entry.id} ${entry.target}`);
     },
 
     // --- Inject PAL_DIR into shell environment ---