@heretyc/subagent-mcp 2.6.0

package/dist/orchestration/hook-core.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+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";
+/**
+ * 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)
+ * so the bundled plugin finds its assets wherever it is installed. Otherwise we
+ * walk up from the COMPILED file location: dist/hooks/<x>.js -> ../../directives
+ * === <repoRoot>/directives.
+ */
+export function resolveDirectivesDir(env) {
+    const root = env.CLAUDE_PLUGIN_ROOT || env.PLUGIN_ROOT;
+    if (root) {
+        return join(root, "directives");
+    }
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Compiled location is dist/orchestration/hook-core.js, so ../../directives
+    // is the repo root's directives dir; the entry shims live at dist/hooks/<x>.js
+    // and import this module, but __dirname here is the hook-core module's own
+    // dir. Two levels up from dist/orchestration is the repo root either way.
+    return join(here, "..", "..", "directives");
+}
+/** Read a directive asset by filename. On ANY failure return '' (fail-safe). */
+export function readDirective(env, fileName) {
+    try {
+        return readFileSync(join(resolveDirectivesDir(env), fileName), "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Hard cap on how many bytes of a transcript we will read when counting turns.
+ * Transcripts grow without bound over a long session, and the hook runs INLINE
+ * on every UserPromptSubmit before the prompt is sent — an unbounded
+ * readFileSync(...,'utf8') + full split('\n') is O(file size) per turn (O(n^2)
+ * over a session) and a multi-hundred-MB (or attacker-supplied) transcript_path
+ * could stall the user's turn for seconds or OOM the hook. We therefore read at
+ * most the trailing TRANSCRIPT_READ_CAP bytes.
+ */
+export const TRANSCRIPT_READ_CAP = 16 * 1024 * 1024; // 16 MB
+/**
+ * Count JSONL lines in a transcript whose parsed object.type === `wantedType`,
+ * reading at most the trailing TRANSCRIPT_READ_CAP bytes (the most recent turns
+ * are at the end of the file). Fully fail-safe: any error -> 0, which makes the
+ * caller emit FULL (a visible directive) rather than silently suppressing.
+ *
+ * For a tail read we drop the first (likely partial) line of the window so we
+ * never mis-parse a line cut in half by the cap boundary. Under-counting by at
+ * most one line at the boundary is acceptable for cadence; over a 16 MB window
+ * the relative turn count stays stable across consecutive turns.
+ */
+export function countJsonlType(transcriptPath, wantedType) {
+    if (!transcriptPath)
+        return 0;
+    let fd;
+    try {
+        const size = statSync(transcriptPath).size;
+        let raw;
+        let droppedPartialHead = false;
+        if (size <= TRANSCRIPT_READ_CAP) {
+            raw = readFileSync(transcriptPath, "utf8");
+        }
+        else {
+            // Read only the trailing window via an fd so we never materialize the
+            // whole file. The first line of the window is probably truncated.
+            const start = size - TRANSCRIPT_READ_CAP;
+            const buf = Buffer.allocUnsafe(TRANSCRIPT_READ_CAP);
+            fd = openSync(transcriptPath, "r");
+            let offset = 0;
+            let pos = start;
+            while (offset < TRANSCRIPT_READ_CAP) {
+                const bytes = readSync(fd, buf, offset, TRANSCRIPT_READ_CAP - offset, pos);
+                if (bytes <= 0)
+                    break;
+                offset += bytes;
+                pos += bytes;
+            }
+            raw = buf.toString("utf8", 0, offset);
+            droppedPartialHead = true;
+        }
+        let count = 0;
+        let first = true;
+        for (const line of raw.split("\n")) {
+            // Drop the first (partial) line only when we read a tail window.
+            if (first) {
+                first = false;
+                if (droppedPartialHead)
+                    continue;
+            }
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const obj = JSON.parse(trimmed);
+                if (obj && obj.type === wantedType)
+                    count++;
+            }
+            catch {
+                // Skip unparseable lines; never throw.
+            }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Best-effort close; never throw.
+            }
+        }
+    }
+}
+/**
+ * Return the stable key used to compare hook claims. Some hosts omit
+ * session_id; transcript_path is per-session, so a short hash keeps the claim
+ * sticky without changing classifyClaim's string/undefined contract.
+ */
+export function sessionKey(payload) {
+    if (typeof payload.session_id === "string") {
+        return payload.session_id;
+    }
+    if (typeof payload.transcript_path === "string" &&
+        payload.transcript_path.length > 0) {
+        return ("tp-" +
+            createHash("sha256")
+                .update(payload.transcript_path, "utf8")
+                .digest("hex")
+                .slice(0, 16));
+    }
+    return undefined;
+}
+export function classifyClaim(owner_session, baseline_turn, current) {
+    if (baseline_turn == null || owner_session == null) {
+        return "fresh";
+    }
+    // owner_session is a real string here.
+    if (current === undefined || owner_session !== current) {
+        return "carryover";
+    }
+    return "same";
+}
+/**
+ * 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.
+ */
+export function runHook(payload, env, adapter) {
+    try {
+        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);
+        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);
+        }
+        const rel = turn - m.baseline_turn;
+        return rel % 5 === 0
+            ? readDirective(env, adapter.fullDirectiveFile)
+            : readDirective(env, adapter.offTurnFile);
+    }
+    catch {
+        // Any failure -> inject nothing. Never crash or stall the host turn.
+        return "";
+    }
+}

