heedvane 0.0.0-stage → 0.1.0

package/dist/render.d.ts

@@ -0,0 +1,30 @@
+import { type PlannedAction } from "./plan.js";
+import type { ResolvedClient } from "./clients/definitions.js";
+export interface DetectionRow {
+    client: ResolvedClient;
+    detected: boolean;
+    /** Marker path relative to home, e.g. ~/.claude */
+    markerRel: string;
+}
+export declare function renderDetection(rows: DetectionRow[]): string[];
+/**
+ * The summary line from the spec:
+ *   Would install: hooks -> 2 agents · skill -> 3 agents · MCP -> 3 agents
+ * Kinds with zero pending writes are omitted; singularized when 1.
+ */
+export declare function wouldInstallSummary(actions: PlannedAction[]): string;
+/** File-by-file plan lines, with backup paths where a write would occur. */
+export declare function renderPlan(actions: PlannedAction[]): string[];
+export interface AppliedResult {
+    clientId: string;
+    kind: string;
+    status: string;
+    path: string;
+    backupPath?: string;
+    reason?: string;
+    remediation?: string;
+}
+/** A refused or failed write: printed with ✗ and makes the command exit non-zero. */
+export declare function appliedFailed(result: AppliedResult): boolean;
+/** Applied-result lines matching the mock's ✓ block. */
+export declare function renderApplied(results: AppliedResult[]): string[];

package/dist/render.js

