harnery 0.0.1 → 0.2.0

package/dist/core/hooks/events/emit.js

@@ -0,0 +1,89 @@
+import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { SCHEMA_VERSION, } from "./schema.js";
+import { ulid } from "./ulid.js";
+const LOCK_FILE = ".harnery/events.ndjson.lock";
+const STREAM_FILE = ".harnery/events.ndjson";
+const MAX_LINE_BYTES = 64 * 1024;
+/**
+ * Build a canonical envelope around the caller's `data` payload. Pure;
+ * doesn't touch the filesystem. Useful for tests + replay fixtures.
+ */
+export function buildEnvelope(input) {
+    return {
+        schema_version: SCHEMA_VERSION,
+        event_id: ulid(),
+        event_type: input.event_type,
+        ts: input.ts ?? new Date().toISOString(),
+        instance_id: input.instance_id,
+        session_id: input.session_id,
+        parent_session_id: input.parent_session_id,
+        turn_id: input.turn_id,
+        parent_turn_id: input.parent_turn_id,
+        harness: input.harness,
+        source: input.source ?? "agent-hooks",
+        data: input.data,
+    };
+}
+/**
+ * Append one canonical event to `.harnery/events.ndjson` under a file lock.
+ * Append-only, one JSON object per line, lock-serialized.
+ *
+ * Synchronous because hooks are short-lived processes: we want the append to
+ * land before the binary exits, and async/await across a tiny write is just
+ * latency for no benefit.
+ *
+ * Returns the envelope so callers can chain off it (debug logs, post-emit
+ * verdict requests).
+ */
+export function emit(coordRoot, input) {
+    const envelope = buildEnvelope(input);
+    const streamPath = join(coordRoot, STREAM_FILE);
+    const lockPath = join(coordRoot, LOCK_FILE);
+    ensureDir(dirname(streamPath));
+    ensureFile(lockPath);
+    let line = `${JSON.stringify(envelope)}\n`;
+    if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
+        // lines >64KB are a schema bug. Phase 2 hard-truncates the `data`
+        // payload + sets `truncated: true` so we keep audit visibility without
+        // breaking downstream consumers.
+        const truncated = `${JSON.stringify({
+            ...envelope,
+            data: { __over_size_limit: true, original_bytes: Buffer.byteLength(line, "utf8") },
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+        })}\n`;
+        line = truncated;
+    }
+    const lockFd = openSync(lockPath, "r+");
+    try {
+        // flock isn't directly exposed in node fs; use fcntl-like via shelling out
+        // would be slower than POSIX flock(2) inside the kernel. Bun exposes
+        // `Bun.flock` in recent builds, but a simple fs-level append is atomic
+        // for lines <PIPE_BUF (4KB on Linux) anyway. For larger lines we rely on
+        // append-mode flag (O_APPEND) which kernels serialize per-fd.
+        //
+        // The `events.ndjson.lock` file is kept around for forward
+        // compatibility: Phase 4+ helpers acquire it before multi-write batches.
+        appendFileSync(streamPath, line, { encoding: "utf8", flag: "a" });
+    }
+    finally {
+        closeSync(lockFd);
+    }
+    return envelope;
+}
+function ensureDir(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+    }
+    catch {
+        /* swallow */
+    }
+}
+function ensureFile(path) {
+    try {
+        closeSync(openSync(path, "a"));
+    }
+    catch {
+        /* swallow */
+    }
+}