package/dist/orchestration/marker.js

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+const markerDir = join(tmpdir(), "subagent-mcp");
+/**
+ * Canonicalize a working directory so two spellings of the same path hash
+ * identically. Strip a leading Windows \\?\ extended-length prefix FIRST (on
+ * the raw input) — resolve() canonicalizes that prefix away, so stripping after
+ * resolve is dead code and an extended-length cwd would otherwise hash
+ * differently from its plain form. Then resolve() to an absolute path; use
+ * forward slashes; lowercase on win32 (the FS is case-insensitive there); drop
+ * a trailing slash.
+ */
+export function normalizeCwd(cwd) {
+    let raw = cwd;
+    if (raw.startsWith("\\\\?\\")) {
+        raw = raw.slice(4);
+    }
+    let p = resolve(raw);
+    p = p.replace(/\\/g, "/");
+    if (process.platform === "win32") {
+        p = p.toLowerCase();
+    }
+    if (p.length > 1 && p.endsWith("/")) {
+        p = p.slice(0, -1);
+    }
+    return p;
+}
+export function cwdHash(cwd) {
+    return createHash("sha256")
+        .update(normalizeCwd(cwd), "utf8")
+        .digest("hex")
+        .slice(0, 16);
+}
+export function markerPath(cwd) {
+    return join(markerDir, "orch-" + cwdHash(cwd) + ".flag");
+}
+/**
+ * Enable orchestration for cwd. ALWAYS overwrites — re-enabling re-baselines by
+ * clearing owner_session/baseline_turn back to null so the next hook turn
+ * re-claims and re-baselines.
+ */
+export function enable(cwd) {
+    try {
+        // Restrictive POSIX perms: the marker dir/file live in the shared,
+        // world-readable /tmp on Linux/macOS and persist a session_id. mode 0o700/
+        // 0o600 keeps them owner-only so other local users cannot read the
+        // session_id or enumerate which projects have orchestration enabled. mode is
+        // ignored on Windows (harmless; tmpdir is already per-user there).
+        mkdirSync(markerDir, { recursive: true, mode: 0o700 });
+        const state = {
+            owner_session: null,
+            baseline_turn: null,
+            provenance: "user-enabled",
+            carryover_ack: false,
+        };
+        writeFileSync(markerPath(cwd), JSON.stringify(state), { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Fail-safe: never throw to the caller.
+    }
+}
+/**
+ * Disable orchestration for cwd by removing the marker.
+ *
+ * No existsSync() guard: that only opens a TOCTOU window where a concurrent
+ * clearForCwd/disable for the same cwd removes the file between the check and
+ * the unlink. We just unlink and swallow ENOENT (already-gone is success).
+ *
+ * KNOWN LIMITATION: the marker is keyed by cwd, NOT by session. Two CLI
+ * sessions in the same project share one marker, so their enable/disable
+ * interleave and the last writer wins. Per-session isolation would require
+ * keying the marker by cwd+session_id; not done here because LOCKED DECISION 1
+ * keys the marker by working directory alone. (The hook tracks the owning
+ * session via owner_session so a carried-over marker is re-claimed, but the
+ * marker file itself is still shared per cwd.)
+ */
+export function disable(cwd) {
+    try {
+        unlinkSync(markerPath(cwd));
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT") {
+            // Any non-ENOENT failure is still swallowed (fail-safe); ENOENT means the
+            // marker was already gone, which is the desired end state anyway.
+        }
+    }
+}
+export function isActive(cwd) {
+    try {
+        return existsSync(markerPath(cwd));
+    }
+    catch {
+        return false;
+    }
+}
+export function readMarker(cwd) {
+    try {
+        const raw = readFileSync(markerPath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        const provenance = parsed.provenance === "user-enabled" || parsed.provenance === "carried-over"
+            ? parsed.provenance
+            : null;
+        return {
+            owner_session: typeof parsed.owner_session === "string" ? parsed.owner_session : null,
+            baseline_turn: typeof parsed.baseline_turn === "number" ? parsed.baseline_turn : null,
+            provenance,
+            carryover_ack: typeof parsed.carryover_ack === "boolean" ? parsed.carryover_ack : false,
+        };
+    }
+    catch {
+        // Missing/corrupt marker -> safe default (unclaimed, no baseline/ack).
+        return {
+            owner_session: null,
+            baseline_turn: null,
+            provenance: null,
+            carryover_ack: false,
+        };
+    }
+}
+export function writeMarker(cwd, obj) {
+    try {
+        // Owner-only perms (see enable()): the marker persists owner_session.
+        mkdirSync(markerDir, { recursive: true, mode: 0o700 });
+        writeFileSync(markerPath(cwd), JSON.stringify(obj), { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // Fail-safe.
+    }
+}
+/**
+ * Marker removal alias, identical to disable. RETAINED for callers that clear a
+ * marker explicitly (e.g. the tool's enabled:false path). NOTE: the server no
+ * longer calls this on startup — orchestration mode now PERSISTS across sessions.
+ */
+export function clearForCwd(cwd) {
+    disable(cwd);
+}

package/dist/output-helpers.js

@@ -0,0 +1,128 @@
+// Defensive extraction of a sub-agent's final assistant turn text from its
+// captured stdout. NEVER throws; on any parse failure, unknown shape, or empty
+// result it falls back to the raw stdout (trimmed). Empty stdout -> "".
+function rawFallback(stdout) {
+    return (stdout || "").trim();
+}
+// Pull a final assistant-message string out of one parsed codex `--json` event.
+// Codex emits newline-delimited JSON; the final assistant message has appeared
+// under a few shapes across CLI versions, so match tolerantly.
+function codexEventText(evt) {
+    if (!evt || typeof evt !== "object")
+        return null;
+    const e = evt;
+    // Shape A: { type: "agent_message", message: "..." }
+    if (e.type === "agent_message" && typeof e.message === "string") {
+        return e.message;
+    }
+    // Shape B: { type: "item.completed", item: { item_type: "agent_message", text: "..." } }
+    if (e.type === "item.completed" && e.item && typeof e.item === "object") {
+        const item = e.item;
+        if (item.item_type === "agent_message" && typeof item.text === "string") {
+            return item.text;
+        }
+    }
+    // Shape C: { msg: { type: "agent_message", message: "..." } }
+    if (e.msg && typeof e.msg === "object") {
+        const msg = e.msg;
+        if (msg.type === "agent_message" && typeof msg.message === "string") {
+            return msg.message;
+        }
+    }
+    return null;
+}
+export function extractFinalTurn(provider, stdout) {
+    if (!stdout)
+        return "";
+    if (provider === "claude") {
+        try {
+            const parsed = JSON.parse(stdout);
+            // Object with a string `result` field is claude's final assistant message.
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const r = parsed.result;
+                if (typeof r === "string")
+                    return r;
+            }
+            // Array form: last element of type "result" or carrying a string result.
+            if (Array.isArray(parsed)) {
+                for (let i = parsed.length - 1; i >= 0; i--) {
+                    const el = parsed[i];
+                    if (el && typeof el === "object") {
+                        const obj = el;
+                        if (obj.type === "result" && typeof obj.result === "string") {
+                            return obj.result;
+                        }
+                        if (typeof obj.result === "string") {
+                            return obj.result;
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Not a single buffered object/array — fall through to stream-json scan.
+        }
+        // stream-json: one JSON event per line. Prefer the final `result` event;
+        // otherwise the last assistant `text` block.
+        let resultText = null;
+        let lastAssistantText = null;
+        for (const line of stdout.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let evt;
+            try {
+                evt = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (!evt || typeof evt !== "object")
+                continue;
+            const e = evt;
+            if (e.type === "result" && typeof e.result === "string") {
+                resultText = e.result;
+            }
+            else if (e.type === "assistant" && e.message && typeof e.message === "object") {
+                const content = e.message.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (block && typeof block === "object") {
+                            const b = block;
+                            if (b.type === "text" && typeof b.text === "string")
+                                lastAssistantText = b.text;
+                        }
+                    }
+                }
+            }
+        }
+        if (resultText !== null)
+            return resultText;
+        if (lastAssistantText !== null)
+            return lastAssistantText;
+        return rawFallback(stdout);
+    }
+    if (provider === "codex") {
+        let last = null;
+        const lines = stdout.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const evt = JSON.parse(trimmed);
+                const text = codexEventText(evt);
+                if (text !== null)
+                    last = text;
+            }
+            catch {
+                // skip non-JSON lines
+            }
+        }
+        if (last !== null)
+            return last;
+        return rawFallback(stdout);
+    }
+    // Unknown provider: raw fallback.
+    return rawFallback(stdout);
+}

package/dist/platform.js

@@ -0,0 +1,59 @@
+import { join, posix } from "path";
+/**
+ * Pure, dependency-injected exe resolver — enables unit testing with mocked
+ * platform and filesystem without spawning real processes.
+ *
+ * win32:   Resolves the real .exe under the npm global prefix (PowerShell/.cmd
+ *          shims cannot be spawned directly). Falls back to bare name if the
+ *          expected path does not exist.
+ *
+ * darwin / linux:  The npm global bin directory contains a real symlink that
+ *          re-execs the correct vendor binary, so the bare name works fine when
+ *          the shell's PATH is set up normally. For minimal-PATH environments
+ *          (non-login shells, some MCP host launchers) we probe candidate
+ *          absolute paths in order and return the first that exists. If none
+ *          exist we return the bare name so PATH is the final arbiter.
+ */
+export function resolveExeFor(provider, platform, deps) {
+    if (platform === "win32") {
+        const prefix = deps.npmPrefix();
+        if (provider === "claude") {
+            const exe = join(prefix, "node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe");
+            if (deps.existsSync(exe))
+                return exe;
+        }
+        else {
+            // codex
+            const exe = join(prefix, "node_modules", "@openai", "codex", "node_modules", "@openai", "codex-win32-x64", "vendor", "x86_64-pc-windows-msvc", "bin", "codex.exe");
+            if (deps.existsSync(exe))
+                return exe;
+        }
+        // Fall back to bare name — PATH resolver
+        return provider;
+    }
+    // darwin / linux: prefer bare name on PATH, but check known absolute
+    // candidate locations for non-login shell environments.
+    // Use posix.join for path construction so that unix-style prefixes produce
+    // forward-slash paths even when this module is built on Windows.
+    const prefix = deps.npmPrefix();
+    let candidates;
+    if (provider === "claude") {
+        candidates = [
+            posix.join(prefix, "bin", "claude"),
+            "/opt/homebrew/bin/claude",
+            "/usr/local/bin/claude",
+        ];
+    }
+    else {
+        candidates = [
+            posix.join(prefix, "bin", "codex"),
+            "/opt/homebrew/bin/codex",
+            "/usr/local/bin/codex",
+        ];
+    }
+    for (const candidate of candidates) {
+        if (deps.existsSync(candidate))
+            return candidate;
+    }
+    return provider; // bare name — last resort, relies on PATH
+}