@@ -0,0 +1,131 @@
+/**
+ * Plain-text renderers (testable: pure string arrays) for detection,
+ * plans, and applied results. --json envelopes are built in cli.ts.
+ */
+import { basename } from "node:path";
+import { wouldInstallCount } from "./plan.js";
+function capabilitySummary(client) {
+    const parts = [];
+    if (client.capabilities.includes("hooks"))
+        parts.push("hooks");
+    if (client.capabilities.includes("mcp"))
+        parts.push("MCP");
+    if (client.capabilities.includes("skill"))
+        parts.push("skill");
+    const hookless = client.events.length === 0 && client.capabilities.includes("mcp");
+    if (hookless) {
+        // e.g. Warp: "MCP + skill — no native hooks; policies via MCP"
+        return `${parts.join(" + ")} — no native hooks; policies via MCP`;
+    }
+    return parts.join(" + ");
+}
+export function renderDetection(rows) {
+    const lines = ["  Detected on this machine:"];
+    const width = Math.max(...rows.map((r) => r.client.displayName.length));
+    for (const row of rows) {
+        const name = row.client.displayName.padEnd(width);
+        if (row.detected) {
+            lines.push(`    ✓ ${name}  (${capabilitySummary(row.client)})  ${row.markerRel}`);
+        }
+        else {
+            lines.push(`    ✗ ${name}  (not detected — skip or force with --agent ${row.client.id})`);
+        }
+    }
+    return lines;
+}
+const VERB = {
+    create: "added",
+    update: "updated",
+    unchanged: "already current",
+    skip: "skipped",
+};
+function kindLabel(kind) {
+    switch (kind) {
+        case "hooks": return "hooks";
+        case "mcp": return "MCP";
+        case "skill": return "skill";
+        case "skip": return "";
+    }
+}
+function plural(n, noun) {
+    return n === 1 ? noun : `${noun}s`;
+}
+/**
+ * The summary line from the spec:
+ *   Would install: hooks -> 2 agents · skill -> 3 agents · MCP -> 3 agents
+ * Kinds with zero pending writes are omitted; singularized when 1.
+ */
+export function wouldInstallSummary(actions) {
+    const parts = [];
+    for (const kind of ["hooks", "skill", "mcp"]) {
+        const n = wouldInstallCount(actions, kind);
+        if (n > 0)
+            parts.push(`${kindLabel(kind)} -> ${n} ${plural(n, "agent")}`);
+    }
+    return parts.length > 0 ? `  Would install: ${parts.join(" · ")}` : "  Would install: nothing — already current";
+}
+/** File-by-file plan lines, with backup paths where a write would occur. */
+export function renderPlan(actions) {
+    const lines = [];
+    for (const action of actions) {
+        if (action.kind === "skip") {
+            lines.push(`    · ${action.reason}`);
+            continue;
+        }
+        if (action.kind === "skill")
+            continue; // collapsed below, one line per unique dir
+        const label = kindLabel(action.kind);
+        const verb = VERB[action.operation] ?? action.operation;
+        const backup = action.backupPath ? ` (backup: ${basename(action.backupPath)})` : "";
+        lines.push(`    ${action.path}  ${label} ${verb}${backup}`);
+    }
+    // One line per unique skill dir (the plan reports it per agent).
+    const skillDirs = new Set(actions.filter((a) => a.kind === "skill" && a.operation !== "unchanged").map((a) => a.path));
+    for (const dir of skillDirs) {
+        lines.push(`    ${dir.slice(0, dir.lastIndexOf("SKILL.md") > 0 ? dir.lastIndexOf("SKILL.md") : undefined)}  skill installed`);
+    }
+    for (const action of actions.filter((a) => a.kind === "skill" && a.operation === "unchanged")) {
+        lines.push(`    ${action.path}  skill already current`);
+    }
+    return lines;
+}
+/** A refused or failed write: printed with ✗ and makes the command exit non-zero. */
+export function appliedFailed(result) {
+    return result.status === "failed" || result.status === "invalid";
+}
+/** ✗ refused or failed, · nothing written, ✓ written. */
+function appliedMarker(result) {
+    if (appliedFailed(result))
+        return "✗";
+    return result.status === "unchanged" || result.status === "skipped" ? "·" : "✓";
+}
+/** One config result: its line, then its reason and remediation when present. */
+function appliedLines(r) {
+    const label = kindLabel(r.kind) ?? r.kind;
+    const verb = VERB[r.status] ?? r.status;
+    const backup = r.backupPath ? ` (backup: ${basename(r.backupPath)})` : "";
+    const lines = [`  ${appliedMarker(r)} ${r.path}  ${label} ${verb}${backup}`];
+    if (r.reason)
+        lines.push(`      ↳ ${r.reason}`);
+    if (r.remediation)
+        lines.push(`      remediation: ${r.remediation}`);
+    return lines;
+}
+/** Applied-result lines matching the mock's ✓ block. */
+export function renderApplied(results) {
+    const lines = [];
+    const seenSkill = new Set();
+    for (const r of results) {
+        if (r.kind === "skill") {
+            const dir = r.path.slice(0, Math.max(r.path.lastIndexOf("/SKILL.md"), 0));
+            if (seenSkill.has(dir))
+                continue;
+            seenSkill.add(dir);
+            const label = r.status === "unchanged" ? "skill already current" : `skill v1 installed`;
+            lines.push(`  ✓ ${dir}/  ${label}`);
+            continue;
+        }
+        lines.push(...appliedLines(r));
+    }
+    return lines;
+}

