harnery 0.32.0 → 0.33.0

package/src/core/agents/render/session-context.ts

@@ -14,6 +14,7 @@ import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
 import { readForkParent } from "../state/names.ts";
+import type { AgentActivity, TaskState } from "../state/session-state.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -27,6 +28,9 @@ interface HeartbeatRow {
   files_touched?: string[];
   platform?: string;
   task?: string;
+  activity?: AgentActivity;
+  task_state?: TaskState;
+  task_state_reason?: string;
   turn_summary?: string;
 }
 
@@ -135,8 +139,12 @@ function formatRemoteMachines(coordRoot: string): string {
         const files = a.files_touched?.length
           ? `holds: ${a.files_touched.slice(0, 3).join(", ")}${a.files_touched.length > 3 ? `, +${a.files_touched.length - 3} more` : ""}`
           : "nothing held";
+        const reason =
+          a.task_state === "blocked" && a.task_state_reason
+            ? `: ${a.task_state_reason.slice(0, 80)}`
+            : "";
         lines.push(
-          `  - agent-${a.name ?? a.instance_id.slice(0, 8)} @${m.machine}${task} (${files})`,
+          `  - agent-${a.name ?? a.instance_id.slice(0, 8)} @${m.machine}${task} (activity=${a.activity}, lifecycle=${a.task_state}${reason}, ${files})`,
         );
       }
     }
