harnery 0.31.6 → 0.33.0

package/dist/core/hooks/adapter/wiring.d.ts

@@ -84,6 +84,29 @@ export interface AdapterWiringStatus {
  * with no settings file at all, or an unparseable one, is skipped.
  */
 export declare function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[];
+export interface AdapterWiringSummary {
+    /** Adapters carrying at least one harnery hook. */
+    wired: AdapterId[];
+    /**
+     * Adapters carrying none: no settings file at all, or a settings file with
+     * none of ours in it. An unparseable file lands in neither list, since
+     * `loadAdapterWiring` already reports that as drift.
+     */
+    unwired: AdapterId[];
+}
+/**
+ * Classify every known adapter as wired or unwired, without judging whether an
+ * unwired one is a problem.
+ *
+ * `loadAdapterWiring` stays deliberately silent about an adapter with zero
+ * harnery hooks, because a bare settings file is not an opt-out signal and
+ * nagging about it would false-warn every session. That silence is right in
+ * isolation and wrong once you also know the adapter's CLI is installed: then
+ * an agent can start a session here and register nothing. Splitting the fact
+ * from the judgement lets a caller holding both (doctor) tell "not used here"
+ * from "never wired" without changing what counts as drift.
+ */
+export declare function summarizeAdapterWiring(projectRoot: string): AdapterWiringSummary;
 /**
  * Resolve the harnery package version for context in nudges/checks. Walks up
  * from this module to the package root (works under Bun from `src/` and Node

package/dist/core/hooks/adapter/wiring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/adapter/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AACD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,eAAe,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAMxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnF;AAQD,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA2ChF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwC5E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAkBvC"}
+{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/adapter/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AACD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,eAAe,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAMxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnF;AAQD,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA2ChF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwC5E;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;;OAIG;IACH,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAkBhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAkBvC"}

package/dist/core/hooks/adapter/wiring.js

@@ -136,6 +136,38 @@ export function loadAdapterWiring(projectRoot) {
     }
     return out;
 }
+/**
+ * Classify every known adapter as wired or unwired, without judging whether an
+ * unwired one is a problem.
+ *
+ * `loadAdapterWiring` stays deliberately silent about an adapter with zero
+ * harnery hooks, because a bare settings file is not an opt-out signal and
+ * nagging about it would false-warn every session. That silence is right in
+ * isolation and wrong once you also know the adapter's CLI is installed: then
+ * an agent can start a session here and register nothing. Splitting the fact
+ * from the judgement lets a caller holding both (doctor) tell "not used here"
+ * from "never wired" without changing what counts as drift.
+ */
+export function summarizeAdapterWiring(projectRoot) {
+    const wired = [];
+    const unwired = [];
+    for (const [id, spec] of Object.entries(ADAPTER_SPECS)) {
+        const settingsPath = resolve(projectRoot, spec.settingsFile);
+        if (!existsSync(settingsPath)) {
+            unwired.push(id);
+            continue;
+        }
+        let settings;
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        }
+        catch {
+            continue; // unparseable → already surfaced by loadAdapterWiring
+        }
+        (diffWiring(settings, spec).present.length > 0 ? wired : unwired).push(id);
+    }
+    return { wired, unwired };
+}
 /**
  * Resolve the harnery package version for context in nudges/checks. Walks up
  * from this module to the package root (works under Bun from `src/` and Node

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

@@ -1,6 +1,5 @@
 /**
- * `agent-hook` CLI entry point. Phase 2: real canonical-event emission
- * alongside the legacy stream.
+ * `agent-hook` CLI entry point for canonical event emission.
  *
  * Flow:
  *   1. Parse argv → event-name + adapter.

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/core/hooks/cli.js

@@ -1,6 +1,5 @@
 /**
- * `agent-hook` CLI entry point. Phase 2: real canonical-event emission
- * alongside the legacy stream.
+ * `agent-hook` CLI entry point for canonical event emission.
  *
  * Flow:
  *   1. Parse argv → event-name + adapter.
@@ -21,17 +20,22 @@ import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.js";
+import { buildInstructionBundle } from "../../lib/instructions/bundle.js";
 import { replayCodexJsonl } from "../agents/codex-replay.js";
 import { coordBinPath } from "../agents/coord-bin.js";
 import { consumeSince, writeCursor } from "../agents/events/consume.js";
+import { classifyWriteClaimFinalization, formatWriteClaimFinalizationDenial, } from "../agents/finalization.js";
 import { evaluateStopHook } from "../agents/rules/stop-hook.js";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.js";
+import { stampSessionStateEvent } from "../agents/state/heartbeat-writer.js";
 import { writePidmapRow } from "../agents/state/pidmap.js";
 import { shellMutationPaths } from "../agents/state/shell-mutation.js";
+import { agentsRequireGitFinalization, resolveBinName } from "../config.js";
 import { checkpointContext, completeContextRecovery, extractContextSample, markContextCompactionCompleted, prepareContextRecovery, readContextState, recordContextSample, } from "../context/index.js";
 import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.js";
 import { detectAdapter } from "./adapter/detect.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./adapter/parse.js";
+import { codexWslFileLinkTelemetry, inspectCodexWslBridge, isWslUncPath, renderCodexWslFileLinkContext, } from "./codex-wsl-bridge.js";
 import { captureImages, detectPresence, imageJanitor, journalArchive, journalJanitor, journalRecoveryCue, playSound, resetSoundCounters, runSessionSyncExtension, runTurnSummary, soundForEvent, } from "./effects/index.js";
 import { emit } from "./events/emit.js";
 import { canonicalize } from "./guard-path.js";
@@ -39,16 +43,18 @@ import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/
 import { findCoordRoot } from "./resolve/coord-root.js";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
-import { scanStatusBoxPresent, scanTranscriptModel } from "./resolve/transcript.js";
+import { detectForkParent, scanAssistantTextIncludes, scanStatusBoxPresent, scanTranscriptModel, } from "./resolve/transcript.js";
+import { sessionNamePresence } from "./session-name-presence.js";
+import { unsafeCrossShellReason } from "./unsafe-cross-shell.js";
 function parseArgv(argv) {
     const out = { eventName: null, extra: [] };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg === "--adapter" || arg === "--harness") {
+        if (arg === "--adapter") {
             i++; // detectAdapter will re-parse; just consume the value here.
             continue;
         }
-        if (arg.startsWith("--adapter=") || arg.startsWith("--harness="))
+        if (arg.startsWith("--adapter="))
             continue;
         if (!out.eventName && !arg.startsWith("--")) {
             out.eventName = arg;
@@ -118,12 +124,15 @@ function logError(coordRoot, err, context) {
  * Lives at agent-hooks side (not agent-coord) to keep emitter/consumer
  * separation: we spawn rather than import.
  */