package/dist/core/hooks/events/schema.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Canonical event schema v1. Inter-module contract between agent-hooks (writer)
+ * and agent-coord (consumer + projector).
+ *
+ * Schema evolution rules:
+ *   - Forward-compatible only within a major version. Consumers ignore unknown
+ *     fields. Adding an optional field is a minor bump; removing or retyping a
+ *     field is a major bump.
+ *   - Mixed-version streams are legal during migrations; consumers branch on
+ *     `schema_version`.
+ */
+export declare const SCHEMA_VERSION: 1;
+export type Harness = "claude-code" | "cursor" | "codex";
+export type Source = "agent-hooks" | "agent-coord" | "user" | "system";
+/**
+ * Common envelope every event carries. Tool events, `user_prompt.submit`, and
+ * `turn.stop` MUST carry `turn_id`; CLI/state/council/presence/health/session
+ * events MAY carry `turn_id` when agent-coord can bind them to the active turn
+ * for that owner.
+ */
+export interface EventEnvelope<TType extends string, TData> {
+    schema_version: typeof SCHEMA_VERSION;
+    event_id: string;
+    event_type: TType;
+    ts: string;
+    instance_id: string;
+    session_id: string;
+    parent_session_id?: string;
+    turn_id?: string;
+    parent_turn_id?: string;
+    harness: Harness;
+    source: Source;
+    data: TData;
+}
+export type SessionStart = EventEnvelope<"session.start", {
+    started_at: string;
+    cwd: string;
+    model?: string;
+    pid: number;
+}>;
+export type SessionEnd = EventEnvelope<"session.end", {
+    ended_at: string;
+    clean_exit: boolean;
+}>;
+export type SubagentStart = EventEnvelope<"subagent.start", {
+    agent_type: string;
+    prompt_summary?: string;
+}>;
+export type SubagentStop = EventEnvelope<"subagent.stop", {
+    exit_status: "ok" | "error" | "interrupted";
+}>;
+export type UserPromptSubmit = EventEnvelope<"user_prompt.submit", {
+    prompt_text: string;
+    truncated?: boolean;
+}>;
+export type TurnStop = EventEnvelope<"turn.stop", {
+    tool_call_count: number;
+    text_length: number;
+    status_box_present: boolean;
+}>;
+export type CommandStart = EventEnvelope<"command.start", {
+    cmd_id: string;
+    intent?: string;
+    cmd: string;
+}>;
+export type CommandOutput = EventEnvelope<"command.output", {
+    cmd_id: string;
+    stream: "stdout" | "stderr";
+    line: string;
+}>;
+export type CommandEnd = EventEnvelope<"command.end", {
+    cmd_id: string;
+    exit: number;
+    duration_ms: number;
+    signal?: string;
+}>;
+export type Narration = EventEnvelope<"narration", {
+    message: string;
+}>;
+export type ToolPreUse = EventEnvelope<"tool.pre_use", {
+    tool_name: string;
+    tool_input: unknown;
+    intent?: string;
+    truncated?: boolean;
+}>;
+export type ToolPostUse = EventEnvelope<"tool.post_use", {
+    tool_name: string;
+    output_summary: string;
+    exit_status: "ok" | "error";
+    duration_ms: number;
+    truncated?: boolean;
+}>;
+export type ToolPostUseFailure = EventEnvelope<"tool.post_use_failure", {
+    tool_name: string;
+    error: string;
+    duration_ms: number;
+}>;
+export type ToolOutputChunk = EventEnvelope<"tool.output_chunk", {
+    chunk: string;
+    chunk_no: number;
+    stream: "stdout" | "stderr";
+    truncated?: boolean;
+}>;
+/**
+ * An image an agent viewed (Read tool) or produced (a Bash command wrote it).
+ * Emitted by agent-hooks as a side-effect of a tool event when the tool
+ * references an image path on disk; the bytes are content-addressed into
+ * `.harnery/images/<hash>.<ext>` (dedup) and this event records the provenance
+ * for the web image feed. Grouped by `hash` downstream → one card per distinct
+ * image with a touch timeline.
+ */
+export type ImageCaptured = EventEnvelope<"image.captured", {
+    hash: string;
+    ext: string;
+    bytes: number;
+    role: "viewed" | "produced";
+    source_path: string;
+    tool_name: string;
+    tool_use_id?: string;
+    intent?: string;
+    command_head?: string;
+}>;
+export type ClaimAcquire = EventEnvelope<"claim.acquire", {
+    path: string;
+    mode: "read" | "write";
+}>;
+export type ClaimRelease = EventEnvelope<"claim.release", {
+    path: string;
+    reason: "explicit" | "turn_end" | "session_end" | "heal";
+}>;
+export type ClaimConflict = EventEnvelope<"claim.conflict", {
+    path: string;
+    peer_instance_id: string;
+    reason?: "ordering_violation" | "concurrent_write";
+}>;
+export type StateTaskSet = EventEnvelope<"state.task_set", {
+    task: string;
+    cleared: boolean;
+}>;
+export type StateStatusChecked = EventEnvelope<"state.status_checked", {
+    format: "box" | "json" | "table";
+    agent_count: number;
+    included_self: boolean;
+}>;
+export type StateScratchAppend = EventEnvelope<"state.scratch_append", {
+    category: "note" | "plan" | "decision" | "blocker" | "question" | "done" | "handoff";
+    body_summary: string;
+}>;
+export type StatePresenceChange = EventEnvelope<"state.presence_change", {
+    from: "mobile" | "office";
+    to: "mobile" | "office";
+    source: "hook" | "cli" | "user";
+}>;
+export type StateHeartbeat = EventEnvelope<"state.heartbeat", Record<string, never>>;
+export type CouncilOpen = EventEnvelope<"council.open", {
+    council_id: string;
+    topic: string;
+    members: string[];
+    target_doc?: string;
+}>;
+export type CouncilRoundOpen = EventEnvelope<"council.round_open", {
+    council_id: string;
+    round_no: number;
+}>;
+export type CouncilContribution = EventEnvelope<"council.contribution", {
+    council_id: string;
+    round_no: number;
+    member: string;
+    body_summary: string;
+}>;
+export type CouncilRoundClose = EventEnvelope<"council.round_close", {
+    council_id: string;
+    round_no: number;
+}>;
+export type CouncilClose = EventEnvelope<"council.close", {
+    council_id: string;
+    closed_at: string;
+}>;
+export type CouncilArchive = EventEnvelope<"council.archive", {
+    council_id: string;
+}>;
+export type DecisionBlock = EventEnvelope<"decision.block", {
+    rule: string;
+    reason: string;
+}>;
+export type DecisionWarn = EventEnvelope<"decision.warn", {
+    rule: string;
+    reason: string;
+}>;
+export type DecisionAllow = EventEnvelope<"decision.allow", {
+    rule: string;
+}>;
+export type HealthHeartbeatHeal = EventEnvelope<"health.heartbeat_heal", {
+    reason: string;
+}>;
+export type HealthPidmapHeal = EventEnvelope<"health.pidmap_heal", {
+    reason: string;
+}>;
+/**
+ * A heartbeat file was removed by stale-sweep. Symmetric with
+ * `health.heartbeat_heal` so the full lifecycle (created → healed → swept) is
+ * auditable from the event stream alone. Sweeps were silent before, which
+ * made "why did this agent vanish?" un-answerable without guesswork.
+ * `reason`: "stale" (last_heartbeat past the freshness cutoff) | "unparseable"
+ * (JSON.parse failed AND mtime was old) | "missing_ts" (no last_heartbeat AND
+ * mtime was old). Fresh-mtime files are never swept regardless of content.
+ */
+export type HealthHeartbeatSwept = EventEnvelope<"health.heartbeat_swept", {
+    reason: "stale" | "unparseable" | "missing_ts";
+    age_secs?: number;
+}>;
+/**
+ * fail-open verdict failure mode. Emitted by agent-hooks when
+ * `agent-coord verdict` fails to spawn / exits non-zero / returns malformed
+ * JSON / times out. Adapter falls through to ALLOW; the event preserves the
+ * fail-open for audit.
+ */
+export type HealthVerdictFailure = EventEnvelope<"health.verdict_failure", {
+    failure_kind: "spawn_failed" | "nonzero_exit" | "malformed_json" | "timeout";
+    timeout_ms?: number;
+    fallback: "allow";
+}>;
+export type Event = SessionStart | SessionEnd | SubagentStart | SubagentStop | UserPromptSubmit | TurnStop | CommandStart | CommandOutput | CommandEnd | Narration | ToolPreUse | ToolPostUse | ToolPostUseFailure | ToolOutputChunk | ImageCaptured | ClaimAcquire | ClaimRelease | ClaimConflict | StateTaskSet | StateStatusChecked | StateScratchAppend | StatePresenceChange | StateHeartbeat | CouncilOpen | CouncilRoundOpen | CouncilContribution | CouncilRoundClose | CouncilClose | CouncilArchive | DecisionBlock | DecisionWarn | DecisionAllow | HealthHeartbeatHeal | HealthPidmapHeal | HealthHeartbeatSwept | HealthVerdictFailure;
+export type EventType = Event["event_type"];
+/**
+ * Redaction marker that may be attached to any `data` payload during emission.
+ * Tracked here so the schema documents the convention; the actual
+ * shape lives inside `data` so it doesn't widen the envelope.
+ */
+export interface RedactionMarker {
+    field: string;
+    kind: "secret_signature" | "env_secret_match" | "length_clamp";
+    count: number;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/hooks/events/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/events/schema.ts"],"names":[],"mappings":"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"}

package/dist/core/hooks/events/schema.js

@@ -0,0 +1,12 @@
+/**
+ * Canonical event schema v1. Inter-module contract between agent-hooks (writer)
+ * and agent-coord (consumer + projector).
+ *
+ * Schema evolution rules:
+ *   - Forward-compatible only within a major version. Consumers ignore unknown
+ *     fields. Adding an optional field is a minor bump; removing or retyping a
+ *     field is a major bump.
+ *   - Mixed-version streams are legal during migrations; consumers branch on
+ *     `schema_version`.
+ */
+export const SCHEMA_VERSION = 1;

package/dist/core/hooks/events/ulid.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tiny ULID generator. Crockford-base32, 10-char timestamp (48-bit ms epoch)
+ * + 16-char random (80-bit). 26 chars total, monotonically-sortable.
+ *
+ * Library-free so the module stays dep-free (no `ulid` package). Quality is
+ * sufficient for event_id uniqueness: the kth event in a millisecond uses a
+ * fresh 80-bit random, collision probability negligible.
+ */
+export declare function ulid(): string;
+//# sourceMappingURL=ulid.d.ts.map

package/dist/core/hooks/events/ulid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/events/ulid.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,wBAAgB,IAAI,IAAI,MAAM,CAI7B"}

package/dist/core/hooks/events/ulid.js

@@ -0,0 +1,47 @@
+/**
+ * Tiny ULID generator. Crockford-base32, 10-char timestamp (48-bit ms epoch)
+ * + 16-char random (80-bit). 26 chars total, monotonically-sortable.
+ *
+ * Library-free so the module stays dep-free (no `ulid` package). Quality is
+ * sufficient for event_id uniqueness: the kth event in a millisecond uses a
+ * fresh 80-bit random, collision probability negligible.
+ */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function ulid() {
+    const ts = encodeTime(Date.now());
+    const rnd = encodeRandom();
+    return ts + rnd;
+}
+function encodeTime(ms) {
+    let out = "";
+    let n = BigInt(ms);
+    const base = BigInt(32);
+    for (let i = 0; i < 10; i++) {
+        const mod = Number(n % base);
+        out = ALPHABET[mod] + out;
+        n = n / base;
+    }
+    return out;
+}
+function encodeRandom() {
+    const bytes = new Uint8Array(10);
+    crypto.getRandomValues(bytes);
+    // Map each pair of bytes to 3 alphabet chars (5 bits per char, 16 chars).
+    let out = "";
+    let buf = 0n;
+    let bits = 0;
+    for (const b of bytes) {
+        buf = (buf << 8n) | BigInt(b);
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            const idx = Number((buf >> BigInt(bits)) & 0x1fn);
+            out += ALPHABET[idx];
+        }
+    }
+    if (bits > 0) {
+        const idx = Number((buf << BigInt(5 - bits)) & 0x1fn);
+        out += ALPHABET[idx];
+    }
+    return out.slice(0, 16);
+}

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

