harnery 0.29.0 → 0.31.0

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

@@ -0,0 +1,30 @@
+import { coordEnv } from "../../../lib/env.ts";
+import type { Adapter } from "../events/schema.ts";
+
+/**
+ * Resolve the adapter firing the hook. The dispatcher binary is always
+ * invoked with `--adapter <name>` per the wiring in each adapter'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 detectAdapter(argv: readonly string[]): Adapter | null {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--adapter") {
+      return validate(argv[i + 1]);
+    }
+    if (a.startsWith("--adapter=")) {
+      return validate(a.slice("--adapter=".length));
+    }
+  }
+  return validate(coordEnv("AGENT_COORD_ADAPTER"));
+}
+
+function validate(v: string | undefined): Adapter | null {
+  if (v === "claude-code" || v === "cursor" || v === "codex") return v;
+  // Legacy: some adapters 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/src/core/hooks/{harness → adapter}/events.ts

@@ -1,47 +1,49 @@
 /**
- * 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
+ * Canonical hook-wiring spec per adapter: which settings file to write, which
+ * event key maps to which `agent-hook <subcommand>`, and how each adapter 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`,
+ * for each adapter (Claude Code `.claude/settings.json`, Cursor `.cursor/hooks.json`,
  * Codex `.codex/hooks.json`).
  */
 
