harnery 0.0.1 → 0.2.0

package/dist/core/hooks/harness/output.js

@@ -0,0 +1,87 @@
+/**
+ * Harness-aware hook output JSON. Each adapter target has its own protocol
+ * shape, so encode it once here so post-emit handlers don't have to branch on
+ * `harness` everywhere.
+ *
+ * Shapes (verified against live dispatchers + each harness's upstream hooks docs):
+ *
+ * - **Claude Code**: `{hookSpecificOutput: {hookEventName, additionalContext}}`
+ *   for SessionStart / UserPromptSubmit / SubagentStart; deny uses
+ *   `{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason}}`.
+ * - **Cursor**: `{additional_context, env?}` flat for sessionStart /
+ *   beforeSubmitPrompt; deny uses `{permission: "deny", agent_message, user_message}`.
+ * - **Codex**: structurally identical to Claude Code (confirmed by Phase 0
+ *   probe + the matching shape in the Codex harness adapter).
+ *
+ * Every helper writes to process.stdout + newline-terminates so callers can
+ * fire-and-forget. Empty text → no-op (no JSON written).
+ */
+/** Emit a context-injection (peer table, wiring check, council pending, …). */
+export function emitContext(harness, event, text) {
+    if (!text || text.length === 0)
+        return;
+    const json = buildContextJson(harness, event, text);
+    process.stdout.write(`${JSON.stringify(json)}\n`);
+}
+/** Emit a PreToolUse deny: blocks the tool call with `reason` shown to the model. */
+export function emitDeny(harness, reason) {
+    if (!reason)
+        return;
+    const json = buildDenyJson(harness, reason);
+    process.stdout.write(`${JSON.stringify(json)}\n`);
+}
+/**
+ * Emit a Stop-hook block in the firing harness's enforcement channel and return
+ * the process exit code the caller should use.
+ *
+ * The verdict (allow/block + reason) is computed harness-agnostically in
+ * agents/rules/stop-hook.ts; this function only shapes *how the block is
+ * communicated back*, because each harness has a different mechanism:
+ *
+ * - **Claude Code / Codex** honor `exit 2` + a stderr reason as a turn block,
+ *   and the harness re-prompts the model with the stderr text.
+ * - **Cursor** ignores stop-hook exit codes (non-zero = fail-open, the turn
+ *   proceeds) and re-prompts ONLY via a `followup_message` field in stdout
+ *   JSON, which it auto-submits as the next user message: the sanctioned
+ *   "iterate until a goal is met" channel, capped by `loop_limit` (default 5).
+ *   We exit 0 so Cursor treats the run as a success and honors the output.
+ *   (Confirmed against cursor.com/docs/agent/hooks.)
+ */
+export function emitStopBlock(harness, verdict) {
+    const message = `${verdict.reason ?? "End-of-turn coordination ritual incomplete."}\n[agent-hook stop]: rule=${verdict.rule}`;
+    if (harness === "cursor") {
+        process.stdout.write(`${JSON.stringify({ followup_message: message })}\n`);
+        return 0;
+    }
+    process.stderr.write(`${message}\n`);
+    return 2;
+}
+function buildContextJson(harness, event, text) {
+    if (harness === "cursor") {
+        // Cursor uses a flat top-level key + an env block that survives across the
+        // session. The dispatcher historically also wrote
+        // `env: {HARNERY_AGENT_COORD_HARNESS, HARNERY_AGENT_COORD_PLATFORM}`. These are
+        // observer hints, not load-bearing; agent-hook + agent-coord recover the
+        // harness from event metadata. Drop them.
+        return { additional_context: text };
+    }
+    // Claude Code + Codex share the `hookSpecificOutput` envelope.
+    return {
+        hookSpecificOutput: {
+            hookEventName: event,
+            additionalContext: text,
+        },
+    };
+}
+function buildDenyJson(harness, reason) {
+    if (harness === "cursor") {
+        return { permission: "deny", agent_message: reason, user_message: reason };
+    }
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+        },
+    };
+}