@@ -0,0 +1,9 @@
+import type { Harness } from "../events/schema.js";
+/**
+ * Resolve the harness firing the hook. The dispatcher binary is always
+ * invoked with `--harness <name>` per the wiring in each harness's settings
+ * file (Phase 1). Returns null when the flag is missing; caller falls
+ * through to the env-based fallback or skips emission.
+ */
+export declare function detectHarness(argv: readonly string[]): Harness | null;
+//# sourceMappingURL=detect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/detect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,GAAG,IAAI,CAWrE"}

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

@@ -0,0 +1,29 @@
+import { coordEnv } from "../../../lib/env.js";
+/**
+ * Resolve the harness firing the hook. The dispatcher binary is always
+ * invoked with `--harness <name>` per the wiring in each harness's settings
+ * file (Phase 1). Returns null when the flag is missing; caller falls
+ * through to the env-based fallback or skips emission.
+ */
+export function detectHarness(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--harness") {
+            return validate(argv[i + 1]);
+        }
+        if (a.startsWith("--harness=")) {
+            return validate(a.slice("--harness=".length));
+        }
+    }
+    return validate(coordEnv("AGENT_COORD_HARNESS"));
+}
+function validate(v) {
+    if (v === "claude-code" || v === "cursor" || v === "codex")
+        return v;
+    // Legacy: some harnesses use `claude_code` (underscore). Map
+    // it through so the env-based fallback works for callers that haven't
+    // updated yet.
+    if (v === "claude_code")
+        return "claude-code";
+    return null;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Canonical hook-wiring spec per harness: which settings file to write, which
+ * event key maps to which `agent-hook <subcommand>`, and how each harness encodes
+ * a command hook. Single source of truth for `harn init` (and any future docs /
+ * installers) so the wired set can't drift from what agent-hook actually handles.
+ *
+ * The event lists + entry shapes mirror exactly what a fully-wired project uses
+ * for each harness (Claude Code `.claude/settings.json`, Cursor `.cursor/hooks.json`,
+ * Codex `.codex/hooks.json`).
+ */
+export type HarnessId = "claude-code" | "cursor" | "codex";
+export interface HookEvent {
+    /** Key under the harness settings file's `hooks` map (e.g. `SessionStart`, `preToolUse`). */
+    settingsKey: string;
+    /** agent-hook subcommand to invoke for this event. */
+    subcommand: string;
+}
+/**
+ * How a harness encodes a single command hook under `hooks.<settingsKey>`:
+ * - `claude`: `[{ hooks: [{ type: "command", command }] }]` (Claude Code + Codex)
+ * - `cursor`: `[{ command }]` (Cursor: flat entry, no inner `hooks` array)
+ */
+export type HookEntryShape = "claude" | "cursor";
+export interface HarnessSpec {
+    /** Settings file to wire, relative to the project root. */
+    settingsFile: string;
+    /** Events this harness fires, mapped to agent-hook subcommands. */
+    events: HookEvent[];
+    /** Per-entry encoding under the root `hooks` object. */
+    entryShape: HookEntryShape;
+    /** When set, ensure this top-level `version` key in the file (Cursor requires `1`). */
+    rootVersion?: number;
+}
+/** Claude Code: `.claude/settings.json`. */
+export declare const CLAUDE_CODE_EVENTS: HookEvent[];
+/**
+ * Cursor: `.cursor/hooks.json`. camelCase event keys; flat `{ command }` entries;
+ * no `StopFailure` event, but a distinct `beforeShellExecution` (shell-mutation warn).
+ */
+export declare const CURSOR_EVENTS: HookEvent[];
+/** Codex: `.codex/hooks.json`. PascalCase keys + the same entry shape as Claude Code. */
+export declare const CODEX_EVENTS: HookEvent[];
+/** Every supported harness, fully wireable by `harn init`. */
+export declare const HARNESS_SPECS: Record<HarnessId, HarnessSpec>;
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,SAAS;IACxB,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,wDAAwD;IACxD,UAAU,EAAE,cAAc,CAAC;IAC3B,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,EAAE,SAAS,EAWzC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,EAWpC,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,YAAY,EAAE,SAAS,EAWnC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAiBxD,CAAC"}

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

@@ -0,0 +1,71 @@
+/**
+ * Canonical hook-wiring spec per harness: which settings file to write, which
+ * event key maps to which `agent-hook <subcommand>`, and how each harness encodes
+ * a command hook. Single source of truth for `harn init` (and any future docs /
+ * installers) so the wired set can't drift from what agent-hook actually handles.
+ *
+ * The event lists + entry shapes mirror exactly what a fully-wired project uses
+ * for each harness (Claude Code `.claude/settings.json`, Cursor `.cursor/hooks.json`,
+ * Codex `.codex/hooks.json`).
+ */
+/** Claude Code: `.claude/settings.json`. */
+export const CLAUDE_CODE_EVENTS = [
+    { settingsKey: "SessionStart", subcommand: "session-start" },
+    { settingsKey: "UserPromptSubmit", subcommand: "user-prompt-submit" },
+    { settingsKey: "Stop", subcommand: "stop" },
+    { settingsKey: "StopFailure", subcommand: "stop-failure" },
+    { settingsKey: "SessionEnd", subcommand: "session-end" },
+    { settingsKey: "SubagentStart", subcommand: "sub-agent-start" },
+    { settingsKey: "SubagentStop", subcommand: "sub-agent-stop" },
+    { settingsKey: "PreToolUse", subcommand: "pre-tool-use" },
+    { settingsKey: "PostToolUse", subcommand: "post-tool-use" },
+    { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
+];
+/**
+ * Cursor: `.cursor/hooks.json`. camelCase event keys; flat `{ command }` entries;
+ * no `StopFailure` event, but a distinct `beforeShellExecution` (shell-mutation warn).
+ */
+export const CURSOR_EVENTS = [
+    { settingsKey: "sessionStart", subcommand: "session-start" },
+    { settingsKey: "sessionEnd", subcommand: "session-end" },
+    { settingsKey: "preToolUse", subcommand: "pre-tool-use" },
+    { settingsKey: "beforeShellExecution", subcommand: "before-shell-execution" },
+    { settingsKey: "postToolUse", subcommand: "post-tool-use" },
+    { settingsKey: "postToolUseFailure", subcommand: "post-tool-use-failure" },
+    { settingsKey: "subagentStart", subcommand: "sub-agent-start" },
+    { settingsKey: "subagentStop", subcommand: "sub-agent-stop" },
+    { settingsKey: "beforeSubmitPrompt", subcommand: "user-prompt-submit" },
+    { settingsKey: "stop", subcommand: "stop" },
+];
+/** Codex: `.codex/hooks.json`. PascalCase keys + the same entry shape as Claude Code. */
+export const CODEX_EVENTS = [
+    { settingsKey: "SessionStart", subcommand: "session-start" },
+    { settingsKey: "SessionEnd", subcommand: "session-end" },
+    { settingsKey: "PreToolUse", subcommand: "pre-tool-use" },
+    { settingsKey: "PostToolUse", subcommand: "post-tool-use" },
+    { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
+    { settingsKey: "UserPromptSubmit", subcommand: "user-prompt-submit" },
+    { settingsKey: "SubagentStart", subcommand: "sub-agent-start" },
+    { settingsKey: "SubagentStop", subcommand: "sub-agent-stop" },
+    { settingsKey: "Stop", subcommand: "stop" },
+    { settingsKey: "StopFailure", subcommand: "stop-failure" },
+];
+/** Every supported harness, fully wireable by `harn init`. */
+export const HARNESS_SPECS = {
+    "claude-code": {
+        settingsFile: ".claude/settings.json",
+        events: CLAUDE_CODE_EVENTS,
+        entryShape: "claude",
+    },
+    cursor: {
+        settingsFile: ".cursor/hooks.json",
+        events: CURSOR_EVENTS,
+        entryShape: "cursor",
+        rootVersion: 1,
+    },
+    codex: {
+        settingsFile: ".codex/hooks.json",
+        events: CODEX_EVENTS,
+        entryShape: "claude",
+    },
+};

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

@@ -0,0 +1,46 @@
+/**
+ * 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).
+ */
+import type { Harness } from "../events/schema.js";
+export type SystemEvent = "SessionStart" | "UserPromptSubmit" | "SubagentStart";
+/** Emit a context-injection (peer table, wiring check, council pending, …). */
+export declare function emitContext(harness: Harness, event: SystemEvent, text: string): void;
+/** Emit a PreToolUse deny: blocks the tool call with `reason` shown to the model. */
+export declare function emitDeny(harness: Harness, reason: string): void;
+/**
+ * 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 declare function emitStopBlock(harness: Harness, verdict: {
+    reason?: string;
+    rule: string;
+}): 0 | 2;
+//# sourceMappingURL=output.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/harness/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAEhF,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIpF;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC,GAAG,CAAC,CAUjG"}