-function assignNameViaAgentCoord(coordRoot, instanceId, kind) {
+function assignNameViaAgentCoord(coordRoot, instanceId, kind, forkedFrom) {
     const binary = coordBinPath("agent-coord", coordRoot) ?? "";
     if (!existsSync(binary))
         return null;
     try {
-        const result = spawnSync(binary, ["assign-name", instanceId, kind], {
+        const args = ["assign-name", instanceId, kind];
+        if (forkedFrom)
+            args.push("--forked-from", forkedFrom);
+        const result = spawnSync(binary, args, {
             encoding: "utf8",
             timeout: 2000,
             env: childEnv(coordRoot),
@@ -178,13 +187,21 @@ function buildEventData(eventType, ctx) {
     switch (eventType) {
         case "session.start": {
             const adapterPlatform = ctx.adapter === "claude-code"
-                ? "claude_code"
+                ? "claude-code"
                 : ctx.adapter === "cursor"
                     ? "cursor"
                     : "codex";
+            // Recorded fork lineage is NOT detected here. On claude-code a fork
+            // never fires its own session.start — SessionStart fires under the
+            // PARENT's session id (source=resume) before the fork id is minted
+            // (verified 2026-08-05) — so detection at this point can only mislabel
+            // the resumed parent. The fork's new instance is caught by the
+            // tool.pre_use heal path instead. The forkedFrom plumbing below stays
+            // for adapters that DO report a parent at session start.
+            const forkedFrom = undefined;
             // Assign (or recover) name + kind via agent-coord. Idempotent: resume
             // returns the original name; new owner consumes a counter slot.
-            const assigned = assignNameViaAgentCoord(ctx.coordRoot, ctx.instanceId, "session");
+            const assigned = assignNameViaAgentCoord(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
             // Write the adapter pid-map row so `harn agents whoami` ppid-walks find
             // this owner. Prefer the payload pid (the actual claude binary), then the
             // anchor walk (the `node` ancestor for Cursor, which has no payload pid),
@@ -195,6 +212,7 @@ function buildEventData(eventType, ctx) {
             if (adapterPid) {
                 writePidmapViaAgentCoord(ctx.coordRoot, adapterPid, ctx.instanceId, adapterPlatform);
             }
+            const bundle = safeInstructionBundle(ctx.coordRoot, p?.cwd ?? process.cwd(), ctx.adapter);
             return {
                 started_at: new Date().toISOString(),
                 cwd: p?.cwd ?? process.cwd(),
@@ -208,6 +226,18 @@ function buildEventData(eventType, ctx) {
                 name: assigned?.name,
                 kind: "session",
                 agent_id: ctx.instanceId,
+                ...(bundle
+                    ? {
+                        instruction_bundle_id: bundle.instruction_bundle_id,
+                        instruction_source_id: bundle.canonical_source_id,
+                        instruction_profile_root: bundle.profile_root,
+                        instruction_component_count: bundle.components.length,
+                    }
+                    : {}),
+                // Recorded fork lineage rides the canonical event too, so full replay
+                // and derived readers converge on the same parent linkage that
+                // .name-history carries (the ADR 0017 dual-write pattern).
+                ...(forkedFrom ? { forked_from: forkedFrom } : {}),
                 // Workflow-child linkage: `workflow run` children carry the run id in
                 // env (spawn adapters set it via buildChildEnv), so their sessions and
                 // heartbeats join back to the run transcript + /workflows web view.
@@ -235,6 +265,10 @@ function buildEventData(eventType, ctx) {
             return { prompt_text: value, ...(truncated ? { truncated: true } : {}) };
         }
         case "turn.stop": {
+            const lastAssistantMessage = p?.raw.last_assistant_message ?? "";
+            const fileLinkTelemetry = ctx.adapter === "codex"
+                ? codexWslFileLinkTelemetry(ctx.coordRoot, p?.cwd, lastAssistantMessage)
+                : null;
             return {
                 // Backfill the model for adapters that omit it at session.start
                 // (Claude Code). The transcript is populated with assistant turns by
@@ -252,8 +286,24 @@ function buildEventData(eventType, ctx) {
                 // text-only stop (box in last_assistant_message, no transcript), which
                 // the verdict now sees because agent-hook emits this turn.stop itself
                 // (the previous path passed those via the no-history fail-open).
-                status_box_present: scanStatusBoxPresent(p?.transcript_path) ||
-                    (p?.raw.last_assistant_message ?? "").includes("┌─ agent-"),
+                status_box_present: scanStatusBoxPresent(p?.transcript_path) || lastAssistantMessage.includes("┌─ agent-"),
+                // Shadow measurement for the rule-2/3 detector: the loose scan above
+                // matches the box prefix ANYWHERE in the transcript tail, including
+                // the tool_result row the status command itself writes, so it can
+                // report a paste that never happened. The strict variant counts
+                // assistant text only (same window, same scanner as the session-name
+                // detection). Telemetry-only: the Stop verdict still reads
+                // status_box_present. Once the divergence rate between the two fields
+                // is known, the gate either flips to strict or the rule gets
+                // reconsidered; either way this field decides it with data.
+                status_box_present_strict: scanAssistantTextIncludes(p?.transcript_path, "┌─ agent-") ||
+                    lastAssistantMessage.includes("┌─ agent-"),
+                // Whether the session's suggested name is satisfied as of this turn,
+                // and which name that refers to. Reported on every stop while a name
+                // exists (the stop-hook.session_name verdict reads it per turn); the
+                // transcript scan itself stops once the name has been sighted.
+                ...sessionNamePresence(ctx.coordRoot, ctx.instanceId, lastAssistantMessage, (name) => scanAssistantTextIncludes(p?.transcript_path, name)),
+                ...(fileLinkTelemetry ?? {}),
                 stop_hook_active: p?.stop_hook_active,
             };
         }
@@ -301,6 +351,15 @@ function buildEventData(eventType, ctx) {
                 ...(clamped.truncated ? { truncated: true } : {}),
             };
         }
+        case "interaction.input_requested": {
+            const description = extractToolDescription(p?.tool_input);
+            const reason = description ? clampString(description, 500).value : undefined;
+            return {
+                request_kind: "permission",
+                tool_name: p?.tool_name,
+                ...(reason ? { reason } : {}),
+            };
+        }
         case "tool.post_use": {
             const toolName = p?.tool_name ?? "unknown";
             const summary = summarizeOutput(p?.tool_response);
@@ -347,6 +406,15 @@ function buildEventData(eventType, ctx) {
         }
     }
 }
+function safeInstructionBundle(coordRoot, cwd, adapter) {
+    try {
+        return buildInstructionBundle({ coordRoot, cwd, adapter });
+    }
+    catch (err) {
+        logError(coordRoot, err, { phase: "instruction-bundle-identity" });
+        return null;
+    }
+}
 function objectRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value)
         ? value
@@ -449,6 +517,19 @@ async function main() {
         owner_source: owner.source,
         event_id: envelope.event_id,
     });
+    // Activity is only useful while it is current. Stamp prompt and permission
+    // evidence directly from this envelope rather than draining the global
+    // projector: a drain here could apply a tool event before its authorization
+    // verdict. Tool progress is stamped later, after the guard allows it.
+    if (norm.event_type === "user_prompt.submit" ||
+        norm.event_type === "interaction.input_requested") {
+        try {
+            stampSessionStateEvent(coordRoot, owner.instance_id, envelope);
+        }
+        catch (err) {
+            logError(coordRoot, err, { phase: "activity-projection" });
+        }
+    }
     // Context telemetry is opportunistic and truthful: only persist a sample
     // when the adapter payload actually exposes usage/window data. Identical
     // measurements are de-duplicated before they reach the canonical stream.
@@ -694,7 +775,7 @@ async function main() {
             }
         }
         try {
-            const injected = await emitUserPromptSubmitSystemMessage(coordRoot, owner.instance_id, sessionId, adapter, recovery?.briefing ?? "");
+            const injected = await emitUserPromptSubmitSystemMessage(coordRoot, owner.instance_id, sessionId, adapter, payload?.cwd, recovery?.briefing ?? "");
             if (injected && recovery) {
                 completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, adapter, recovery, "UserPromptSubmit");
             }
@@ -772,13 +853,30 @@ async function main() {
             bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
             workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
         });
+        const enforcementMode = stopEnforcementMode(verdict.rule);
+        emit(coordRoot, {
+            event_type: "stop.verdict",
+            instance_id: owner.instance_id,
+            session_id: sessionId,
+            turn_id: payload?.turn_id,
+            parent_turn_id: payload?.parent_turn_id,
+            adapter,
+            data: {
+                allow: verdict.allow,
+                rule: verdict.rule,
+                ...(verdict.reason ? { reason: verdict.reason } : {}),
+                enforcement_mode: enforcementMode,
+                eligible: enforcementMode === "enforced",
+                nag_delivered: enforcementMode === "enforced" && !verdict.allow,
+            },
+        });
         if (!verdict.allow) {
             // Adapter-aware enforcement channel: Claude Code / Codex honor exit-2 +
             // stderr as a turn block; Cursor ignores exit codes (fail-open) and
             // re-prompts only via a `followup_message` it auto-submits. emitStopBlock
             // writes the right shape and returns the exit code to use.
             const { emitStopBlock } = await import("./adapter/output.js");
-            return emitStopBlock(adapter, verdict);
+            return emitStopBlock(adapter, verdict, coordRoot);
         }
     }
     // Phase 7: PreToolUse: heartbeat + pid-map self-heal on every tool call.
@@ -792,7 +890,19 @@ async function main() {
     // call was restored here afterward.
     if (norm.event_type === "tool.pre_use") {
         try {
-            healHeartbeatViaCli(coordRoot, owner.instance_id, sessionId, adapter);
+            // Recorded fork lineage, heal-path flavor. A forked CC conversation
+            // never fires its own session.start (SessionStart fires under the
+            // PARENT's session id with source=resume, before the fork id is
+            // minted; verified 2026-08-05), so the fork's new instance first
+            // materializes right here. Gate detection on "no heartbeat yet" so the
+            // transcript scan runs once per instance lifetime, not per tool call.
+            let forkedFrom;
+            if (adapter === "claude-code" &&
+                payload?.transcript_path &&
+                !existsSync(join(coordRoot, ".harnery", "active", `${owner.instance_id}.json`))) {
+                forkedFrom = detectForkParent(payload.transcript_path, owner.instance_id);
+            }
+            healHeartbeatViaCli(coordRoot, owner.instance_id, sessionId, adapter, forkedFrom);
             refreshPidmap(coordRoot, owner.instance_id, adapter, payload?.pid);
         }
         catch (err) {
@@ -813,6 +923,28 @@ async function main() {
         catch (err) {
             logError(coordRoot, err, { phase: "pre-tool-use-image-capture" });
         }
+        // Windows-native Codex + WSL UNC only: block the one cross-shell shape
+        // proven to corrupt argument boundaries. Normal WSL argv calls, literal
+        // bash -s scripts, native Linux/macOS sessions, and every other adapter
+        // pass through. The host instructions name its concrete safe bridge.
+        const unsafeShellReason = unsafeCrossShellReason({
+            adapter,
+            cwd: payload?.cwd,
+            toolName: payload?.tool_name,
+            toolInput: payload?.tool_input,
+        });
+        if (unsafeShellReason) {
+            emit(coordRoot, {
+                event_type: "decision.block",
+                instance_id: owner.instance_id,
+                session_id: sessionId,
+                adapter,
+                data: { rule: "unsafe_cross_shell", reason: unsafeShellReason },
+            });
+            const { emitDeny } = await import("./adapter/output.js");
+            emitDeny(adapter, unsafeShellReason);
+            return 0;
+        }
         // G-guard for ALL adapters. Claude Code previously ran this via a
         // pre-tool-use bash adapter (which called `agent-coord verdict --rule=claim`);
         // that adapter is now deleted, so agent-hook owns the deny for every adapter.
@@ -821,12 +953,21 @@ async function main() {
         // apply_patch (codex) parses paths from the patch body and runs verdict
         // per-path; Edit/Write/NotebookEdit resolve a single target. Non-write tools
         // (incl. Agent) yield no targets and pass through with no deny.
+        let guardAllowed = true;
         try {
-            await runPreToolUseGuard(coordRoot, owner.instance_id, sessionId, data, adapter);
+            guardAllowed = await runPreToolUseGuard(coordRoot, owner.instance_id, sessionId, data, adapter);
         }
         catch (err) {
             logError(coordRoot, err, { phase: "pre-tool-use-guard" });
         }
+        if (guardAllowed) {
+            try {
+                stampSessionStateEvent(coordRoot, owner.instance_id, envelope);
+            }
+            catch (err) {
+                logError(coordRoot, err, { phase: "activity-projection" });
+            }
+        }
         // Shell-mutation warn (warn-only, never blocks). Was the cursor
         // beforeShellExecution + codex preToolUse-Bash shell-mutation-claim-log in
         // the per-adapter shell adapters. Cursor sends the command at payload.command;
@@ -901,16 +1042,52 @@ async function main() {
     }
     return 0;
 }
+function stopEnforcementMode(rule) {
+    if (rule === "stop-hook.codex_observe_only")
+        return "observe_only";
+    if (rule === "stop-hook.fail_open" || rule === "stop-hook.no_history")
+        return "fail_open";
+    if (rule === "stop-hook.bypass" || rule === "stop-hook.workflow_child")
+        return "exempt";
+    return "enforced";
+}
 async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, adapter) {
     const toolName = data.tool_name ?? "";
-    const targets = collectGuardTargets(toolName, data)
-        .map((p) => canonicalize(coordRoot, p))
-        .filter((p) => p !== null);
+    const rawTargets = collectGuardTargets(toolName, data);
+    if (rawTargets.length === 0)
+        return true;
+    let targets;
+    if (agentsRequireGitFinalization(coordRoot)) {
+        const decisions = rawTargets.map((path) => classifyWriteClaimFinalization(coordRoot, path));
+        const denied = decisions.find((decision) => !decision.allow);
+        if (denied && !denied.allow) {
+            const { emitDeny } = await import("./adapter/output.js");
+            emitDeny(adapter, formatWriteClaimFinalizationDenial(denied, resolveBinName(coordRoot)));
+            return false;
+        }
+        const allowed = decisions.filter((decision) => decision.allow);
+        targets = allowed.map((decision) => ({
+            path: decision.path,
+            finalization: decision.descriptor,
+        }));
+    }
+    else {
+        targets = rawTargets
+            .map((path) => canonicalize(coordRoot, path))
+            .filter((path) => path !== null)
+            .map((path) => ({ path }));
+    }
     if (targets.length === 0)
-        return;
+        return true;
     const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
-    if (!existsSync(agentCoordBin))
-        return;
+    if (!existsSync(agentCoordBin)) {
+        if (agentsRequireGitFinalization(coordRoot)) {
+            const { emitDeny } = await import("./adapter/output.js");
+            emitDeny(adapter, "Harnery denied the write before mutation because the claim coordinator is unavailable; repair the project's Harnery installation and retry.");
+            return false;
+        }
+        return true;
+    }
     // For apply_patch (multi-file), collect siblings so the deny reason names
     // them. For single-file tools the array has one entry.
     for (const target of targets) {
@@ -918,7 +1095,7 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, adapte
             rule: "claim",
             instance_id: instanceId,
             session_id: sessionId,
-            path: target,
+            path: target.path,
         });
         const result = spawnSync(agentCoordBin, ["verdict"], {
             input: verdictReq,
@@ -936,10 +1113,11 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, adapte
             continue;
         }
         if (parsed.allow === false) {
-            let reason = parsed.reason ?? `Path ${target} is currently being edited by another agent.`;
+            let reason = parsed.reason ?? `Path ${target.path} is currently being edited by another agent.`;
             if (targets.length > 1) {
                 const siblings = targets
-                    .filter((p) => p !== target)
+                    .filter((candidate) => candidate !== target)
+                    .map((candidate) => candidate.path)
                     .slice(0, 3)
                     .join(", ");
                 if (siblings) {
@@ -948,9 +1126,27 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, adapte
             }
             const { emitDeny } = await import("./adapter/output.js");
             emitDeny(adapter, reason);
-            return;
-        }
+            return false;
+        }
+        // The verdict mutates the live heartbeat immediately, but that file is a
+        // projection and can be rebuilt at any later hook. Persist the acquisition
+        // in the canonical stream too. This matters most for Codex apply_patch:
+        // one tool call can claim several files, and tool.pre_use's clamped payload
+        // is not a durable ownership representation for those targets.
+        emit(coordRoot, {
+            event_type: "claim.acquire",
+            instance_id: instanceId,
+            session_id: sessionId,
+            adapter,
+            source: "agent-hooks",
+            data: {
+                path: target.path,
+                mode: "write",
+                ...(target.finalization ? { finalization: target.finalization } : {}),
+            },
+        });
     }
+    return true;
 }
 /** Canonicalize a path to monorepo-relative form. Absolute paths under
  * coordRoot get the prefix stripped; relative paths pass through (assumed
@@ -1008,15 +1204,19 @@ function parseApplyPatchPaths(data) {
     }
     return out;
 }
-function healHeartbeatViaCli(coordRoot, instanceId, sessionId, adapter) {
+function healHeartbeatViaCli(coordRoot, instanceId, sessionId, adapter, forkedFrom) {
     const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     if (!existsSync(agentCoordBin))
         return;
     // Pass the detected adapter so a pruned Cursor/Codex heartbeat is recreated
     // with the correct platform; without it, healHeartbeat defaults to
-    // claude_code and the dashboard mislabels the agent. See
-    // heartbeat-writer.healHeartbeat.
-    spawnSync(agentCoordBin, ["heal-heartbeat", instanceId, sessionId, `--adapter=${adapter}`], {
+    // claude-code and the dashboard mislabels the agent. See
+    // heartbeat-writer.healHeartbeat. --forked-from carries detected fork
+    // lineage for an instance that never session.started (the CC fork flow).
+    const args = ["heal-heartbeat", instanceId, sessionId, `--adapter=${adapter}`];
+    if (forkedFrom)
+        args.push(`--forked-from=${forkedFrom}`);
+    spawnSync(agentCoordBin, args, {
         encoding: "utf8",
         timeout: 2000,
         env: childEnv(coordRoot),
@@ -1238,7 +1438,7 @@ function cleanupSessionEnd(coordRoot, instanceId, reason) {
         spawnSync(agentCoordBin, ["log", `SESSION_END     reason=${reason}`, "--instance", instanceId], { encoding: "utf8", timeout: 2000 });
     }
 }
-async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, adapter, recoveryBriefing = "") {
+async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, adapter, workspaceCwd, recoveryBriefing = "") {
     const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
     let additionalContext = "";
     if (existsSync(agentCoordBin)) {
@@ -1263,15 +1463,26 @@ async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionI
         // staleness nudges; Claude Code enforces those via its Stop transcript.
         // Codex gets a fresh status-footer reminder on every prompt. Its Stop hook
         // stays observe-only, so missing the footer never replaces the answer.
+        // Claude Code + Cursor (the Stop-ENFORCING adapters) get a fresh per-turn
+        // ritual reminder: satisfying the contract up front is far cheaper than
+        // the bounce-and-retry the Stop hook otherwise forces.
         args.push("--session-name-nudge");
         if (adapter === "cursor" || adapter === "codex")
             args.push("--task-nudge");
         if (adapter === "codex")
             args.push("--status-footer-nudge");
+        if (adapter === "claude-code" || adapter === "cursor")
+            args.push("--turn-ritual-nudge", adapter);
         const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
         if (result.status === 0 && result.stdout)
             additionalContext = result.stdout.trim();
     }
+    if (adapter === "codex") {
+        const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, workspaceCwd);
+        if (fileLinkContext) {
+            additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
+        }
+    }
     if (recoveryBriefing) {
         additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
     }
@@ -1310,7 +1521,7 @@ function emitSubagentStartContext(coordRoot, instanceId, sessionId, data, adapte
 }
 function adapterPlatform(adapter) {
     if (adapter === "claude-code")
-        return "claude_code";
+        return "claude-code";
     return adapter;
 }
 async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, emittedData, adapter, recoveryBriefing = "") {
@@ -1359,6 +1570,21 @@ async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, e
     if (recoveryBriefing) {
         additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
     }
+    if (adapter === "codex" && isWslUncPath(emittedData.cwd)) {
+        const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, emittedData.cwd);
+        if (fileLinkContext) {
+            additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
+        }
+        const bridge = inspectCodexWslBridge(process.env, { expected: true });
+        if (bridge && !bridge.ok) {
+            additionalContext = [
+                additionalContext,
+                `Harnery hybrid warning: ${bridge.detail}. Run \`${resolveBinName(coordRoot)} doctor\` for the repair hint.`,
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+        }
+    }
     if (!additionalContext)
         return false;
     const { emitContext } = await import("./adapter/output.js");

package/dist/core/hooks/codex-authorization.d.ts

@@ -0,0 +1,30 @@
+export type CodexHookTrustStatus = "managed" | "trusted" | "untrusted" | "modified";
+export type CodexHookAuthorizationStatus = "runnable" | "review_required" | "disabled" | "not_wired" | "error";
+export interface CodexHookAuthorizationResult {
+    status: CodexHookAuthorizationStatus;
+    detail: string;
+    hookCount: number;
+    disabledCount: number;
+    trustCounts: Partial<Record<CodexHookTrustStatus, number>>;
+}
+export interface CodexHookAuthorizationProbeOptions {
+    cwd: string;
+    codexBin?: string;
+    appServerArgs?: string[];
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+/**
+ * Convert Codex app-server's `hooks/list` response into the one authorization
+ * state doctor needs. This is intentionally read-only: hashes are observed but
+ * never persisted, and only commands containing Harnery's `agent-hook` binary
+ * are included in the result.
+ */
+export declare function assessCodexHookList(response: unknown, cwd: string): CodexHookAuthorizationResult;
+/**
+ * Ask the active Codex CLI for hook authorization through its app-server
+ * protocol. The child is closed as soon as `hooks/list` responds. Harnery never
+ * calls the trust-write method and never reads Codex's private config format.
+ */
+export declare function probeCodexHookAuthorization(options: CodexHookAuthorizationProbeOptions): Promise<CodexHookAuthorizationResult>;
+//# sourceMappingURL=codex-authorization.d.ts.map

package/dist/core/hooks/codex-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-authorization.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/codex-authorization.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAEpF,MAAM,MAAM,4BAA4B,GACpC,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,WAAW,GACX,OAAO,CAAC;AAEZ,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,4BAA4B,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,kCAAkC;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,4BAA4B,CAqGhG;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,CAoFvC"}