@@ -230,11 +238,15 @@ function renderSubtable(
 
 function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number): string {
   const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
+  const activity = r.activity ?? "unknown";
+  const lifecycle = r.task_state ?? "active";
+  const reason =
+    lifecycle === "blocked" && r.task_state_reason ? `: ${r.task_state_reason.slice(0, 80)}` : "";
   const ageFrom = fmtAge(nowSec - parseIsoSec(r.started_at));
   const filesPart = fmtFiles(r.display_files);
   const lastActivity = fmtLastActivity(r, nowSec);
   const turnSummary = r.turn_summary ? `\n    last turn: ${r.turn_summary.slice(0, 80)}` : "";
-  return `  - agent-${r.name ?? "unknown"}${taskPart}   (${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
+  return `  - agent-${r.name ?? "unknown"}${taskPart}   (activity=${activity}, lifecycle=${lifecycle}${reason}, ${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
 }
 
 function fmtFiles(files: string[]): string {

package/src/core/agents/rules/stop-hook.ts

@@ -308,14 +308,14 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
   // `session_name_present` (assistant-text-only transcript scan), mirroring
   // how rule 2/3 rides `status_box_present`.
   if (ackSignal === "status_box_present") {
-    const namingTaskSet = inTurn.find(
+    const namingEvent = inTurn.find(
       (e) =>
-        e.event_type === "state.task_set" &&
-        e.data.first_of_session === true &&
+        ((e.event_type === "state.task_set" && e.data.first_of_session === true) ||
+          (e.event_type === "state.task_state" && e.data.name_reminted === true)) &&
         typeof e.data.suggested_session_name === "string" &&
         e.data.suggested_session_name.length > 0,
     );
-    if (namingTaskSet) {
+    if (namingEvent) {
       // ANY in-window turn.stop with the flag satisfies the rule, not just the
       // latest: once seen, `session_name_seen_at` is stamped and later
       // turn.stops OMIT the field, so a later block on a different rule (whose
@@ -324,7 +324,7 @@ export function evaluateStopHook(coordRoot: string, req: StopHookRequest): Verdi
         (e) => e.event_type === "turn.stop" && e.data.session_name_present === true,
       );
       if (!namePresent) {
-        return sessionNameBlock(String(namingTaskSet.data.suggested_session_name));
+        return sessionNameBlock(String(namingEvent.data.suggested_session_name));
       }
     }
   }

package/src/core/agents/state/heartbeat-projector.ts

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { CanonicalEvent } from "../events/consume.ts";
+import { type AgentActivity, applySessionStateEvent, type TaskState } from "./session-state.ts";
 
 export interface V2Heartbeat {
   instance_id: string;
@@ -21,6 +22,10 @@ export interface V2Heartbeat {
   name?: string;
   kind?: "session" | "subagent" | "transient";
   model?: string;
+  instruction_bundle_id?: string;
+  instruction_source_id?: string;
+  instruction_profile_root?: string;
+  instruction_component_count?: number;
   platform?: string;
   subagent_call_id?: string;
   parent_session_id?: string;
@@ -34,6 +39,12 @@ export interface V2Heartbeat {
   last_tool_at?: string;
   task?: string;
   task_updated_at?: string;
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
   suggested_session_name?: string;
   session_name_seen_at?: string;
   session_name_seen_for?: string;
@@ -180,6 +191,14 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
   hb.v2_meta.last_projected = new Date().toISOString();
   if (ev.turn_id) hb.last_turn_id = ev.turn_id;
 
+  const sessionState = applySessionStateEvent(hb, ev);
+  hb.activity = sessionState.activity;
+  hb.activity_updated_at = sessionState.activity_updated_at;
+  hb.activity_source = sessionState.activity_source;
+  hb.task_state = sessionState.task_state;
+  hb.task_state_updated_at = sessionState.task_state_updated_at;
+  hb.task_state_reason = sessionState.task_state_reason;
+
   const d = ev.data;
   switch (ev.event_type) {
     case "session.start":
@@ -188,6 +207,16 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       {
         const model = pickStr(d, "model");
         if (model) hb.model = model;
+        const instructionBundleId = pickStr(d, "instruction_bundle_id");
+        if (instructionBundleId) hb.instruction_bundle_id = instructionBundleId;
+        const instructionSourceId = pickStr(d, "instruction_source_id");
+        if (instructionSourceId) hb.instruction_source_id = instructionSourceId;
+        const instructionProfileRoot = pickStr(d, "instruction_profile_root");
+        if (instructionProfileRoot) hb.instruction_profile_root = instructionProfileRoot;
+        const instructionComponentCount = pickNum(d, "instruction_component_count");
+        if (instructionComponentCount !== undefined) {
+          hb.instruction_component_count = instructionComponentCount;
+        }
         const platform = pickStr(d, "platform") ?? adapterToPlatform(ev.adapter);
         hb.platform = platform;
         const name = pickStr(d, "name");
@@ -324,6 +353,21 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       break;
     }
 
+    case "state.task_state": {
+      const suggested = pickStr(d, "suggested_session_name");
+      if (suggested && suggested !== hb.suggested_session_name) {
+        // Older heartbeats predate session_name_seen_for. A lifecycle re-mint
+        // still needs a mismatch the prompt and Stop paths can enforce, so
+        // attribute the prior title before replacing it. Ordinary legacy
+        // heartbeats remain quiet until a real lifecycle event changes them.
+        if (!hb.session_name_seen_for && hb.suggested_session_name) {
+          hb.session_name_seen_for = hb.suggested_session_name;
+        }
+        hb.suggested_session_name = suggested;
+      }
+      break;
+    }
+
     case "state.status_checked":
       hb.last_status_at = ev.ts;
       break;
@@ -513,6 +557,10 @@ function writeHeartbeat(coordRoot: string, instanceId: string, hb: V2Heartbeat):
     setIfDefined(merged, "workflow_run_id", hb.workflow_run_id);
     setIfDefined(merged, "workflow_agent_id", hb.workflow_agent_id);
     setIfDefined(merged, "model", hb.model);
+    setIfDefined(merged, "instruction_bundle_id", hb.instruction_bundle_id);
+    setIfDefined(merged, "instruction_source_id", hb.instruction_source_id);
+    setIfDefined(merged, "instruction_profile_root", hb.instruction_profile_root);
+    setIfDefined(merged, "instruction_component_count", hb.instruction_component_count);
     setIfDefined(merged, "platform", hb.platform);
     setIfDefined(merged, "started_at", hb.started_at);
     // files_touched is a required-array invariant for every reader
@@ -526,6 +574,16 @@ function writeHeartbeat(coordRoot: string, instanceId: string, hb: V2Heartbeat):
     setIfDefined(merged, "last_tool_at", hb.last_tool_at);
     setIfDefined(merged, "task", hb.task);
     setIfDefined(merged, "task_updated_at", hb.task_updated_at);
+    setIfDefined(merged, "activity", hb.activity);
+    setIfDefined(merged, "activity_updated_at", hb.activity_updated_at);
+    setIfDefined(merged, "activity_source", hb.activity_source);
+    setIfDefined(merged, "task_state", hb.task_state);
+    setIfDefined(merged, "task_state_updated_at", hb.task_state_updated_at);
+    if (hb.task_state_reason) {
+      merged.task_state_reason = hb.task_state_reason;
+    } else if (hb.task_state) {
+      delete merged.task_state_reason;
+    }
     setIfDefined(merged, "suggested_session_name", hb.suggested_session_name);
     setIfDefined(merged, "session_name_seen_at", hb.session_name_seen_at);
     if (hb.session_name_seen_for) {
@@ -580,3 +638,8 @@ function pickBool(o: Record<string, unknown>, k: string): boolean | undefined {
   const v = o[k];
   return typeof v === "boolean" ? v : undefined;
 }
+
+function pickNum(o: Record<string, unknown>, k: string): number | undefined {
+  const v = o[k];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}

package/src/core/agents/state/heartbeat-writer.ts

@@ -24,6 +24,12 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { emit } from "../events/emit.ts";
+import {
+  type AgentActivity,
+  applySessionStateEvent,
+  type SessionStateEvidenceEvent,
+  type TaskState,
+} from "./session-state.ts";
 
 /** Inline adapter normalizer (mirrors canonical-emit.normalizeAdapter), kept
  * local so the writer's only cross-module dep is the in-process emit(). */
@@ -86,6 +92,12 @@ export interface Heartbeat {
   files_touched: string[];
   task?: string;
   task_updated_at?: string | null;
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
   /** Session name built on the first non-empty set-task (never rebuilt). Its
    * presence is the "this session has been named" signal the prompt-context
    * nudge and the Stop-hook naming rule key on. */
@@ -134,6 +146,32 @@ export function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat
   }
 }
 
+/** Apply one evidence event to the live state fields without draining the
+ * global event stream. This keeps permission prompts current while avoiding
+ * unrelated projector side effects before a tool authorization verdict. */
+export function stampSessionStateEvent(
+  coordRoot: string,
+  instanceId: string,
+  event: Omit<SessionStateEvidenceEvent, "data"> & { data: unknown },
+): Heartbeat | null {
+  return mutate(coordRoot, instanceId, (heartbeat) => {
+    const data =
+      typeof event.data === "object" && event.data !== null && !Array.isArray(event.data)
+        ? (event.data as Record<string, unknown>)
+        : {};
+    const state = applySessionStateEvent(heartbeat, { ...event, data });
+    return {
+      ...heartbeat,
+      activity: state.activity,
+      activity_updated_at: state.activity_updated_at,
+      activity_source: state.activity_source,
+      task_state: state.task_state,
+      task_state_updated_at: state.task_state_updated_at,
+      task_state_reason: state.task_state_reason,
+    };
+  });
+}
+
 function mutate(
   coordRoot: string,
   instanceId: string,
@@ -183,6 +221,19 @@ export function buildSuggestedName(
   return { suggestedName: `Agent ${name} - ${description}`, description };
 }
 
+/** Build the operator-facing title projected from an explicit task lifecycle. */
+export function buildLifecycleSuggestedName(
+  agentName: string,
+  task: string | undefined,
+  state: TaskState,
+): string | null {
+  const built = buildSuggestedName(agentName, task ? [task] : []);
+  if (!built) return null;
+  if (state === "blocked") return `[BLOCKED] - ${built.suggestedName}`;
+  if (state === "done") return `[DONE] - ${built.suggestedName}`;
+  return built.suggestedName;
+}
+
 /** Stamp the sighting once the suggested name has been observed in assistant
  * reply text; later turns skip the transcript scan. Records WHICH name was seen,
  * because the skip is only valid for that one: if a later set-task mints a

package/src/core/agents/state/session-state.ts

@@ -0,0 +1,131 @@
+/** What the agent is doing now. `unknown` is evidence-safe, not an error. */
+export type AgentActivity = "unknown" | "working" | "needs_input" | "idle";
+
+/** Whether the declared task remains open. Activity never changes this axis. */
+export type TaskState = "active" | "blocked" | "done";
+
+/** Raw fields stored in a live heartbeat and rebuilt from canonical events. */
+export interface SessionStateFields {
+  activity?: AgentActivity;
+  activity_updated_at?: string;
+  activity_source?: string;
+  task_state?: TaskState;
+  task_state_updated_at?: string;
+  task_state_reason?: string;
+}
+
+/** Reader-facing state with compatibility defaults applied. */
+export interface SessionState extends SessionStateFields {
+  activity: AgentActivity;
+  task_state: TaskState;
+}
+
+export interface SessionStateSelector {
+  instance_id?: string;
+  session_id?: string;
+}
+
+export interface SessionStateEvidenceEvent {
+  event_type: string;
+  ts: string;
+  data?: Record<string, unknown>;
+  instance_id?: string;
+  session_id?: string;
+}
+
+const TERMINAL_ACTIVITY_EVENTS = new Set(["session.end", "subagent.stop", "turn.stop"]);
+
+/**
+ * Apply one canonical event to the two independent state axes.
+ *
+ * The table is deliberately evidence-only. Output chunks, post-tool events,
+ * narration, coordination commands, and elapsed time cannot clear an observed
+ * input wait. A command start only counts as progress when the session was
+ * already inside an open turn (`working` or `needs_input`).
+ */
+export function applySessionStateEvent(
+  current: Readonly<SessionStateFields>,
+  event: SessionStateEvidenceEvent,
+): SessionStateFields {
+  const next: SessionStateFields = { ...current };
+
+  if (event.event_type === "session.start" || event.event_type === "subagent.start") {
+    setActivity(next, "idle", event);
+  } else if (event.event_type === "user_prompt.submit" || event.event_type === "tool.pre_use") {
+    setActivity(next, "working", event);
+  } else if (event.event_type === "interaction.input_requested") {
+    setActivity(next, "needs_input", event);
+  } else if (
+    event.event_type === "command.start" &&
+    (current.activity === "working" || current.activity === "needs_input")
+  ) {
+    setActivity(next, "working", event);
+  } else if (TERMINAL_ACTIVITY_EVENTS.has(event.event_type)) {
+    setActivity(next, "idle", event);
+  }
+
+  if (event.event_type === "state.task_state") {
+    const data = event.data ?? {};
+    const state = field(data, "state");
+    if (state === "active" || state === "blocked" || state === "done") {
+      next.task_state = state;
+      next.task_state_updated_at = event.ts;
+      const reason = field(data, "reason");
+      if (typeof reason === "string" && reason.length > 0) {
+        next.task_state_reason = reason;
+      } else {
+        delete next.task_state_reason;
+      }
+    }
+  }
+
+  return next;
+}
+
+/**
+ * Rebuild both axes from canonical events after a heartbeat has disappeared.
+ * Events may be the whole ledger or an already-filtered session slice.
+ */
+export function foldSessionState(
+  events: readonly SessionStateEvidenceEvent[],
+  selector: SessionStateSelector = {},
+): SessionState {
+  const ordered = events
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => matches(event, selector))
+    .sort((a, b) => timestamp(a.event) - timestamp(b.event) || a.index - b.index);
+
+  let fields: SessionStateFields = {};
+  for (const { event } of ordered) fields = applySessionStateEvent(fields, event);
+
+  return {
+    ...fields,
+    activity: fields.activity ?? "unknown",
+    task_state: fields.task_state ?? "active",
+  };
+}
+
+function setActivity(
+  target: SessionStateFields,
+  activity: AgentActivity,
+  event: SessionStateEvidenceEvent,
+): void {
+  target.activity = activity;
+  target.activity_updated_at = event.ts;
+  target.activity_source = event.event_type;
+}
+
+function matches(event: SessionStateEvidenceEvent, selector: SessionStateSelector): boolean {
+  if (selector.instance_id && event.instance_id !== selector.instance_id) return false;
+  if (selector.session_id && event.session_id !== selector.session_id) return false;
+  return true;
+}
+
+function timestamp(event: SessionStateEvidenceEvent): number {
+  const parsed = Date.parse(event.ts);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function field(data: Record<string, unknown>, key: string): unknown {
+  return data[key];
+}

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

@@ -87,6 +87,7 @@ export const CURSOR_EVENTS: HookEvent[] = [
 export const CODEX_EVENTS: HookEvent[] = [
   { settingsKey: "SessionStart", subcommand: "session-start" },
   { settingsKey: "PreToolUse", subcommand: "pre-tool-use" },
+  { settingsKey: "PermissionRequest", subcommand: "permission-request" },
   { settingsKey: "PostToolUse", subcommand: "post-tool-use" },
   { settingsKey: "UserPromptSubmit", subcommand: "user-prompt-submit" },
   { settingsKey: "SubagentStart", subcommand: "sub-agent-start" },

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

@@ -178,6 +178,8 @@ export function normalizeEventName(
     case "pre-tool-use":
     case "before-shell-execution":
       return { event_type: "tool.pre_use", intra_turn: true };
+    case "permission-request":
+      return { event_type: "interaction.input_requested", intra_turn: true };
     case "post-tool-use":
       return { event_type: "tool.post_use", intra_turn: true };
     case "post-tool-use-failure":
@@ -199,6 +201,7 @@ export type NormalizedEventType =
   | "subagent.start"
   | "subagent.stop"
   | "tool.pre_use"
+  | "interaction.input_requested"
   | "tool.post_use"
   | "tool.post_use_failure"
   | "context.compaction.started"

package/src/core/hooks/cli.ts

@@ -21,6 +21,7 @@ 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.ts";
+import { buildInstructionBundle } from "../../lib/instructions/bundle.ts";
 import { replayCodexJsonl } from "../agents/codex-replay.ts";
 import { coordBinPath } from "../agents/coord-bin.ts";
 import { consumeSince, writeCursor } from "../agents/events/consume.ts";
@@ -32,6 +33,7 @@ import {
 } from "../agents/finalization.ts";
 import { evaluateStopHook } from "../agents/rules/stop-hook.ts";
 import { projectHeartbeats } from "../agents/state/heartbeat-projector.ts";
+import { stampSessionStateEvent } from "../agents/state/heartbeat-writer.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
 import { shellMutationPaths } from "../agents/state/shell-mutation.ts";
 import { agentsRequireGitFinalization, resolveBinName } from "../config.ts";
@@ -290,6 +292,7 @@ function buildEventData(
       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(),
@@ -303,6 +306,14 @@ function buildEventData(
         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).
@@ -435,6 +446,16 @@ function buildEventData(
       };
     }
 
+    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);
@@ -488,6 +509,15 @@ function buildEventData(
   }
 }
 
+function safeInstructionBundle(coordRoot: string, cwd: string, adapter: Adapter) {
+  try {
+    return buildInstructionBundle({ coordRoot, cwd, adapter });
+  } catch (err) {
+    logError(coordRoot, err, { phase: "instruction-bundle-identity" });
+    return null;
+  }
+}
+
 function objectRecord(value: unknown): Record<string, unknown> | undefined {
   return typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -602,6 +632,21 @@ async function main(): Promise<number> {
     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.
@@ -955,6 +1000,23 @@ async function main(): Promise<number> {
       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
@@ -1042,12 +1104,27 @@ async function main(): Promise<number> {
     // 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;
@@ -1126,16 +1203,23 @@ async function main(): Promise<number> {
   return 0;
 }
 
+function stopEnforcementMode(rule: string): "enforced" | "observe_only" | "exempt" | "fail_open" {
+  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: string,
   instanceId: string,
   sessionId: string,
   data: Record<string, unknown>,
   adapter: Adapter,
-): Promise<void> {
+): Promise<boolean> {
   const toolName = (data.tool_name as string | undefined) ?? "";
   const rawTargets = collectGuardTargets(toolName, data);
-  if (rawTargets.length === 0) return;
+  if (rawTargets.length === 0) return true;
 
   let targets: Array<{ path: string; finalization?: ClaimFinalizationDescriptor }>;
   if (agentsRequireGitFinalization(coordRoot)) {
@@ -1144,7 +1228,7 @@ async function runPreToolUseGuard(
     if (denied && !denied.allow) {
       const { emitDeny } = await import("./adapter/output.ts");
       emitDeny(adapter, formatWriteClaimFinalizationDenial(denied, resolveBinName(coordRoot)));
-      return;
+      return false;
     }
     const allowed = decisions.filter(
       (decision): decision is Extract<ClaimFinalizationDecision, { allow: true }> => decision.allow,
@@ -1159,7 +1243,7 @@ async function runPreToolUseGuard(
       .filter((path): path is string => path !== null)
       .map((path) => ({ path }));
   }
-  if (targets.length === 0) return;
+  if (targets.length === 0) return true;
 
   const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
   if (!existsSync(agentCoordBin)) {
@@ -1169,8 +1253,9 @@ async function runPreToolUseGuard(
         adapter,
         "Harnery denied the write before mutation because the claim coordinator is unavailable; repair the project's Harnery installation and retry.",
       );
+      return false;
     }
-    return;
+    return true;
   }
 
   // For apply_patch (multi-file), collect siblings so the deny reason names
@@ -1210,7 +1295,7 @@ async function runPreToolUseGuard(
       }
       const { emitDeny } = await import("./adapter/output.ts");
       emitDeny(adapter, reason);
-      return;
+      return false;
     }
 
     // The verdict mutates the live heartbeat immediately, but that file is a
@@ -1231,6 +1316,7 @@ async function runPreToolUseGuard(
       },
     });
   }
+  return true;
 }
 
 /** Canonicalize a path to monorepo-relative form. Absolute paths under
@@ -1567,9 +1653,14 @@ async function emitUserPromptSubmitSystemMessage(
     // 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();
   }