@heretyc/subagent-mcp 2.7.1 → 2.8.0

package/dist/hooks/orchestration-codex.js

@@ -1,17 +1,13 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { classifyClaim, countJsonlType, readDirective, runHook, sessionKey, } from "../orchestration/hook-core.js";
+import { claimAndEmit, classifyClaim, countJsonlType, runHook, sessionKey, } from "../orchestration/hook-core.js";
 import * as marker from "../orchestration/marker.js";
 /**
  * Codex CLI hook entry. Branches on payload.hook_event_name:
- *   - 'SessionStart'     -> if active and not a subagent, emit FULL (covers the
- *                           turn-0 directive before the first UserPromptSubmit).
- *   - 'UserPromptSubmit' -> the normal %5 runHook cadence.
- *
- * NOTE: the Python prototype carried inline 'alternating/odd-turn' comments;
- * those were STALE. The operative cadence is every 5th relative turn (%5),
- * matching INSTALL.md. The stale alternating comments are intentionally NOT
- * reproduced here.
+ *   - 'SessionStart'     -> if active and not a subagent, emit FULL + the ON
+ *                           reminder block (covers the turn-0 directive before
+ *                           the first UserPromptSubmit).
+ *   - 'UserPromptSubmit' -> the normal per-prompt reminder cadence (runHook).
  *
  * Compiles to dist/hooks/orchestration-codex.js and is invoked as:
  *   node "<PLUGIN_ROOT>/dist/hooks/orchestration-codex.js"
@@ -56,13 +52,16 @@ export const codexAdapter = {
     // Count JSONL lines whose parsed object.type === 'turn_context'. Delegates to
     // the bounded counter (reads at most the trailing window so a huge/
     // attacker-supplied transcript can't stall the inline host turn). Unreadable
-    // -> 0 (fail-safe: emits FULL rather than silently suppressing).
+    // -> 0 (fail-safe: the claim baseline stamps at 0; cadence is counter-driven
+    // and unaffected). Read on claim turns only.
     currentTurn(transcriptPath) {
         return countJsonlType(transcriptPath, "turn_context");
     },
     fullDirectiveFile: "orchestration-codex.md",
     offTurnFile: "off-turn-reminder.md",
     carryoverDirectiveFile: "carryover-codex.md",
+    reminderOnFile: "reminder-on.md",
+    reminderOffFile: "reminder-off-codex.md",
 };
 /**
  * Codex dispatcher. SessionStart fires once before the first prompt; it covers
@@ -89,19 +88,11 @@ export function runCodexHook(payload, env, adapter = codexAdapter) {
             const turn = adapter.currentTurn(payload.transcript_path);
             const m = marker.readMarker(cwd);
             const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
-            // Claim/re-claim for this session and baseline at the current turn.
-            const firstCarryover = kind === "carryover" && !m.carryover_ack;
-            m.baseline_turn = turn;
-            m.owner_session = current ?? null;
-            if (kind === "carryover") {
-                m.provenance = "carried-over";
-                m.carryover_ack = true;
-            }
-            marker.writeMarker(cwd, m);
-            return firstCarryover
-                ? readDirective(env, adapter.carryoverDirectiveFile) +
-                    readDirective(env, adapter.fullDirectiveFile)
-                : readDirective(env, adapter.fullDirectiveFile);
+            // Claim/re-claim + emit via the SHARED claim path (one copy of the
+            // semantics — FULL + ON reminder, ack-latched CARRYOVER prepend, counter
+            // re-baseline). SessionStart claims even on SAME-SESSION (resume) so
+            // turn 0 is always covered.
+            return claimAndEmit(cwd, current, turn, m, kind, env, adapter);
         }
         // UserPromptSubmit (and any other event) -> normal cadence.
         return runHook(payload, env, adapter);

package/dist/orchestration/hook-core.js

@@ -3,6 +3,31 @@ import { closeSync, openSync, readFileSync, readSync, statSync, } from "node:fs"
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import * as marker from "./marker.js";
+import * as reminder from "./reminder.js";
+/**
+ * Provider-agnostic core of the UserPromptSubmit / SessionStart hook.
+ *
+ * The MCP tool only ever WRITES the marker. A SEPARATE hook process (one per
+ * turn) READS the marker here and decides what to inject. The hook now emits in
+ * BOTH marker states, on a per-prompt counter (reminder.ts): every
+ * REMINDER_PERIOD-th prompt injects the LONG mode-specific
+ * <ORCHESTRATION-REMINDER-INVARIANT> block, every prompt between injects the
+ * one-line pointer at it. Marker ON adds the claim machinery: the claim turn
+ * (fresh enable or carryover re-claim) emits the FULL directive plus the ON
+ * reminder block and re-baselines the counter. (Supersedes LOCKED DECISION 2's
+ * same-session rel%5 FULL re-emission — owner directive 2026-06-11: steady
+ * state is the leaner tagged reminder, FULL fires on claim turns only.) The
+ * marker PERSISTS across sessions/restarts, so the first turn of a new session
+ * that inherits an already-ON marker emits a CARRYOVER notice (prepended to
+ * FULL) once per project marker, ack-latched in marker state, and re-claims
+ * for that session.
+ *
+ * The entire run is wrapped in try/catch: on ANY error we emit nothing. A hook
+ * must never crash or stall the host turn. "Emit" means RETURN the string; the
+ * entry shim is what writes it to process.stdout.
+ */
+/** Long-reminder cadence: every Nth counted prompt is a LONG turn. */
+export const REMINDER_PERIOD = 5;
 /**
  * Resolve the repo-root `directives/` dir at runtime. Honors an explicit plugin
  * root (Claude sets CLAUDE_PLUGIN_ROOT; a generic PLUGIN_ROOT is also accepted)
@@ -147,20 +172,60 @@ export function classifyClaim(owner_session, baseline_turn, current) {
     }
     return "same";
 }
+/**
+ * Per-prompt reminder cadence emission: the LONG block (longFile) on every
+ * REMINDER_PERIOD-th counted prompt, the one-line pointer between. When the
+ * counter could NOT persist, emit the LONG block — fail VISIBLE: a host whose
+ * temp dir cannot hold the state file would otherwise inject the pointer on
+ * every prompt at a block that never arrives.
+ */
+function cadenceEmit(env, adapter, longFile, count, persisted) {
+    return !persisted || count % REMINDER_PERIOD === 0
+        ? readDirective(env, longFile)
+        : readDirective(env, adapter.offTurnFile);
+}
+/**
+ * Claim (or re-claim) an active marker for the current session and emit the
+ * claim-turn payload: FULL directive + ON reminder block, with the CARRYOVER
+ * notice prepended on the first foreign-owner claim of a marker (ack-latched,
+ * so sub-agent/parallel-session marker ping-pong cannot re-fire it). The
+ * reminder counter re-baselines to 0 — the claim turn IS a LONG turn, so the
+ * next LONG fires exactly REMINDER_PERIOD prompts later. Shared by runHook's
+ * claim branch and the Codex SessionStart dispatcher (one copy of the claim
+ * semantics, no drift).
+ */
+export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
+    const firstCarryover = kind === "carryover" && !m.carryover_ack;
+    m.baseline_turn = turn;
+    m.owner_session = current ?? null;
+    if (kind === "carryover") {
+        m.provenance = "carried-over";
+        m.carryover_ack = true;
+    }
+    marker.writeMarker(cwd, m);
+    reminder.rebase(cwd, current, 0);
+    const full = readDirective(env, adapter.fullDirectiveFile) +
+        readDirective(env, adapter.reminderOnFile);
+    return firstCarryover
+        ? readDirective(env, adapter.carryoverDirectiveFile) + full
+        : full;
+}
 /**
  * Core hook logic. Returns the string to inject, or '' to inject nothing.
  *
  * Order:
- *  1. subagent -> '' (a subagent must never be nagged to delegate).
- *  2. marker not active for cwd -> '' (OFF; zero emission).
- *  3. read current turn + marker state, classify the claim.
- *  4. FRESH (never claimed) -> claim + baseline at this turn, persist, emit FULL
- *     (this is the freshly-enabled turn, relTurn 0).
- *  5. CARRYOVER (owned by another/prior session) -> re-claim + re-baseline at
- *     this turn, persist, emit the CARRYOVER notice prepended to FULL only
- *     before the marker's carryover_ack has latched.
- *  6. SAME-SESSION -> rel = turn - baseline; FULL when rel % 5 === 0, else
- *     off-turn.
+ *  1. subagent -> '' (a subagent must never be nagged to delegate; the counter
+ *     does not advance).
+ *  2. marker not active for cwd -> OFF cadence: advance the session's counter
+ *     (per-owner; a new session starts its own), LONG OFF-variant reminder when
+ *     count % REMINDER_PERIOD === 0, else the one-line pointer.
+ *  3. marker active: classify the claim from marker state.
+ *  4. FRESH / CARRYOVER -> claimAndEmit (FULL + ON reminder; CARRYOVER notice
+ *     prepended once per marker; counter re-baselined). The transcript turn is
+ *     read ONLY here — claim turns are the only consumer of the baseline, and
+ *     the tail read is too expensive for the per-prompt steady state.
+ *  5. SAME-SESSION -> ON cadence: LONG ON-variant reminder when
+ *     count % REMINDER_PERIOD === 0, else the one-line pointer.
  */
 export function runHook(payload, env, adapter) {
     try {
@@ -168,38 +233,21 @@ export function runHook(payload, env, adapter) {
             return "";
         }
         const cwd = payload.cwd || process.cwd();
+        const current = sessionKey(payload);
         if (!marker.isActive(cwd)) {
-            return "";
+            // OFF: no claim machinery — just the per-prompt reminder cadence.
+            const r = reminder.advance(cwd, current);
+            return cadenceEmit(env, adapter, adapter.reminderOffFile, r.count, r.persisted);
         }
-        const current = sessionKey(payload);
-        const turn = adapter.currentTurn(payload.transcript_path);
         const m = marker.readMarker(cwd);
         const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
-        if (kind === "fresh") {
-            m.baseline_turn = turn;
-            m.owner_session = current ?? null;
-            marker.writeMarker(cwd, m);
-            return readDirective(env, adapter.fullDirectiveFile);
-        }
-        if (kind === "carryover") {
-            // Re-claim for the current session and re-baseline at this turn so the
-            // notice fires once per project marker. The ack survives re-claims, so
-            // sub-agent/parallel-session marker ping-pong cannot re-fire it.
-            const firstTime = !m.carryover_ack;
-            m.baseline_turn = turn;
-            m.owner_session = current ?? null;
-            m.provenance = "carried-over";
-            m.carryover_ack = true;
-            marker.writeMarker(cwd, m);
-            return firstTime
-                ? readDirective(env, adapter.carryoverDirectiveFile) +
-                    readDirective(env, adapter.fullDirectiveFile)
-                : readDirective(env, adapter.fullDirectiveFile);
+        if (kind === "fresh" || kind === "carryover") {
+            const turn = adapter.currentTurn(payload.transcript_path);
+            return claimAndEmit(cwd, current, turn, m, kind, env, adapter);
         }
-        const rel = turn - m.baseline_turn;
-        return rel % 5 === 0
-            ? readDirective(env, adapter.fullDirectiveFile)
-            : readDirective(env, adapter.offTurnFile);
+        // SAME-SESSION: per-prompt reminder cadence, ON variant.
+        const r = reminder.advance(cwd, current);
+        return cadenceEmit(env, adapter, adapter.reminderOnFile, r.count, r.persisted);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.

package/dist/orchestration/marker.js

@@ -3,6 +3,12 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 const markerDir = join(tmpdir(), "subagent-mcp");
+/**
+ * Shared per-project state dir for ALL hook state files (marker + reminder
+ * counter). Exported so sibling state modules key off the SAME location — a
+ * future move edits one constant, not N copies.
+ */
+export const stateDir = markerDir;
 /**
  * Canonicalize a working directory so two spellings of the same path hash
  * identically. Strip a leading Windows \\?\ extended-length prefix FIRST (on

package/dist/orchestration/reminder.js

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwdHash, stateDir } from "./marker.js";
+/** Bound the per-owner map so a busy multi-session cwd cannot grow it without
+ * limit; evicting ALL entries on overflow is crude but rare and self-heals. */
+const OWNER_CAP = 8;
+function ownerKey(current) {
+    return current ?? "null";
+}
+export function reminderPath(cwd) {
+    return join(stateDir, "remind-" + cwdHash(cwd) + ".json");
+}
+export function readReminder(cwd) {
+    try {
+        const raw = readFileSync(reminderPath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        const counts = {};
+        if (parsed.counts && typeof parsed.counts === "object") {
+            for (const [owner, count] of Object.entries(parsed.counts)) {
+                if (typeof count === "number" && Number.isFinite(count)) {
+                    counts[owner] = count;
+                }
+            }
+        }
+        return { counts };
+    }
+    catch {
+        // Missing/corrupt state -> safe default (no owners counted yet).
+        return { counts: {} };
+    }
+}
+/** Persist the state. Returns true on success, false on any write failure. */
+export function writeReminder(cwd, obj) {
+    try {
+        // Owner-only perms (see marker.enable()): the state persists session keys.
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(reminderPath(cwd), JSON.stringify(obj), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        // Fail-safe: report the failure; never throw.
+        return false;
+    }
+}
+/**
+ * Count one user prompt for the current session and persist. Returns the
+ * session's advanced count plus whether the state persisted (persisted=false
+ * lets the caller fail visible instead of never reaching the LONG cadence).
+ */
+export function advance(cwd, current) {
+    const owner = ownerKey(current);
+    const state = readReminder(cwd);
+    if (!(owner in state.counts) && Object.keys(state.counts).length >= OWNER_CAP) {
+        state.counts = {};
+    }
+    const count = (state.counts[owner] ?? 0) + 1;
+    state.counts[owner] = count;
+    const persisted = writeReminder(cwd, state);
+    return { count, persisted };
+}
+/**
+ * Re-baseline the current session's count (claim turns set 0: the claim turn
+ * IS a LONG turn, so the next LONG fires exactly REMINDER_PERIOD prompts on).
+ */
+export function rebase(cwd, current, count) {
+    const state = readReminder(cwd);
+    state.counts[ownerKey(current)] = count;
+    writeReminder(cwd, state);
+}