package/dist/reply/harness-output.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A verdict as the JSON a harness reads from its hook's stdout. The mapping is the steering contract's
+ * (docs/product/agent-integration/steering.md, "Mapping to harness hook output"), each harness checked
+ * against its own hook reference. Claude Code: decisions and context sit under `hookSpecificOutput` with
+ * `hookEventName`; a top-level `permissionDecision` would be ignored, turning a deny into an allow.
+ */
+import type { Envelope } from "../events/contract.js";
+import type { Verdict } from "./verdict.js";
+/**
+ * Claude Code shows the agent only a 2,000-character preview of a hook's `additionalContext` over 10,000
+ * characters. The session-start answer (organization rules first, then private memories) stays under this.
+ */
+export declare const ADDITIONAL_CONTEXT_BUDGET = 9500;
+/** Between the pieces of one answer's context. */
+export declare const CONTEXT_SEPARATOR = "\n\n";
+/** What a harness reads from its hook's stdout; `{}` lets the agent continue untouched. */
+export type HarnessOutput = Record<string, never> | {
+    hookSpecificOutput: {
+        hookEventName: string;
+        permissionDecision: "deny";
+        permissionDecisionReason: string;
+    };
+} | {
+    hookSpecificOutput: {
+        hookEventName: string;
+        additionalContext: string;
+    };
+} | {
+    decision: "block" | "deny";
+    reason: string;
+} | {
+    continue: false;
+    stopReason: string;
+} | {
+    permission: "deny";
+    user_message: string;
+    agent_message: string;
+} | {
+    followup_message: string;
+} | {
+    additional_context: string;
+} | {
+    action: "block";
+    message: string;
+} | {
+    context: string;
+};
+/** The events a stop block or halt applies to. */
+export declare const STOP_EVENTS: ReadonlySet<string>;
+/**
+ * The stdout JSON for the envelope's agent and event. A `steer` always enforces where the harness can:
+ * PreToolUse denies the tool; Stop and SubagentStop block with the reason; a halted Stop (Heedvane's
+ * `halt`, or the Stop cap in src/reply/reply.ts) ends the turn, so the person sees why. Nothing else is
+ * enforceable. A `warn` (the skill check only), recalled memory and organization instructions are
+ * context.
+ */
+export declare function harnessOutput(envelope: Envelope, verdict: Verdict): HarnessOutput;

package/dist/reply/harness-output.js

@@ -0,0 +1,88 @@
+import { normalizeAgent } from "../events/normalize.js";
+const CLAUDE_EVENT_NAMES = {
+    pre_tool_use: "PreToolUse",
+    user_prompt_submit: "UserPromptSubmit",
+    session_start: "SessionStart",
+    stop: "Stop",
+    subagent_stop: "SubagentStop",
+};
+/**
+ * Claude Code shows the agent only a 2,000-character preview of a hook's `additionalContext` over 10,000
+ * characters. The session-start answer (organization rules first, then private memories) stays under this.
+ */
+export const ADDITIONAL_CONTEXT_BUDGET = 9_500;
+/** Between the pieces of one answer's context. */
+export const CONTEXT_SEPARATOR = "\n\n";
+/** The events a stop block or halt applies to. */
+export const STOP_EVENTS = new Set(["stop", "subagent_stop"]);
+const CLAUDE_STEERING = {
+    names: CLAUDE_EVENT_NAMES,
+    deny: (hookEventName, reason) => ({ hookSpecificOutput: { hookEventName, permissionDecision: "deny", permissionDecisionReason: reason } }),
+    block: (reason) => ({ decision: "block", reason }),
+    halt: (reason) => ({ continue: false, stopReason: reason }),
+    context: (hookEventName, text) => ({ hookSpecificOutput: { hookEventName, additionalContext: text } }),
+};
+/**
+ * Each harness checked against its own hook reference on 2026-10-11; any other agent gets `{}`.
+ * - Codex (developers.openai.com/codex/hooks, rust-v0.162): Claude Code's output, with the same event
+ *   names.
+ * - Gemini CLI (geminicli.com/docs/hooks/reference): a top-level `decision: "deny"` refuses BeforeTool and
+ *   makes AfterAgent retry with the reason; `continue: false` ends the session. BeforeTool carries no
+ *   context, and there is no subagent stop.
+ * - Cursor (cursor.com/docs/hooks): `permission: "deny"` refuses preToolUse; a stop's `followup_message`
+ *   is submitted as the next user message. Nothing documented ends a turn, and only sessionStart carries
+ *   context.
+ * - Hermes (hermes-agent.nousresearch.com/docs/user-guide/features/hooks): its plugin's `pre_tool_call`
+ *   blocks with `{action: "block", message}`, which Hermes ignores without a message; `pre_llm_call`
+ *   adds `{context}` to the turn. It has no stop hook.
+ */
+const HARNESS_STEERING = {
+    claude: CLAUDE_STEERING,
+    codex: CLAUDE_STEERING,
+    antigravity: CLAUDE_STEERING,
+    gemini: {
+        names: { pre_tool_use: "BeforeTool", user_prompt_submit: "BeforeAgent", session_start: "SessionStart", stop: "AfterAgent" },
+        deny: (_name, reason) => ({ decision: "deny", reason }),
+        block: (reason) => ({ decision: "deny", reason }),
+        halt: (reason) => ({ continue: false, stopReason: reason }),
+        context: (hookEventName, text) => (hookEventName === "BeforeTool" ? null : { hookSpecificOutput: { hookEventName, additionalContext: text } }),
+    },
+    cursor: {
+        names: { pre_tool_use: "preToolUse", user_prompt_submit: "beforeSubmitPrompt", session_start: "sessionStart", stop: "stop", subagent_stop: "subagentStop" },
+        deny: (_name, reason) => ({ permission: "deny", user_message: reason, agent_message: reason }),
+        block: (reason) => ({ followup_message: reason }),
+        context: (name, text) => (name === "sessionStart" ? { additional_context: text } : null),
+    },
+    hermes: {
+        names: { pre_tool_use: "pre_tool_call", user_prompt_submit: "pre_llm_call" },
+        deny: (_name, reason) => (reason === "" ? {} : { action: "block", message: reason }),
+        context: (name, text) => (name === "pre_llm_call" ? { context: text } : null),
+    },
+};
+/**
+ * The stdout JSON for the envelope's agent and event. A `steer` always enforces where the harness can:
+ * PreToolUse denies the tool; Stop and SubagentStop block with the reason; a halted Stop (Heedvane's
+ * `halt`, or the Stop cap in src/reply/reply.ts) ends the turn, so the person sees why. Nothing else is
+ * enforceable. A `warn` (the skill check only), recalled memory and organization instructions are
+ * context.
+ */
+export function harnessOutput(envelope, verdict) {
+    const { agent, event } = envelope;
+    const steering = HARNESS_STEERING[normalizeAgent(agent)];
+    const name = steering?.names[event];
+    if (steering === undefined || name === undefined)
+        return {};
+    if (verdict.decision === "steer")
+        return enforced(steering, { event, name }, verdict);
+    const text = [...verdict.messages, ...verdict.context].join(CONTEXT_SEPARATOR);
+    return text === "" || STOP_EVENTS.has(event) ? {} : (steering.context(name, text) ?? {});
+}
+/** `event` is canonical, `name` the harness's own name for it. */
+function enforced(steering, { event, name }, verdict) {
+    const reason = verdict.messages.join("\n\n");
+    if (event === "pre_tool_use")
+        return steering.deny?.(name, reason) ?? {};
+    if (!STOP_EVENTS.has(event))
+        return {};
+    return (verdict.halt === true ? steering.halt?.(reason) : steering.block?.(reason)) ?? {};
+}

