harnery 0.32.0 → 0.34.0

package/src/core/hooks/adapter/parse.ts

@@ -10,7 +10,7 @@
  * events without affecting behavior": fail-soft beats fail-hard.
  */
 
-import type { Adapter } from "../events/schema.ts";
+import type { Adapter } from "../../adapter.ts";
 
 export interface ParsedPayload {
   hook_event_name?: string;
@@ -27,6 +27,7 @@ export interface ParsedPayload {
   model?: string;
   source?: string; // SessionStart: "startup" | "resume" | …
   prompt?: string; // UserPromptSubmit / beforeSubmitPrompt
+  agent_message?: string; // Cursor PreToolUse: user-visible assistant text before the tool
   tool_name?: string; // Pre/PostToolUse
   tool_input?: unknown; // Pre/PostToolUse: the model's call arguments
   tool_response?: unknown; // PostToolUse: the tool's output (string or object)
@@ -35,6 +36,8 @@ export interface ParsedPayload {
   clean_exit?: boolean; // SessionEnd
   exit_status?: string; // SubagentStop
   reason?: string; // SubagentStop / StopFailure
+  /** Privacy-safe Cursor execution surface, derived from native lifecycle metadata. */
+  cursor_mode?: "local" | "cloud" | "unknown";
   /** original parsed object, preserved for callers that need a field we didn't pluck. */
   raw: Record<string, unknown>;
 }
@@ -52,9 +55,18 @@ export function parsePayload(raw: string, adapter: Adapter): ParsedPayload | nul
     return null;
   }
 
-  const sessionId = normalizeSessionId(adapter, pickStr(json, "session_id"));
-  const conversationId = normalizeSessionId(adapter, pickStr(json, "conversation_id"));
+  const rawSessionId = pickStr(json, "session_id");
+  const rawConversationId = pickStr(json, "conversation_id");
+  const sessionId = normalizeSessionId(adapter, rawSessionId);
+  const conversationId = normalizeSessionId(adapter, rawConversationId);
   const parentSessionId = normalizeSessionId(adapter, pickStr(json, "parent_session_id"));
+  const hookEventName = pickStr(json, "hook_event_name");
+  const cursorGenerationId = adapter === "cursor" ? pickStr(json, "generation_id") : undefined;
+  const cursorShellHook =
+    adapter === "cursor" &&
+    (hookEventName === "beforeShellExecution" || hookEventName === "afterShellExecution");
+  const cursorCommand = cursorShellHook ? pickStr(json, "command") : undefined;
+  const normalizedToolInput = normalizeToolInput(json.tool_input, adapter);
   const normalizedRaw =
     adapter === "cursor"
       ? {
@@ -66,13 +78,15 @@ export function parsePayload(raw: string, adapter: Adapter): ParsedPayload | nul
       : json;
 
   return {
-    hook_event_name: pickStr(json, "hook_event_name"),
+    hook_event_name: hookEventName,
     session_id: sessionId,
     agent_id: pickStr(json, "agent_id"),
     subagent_id: pickStr(json, "subagent_id"),
     conversation_id: conversationId,
     parent_session_id: parentSessionId,
-    turn_id: pickStr(json, "turn_id"),
+    // Claude Code names its native turn identifier prompt_id; both are the
+    // adapter's turn-scoped id and feed native turn stamping (ADR 0078).
+    turn_id: pickStr(json, "turn_id") ?? pickStr(json, "prompt_id") ?? cursorGenerationId,
     parent_turn_id: pickStr(json, "parent_turn_id"),
     transcript_path: pickStr(json, "transcript_path"),
     cwd: pickStr(json, "cwd"),
@@ -80,18 +94,50 @@ export function parsePayload(raw: string, adapter: Adapter): ParsedPayload | nul
     model: pickStr(json, "model"),
     source: pickStr(json, "source"),
     prompt: pickStr(json, "prompt"),
-    tool_name: pickStr(json, "tool_name"),
-    tool_input: json.tool_input,
-    tool_response: json.tool_response,
+    agent_message: pickStr(json, "agent_message"),
+    tool_name: cursorShellHook ? "Shell" : pickStr(json, "tool_name"),
+    tool_input: cursorCommand ? { command: cursorCommand } : normalizedToolInput,
+    tool_response: hookEventName === "afterShellExecution" ? json.output : json.tool_response,
     tool_use_id: pickStr(json, "tool_use_id"),
     stop_hook_active: pickBool(json, "stop_hook_active"),
     clean_exit: pickBool(json, "clean_exit"),
     exit_status: pickStr(json, "exit_status"),
     reason: pickStr(json, "reason"),
+    cursor_mode: cursorMode(json, adapter, rawSessionId, rawConversationId),
     raw: normalizedRaw,
   };
 }
 
+/**
+ * Cursor prefixes cloud/private-worker conversations with `bc-`. Current
+ * sessionStart payloads also expose `is_background_agent`; either native
+ * signal is enough to classify the execution surface without retaining text.
+ */
+function cursorMode(
+  json: Record<string, unknown>,
+  adapter: Adapter,
+  sessionId: string | undefined,
+  conversationId: string | undefined,
+): ParsedPayload["cursor_mode"] {
+  if (adapter !== "cursor") return undefined;
+  const background = pickBool(json, "is_background_agent");
+  if (background === true) return "cloud";
+  if (background === false) return "local";
+  const nativeId = conversationId ?? sessionId;
+  if (!nativeId) return "unknown";
+  return nativeId.startsWith("bc-") ? "cloud" : "local";
+}
+
+/** Cursor can serialize generic tool_input as a JSON string instead of an object. */
+function normalizeToolInput(value: unknown, adapter: Adapter): unknown {
+  if (adapter !== "cursor" || typeof value !== "string") return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
 /** Cursor Glass prefixes conversation ids with `bc-`; coordination uses the bare id everywhere. */
 function normalizeSessionId(adapter: Adapter, value: string | undefined): string | undefined {
   if (adapter !== "cursor" || !value?.startsWith("bc-") || value.length <= 3) return value;
@@ -151,55 +197,54 @@ function pickBool(o: Record<string, unknown>, k: string): boolean | undefined {
  * Map the CLI-arg event-name (kebab-case, set by us in the wiring) to one of
  * the canonical event_types. Phase 2's CLI passes the kebab event
  * name; this returns the canonical event_type or null when the event has no
- * canonical equivalent (e.g. Cursor's before-shell-execution duplicates
- * pre-tool-use semantically, so we route both to `tool.pre_use`).
+ * canonical equivalent. Cursor's shell-specific hooks are retained as reliable
+ * remote/CLI fallbacks and normalized to the same tool events as generic hooks.
  */
 export function normalizeEventName(
   eventName: string,
 ): { event_type: NormalizedEventType; intra_turn: boolean } | null {
   switch (eventName) {
     case "session-start":
-      return { event_type: "session.start", intra_turn: false };
+      return { event_type: "session.started", intra_turn: false };
     case "session-end":
-      return { event_type: "session.end", intra_turn: false };
+      return { event_type: "session.ended", intra_turn: false };
     case "user-prompt-submit":
-      return { event_type: "user_prompt.submit", intra_turn: false };
+      return { event_type: "turn.started", intra_turn: false };
     case "stop":
-      return { event_type: "turn.stop", intra_turn: false };
+      return { event_type: "turn.completed", intra_turn: false };
     case "stop-failure":
-      // Phase 2: a failed stop is still a turn boundary; emit turn.stop and
-      // attach the failure signal in `data`. Phase 5 may introduce a
-      // dedicated `turn.stop_failure` event if the projector needs to branch.
-      return { event_type: "turn.stop", intra_turn: false };
+      return { event_type: "turn.completed", intra_turn: false };
     case "sub-agent-start":
-      return { event_type: "subagent.start", intra_turn: false };
+      return { event_type: "agent.started", intra_turn: false };
     case "sub-agent-stop":
-      return { event_type: "subagent.stop", intra_turn: false };
+      return { event_type: "agent.completed", intra_turn: false };
     case "pre-tool-use":
     case "before-shell-execution":
-      return { event_type: "tool.pre_use", intra_turn: true };
+      return { event_type: "tool.requested", intra_turn: true };
+    case "permission-request":
+      return { event_type: "wait.started", intra_turn: true };
     case "post-tool-use":
-      return { event_type: "tool.post_use", intra_turn: true };
+    case "after-shell-execution":
     case "post-tool-use-failure":
-      return { event_type: "tool.post_use_failure", intra_turn: true };
+      return { event_type: "tool.completed", intra_turn: true };
     case "pre-compact":
-      return { event_type: "context.compaction.started", intra_turn: false };
+      return { event_type: "context.compaction_started", intra_turn: false };
     case "post-compact":
-      return { event_type: "context.compaction.completed", intra_turn: false };
+      return { event_type: "context.compaction_completed", intra_turn: false };
     default:
       return null;
   }
 }
 
 export type NormalizedEventType =
-  | "session.start"
-  | "session.end"
-  | "user_prompt.submit"
-  | "turn.stop"
-  | "subagent.start"
-  | "subagent.stop"
-  | "tool.pre_use"
-  | "tool.post_use"
-  | "tool.post_use_failure"
-  | "context.compaction.started"
-  | "context.compaction.completed";
+  | "session.started"
+  | "session.ended"
+  | "turn.started"
+  | "turn.completed"
+  | "agent.started"
+  | "agent.completed"
+  | "tool.requested"
+  | "wait.started"
+  | "tool.completed"
+  | "context.compaction_started"
+  | "context.compaction_completed";

package/src/core/hooks/adapter/wiring.ts

@@ -12,7 +12,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   ADAPTER_SPECS,
@@ -58,18 +58,54 @@ export function groupCommands(group: HookGroup): string[] {
 
 /**
  * Whether a hook command string wires the given agent-hook subcommand. The
- * trailing space is load-bearing: it keeps `stop` from matching `stop-failure`.
+ * token boundary keeps `stop` from matching `stop-failure`, while accepting a
+ * minimal command that ends immediately after the subcommand.
  */
 export function commandWiresSubcommand(command: string, subcommand: string): boolean {
-  return command.includes(`agent-hook ${subcommand} `);
+  const escaped = subcommand.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|[\\/\\s])agent-hook\\s+${escaped}(?:\\s|$)`).test(command);
 }
 
 /** Pull the agent-hook subcommand out of a command string, or null if none. */
 function commandSubcommand(command: string): string | null {
-  const m = command.match(/agent-hook\s+([a-z][a-z-]*)\s/);
+  const m = command.match(/(?:^|[/\s])agent-hook\s+([a-z][a-z-]*)(?:\s|$)/);
   return m ? m[1]! : null;
 }
 
+/** Whether a command invokes Harnery's agent-hook binary at all. */
+export function isAgentHookCommand(command: string): boolean {
+  return commandSubcommand(command) !== null;
+}
+
+/** The canonical command installed for one adapter event. */
+export function hookCommand(
+  spec: AdapterSpec,
+  agentHookPath: string,
+  subcommand: string,
+  adapter: AdapterId,
+): string {
+  if (agentHookPath === "agent-hook") {
+    return `agent-hook ${subcommand} --adapter ${adapter}`;
+  }
+  const anchor = spec.projectDirEnv ? `"\${${spec.projectDirEnv}:-.}"/` : "";
+  return `bash ${anchor}${agentHookPath} ${subcommand} --adapter ${adapter}`;
+}
+
+/**
+ * Pick a committed hook target that survives cloning the consumer elsewhere.
+ * Projects that contain Harnery can use its repo-relative launcher. Standalone
+ * consumers use the package's installed `agent-hook` executable from PATH
+ * instead of recording a relative path back into one developer's package tree.
+ */
+export function agentHookPathForProject(projectRoot: string, packageRoot: string): string {
+  const hook = join(packageRoot, "bin", "agent-hook");
+  const candidate = relative(projectRoot, hook);
+  if (candidate === ".." || candidate.startsWith(`..${sep}`) || isAbsolute(candidate)) {
+    return "agent-hook";
+  }
+  return candidate;
+}
+
 export interface WiringDiff {
   /** Spec events not wired in the settings file. */
   missing: HookEvent[];
@@ -77,10 +113,16 @@ export interface WiringDiff {
   present: HookEvent[];
   /**
    * agent-hook subcommands wired in the file that are NOT in the current spec
-   * (e.g. an event renamed/removed by an upgrade). Additive re-init won't clean
-   * these — they need explicit removal — so they're surfaced separately.
+   * (e.g. an event renamed/removed by an upgrade). Re-init removes these, so
+   * they are surfaced separately from missing hooks.
    */
   orphans: string[];
+  /** Spec events wired more than once under their correct event key. */
+  duplicates: HookEvent[];
+  /** Spec events wired under an event key other than the canonical one. */
+  misplaced: HookEvent[];
+  /** Spec events whose correct-key command differs from init's canonical command. */
+  stale: HookEvent[];
   /** Settings fields rejected by a adapter with a strict top-level schema. */
   invalidTopLevelKeys: string[];
   /** Hook event names rejected by a adapter with a strict event schema. */
@@ -91,17 +133,43 @@ export interface WiringDiff {
  * Pure diff of one settings object against one adapter spec. Read-only inverse
  * of `wireHooks`; no fs, so it's unit-testable.
  */
-export function diffWiring(settings: SettingsFile, spec: AdapterSpec): WiringDiff {
+export function diffWiring(
+  settings: SettingsFile,
+  spec: AdapterSpec,
+  expected?: { agentHookPath: string; adapter: AdapterId },
+): WiringDiff {
   const missing: HookEvent[] = [];
   const present: HookEvent[] = [];
+  const duplicates: HookEvent[] = [];
+  const misplaced: HookEvent[] = [];
+  const stale: HookEvent[] = [];
   const hooks = settings.hooks ?? {};
 
   for (const event of spec.events) {
     const groups = hooks[event.settingsKey] ?? [];
-    const wired = groups.some((g) =>
-      groupCommands(g).some((c) => commandWiresSubcommand(c, event.subcommand)),
+    const commands = groups
+      .flatMap(groupCommands)
+      .filter((c) => commandWiresSubcommand(c, event.subcommand));
+    (commands.length > 0 ? present : missing).push(event);
+    if (commands.length > 1) duplicates.push(event);
+    if (expected && commands.length > 0) {
+      const canonical = hookCommand(
+        spec,
+        expected.agentHookPath,
+        event.subcommand,
+        expected.adapter,
+      );
+      if (commands.some((command) => command !== canonical)) stale.push(event);
+    }
+    const wrongKey = Object.entries(hooks).some(
+      ([key, otherGroups]) =>
+        key !== event.settingsKey &&
+        Array.isArray(otherGroups) &&
+        otherGroups.some((group) =>
+          groupCommands(group).some((command) => commandWiresSubcommand(command, event.subcommand)),
+        ),
     );
-    (wired ? present : missing).push(event);
+    if (wrongKey) misplaced.push(event);
   }
 
   const specSubcommands = new Set(spec.events.map((e) => e.subcommand));
@@ -131,6 +199,9 @@ export function diffWiring(settings: SettingsFile, spec: AdapterSpec): WiringDif
     missing,
     present,
     orphans: [...orphans].sort(),
+    duplicates,
+    misplaced,
+    stale,
     invalidTopLevelKeys,
     invalidEventKeys,
   };
@@ -142,6 +213,9 @@ export interface AdapterWiringStatus {
   settingsFile: string;
   missing: HookEvent[];
   orphans: string[];
+  duplicates: HookEvent[];
+  misplaced: HookEvent[];
+  stale: HookEvent[];
   invalidTopLevelKeys: string[];
   invalidEventKeys: string[];
   parseError?: string;
@@ -172,17 +246,33 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
         settingsFile: spec.settingsFile,
         missing: [],
         orphans: [],
+        duplicates: [],
+        misplaced: [],
+        stale: [],
         invalidTopLevelKeys: [],
         invalidEventKeys: [],
         parseError: (error as Error).message,
       });
       continue;
     }
-    const diff = diffWiring(settings, spec);
+    const packageRoot = harneryPackageRoot();
+    const diff = diffWiring(
+      settings,
+      spec,
+      packageRoot
+        ? {
+            agentHookPath: agentHookPathForProject(projectRoot, packageRoot),
+            adapter: id,
+          }
+        : undefined,
+    );
     if (diff.present.length === 0) continue; // not opted in → not drift
     if (
       diff.missing.length === 0 &&
       diff.orphans.length === 0 &&
+      diff.duplicates.length === 0 &&
+      diff.misplaced.length === 0 &&
+      diff.stale.length === 0 &&
       diff.invalidTopLevelKeys.length === 0 &&
       diff.invalidEventKeys.length === 0
     ) {
@@ -193,6 +283,9 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
       settingsFile: spec.settingsFile,
       missing: diff.missing,
       orphans: diff.orphans,
+      duplicates: diff.duplicates,
+      misplaced: diff.misplaced,
+      stale: diff.stale,
       invalidTopLevelKeys: diff.invalidTopLevelKeys,
       invalidEventKeys: diff.invalidEventKeys,
     });
@@ -249,12 +342,25 @@ export function summarizeAdapterWiring(projectRoot: string): AdapterWiringSummar
  * from `dist/`). Returns "" if unresolved — callers omit it from the message.
  */
 export function harneryVersion(): string {
+  const root = harneryPackageRoot();
+  if (!root) return "";
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    if (pkg.name === "harnery" && typeof pkg.version === "string") return pkg.version;
+  } catch {
+    /* unreadable package metadata */
+  }
+  return "";
+}
+
+/** Resolve the package root from either src/ (Bun) or dist/ (Node). */
+export function harneryPackageRoot(): string | null {
   try {
     let dir = dirname(fileURLToPath(import.meta.url));
     for (let i = 0; i < 8; i++) {
       try {
         const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
-        if (pkg.name === "harnery" && typeof pkg.version === "string") return pkg.version;
+        if (pkg.name === "harnery") return dir;
       } catch {
         /* no package.json here, or not ours; keep walking up */
       }
@@ -265,5 +371,5 @@ export function harneryVersion(): string {
   } catch {
     /* import.meta.url unavailable or fs error */
   }
-  return "";
+  return null;
 }