-export type HarnessId = "claude-code" | "cursor" | "codex";
+export type { Adapter as AdapterId } from "../events/schema.ts";
+
+import type { Adapter as AdapterId } from "../events/schema.ts";
 
 export interface HookEvent {
-  /** Key under the harness settings file's `hooks` map (e.g. `SessionStart`, `preToolUse`). */
+  /** Key under the adapter 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>`:
+ * How a adapter 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 {
+export interface AdapterSpec {
   /** Settings file to wire, relative to the project root. */
   settingsFile: string;
-  /** Events this harness fires, mapped to agent-hook subcommands. */
+  /** Events this adapter 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;
-  /** Harness-owned entries from older specs that `init` should remove during migration. */
+  /** Adapter-owned entries from older specs that `init` should remove during migration. */
   legacyEvents?: HookEvent[];
-  /** Strict top-level settings keys accepted by this harness, when its parser is closed. */
+  /** Strict top-level settings keys accepted by this adapter, when its parser is closed. */
   allowedTopLevelKeys?: string[];
-  /** Strict hook event keys accepted by this harness, including events harnery does not wire. */
+  /** Strict hook event keys accepted by this adapter, including events harnery does not wire. */
   allowedEventKeys?: string[];
   /**
-   * Env var the harness exports to hook processes carrying the project root
+   * Env var the adapter exports to hook processes carrying the project root
    * (e.g. Claude Code's CLAUDE_PROJECT_DIR). When set, `init` anchors the
    * agent-hook path on it so the hook still spawns when the process cwd has
    * wandered (the session shell `cd`ing into a subdirectory or off-repo).
@@ -115,8 +117,8 @@ export const CODEX_ALLOWED_EVENT_KEYS = [
   "Stop",
 ];
 
-/** Every supported harness, fully wireable by `harn init`. */
-export const HARNESS_SPECS: Record<HarnessId, HarnessSpec> = {
+/** Every supported adapter, fully wireable by `harn init`. */
+export const ADAPTER_SPECS: Record<AdapterId, AdapterSpec> = {
   "claude-code": {
     settingsFile: ".claude/settings.json",
     events: CLAUDE_CODE_EVENTS,

package/src/core/hooks/{harness → adapter}/output.ts

@@ -1,50 +1,56 @@
 /**
- * Harness-aware hook output JSON. Each adapter target has its own protocol
+ * Adapter-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.
+ * `adapter` everywhere.
  *
- * Shapes (verified against live dispatchers + each harness's upstream hooks docs):
+ * Shapes (verified against live dispatchers + each adapter'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).
+ * - **Codex**: structurally identical to Claude Code for context and tool
+ *   denials. Stop blocks are deliberately suppressed because their automatic
+ *   continuation can replace a completed user-facing answer.
  *
  * 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.ts";
+import type { Adapter } from "../events/schema.ts";
 
 export type SystemEvent = "SessionStart" | "UserPromptSubmit" | "SubagentStart";
 
 /** Emit a context-injection (peer table, wiring check, council pending, …). */
-export function emitContext(harness: Harness, event: SystemEvent, text: string): void {
+export function emitContext(adapter: Adapter, event: SystemEvent, text: string): void {
   if (!text || text.length === 0) return;
-  const json = buildContextJson(harness, event, text);
+  const json = buildContextJson(adapter, 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: Harness, reason: string): void {
+export function emitDeny(adapter: Adapter, reason: string): void {
   if (!reason) return;
-  const json = buildDenyJson(harness, reason);
+  const json = buildDenyJson(adapter, reason);
   process.stdout.write(`${JSON.stringify(json)}\n`);
 }
 
 /**
- * Emit a Stop-hook block in the firing harness's enforcement channel and return
+ * Emit a Stop-hook block in the firing adapter's enforcement channel and return
  * the process exit code the caller should use.
  *
- * The verdict (allow/block + reason) is computed harness-agnostically in
+ * The verdict (allow/block + reason) is computed adapter-agnostically in
  * agents/rules/stop-hook.ts; this function only shapes *how the block is
- * communicated back*, because each harness has a different mechanism:
+ * communicated back*, because each adapter 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.
+ * - **Claude Code** honors `exit 2` + a stderr reason as a turn block, and the
+ *   adapter re-prompts the model with the stderr text.
+ * - **Codex** also supports that channel, but Harnery must not use it for
+ *   coordination reminders. A Stop continuation can replace the completed
+ *   answer in clients that retain only the final continuation response. Return
+ *   success without output as a defense in depth behind the observe-only
+ *   verdict in `agents/rules/stop-hook.ts`.
  * - **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
@@ -52,11 +58,13 @@ export function emitDeny(harness: Harness, reason: string): void {
  *   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: Harness, verdict: { reason?: string; rule: string }): 0 | 2 {
+export function emitStopBlock(adapter: Adapter, verdict: { reason?: string; rule: string }): 0 | 2 {
+  if (adapter === "codex") return 0;
+
   const message = `${
     verdict.reason ?? "End-of-turn coordination ritual incomplete."
   }\n[agent-hook stop]: rule=${verdict.rule}`;
-  if (harness === "cursor") {
+  if (adapter === "cursor") {
     process.stdout.write(`${JSON.stringify({ followup_message: message })}\n`);
     return 0;
   }
@@ -65,16 +73,16 @@ export function emitStopBlock(harness: Harness, verdict: { reason?: string; rule
 }
 
 function buildContextJson(
-  harness: Harness,
+  adapter: Adapter,
   event: SystemEvent,
   text: string,
 ): Record<string, unknown> {
-  if (harness === "cursor") {
+  if (adapter === "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
+    // `env: {HARNERY_AGENT_COORD_ADAPTER, HARNERY_AGENT_COORD_PLATFORM}`. These are
     // observer hints, not load-bearing; agent-hook + agent-coord recover the
-    // harness from event metadata. Drop them.
+    // adapter from event metadata. Drop them.
     return { additional_context: text };
   }
   // Claude Code + Codex share the `hookSpecificOutput` envelope.
@@ -86,8 +94,8 @@ function buildContextJson(
   };
 }
 
-function buildDenyJson(harness: Harness, reason: string): Record<string, unknown> {
-  if (harness === "cursor") {
+function buildDenyJson(adapter: Adapter, reason: string): Record<string, unknown> {
+  if (adapter === "cursor") {
     return { permission: "deny", agent_message: reason, user_message: reason };
   }
   return {

package/src/core/hooks/{harness → adapter}/parse.ts

@@ -1,5 +1,5 @@
 /**
- * Harness payload parser. One file because all three harnesses (CC, Cursor,
+ * Adapter payload parser. One file because all three adapters (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.
@@ -10,7 +10,7 @@
  * events without affecting behavior": fail-soft beats fail-hard.
  */
 
-import type { Harness } from "../events/schema.ts";
+import type { Adapter } from "../events/schema.ts";
 
 export interface ParsedPayload {
   hook_event_name?: string;
@@ -40,10 +40,10 @@ export interface ParsedPayload {
 }
 
 /**
- * Parse the raw stdin payload string for any harness. Returns null when JSON
+ * Parse the raw stdin payload string for any adapter. Returns null when JSON
  * parse fails (Cursor occasionally fires hooks with no payload).
  */
-export function parsePayload(raw: string, _harness: Harness): ParsedPayload | null {
+export function parsePayload(raw: string, _adapter: Adapter): ParsedPayload | null {
   if (!raw || raw.trim().length === 0) return null;
   let json: Record<string, unknown>;
   try {
@@ -128,7 +128,7 @@ function pickBool(o: Record<string, unknown>, k: string): boolean | undefined {
 // ── Event-name normalization ────────────────────────────────────────────────
 
 /**
- * Each harness uses a slightly different name for the "same" lifecycle event.
+ * Each adapter 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

package/src/core/hooks/{harness → adapter}/wiring.ts

@@ -1,7 +1,7 @@
 /**
- * Read-only harness-hook wiring inspection — the inverse of `harn init`'s
+ * Read-only adapter-hook wiring inspection — the inverse of `harn init`'s
  * writer (commands/init.ts `wireHooks`). Compares what `init` would wire
- * (HARNESS_SPECS) against what's actually present in a project's harness
+ * (ADAPTER_SPECS) against what's actually present in a project's adapter
  * settings file, so `harn doctor` and the SessionStart nudge can tell an agent
  * when a harnery upgrade changed the hook set but the project hasn't been
  * re-wired yet.
@@ -15,9 +15,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-  HARNESS_SPECS,
-  type HarnessId,
-  type HarnessSpec,
+  ADAPTER_SPECS,
+  type AdapterId,
+  type AdapterSpec,
   type HookEntryShape,
   type HookEvent,
 } from "./events.ts";
@@ -42,7 +42,7 @@ export interface SettingsFile {
   [k: string]: unknown;
 }
 
-/** Build a hook entry in the harness's shape. */
+/** Build a hook entry in the adapter's shape. */
 export function makeEntry(shape: HookEntryShape, command: string): HookGroup {
   return shape === "cursor" ? { command } : { hooks: [{ type: "command", command }] };
 }
@@ -81,17 +81,17 @@ export interface WiringDiff {
    * these — they need explicit removal — so they're surfaced separately.
    */
   orphans: string[];
-  /** Settings fields rejected by a harness with a strict top-level schema. */
+  /** Settings fields rejected by a adapter with a strict top-level schema. */
   invalidTopLevelKeys: string[];
-  /** Hook event names rejected by a harness with a strict event schema. */
+  /** Hook event names rejected by a adapter with a strict event schema. */
   invalidEventKeys: string[];
 }
 
 /**
- * Pure diff of one settings object against one harness spec. Read-only inverse
+ * 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: HarnessSpec): WiringDiff {
+export function diffWiring(settings: SettingsFile, spec: AdapterSpec): WiringDiff {
   const missing: HookEvent[] = [];
   const present: HookEvent[] = [];
   const hooks = settings.hooks ?? {};
@@ -136,8 +136,8 @@ export function diffWiring(settings: SettingsFile, spec: HarnessSpec): WiringDif
   };
 }
 
-export interface HarnessWiringStatus {
-  harness: HarnessId;
+export interface AdapterWiringStatus {
+  adapter: AdapterId;
   /** Settings file path, relative to the project root. */
   settingsFile: string;
   missing: HookEvent[];
@@ -148,19 +148,19 @@ export interface HarnessWiringStatus {
 }
 
 /**
- * Inspect every harness whose settings file exists under `projectRoot` and
+ * Inspect every adapter whose settings file exists under `projectRoot` and
  * return only those with *drift*. Read-only; never writes.
  *
- * Drift is reported only for a harness the project has **already opted into** —
+ * Drift is reported only for a adapter the project has **already opted into** —
  * i.e. at least one harnery hook is already wired. A settings file with zero
- * harnery hooks just means this harness isn't harnery-wired here (a bare
+ * harnery hooks just means this adapter isn't harnery-wired here (a bare
  * `.claude/settings.json` is a generic Claude Code file); that's `harn init`'s
- * job to surface on first run, not drift to nag about every session. A harness
+ * job to surface on first run, not drift to nag about every session. A adapter
  * with no settings file at all, or an unparseable one, is skipped.
  */
-export function loadHarnessWiring(projectRoot: string): HarnessWiringStatus[] {
-  const out: HarnessWiringStatus[] = [];
-  for (const [id, spec] of Object.entries(HARNESS_SPECS) as [HarnessId, HarnessSpec][]) {
+export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
+  const out: AdapterWiringStatus[] = [];
+  for (const [id, spec] of Object.entries(ADAPTER_SPECS) as [AdapterId, AdapterSpec][]) {
     const settingsPath = resolve(projectRoot, spec.settingsFile);
     if (!existsSync(settingsPath)) continue;
     let settings: SettingsFile;
@@ -168,7 +168,7 @@ export function loadHarnessWiring(projectRoot: string): HarnessWiringStatus[] {
       settings = JSON.parse(readFileSync(settingsPath, "utf8")) as SettingsFile;
     } catch (error) {
       out.push({
-        harness: id,
+        adapter: id,
         settingsFile: spec.settingsFile,
         missing: [],
         orphans: [],
@@ -189,7 +189,7 @@ export function loadHarnessWiring(projectRoot: string): HarnessWiringStatus[] {
       continue; // current
     }
     out.push({
-      harness: id,
+      adapter: id,
       settingsFile: spec.settingsFile,
       missing: diff.missing,
       orphans: diff.orphans,