portable-agent-layer 0.66.1 → 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,49 @@
         "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"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts --agent=claude"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=claude"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
+          }
+        ]
+      }
+    ],
+    "PermissionDenied": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
           }
         ]
       }
@@ -140,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.66.1",
+  "version": "0.68.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     "lint": "biome lint",
     "lint-write": "biome lint --write",
     "check": "biome check",
-    "check-write": "biome check --write",
+    "check-write": "bun .agents/scripts/check-write.ts",
     "knip": "knip-bun",
     "klint": "klint",
     "jscpd": "jscpd --noTips",
@@ -96,6 +96,7 @@
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "adm-zip": "^0.5.17",
+    "fast-myers-diff": "^3.2.0",
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
     "playwright": "^1.60.0",

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

@@ -0,0 +1,29 @@
+/**
+ * Hook: PostToolUse — pairs the parked before-state with the result and writes
+ * the ledger entry.
+ *
+ * Only a call that actually landed reaches this event, so every entry written
+ * here is an applied one. A denied or failed call fires the snapshot half and
+ * never this one, leaving its snapshot unclaimed — which is why claiming also
+ * reaps the ones that were abandoned.
+ *
+ * Silent and fail-open, for the same reason as its other half.
+ */
+
+import { commitApplied, ledgeredCalls } from "./lib/ledger-hook";
+import { logDebug } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+
+  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

@@ -0,0 +1,30 @@
+/**
+ * Hook: PreToolUse — parks the target file's current contents before an edit.
+ *
+ * This half exists because the other half cannot do its job alone. A post-tool
+ * event fires once the file has already been rewritten, so the prior contents
+ * are gone and "what changed" is unanswerable from it. Reading the file here,
+ * before the tool runs, is the only moment the before-state still exists.
+ *
+ * Silent and fail-open: stdout is the agent's protocol channel, and a ledger
+ * that could block an edit would be a worse thing than a ledger with a gap.
+ */
+
+import { ledgeredCalls, snapshotCall } from "./lib/ledger-hook";
+import { logDebug } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+
+  const calls = ledgeredCalls(input);
+  if (calls.length === 0) process.exit(0);
+
+  for (const call of calls) {
+    snapshotCall(call);
+    logDebug("LedgerSnapshot", `captured ${call.tool} ${call.toolUseId}`);
+  }
+} catch {
+  process.exit(0);
+}

package/src/hooks/LedgerUnapplied.ts

@@ -0,0 +1,69 @@
+/**
+ * Hook: PostToolUseFailure and PermissionDenied — records an edit that was
+ * attempted and did not land.
+ *
+ * A log that keeps only what succeeded cannot answer what was attempted, and
+ * that is usually the question being asked of it. So the two endings that are
+ * not success are recorded too, and kept apart: `failed` is the tool's own
+ * attempt breaking, `denied` is something refusing to let it run.
+ *
+ * One hook serves both events because they differ only in which key carries the
+ * reason — a difference `unappliedVerdictOf` owns, so registering this on a
+ * third such event later is a line in that table rather than a new file.
+ *
+ * Not everything that fails to land reaches here. A manual denial at the
+ * permission dialog, a `deny` rule, and a PreToolUse hook's own block all fire
+ * PreToolUse and nothing after it; a schema rejection fires no hook at all.
+ * Those attempts leave a snapshot no half ever claims, which is what the reaper
+ * in ledger.ts is for.
+ *
+ * Silent and fail-open, for the same reason as the other halves.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import {
+  claimPending,
+  type PendingSnapshot,
+  reapStalePending,
+  recordAction,
+} from "./lib/ledger";
+import { ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
+import { logDebug } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+/**
+ * The snapshot is the trustworthy source, but its absence is recoverable here
+ * in a way it never is after a successful edit: nothing landed, so whatever is
+ * on disk now is still the before-state.
+ */
+function beforeState(pending: PendingSnapshot | null, target: string): string | null {
+  if (pending) return pending.before;
+  return existsSync(target) ? readFileSync(target, "utf-8") : null;
+}
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+
+  const calls = ledgeredCalls(input);
+  const verdict = calls.length > 0 && unappliedVerdictOf(input);
+  if (!verdict) process.exit(0);
+
+  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();
+} 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),
   };
 }