@heretyc/subagent-mcp 2.6.0

package/dist/hooks/orchestration-claude.js

@@ -0,0 +1,88 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { countJsonlType, runHook, } from "../orchestration/hook-core.js";
+/**
+ * Claude Code UserPromptSubmit hook entry. Reads the JSON payload from stdin,
+ * runs the provider-agnostic core with the Claude adapter, and writes the
+ * result to stdout. Always exits 0 — a hook must never fail the host turn.
+ *
+ * Compiles to dist/hooks/orchestration-claude.js and is invoked as:
+ *   node "${CLAUDE_PLUGIN_ROOT}/dist/hooks/orchestration-claude.js"
+ */
+// Claude entrypoints that are themselves SUBAGENTS and must NOT be nagged.
+// Top-level entrypoints that SHOULD inject (cli, mcp, claude-vscode) are simply
+// absent from this set. DECISION: claude-desktop is a non-hook host (it has no
+// UserPromptSubmit hook), so whether it appears here never matters there; we do
+// NOT add it, which resolves the prototype/INSTALL.md conflict over whether
+// claude-desktop should be skipped.
+const SUBAGENT_ENTRYPOINTS = new Set([
+    "local-agent",
+    "sdk-cli",
+    "sdk-ts",
+    "sdk-py",
+]);
+export const claudeAdapter = {
+    isSubagent(payload, env) {
+        // subagent-mcp-spawned children inherit this guard and must not claim/nag.
+        if (env.SUBAGENT_MCP_SUBAGENT === "1") {
+            return true;
+        }
+        if (payload.agent_id) {
+            return true;
+        }
+        const entrypoint = env.CLAUDE_CODE_ENTRYPOINT;
+        return typeof entrypoint === "string" && SUBAGENT_ENTRYPOINTS.has(entrypoint);
+    },
+    // Count JSONL lines in the transcript whose parsed object.type === 'user'.
+    // 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/missing transcript -> 0, so the hook emits FULL (fail-safe: a
+    // visible directive rather than silent suppression).
+    currentTurn(transcriptPath) {
+        return countJsonlType(transcriptPath, "user");
+    },
+    fullDirectiveFile: "orchestration-claude.md",
+    offTurnFile: "off-turn-reminder.md",
+    carryoverDirectiveFile: "carryover-claude.md",
+};
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+async function main() {
+    let payload = {};
+    try {
+        const raw = await readStdin();
+        if (raw.trim()) {
+            payload = JSON.parse(raw);
+        }
+    }
+    catch {
+        // Bad/empty stdin -> empty payload; runHook degrades to '' safely.
+    }
+    let out = "";
+    try {
+        out = runHook(payload, process.env, claudeAdapter);
+    }
+    catch {
+        out = "";
+    }
+    if (out) {
+        process.stdout.write(out);
+    }
+    process.exit(0);
+}
+// Only run the stdin->stdout shim when invoked directly as the hook command,
+// NOT when a test imports `claudeAdapter`. Importing must have no side effects.
+const isMain = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+if (isMain) {
+    void main();
+}

package/dist/hooks/orchestration-codex.js

@@ -0,0 +1,152 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { classifyClaim, countJsonlType, readDirective, 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.
+ *
+ * Compiles to dist/hooks/orchestration-codex.js and is invoked as:
+ *   node "<PLUGIN_ROOT>/dist/hooks/orchestration-codex.js"
+ */
+// Codex 0.131+ source-string variants that mark a SUBAGENT session.
+const SUBAGENT_SOURCE_STRINGS = new Set([
+    "subAgentReview",
+    "subAgentCompact",
+    "subAgentThreadSpawn",
+    "subAgentOther",
+]);
+const PARENT_PROCESS_MARKER = "this is a request from a parent process";
+export const codexAdapter = {
+    isSubagent(payload, env) {
+        // subagent-mcp-spawned children inherit this guard and must not claim/nag.
+        if (env.SUBAGENT_MCP_SUBAGENT === "1") {
+            return true;
+        }
+        const source = payload.source;
+        // 0.131+: source is an object whose keys name the subagent kind.
+        if (source && typeof source === "object") {
+            if (Object.prototype.hasOwnProperty.call(source, "subagent")) {
+                return true;
+            }
+        }
+        // Older: source is a string enum.
+        if (typeof source === "string" && SUBAGENT_SOURCE_STRINGS.has(source)) {
+            return true;
+        }
+        // Fallback: a parent-process handoff is detectable from the prompt's first
+        // non-empty line (our own subagent contract starts with this sentinel).
+        const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+        const head = prompt.slice(0, 200);
+        for (const line of head.split("\n")) {
+            const trimmed = line.trim().toLowerCase();
+            if (!trimmed)
+                continue;
+            return trimmed.includes(PARENT_PROCESS_MARKER);
+        }
+        return false;
+    },
+    // 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).
+    currentTurn(transcriptPath) {
+        return countJsonlType(transcriptPath, "turn_context");
+    },
+    fullDirectiveFile: "orchestration-codex.md",
+    offTurnFile: "off-turn-reminder.md",
+    carryoverDirectiveFile: "carryover-codex.md",
+};
+/**
+ * Codex dispatcher. SessionStart fires once before the first prompt; it covers
+ * the turn-0 directive (UserPromptSubmit cadence then handles turns 1+).
+ *
+ * Because the marker now PERSISTS across sessions, SessionStart must classify
+ * the claim like runHook does: an inherited marker owned by a prior/other
+ * session is a CARRYOVER (emit the CARRYOVER notice prepended to FULL and
+ * re-claim); a freshly-enabled marker is FRESH (emit FULL and claim). Either
+ * way the marker is re-claimed/baselined so the following UserPromptSubmit turns
+ * run SAME-SESSION cadence and the notice fires exactly once.
+ *
+ * Returns the string to inject, or '' for nothing. Fully fail-safe.
+ */
+export function runCodexHook(payload, env, adapter = codexAdapter) {
+    try {
+        if (payload.hook_event_name === "SessionStart") {
+            if (adapter.isSubagent(payload, env))
+                return "";
+            const cwd = payload.cwd || process.cwd();
+            if (!marker.isActive(cwd))
+                return "";
+            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);
+            // 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);
+        }
+        // UserPromptSubmit (and any other event) -> normal cadence.
+        return runHook(payload, env, adapter);
+    }
+    catch {
+        return "";
+    }
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+async function main() {
+    let payload = {};
+    try {
+        const raw = await readStdin();
+        if (raw.trim()) {
+            payload = JSON.parse(raw);
+        }
+    }
+    catch {
+        // Bad/empty stdin -> empty payload; degrades to '' safely.
+    }
+    let out = "";
+    try {
+        out = runCodexHook(payload, process.env, codexAdapter);
+    }
+    catch {
+        out = "";
+    }
+    if (out) {
+        process.stdout.write(out);
+    }
+    process.exit(0);
+}
+// Only run the shim when invoked directly, not when a test imports the adapter.
+const isMain = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+if (isMain) {
+    void main();
+}