package/dist/reply/reply.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The listener's answer to one hook event, from this machine alone: the local skill check first (a
+ * deny needs no network), then the synced deterministic steering rules and local private-memory recall,
+ * plus the organization's instructions as context, shaped for the harness. Heedvane's own evaluation
+ * never holds an answer back: it runs in the background (src/steering/steer.ts), and an enforcing verdict
+ * is delivered by the session's next tool call or stop (src/steering/violations.ts). A session's stops
+ * are blocked at most {@link MAX_STOP_BLOCKS_IN_A_ROW} times in a row; the next one ends the turn (`halt`)
+ * and no later stop of that session is blocked. Every steering
+ * enforcement is reported to Heedvane as a delivery (steering.md "Enforcement records"): what the hook
+ * emitted, and who decided.
+ */
+import type { Backend } from "../backend/client.js";
+import type { Envelope } from "../events/contract.js";
+import type { HeedvaneConfig } from "../heed-file.js";
+import type { TeamMemoryStart } from "../memory/team-memory.js";
+import { type SteeringPolicy } from "../steering/rules.js";
+import { type Delivery } from "../steering/steer.js";
+import { type Violations } from "../steering/violations.js";
+import { type HarnessOutput } from "./harness-output.js";
+/** How long the session start's one fetch of the steering policy may take; the only wait on Heedvane in a hook. */
+export declare const BACKEND_BUDGET_MS = 1000;
+/** One enforced rule as reported to `POST /api/agent/steering/deliveries`. */
+export interface SteeringDelivery {
+    agent: string;
+    session: string;
+    event: string;
+    tool?: string;
+    eventKey: string;
+    ruleId: string;
+    ruleSha256: string;
+    status: "enforced" | "halted";
+    delivery: Delivery;
+    /** On a `next_event` delivery, the key of the event that carried the block (tool_use_id, else receivedAt). */
+    carriedBy?: string;
+}
+export interface ReplyContext {
+    config: HeedvaneConfig;
+    /** Heedvane with this machine's credential (src/backend/credentials.ts), or null without one. */
+    backend: Backend | null;
+    /** The heed root (approved-skills cache). */
+    root: string;
+    home: string;
+    log: (message: string) => void;
+    /** The steering policy the session started with (fetched once, at its session start), or the last one synced; null before the first sync. */
+    policy: (session: string) => SteeringPolicy | null;
+    /** Queue a delivery report for Heedvane. */
+    report: (delivery: SteeringDelivery) => void;
+    /** Per session, how many Stops in a row were blocked, and whether it ran out of stop blocks (then none is delivered for the rest of the session). */
+    stopBlocks: Map<string, {
+        inARow: number;
+        ranOut: boolean;
+    }>;
+    /** Heedvane's enforcing verdicts, until the session's next tool call or stop carries them. */
+    violations: Violations;
+    /** How many times each session has ended: a verdict judged before the end belongs to a session that is over. */
+    sessionEnds: Map<string, number>;
+}
+/** What only some events bring along: the tool call's whole input, and the team memory the session start learned. */
+export interface ReplyExtras {
+    toolInput?: unknown;
+    teamMemory?: TeamMemoryStart;
+}
+export declare function replyFor(envelope: Envelope, ctx: ReplyContext, extras?: ReplyExtras): Promise<HarnessOutput>;
+/** The event's checkout origin URL (credentials stripped), or "" without a cwd or a git origin. */
+export declare function eventRemote(envelope: Envelope): Promise<string>;