package/dist/core/hooks/harness/parse.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Harness payload parser. One file because all three harnesses (CC, Cursor,
+ * Codex) share most of their PreToolUse / PostToolUse field names (Codex's
+ * field names match CC's directly) and Cursor's deltas are small enough to
+ * branch inline.
+ *
+ * The parser is intentionally tolerant: every field reads through `pickStr`,
+ * `pickNum`, etc., so a missing key returns `undefined` instead of throwing.
+ * Phase 2 ship criterion is "parser correctness across thousands of real
+ * events without affecting behavior": fail-soft beats fail-hard.
+ */
+import type { Harness } from "../events/schema.js";
+export interface ParsedPayload {
+    hook_event_name?: string;
+    session_id?: string;
+    agent_id?: string;
+    subagent_id?: string;
+    conversation_id?: string;
+    parent_session_id?: string;
+    turn_id?: string;
+    parent_turn_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    pid?: number;
+    model?: string;
+    source?: string;
+    prompt?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_response?: unknown;
+    tool_use_id?: string;
+    stop_hook_active?: boolean;
+    clean_exit?: boolean;
+    exit_status?: string;
+    reason?: string;
+    /** original parsed object, preserved for callers that need a field we didn't pluck. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Parse the raw stdin payload string for any harness. Returns null when JSON
+ * parse fails (Cursor occasionally fires hooks with no payload).
+ */
+export declare function parsePayload(raw: string, _harness: Harness): ParsedPayload | null;
+/**
+ * Pull the bash command string out of a Bash/Shell tool_input. Returns
+ * undefined for non-shell tools.
+ */
+export declare function extractBashCommand(toolName: string | undefined, toolInput: unknown): string | undefined;
+/**
+ * Pull the model's description string out of a tool_input. Only Claude Code's
+ * Bash tool requires this field; falls back to undefined elsewhere.
+ */
+export declare function extractToolDescription(toolInput: unknown): string | undefined;
+/**
+ * Each harness uses a slightly different name for the "same" lifecycle event.
+ * 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`).
+ */
+export declare function normalizeEventName(eventName: string): {
+    event_type: NormalizedEventType;
+    intra_turn: boolean;
+} | 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";
+//# sourceMappingURL=parse.d.ts.map

package/dist/core/hooks/harness/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAkCjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,OAAO,GACjB,MAAM,GAAG,SAAS,CASpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO7E;AAmBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CA6BjE;AAED,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,eAAe,GACf,uBAAuB,CAAC"}

package/dist/core/hooks/harness/parse.js

@@ -0,0 +1,132 @@
+/**
+ * Harness payload parser. One file because all three harnesses (CC, Cursor,
+ * Codex) share most of their PreToolUse / PostToolUse field names (Codex's
+ * field names match CC's directly) and Cursor's deltas are small enough to
+ * branch inline.
+ *
+ * The parser is intentionally tolerant: every field reads through `pickStr`,
+ * `pickNum`, etc., so a missing key returns `undefined` instead of throwing.
+ * Phase 2 ship criterion is "parser correctness across thousands of real
+ * events without affecting behavior": fail-soft beats fail-hard.
+ */
+/**
+ * Parse the raw stdin payload string for any harness. Returns null when JSON
+ * parse fails (Cursor occasionally fires hooks with no payload).
+ */
+export function parsePayload(raw, _harness) {
+    if (!raw || raw.trim().length === 0)
+        return null;
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return {
+        hook_event_name: pickStr(json, "hook_event_name"),
+        session_id: pickStr(json, "session_id"),
+        agent_id: pickStr(json, "agent_id"),
+        subagent_id: pickStr(json, "subagent_id"),
+        conversation_id: pickStr(json, "conversation_id"),
+        parent_session_id: pickStr(json, "parent_session_id"),
+        turn_id: pickStr(json, "turn_id"),
+        parent_turn_id: pickStr(json, "parent_turn_id"),
+        transcript_path: pickStr(json, "transcript_path"),
+        cwd: pickStr(json, "cwd"),
+        pid: pickNum(json, "pid"),
+        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,
+        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"),
+        raw: json,
+    };
+}
+/**
+ * Pull the bash command string out of a Bash/Shell tool_input. Returns
+ * undefined for non-shell tools.
+ */
+export function extractBashCommand(toolName, toolInput) {
+    if (!toolName)
+        return undefined;
+    if (toolName !== "Bash" && toolName !== "Shell")
+        return undefined;
+    if (toolInput && typeof toolInput === "object") {
+        const t = toolInput;
+        const cmd = t.command;
+        if (typeof cmd === "string")
+            return cmd;
+    }
+    return undefined;
+}
+/**
+ * Pull the model's description string out of a tool_input. Only Claude Code's
+ * Bash tool requires this field; falls back to undefined elsewhere.
+ */
+export function extractToolDescription(toolInput) {
+    if (toolInput && typeof toolInput === "object") {
+        const t = toolInput;
+        const d = t.description;
+        if (typeof d === "string")
+            return d;
+    }
+    return undefined;
+}
+function pickStr(o, k) {
+    const v = o[k];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function pickNum(o, k) {
+    const v = o[k];
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+function pickBool(o, k) {
+    const v = o[k];
+    return typeof v === "boolean" ? v : undefined;
+}
+// ── Event-name normalization ────────────────────────────────────────────────
+/**
+ * Each harness uses a slightly different name for the "same" lifecycle event.
+ * 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`).
+ */
+export function normalizeEventName(eventName) {
+    switch (eventName) {
+        case "session-start":
+            return { event_type: "session.start", intra_turn: false };
+        case "session-end":
+            return { event_type: "session.end", intra_turn: false };
+        case "user-prompt-submit":
+            return { event_type: "user_prompt.submit", intra_turn: false };
+        case "stop":
+            return { event_type: "turn.stop", 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 };
+        case "sub-agent-start":
+            return { event_type: "subagent.start", intra_turn: false };
+        case "sub-agent-stop":
+            return { event_type: "subagent.stop", intra_turn: false };
+        case "pre-tool-use":
+        case "before-shell-execution":
+            return { event_type: "tool.pre_use", intra_turn: true };
+        case "post-tool-use":
+            return { event_type: "tool.post_use", intra_turn: true };
+        case "post-tool-use-failure":
+            return { event_type: "tool.post_use_failure", intra_turn: true };
+        default:
+            return null;
+    }
+}

package/dist/core/hooks/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * agent-hooks library exports.
+ *
+ * Phase 1 (skeleton): exposes only the canonical event schema types. Parsers,
+ * resolvers, and emit helpers ship in Phase 2.
+ */
+export { type Event, type EventEnvelope, type EventType, type Harness, type RedactionMarker, SCHEMA_VERSION, type Source, } from "./events/schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,cAAc,EACd,KAAK,MAAM,GACZ,MAAM,oBAAoB,CAAC"}

package/dist/core/hooks/index.js

@@ -0,0 +1,7 @@
+/**
+ * agent-hooks library exports.
+ *
+ * Phase 1 (skeleton): exposes only the canonical event schema types. Parsers,
+ * resolvers, and emit helpers ship in Phase 2.
+ */
+export { SCHEMA_VERSION, } from "./events/schema.js";

package/dist/core/hooks/resolve/anchor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure pid-map anchor selection: picks which PID in a process's ppid chain
+ * the heartbeat pid-map row should be keyed to, so the agent's later shell
+ * tool calls (which ppid-walk up to find it) resolve their own identity.
+ *
+ * Split out of cli.ts's `findHarnessAnchorPid` so the comm-matching logic is
+ * unit-testable against the real Phase 0 Cursor probe chains without needing a
+ * live /proc tree.
+ *
+ * Why the cursor `node` fallback exists: Cursor's WSL/Linux process tree has
+ * NO process named `cursor`: the chain is `bash → bash → node → node → sh →
+ * Relay → init`. The `node` ancestors are stable across every hook + tool event
+ * in one IDE-window session, so anchoring there gives the agent's shell tool
+ * calls a reachable, stable pid-map row. This faithfully restores the previous
+ * cursor anchor behavior (match `cursor` first, then fall back to `node`) that
+ * was dropped in the Phase 4-6 TS refactor, the same regression class as the
+ * heartbeat-platform + pidmap-self-heal losses. Scoped to `harness === "cursor"`
+ * so Claude Code / Codex never
+ * mis-anchor on an unrelated `node` ancestor (they match their own comm token
+ * directly).
+ *
+ * Known limitation (matches the bash original): two Cursor chats sharing one
+ * IDE window share their `node` ancestor, so the pid-map row is last-writer-
+ * wins between them. Single-chat-per-window (the common case) is correct;
+ * concurrent same-window chats disambiguate via `--session-id`.
+ */
+/**
+ * Pick the anchor PID from a ppid chain ordered nearest-first (the resolving
+ * process at index 0, walking up toward init). Returns the first ancestor
+ * matching a harness comm token; for cursor, falls back to the first `node`
+ * ancestor; otherwise undefined (caller falls back to process.ppid).
+ */
+export declare function selectAnchorPid(chain: ReadonlyArray<{
+    pid: number;
+    comm: string;
+}>, harness?: string): number | undefined;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/core/hooks/resolve/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAUpB"}

package/dist/core/hooks/resolve/anchor.js

@@ -0,0 +1,48 @@
+/**
+ * Pure pid-map anchor selection: picks which PID in a process's ppid chain
+ * the heartbeat pid-map row should be keyed to, so the agent's later shell
+ * tool calls (which ppid-walk up to find it) resolve their own identity.
+ *
+ * Split out of cli.ts's `findHarnessAnchorPid` so the comm-matching logic is
+ * unit-testable against the real Phase 0 Cursor probe chains without needing a
+ * live /proc tree.
+ *
+ * Why the cursor `node` fallback exists: Cursor's WSL/Linux process tree has
+ * NO process named `cursor`: the chain is `bash → bash → node → node → sh →
+ * Relay → init`. The `node` ancestors are stable across every hook + tool event
+ * in one IDE-window session, so anchoring there gives the agent's shell tool
+ * calls a reachable, stable pid-map row. This faithfully restores the previous
+ * cursor anchor behavior (match `cursor` first, then fall back to `node`) that
+ * was dropped in the Phase 4-6 TS refactor, the same regression class as the
+ * heartbeat-platform + pidmap-self-heal losses. Scoped to `harness === "cursor"`
+ * so Claude Code / Codex never
+ * mis-anchor on an unrelated `node` ancestor (they match their own comm token
+ * directly).
+ *
+ * Known limitation (matches the bash original): two Cursor chats sharing one
+ * IDE window share their `node` ancestor, so the pid-map row is last-writer-
+ * wins between them. Single-chat-per-window (the common case) is correct;
+ * concurrent same-window chats disambiguate via `--session-id`.
+ */
+/** Harness-binary comm names. CC's tool calls descend from `claude`, Codex's
+ * from `codex`; matched directly so neither needs the `node` fallback. */
+const PRIMARY_COMM_TOKENS = new Set(["claude", "claude-code", "cursor", "codex"]);
+/**
+ * Pick the anchor PID from a ppid chain ordered nearest-first (the resolving
+ * process at index 0, walking up toward init). Returns the first ancestor
+ * matching a harness comm token; for cursor, falls back to the first `node`
+ * ancestor; otherwise undefined (caller falls back to process.ppid).
+ */
+export function selectAnchorPid(chain, harness) {
+    for (const hop of chain) {
+        if (PRIMARY_COMM_TOKENS.has(hop.comm))
+            return hop.pid;
+    }
+    if (harness === "cursor") {
+        for (const hop of chain) {
+            if (hop.comm === "node")
+                return hop.pid;
+        }
+    }
+    return undefined;
+}

package/dist/core/hooks/resolve/coord-root.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Walk up from `start` looking for a directory containing `.harnery/`. The
+ * single coord-root resolution so every adapter agrees on the same root.
+ */
+export declare function findCoordRoot(start?: string): string | null;
+//# sourceMappingURL=coord-root.d.ts.map

package/dist/core/hooks/resolve/coord-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-root.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/coord-root.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAgB1E"}

package/dist/core/hooks/resolve/coord-root.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { coordEnv } from "../../../lib/env.js";
+/**
+ * Walk up from `start` looking for a directory containing `.harnery/`. The
+ * single coord-root resolution so every adapter agrees on the same root.
+ */
+export function findCoordRoot(start = process.cwd()) {
+    // HARNERY_COORD_ROOT_OVERRIDE: test-mode escape hatch matched by agent-coord
+    // and the bash side. Lets the sandboxed coord-test suite run against a
+    // temp directory rather than the real monorepo root. agent-hook's
+    // session.start handler may be the FIRST thing to create .harnery/ in a
+    // fresh sandbox, so the override is honored unconditionally (we don't
+    // require .harnery/ to pre-exist).
+    const override = coordEnv("COORD_ROOT_OVERRIDE");
+    if (override)
+        return override;
+    let dir = resolve(start);
+    while (true) {
+        if (existsSync(join(dir, ".harnery")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/core/hooks/resolve/intent.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve the model-declared intent for the current tool call. Three-source
+ * precedence:
+ *
+ *   1. `# intent: X` comment on the first line of the bash command.
+ *   2. `description` field on the tool input (Claude Code only).
+ *   3. `<intent>...</intent>` tag in the most-recent assistant prose, read
+ *      from `.harnery/.last-intent.<instance_id>` (the bash bash-tap is the
+ *      only thing that does transcript scanning today; agent-hook stamps the
+ *      file on precedence 1/2 so the bash-tap can fall back to it).
+ *
+ * Phase 8 (2026-05-27): agent-hook writes the stamp file itself on precedence
+ * 1/2 (replacing coord-intent-stamp.sh's command/description branches). The
+ * transcript-tag branch is now the only thing left in coord-intent-stamp.sh.
+ */
+export declare function resolveIntent(opts: {
+    coordRoot: string;
+    instanceId: string;
+    /** First-line `# intent: X` comment from the bash command (preferred fresh source). */
+    commandIntentComment?: string;
+    /** `description` field on the tool input (Claude Code only). */
+    description?: string;
+}): {
+    intent: string;
+    source: "command-comment" | "description" | "stamp" | "none";
+};
+/**
+ * Match `# intent: X` at the start of a command (after optional leading
+ * whitespace on the first line). Mirrors `extract_command_intent_comment` in
+ * coord-intent-stamp.sh.
+ */
+export declare function extractIntentComment(command: string | undefined): string | undefined;
+//# sourceMappingURL=intent.d.ts.map

package/dist/core/hooks/resolve/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/intent.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,GAAG,OAAO,GAAG,MAAM,CAAA;CAAE,CAkCnF;AAYD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMpF"}

package/dist/core/hooks/resolve/intent.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Resolve the model-declared intent for the current tool call. Three-source
+ * precedence:
+ *
+ *   1. `# intent: X` comment on the first line of the bash command.
+ *   2. `description` field on the tool input (Claude Code only).
+ *   3. `<intent>...</intent>` tag in the most-recent assistant prose, read
+ *      from `.harnery/.last-intent.<instance_id>` (the bash bash-tap is the
+ *      only thing that does transcript scanning today; agent-hook stamps the
+ *      file on precedence 1/2 so the bash-tap can fall back to it).
+ *
+ * Phase 8 (2026-05-27): agent-hook writes the stamp file itself on precedence
+ * 1/2 (replacing coord-intent-stamp.sh's command/description branches). The
+ * transcript-tag branch is now the only thing left in coord-intent-stamp.sh.
+ */
+export function resolveIntent(opts) {
+    const stampPath = join(opts.coordRoot, ".harnery", `.last-intent.${opts.instanceId}`);
+    // 1. Fresh from the command itself (most reliable, cross-harness).
+    if (opts.commandIntentComment) {
+        const cleaned = clamp(opts.commandIntentComment);
+        if (cleaned) {
+            writeStamp(stampPath, cleaned);
+            return { intent: cleaned, source: "command-comment" };
+        }
+    }
+    // 2. Fresh from the tool input description (Claude Code only).
+    if (opts.description) {
+        const cleaned = clamp(opts.description);
+        if (cleaned) {
+            writeStamp(stampPath, cleaned);
+            return { intent: cleaned, source: "description" };
+        }
+    }
+    // 3. Whatever the bash-tap stamped from a transcript <intent> tag.
+    if (existsSync(stampPath)) {
+        try {
+            const stamped = readFileSync(stampPath, "utf8").trim();
+            if (stamped && stamped !== "(no intent)") {
+                return { intent: stamped, source: "stamp" };
+            }
+        }
+        catch {
+            /* fallthrough */
+        }
+    }
+    return { intent: "(no intent)", source: "none" };
+}
+function writeStamp(path, value) {
+    try {
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, value, "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Match `# intent: X` at the start of a command (after optional leading
+ * whitespace on the first line). Mirrors `extract_command_intent_comment` in
+ * coord-intent-stamp.sh.
+ */
+export function extractIntentComment(command) {
+    if (!command)
+        return undefined;
+    const firstLine = command.split("\n", 1)[0];
+    const m = firstLine?.match(/^[ \t]*#[ \t]*intent:[ \t]*(.+)$/);
+    if (!m)
+        return undefined;
+    return m[1]?.trimEnd();
+}
+function clamp(v) {
+    const trimmed = v.trim();
+    if (trimmed.length <= 200)
+        return trimmed;
+    return `${trimmed.slice(0, 197)}...`;
+}

package/dist/core/hooks/resolve/owner.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the canonical `instance_id` for the current hook invocation.
+ *
+ * Precedence:
+ *
+ *   1. `HARNERY_AGENT_COORD_OWNER` env var. Set by harness adapters when they know
+ *      the owner identity at spawn time (Codex's apply_patch tool path uses
+ *      this).
+ *   2. Hook payload fields, in order: `agent_id` → `subagent_id` →
+ *      `session_id` → `conversation_id`. agent_id wins for CC subagent
+ *      events; session_id is the parent-shape default.
+ *   3. PID-map lookup at `.harnery/pid-map/<pid>` for our own pid, then ppid
+ *      chain (up to 20 hops).
+ *
+ * Returns null when nothing resolves. Callers must treat null as "no owner"
+ * and skip the event (Phase 2 fail-safe; Phase 3 will mint a temporary owner
+ * for orphan events).
+ */
+export declare function resolveOwner(opts: {
+    payload: Record<string, unknown> | null;
+    coordRoot: string;
+}): {
+    instance_id: string;
+    source: "env" | "payload" | "pidmap-self" | "pidmap-ancestor";
+} | null;
+/**
+ * Find the parent owner for a subagent invocation. The per-shell marker at
+ * `.harnery/shells/<pid>` is set by `sub-agent-start` and removed by
+ * `sub-agent-stop`.
+ *
+ * Phase 2 stub: the marker file isn't written yet, so we return null in most
+ * cases. Phase 2 callers can pass through.
+ */
+export declare function readShellMarker(coordRoot: string, pid: number): string | null;
+/** Read the heartbeat-recorded `agent_id` for an owner if it exists. */
+export declare function readAgentIdForOwner(coordRoot: string, instanceId: string): string | null;
+/** Diagnostic: list of pid-map entries (for debugging). */
+export declare function listPidmap(coordRoot: string): Array<{
+    pid: number;
+    owner: string;
+}>;
+//# sourceMappingURL=owner.d.ts.map

package/dist/core/hooks/resolve/owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/owner.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,aAAa,GAAG,iBAAiB,CAAA;CAAE,GAAG,IAAI,CA+ChG;AAmBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxF;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnF"}