package/dist/reply/reply.js

@@ -0,0 +1,169 @@
+import { repoRemote, repositoryName } from "../backend/repo-remote.js";
+import { errorMessage } from "../guards.js";
+import { recall } from "../memory/private-memory.js";
+import { renderTableOfContents } from "../memory/table-of-contents.js";
+import { approvedSkillsFor } from "../skills/approved.js";
+import { checkSkill } from "../skills/check.js";
+import { instructionContext } from "../steering/rules.js";
+import { STEERED_EVENTS, localVerdict, steer } from "../steering/steer.js";
+import { DELIVERY_EVENTS, openViolation, takeViolations, withoutRules } from "../steering/violations.js";
+import { ADDITIONAL_CONTEXT_BUDGET, CONTEXT_SEPARATOR, STOP_EVENTS, harnessOutput } from "./harness-output.js";
+import { ALLOW, combine } from "./verdict.js";
+/** How long the session start's one fetch of the steering policy may take; the only wait on Heedvane in a hook. */
+export const BACKEND_BUDGET_MS = 1_000;
+/** André's ruling: block finishing only this many times in a row; after that other mechanisms have to do it. */
+const MAX_STOP_BLOCKS_IN_A_ROW = 4;
+export async function replyFor(envelope, ctx, extras = {}) {
+    if (envelope.event === "session_end")
+        endSession(envelope.session, ctx);
+    const skill = checkSkill(envelope, { config: ctx.config.skills, approved: await approvedSkillsFor(ctx.root, ctx.backend), home: ctx.home });
+    if (skill.decision === "steer")
+        return harnessOutput(envelope, skill);
+    const request = { envelope, repository: repositoryName(await eventRemote(envelope)), toolInput: extras.toolInput };
+    const policy = ctx.policy(envelope.session);
+    const startBlock = await sessionStartBlock(request, ctx, { policy, teamMemory: extras.teamMemory });
+    const steered = steeringBackend(envelope, ctx, policy);
+    const local = steered === null ? ALLOW : localVerdict(request, policy?.rules ?? []);
+    if (steered !== null)
+        judgeInBackground(request, { backend: steered, enforcedLocally: new Set((local.enforcements ?? []).map((enforced) => enforced.ruleId)) }, ctx);
+    reportDeliveries(envelope, local.enforcements ?? [], { status: "enforced", delivery: "local", report: ctx.report });
+    const delivered = steered === null ? ALLOW : deliverViolations(envelope, ctx);
+    return harnessOutput(envelope, combine([skill, local, delivered, ...startBlock]));
+}
+/** A session that ended keeps no stop count or violation, and a verdict still being judged for it is dropped on arrival. */
+function endSession(session, ctx) {
+    ctx.stopBlocks.delete(session);
+    ctx.violations.delete(session);
+    ctx.sessionEnds.set(session, (ctx.sessionEnds.get(session) ?? 0) + 1);
+}
+/**
+ * The session-start block (policies.md "Session start"): the organization's instructions first, whole; then the team
+ * memory's table of contents; then the private memories, each in the room the ones before left.
+ */
+async function sessionStartBlock(request, ctx, known) {
+    const { envelope, repository } = request;
+    const { policy, teamMemory } = known;
+    const instructions = { ...ALLOW, context: instructionContext(policy, envelope.event) };
+    const afterPolicies = ADDITIONAL_CONTEXT_BUDGET - instructions.context.reduce((used, text) => used + text.length + CONTEXT_SEPARATOR.length, 0);
+    const contents = tableOfContents({ envelope, repository, teamMemory }, afterPolicies - CONTEXT_SEPARATOR.length);
+    const tableVerdict = { ...ALLOW, context: contents === "" ? [] : [contents] };
+    const room = afterPolicies - (contents === "" ? 0 : contents.length + CONTEXT_SEPARATOR.length);
+    const recalled = ctx.config.memory ? await recall(ctx.root, { envelope, repository }, room) : ALLOW;
+    return [instructions, tableVerdict, recalled];
+}
+/** The team memory's table of contents for a session start, in at most `room` characters; a line saying where to look when Heedvane did not answer. */
+function tableOfContents({ envelope, repository, teamMemory }, room) {
+    if (envelope.event !== "session_start" || teamMemory === undefined || teamMemory.state === "none")
+        return "";
+    if (teamMemory.state === "map")
+        return renderTableOfContents(teamMemory.map, repository, room);
+    const unavailable = `Team memory for ${repository} could not be reached: npx heedvane memory list`;
+    return unavailable.length <= room ? unavailable : "";
+}
+/** Heedvane, when heed.yaml, a credential and the policy allow steering this event; else null. */
+function steeringBackend(envelope, ctx, policy) {
+    const steering = ctx.config.steering && policy?.enabled !== false && STEERED_EVENTS.has(envelope.event);
+    return steering ? ctx.backend : null;
+}
+/**
+ * Heedvane evaluates the event while the agent goes on: an enforcing answer opens a violation for the
+ * session, less the rules the synced rules enforced on this event on the spot. Nothing waits for it; a verdict that
+ * arrives after the sign-in changed, or the session ended, belongs to another organization or a session that is over and is dropped.
+ */
+function judgeInBackground(request, judge, ctx) {
+    const { envelope } = request;
+    const { backend, enforcedLocally } = judge;
+    const endsBefore = ctx.sessionEnds.get(envelope.session) ?? 0;
+    void (async () => {
+        const identity = await backend.identity();
+        const verdict = await steer(backend, request);
+        if (verdict === null || verdict.decision === "allow" || (await backend.identity()) !== identity)
+            return;
+        if ((ctx.sessionEnds.get(envelope.session) ?? 0) !== endsBefore)
+            return;
+        const violation = withoutRules(verdict, enforcedLocally);
+        if (violation !== null)
+            openViolation(ctx.violations, { judged: envelope, verdict: violation });
+    })().catch((err) => ctx.log(`[heedvane] could not evaluate a ${envelope.event} event: ${errorMessage(err)}`));
+}
+/**
+ * The session's open violations as one verdict on a tool call or stop, each delivered once and reported
+ * against the event Heedvane judged. A stop that finds none goes through and starts the count of blocked
+ * stops again; the stop after {@link MAX_STOP_BLOCKS_IN_A_ROW} blocked ones ends the turn instead, and
+ * from then on the session's stops are not blocked (its violations wait for a tool call).
+ */
+function deliverViolations(envelope, ctx) {
+    if (!DELIVERY_EVENTS.has(envelope.event))
+        return ALLOW;
+    if (STOP_EVENTS.has(envelope.event) && stopRun(envelope.session, ctx).ranOut)
+        return ALLOW;
+    const violations = takeViolations(ctx.violations, envelope.session);
+    if (violations.length > 0)
+        return blockWith(violations, envelope, ctx);
+    // Only the main agent's clean stop starts the count again; a subagent finishing does not.
+    if (envelope.event === "stop")
+        ctx.stopBlocks.set(envelope.session, { inARow: 0, ranOut: false });
+    return ALLOW;
+}
+/** The session's count of stops blocked in a row, and whether it ran out of stop blocks. */
+function stopRun(session, ctx) {
+    return ctx.stopBlocks.get(session) ?? { inARow: 0, ranOut: false };
+}
+/** The open violations as one verdict on this tool call or stop, with the stop count moved on and each delivery reported. */
+function blockWith(violations, envelope, ctx) {
+    const stops = STOP_EVENTS.has(envelope.event);
+    const run = stopRun(envelope.session, ctx);
+    const combined = combine(violations.map((violation) => violation.verdict));
+    // After four blocked stops the session's stop blocks are over, whatever the fifth stop carries.
+    const ranOut = stops && run.inARow >= MAX_STOP_BLOCKS_IN_A_ROW;
+    // Heedvane's own halt ends the turn but is not one of the blocks in a row.
+    if (stops)
+        ctx.stopBlocks.set(envelope.session, { inARow: combined.halt === true ? run.inARow : run.inARow + 1, ranOut });
+    const verdict = ranOut ? { ...combined, halt: true } : combined;
+    const outcome = {
+        status: verdict.halt === true && stops ? "halted" : "enforced",
+        delivery: ranOut && combined.halt !== true ? "local" : "next_event",
+        report: ctx.report,
+        carrier: envelope,
+    };
+    for (const { judged, verdict: judgedVerdict } of violations)
+        reportDeliveries(judged, judgedVerdict.enforcements ?? [], outcome);
+    return verdict;
+}
+/**
+ * One delivery per enforced rule, keyed like Heedvane's records: `tool_use_id` on tool events, else
+ * `receivedAt`, of the event Heedvane judged (the one that is being enforced). Heedvane requires the
+ * rule's version and a non-empty tool, so a rule without a known version (a policy cached before rules
+ * carried one) is not reported, and an empty tool is left out.
+ */
+function reportDeliveries(judged, enforcements, outcome) {
+    const { payload } = judged;
+    const { status, delivery, report, carrier } = outcome;
+    const tool = payload["tool"];
+    for (const { ruleId, ruleSha256 } of enforcements) {
+        if (ruleSha256 === undefined || ruleSha256 === "")
+            continue;
+        report({
+            agent: judged.agent,
+            session: judged.session,
+            event: judged.event,
+            ...(typeof tool === "string" && tool !== "" ? { tool } : {}),
+            eventKey: eventKeyOf(judged),
+            ruleId,
+            ruleSha256,
+            status,
+            delivery,
+            ...(delivery === "next_event" && carrier !== undefined ? { carriedBy: eventKeyOf(carrier) } : {}),
+        });
+    }
+}
+/** Heedvane's key for an event in enforcement records: `tool_use_id` on tool events, else `receivedAt`. */
+function eventKeyOf(envelope) {
+    const toolUseId = envelope.payload["tool_use_id"];
+    return typeof toolUseId === "string" && toolUseId !== "" ? toolUseId : envelope.receivedAt;
+}
+/** The event's checkout origin URL (credentials stripped), or "" without a cwd or a git origin. */
+export function eventRemote(envelope) {
+    const cwd = envelope.payload["cwd"];
+    return typeof cwd === "string" && cwd !== "" ? repoRemote(cwd) : Promise.resolve("");
+}

package/dist/reply/verdict.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the listener answers a hook with, before it is shaped for one harness. Steering, the skill
+ * check and memory recall each produce one; `combine` merges them with one precedence rule.
+ */
+export type Decision = "allow" | "warn" | "steer";
+/** One enforced steering rule and its version (steering.md "Hook response contract", `enforcements`). */
+export interface Enforced {
+    ruleId: string;
+    ruleSha256?: string;
+}
+export interface Verdict {
+    /** The strongest action: `steer` enforces (denies a tool, blocks a prompt or stop); `warn` only informs (the skill check). */
+    decision: Decision;
+    /** Guidance from rules that matched, strongest first. */
+    messages: string[];
+    /** Context to inject (recalled memories, organization instructions); never a reason to deny. */
+    context: string[];
+    /** The steering rules this verdict enforces, for the Stop cap and the delivery report. */
+    enforcements?: Enforced[];
+    /** End the turn instead of blocking the stop again (Heedvane's `halt`, or the Stop cap). */
+    halt?: boolean;
+}
+export declare const ALLOW: Verdict;
+/**
+ * Strongest decision wins; messages keep the stronger verdict's first, each once (a rule matched
+ * locally and by Heedvane is one message); enforcements once per rule; context is concatenated.
+ */
+export declare function combine(verdicts: Verdict[]): Verdict;

package/dist/reply/verdict.js

@@ -0,0 +1,17 @@
+export const ALLOW = { decision: "allow", messages: [], context: [] };
+const RANK = { allow: 0, warn: 1, steer: 2 };
+/**
+ * Strongest decision wins; messages keep the stronger verdict's first, each once (a rule matched
+ * locally and by Heedvane is one message); enforcements once per rule; context is concatenated.
+ */
+export function combine(verdicts) {
+    const ordered = [...verdicts].sort((a, b) => RANK[b.decision] - RANK[a.decision]);
+    const enforcements = new Map(verdicts.flatMap((verdict) => verdict.enforcements ?? []).map((enforced) => [enforced.ruleId, enforced]));
+    return {
+        decision: ordered[0]?.decision ?? "allow",
+        messages: [...new Set(ordered.flatMap((verdict) => verdict.messages))],
+        enforcements: [...enforcements.values()],
+        context: verdicts.flatMap((verdict) => verdict.context),
+        ...(verdicts.some((verdict) => verdict.halt === true) ? { halt: true } : {}),
+    };
+}

package/dist/skill/bundle.d.ts

@@ -0,0 +1,23 @@
+import { type SkillFile } from "./content.js";
+export type SkillInstallStatus = "installed" | "unchanged" | "failed";
+/** Where the skill lives for a given skills root (~/.agents/skills). */
+export declare function skillInstallDir(skillsRoot: string, name?: string): string;
+/** Backup path for any differing existing skill file. */
+export declare function skillBackupPath(target: string): string;
+export interface InstallSkillOptions {
+    name?: string;
+    /**
+     * Whether a differing file on disk is the person's own and needs a backup; default: always. A
+     * backup is never overwritten, so it keeps the first original even across later updates.
+     */
+    backUp?: (existing: Buffer) => boolean;
+}
+/**
+ * REA's co-install pattern, applied to the skill bundle: compare canonical
+ * files against disk, back up any differing file as <path>.heedvane.backup,
+ * atomic-write (write-file-atomic), then read back to verify — restore on
+ * mismatch and report 'failed'.
+ */
+export declare function installSkill(skillsRoot: string, files?: SkillFile[], options?: InstallSkillOptions): Promise<SkillInstallStatus>;
+/** Digest of the currently installed skill files, or null when absent/incomplete. */
+export declare function readInstalledSkillDigest(skillsRoot: string, files?: SkillFile[]): Promise<string | null>;