@heretyc/subagent-mcp 2.10.4 → 2.12.1

package/dist/drivers.js

@@ -108,6 +108,12 @@ class AsyncInputQueue {
         for (const taker of this.takers.splice(0))
             taker({ value: undefined, done: true });
     }
+    // True when the consumer (SDK query loop) is blocked awaiting input and nothing
+    // is buffered — i.e. the model turn ended and it is idle. A watchdog uses this
+    // to decide whether a resume turn is warranted.
+    get isAwaitingInput() {
+        return !this.closed && this.items.length === 0 && this.takers.length > 0;
+    }
     [Symbol.asyncIterator]() {
         return {
             next: () => {
@@ -147,6 +153,48 @@ function userMessage(text) {
 function textInput(text) {
     return { type: "text", text, text_elements: [] };
 }
+// Server->client RPC methods that block on a client answer (elicitation /
+// approval). Matched case-insensitively so provider-namespaced variants
+// (e.g. "codex/requestUserInput", "session/requestApproval") are covered.
+function isElicitationMethod(method) {
+    return /requestuserinput|elicit|approv/i.test(method);
+}
+// Shape the `result` payload for an elicitation reply. When the RPC offered a
+// discrete option set, select only an exact case-insensitive label match and
+// echo its identifier; otherwise pass the answer through as text.
+function buildElicitationResult(options, answer) {
+    if (options && options.length > 0) {
+        const norm = answer.trim().toLowerCase();
+        const chosen = options.find((opt) => {
+            const label = optionLabel(opt);
+            return label !== null && norm === label.trim().toLowerCase();
+        });
+        if (chosen) {
+            const id = optionId(chosen);
+            return id !== null ? { optionId: id } : { option: chosen };
+        }
+    }
+    return { text: answer };
+}
+function optionLabel(opt) {
+    for (const key of ["label", "name", "title", "text", "value", "id"]) {
+        const v = opt[key];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return null;
+}
+function optionId(opt) {
+    for (const key of ["id", "value", "optionId", "label", "name"]) {
+        const v = opt[key];
+        if (typeof v === "string" || typeof v === "number")
+            return v;
+    }
+    return null;
+}
+function isJsonRpcId(id) {
+    return typeof id === "string" || typeof id === "number";
+}
 export class MockJsonlDriver {
     child;
     provider;
@@ -254,6 +302,10 @@ export class CodexAppServerDriver {
     initialized = false;
     turnInFlight = false;
     maxQueueDepth = 32;
+    // An inbound server->client RPC (elicitation, e.g. requestUserInput / approval)
+    // awaiting a reply. While set, the next send() answers this request instead of
+    // enqueuing a new turn — otherwise the in-flight question turn wedges the queue.
+    pendingServerRequest = null;
     constructor(child, options) {
         this.child = child;
         this.options = options;
@@ -301,6 +353,18 @@ export class CodexAppServerDriver {
         if (!this.initialized || !this.threadId) {
             return Promise.reject(new Error("codex app-server thread is not initialized"));
         }
+        if (this.pendingServerRequest) {
+            // The message is the user's answer to a parked server-side elicitation.
+            // Reply on the same JSON-RPC id (mirroring the { id, result } envelope our
+            // own request() responses arrive in) instead of enqueuing a fresh turn.
+            const req = this.pendingServerRequest;
+            this.pendingServerRequest = null;
+            return writeLine(this.child.stdin, {
+                jsonrpc: "2.0",
+                id: req.id,
+                result: buildElicitationResult(req.options, message),
+            });
+        }
         if (this.queuedTurns.length >= this.maxQueueDepth) {
             return Promise.reject(new Error(`provider input queue is full (${this.maxQueueDepth})`));
         }
@@ -315,6 +379,7 @@ export class CodexAppServerDriver {
         this.process.kill("SIGKILL");
         this.rejectPending(new Error("codex app-server driver was killed"));
         this.queuedTurns.length = 0;
+        this.pendingServerRequest = null;
     }
     async drainQueuedTurns() {
         if (this.drainActive)
@@ -406,6 +471,16 @@ export class CodexAppServerDriver {
                 pending.resolve(message);
             }
         }
+        else if (isJsonRpcId(message.id) &&
+            typeof message.method === "string" &&
+            isElicitationMethod(message.method)) {
+            // Inbound server->client RPC (elicitation) that is NOT a reply to one of
+            // our requests. Park it so the next send() answers it instead of queuing a
+            // new turn; leaving it unanswered wedges the in-flight question turn.
+            const params = (message.params ?? {});
+            const options = Array.isArray(params.options) ? params.options : undefined;
+            this.pendingServerRequest = { id: message.id, method: message.method, options };
+        }
         if (message.method === "turn/started" && message.params && typeof message.params === "object") {
             const turn = (message.params.turn ?? {});
             if (typeof turn.id === "string")
@@ -448,6 +523,10 @@ export class ClaudeSdkDriver {
     queue = Promise.resolve();
     queryHandle = null;
     closedFlag = false;
+    // Debounce for notifyTaskComplete(): set when a resume turn is pushed, cleared
+    // as soon as the model streams any message (see pump). Prevents a stalled agent
+    // from being resumed more than once per idle cycle.
+    resumePending = false;
     constructor(queryFn) {
         this.queryFn = queryFn;
     }
@@ -490,6 +569,30 @@ export class ClaudeSdkDriver {
         this.queue = next.catch(() => { });
         return next;
     }
+    // Wake the SDK query loop after the agent's own background task finishes. The
+    // loop parks on `await next input` once the model turn ends; nothing else
+    // pushes a resume, so a sub-agent that spawned a bg task would stall forever.
+    // Pushes a synthetic user turn through the SAME input queue send() uses.
+    //
+    // WIRING: the notification source (task_notification for THIS agent's bg task)
+    // is not visible inside drivers.ts. The owning server/monitor must call
+    // driver.notifyTaskComplete() when it observes this agent's background
+    // task_notification while the agent is `stalled` with an empty input queue
+    // (see AsyncInputQueue.isAwaitingInput). Guarded so repeat calls are no-ops
+    // until the model next produces output.
+    notifyTaskComplete(text) {
+        if (this.closed || this.resumePending)
+            return Promise.resolve();
+        this.resumePending = true;
+        const resumeText = text ?? "Your background task has completed. Resume and continue where you left off.";
+        const next = this.queue.then(() => {
+            if (this.closed)
+                return;
+            return this.input.push(userMessage(resumeText));
+        });
+        this.queue = next.catch(() => { });
+        return next;
+    }
     kill() {
         if (this.closedFlag)
             return;
@@ -503,6 +606,9 @@ export class ClaudeSdkDriver {
         let started = false;
         try {
             for await (const message of query) {
+                // The model is producing output again: clear the resume debounce so a
+                // future bg-task completion can wake it once more.
+                this.resumePending = false;
                 const text = claudeMessageText(message);
                 if (!started && text && isClaudeSessionLimit(text)) {
                     // Launch-time failover only applies before startup resolves/spawn grace ends;

package/dist/global-concurrency.jsonc

@@ -1,29 +1,29 @@
-// subagent-mcp — Global Concurrent Subagent Cap
-// ------------------------------------------------------------------
-// SOLE source of truth for the machine-wide limit on how many subagents
-// may be ALIVE AT ONCE across EVERY session, process, and user on this
-// machine. There is NO environment-variable override.
-//
-// The whole recursive descendant tree counts toward this ONE number: a
-// subagent that itself launches subagents adds to the same machine-wide
-// total, and OTHER active agentic sessions count too.
-//
-// RE-READ on every launch_agent call — edits take effect immediately, no
-// server restart required.
-//
-// Value rules (forcibly applied to the number below):
-//   - missing / unset / non-integer / 0 / negative  -> reset to default 20
-//   - 1 through 9                                    -> forced UP to minimum 10
-//   - 10 or greater                                 -> used as-is
-//
+// subagent-mcp — Global Concurrent Subagent Cap
+// ------------------------------------------------------------------
+// SOLE source of truth for the machine-wide limit on how many subagents
+// may be ALIVE AT ONCE across EVERY session, process, and user on this
+// machine. There is NO environment-variable override.
+//
+// The whole recursive descendant tree counts toward this ONE number: a
+// subagent that itself launches subagents adds to the same machine-wide
+// total, and OTHER active agentic sessions count too.
+//
+// RE-READ on every launch_agent call — edits take effect immediately, no
+// server restart required.
+//
+// Value rules (forcibly applied to the number below):
+//   - missing / unset / non-integer / 0 / negative  -> reset to default 20
+//   - 1 through 9                                    -> forced UP to minimum 10
+//   - 10 or greater                                 -> used as-is
+//
 // Zombie culling is always enabled. There is no config knob. Before cap
 // rejection, launch/tool/hook paths refresh live owned slots, preserve stale
 // slots whose owner server is still alive, and cull stale slots whose owner is
 // gone. Managed stale slots terminate the child process tree, then force-kill
 // after 20s when needed; unmanaged stale slots are only unlinked.
-//
-// When the cap is reached after culling, launch_agent is REJECTED (never
-// queued). Free a slot with list_agents + kill_agent, then retry.
-{
-  "globalConcurrentSubagents": 20
-}
+//
+// When the cap is reached after culling, launch_agent is REJECTED (never
+// queued). Free a slot with list_agents + kill_agent, then retry.
+{
+  "globalConcurrentSubagents": 20
+}

package/dist/index.js

@@ -24,9 +24,8 @@ import * as modelMode from "./orchestration/model-mode.js";
 import { startLivenessHeartbeat } from "./orchestration/liveness.js";
 import { ensureParentMarker } from "./launch-prompt.js";
 const agents = new Map();
-const MAX_CLAUDE = 5;
-const MAX_CODEX = 5;
 const deadlockWindow = createDeadlockWindow();
+const STDOUT_RING_BYTES = 2 * 1024 * 1024;
 // Advanced-ruleset gate: per-process latch with exactly the deadlock-window
 // scoping. The env-check runs lazily at the FIRST launch_agent call; success
 // latches enabled/disabled for the process lifetime, failure never latches.
@@ -290,12 +289,96 @@ function failureTypeForError(error, stderr) {
         : classifyFailureReason(error.message, stderr);
 }
 const isWindows = process.platform === "win32";
-let _npmPrefix = null;
+// Resolved lazily and memoized on first use so that plain CLI invocations never
+// spawn `npm prefix -g` at import time. The server warms this once during
+// startup (see main()) so a live, long-lived server never stalls mid-request.
+let npmPrefixCache;
 function getNpmPrefix() {
-    if (!_npmPrefix) {
-        _npmPrefix = execSync("npm prefix -g", { encoding: "utf-8" }).trim();
+    if (npmPrefixCache === undefined) {
+        npmPrefixCache = execSync("npm prefix -g", { encoding: "utf-8" }).trim();
+    }
+    return npmPrefixCache;
+}
+const CLAUDE_BACKGROUND_RESUME_TEXT = "Your background task has completed. Resume and continue where you left off.";
+export function isClaudeBackgroundWakeLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return false;
+    try {
+        const evt = JSON.parse(trimmed);
+        if (evt.type === "result")
+            return false;
+        const method = typeof evt.method === "string" ? evt.method : "";
+        const type = typeof evt.type === "string" ? evt.type : "";
+        const name = typeof evt.name === "string" ? evt.name : "";
+        const marker = `${method} ${type} ${name}`.toLowerCase();
+        if (marker.includes("task_notification") || marker.includes("task-notification"))
+            return true;
+        if (marker.includes("background") && marker.includes("complete"))
+            return true;
+        if (marker.includes("taskoutput") && marker.includes("complete"))
+            return true;
+        // No concrete Claude bg-task-complete JSONL fixture exists in-repo. As a
+        // backstop, any non-result JSONL activity after a finished turn means the
+        // still-live SDK stream observed something new and needs a nudge.
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function noteBackgroundResumeSignal(agent, at) {
+    if (agent.provider !== "claude" || agent.driver.closed)
+        return;
+    agent.bgTaskResumeObservedAt = Math.max(agent.bgTaskResumeObservedAt ?? 0, at);
+}
+export async function maybeResumeAfterBackgroundTask(agent, now = Date.now()) {
+    if (agent.provider !== "claude")
+        return false;
+    if (agent.driver.closed)
+        return false;
+    if (agent.bgTaskResumeInFlight)
+        return false;
+    const observedAt = agent.bgTaskResumeObservedAt ?? 0;
+    if (observedAt === 0 || observedAt <= (agent.bgTaskResumeSentAt ?? 0))
+        return false;
+    agent.bgTaskResumeInFlight = true;
+    try {
+        if (typeof agent.driver.notifyTaskComplete === "function") {
+            await agent.driver.notifyTaskComplete(CLAUDE_BACKGROUND_RESUME_TEXT);
+        }
+        else {
+            await agent.driver.send(CLAUDE_BACKGROUND_RESUME_TEXT);
+        }
+        agent.bgTaskResumeSentAt = observedAt;
+        agent.status = "processing";
+        agent.lastExitCode = agent.exitCode;
+        agent.lastExitedAt = agent.exitedAt;
+        agent.exitCode = null;
+        agent.exitedAt = null;
+        agent.waitReported = false;
+        agent.turnCompleted = false;
+        agent.lastActivity = now;
+        return true;
+    }
+    finally {
+        agent.bgTaskResumeInFlight = false;
+    }
+}
+function handleCompletedStdoutLines(agent, lines, at) {
+    let turnWasComplete = agent.turnCompleted === true;
+    for (const line of lines) {
+        if (turnWasComplete && isClaudeBackgroundWakeLine(line)) {
+            noteBackgroundResumeSignal(agent, at);
+        }
+        if (isTurnCompletedLine(agent.provider, line)) {
+            turnWasComplete = true;
+            agent.turnCompleted = true;
+            agent.status = "finished";
+            if (agent.exitedAt === null)
+                agent.exitedAt = at;
+        }
     }
-    return _npmPrefix;
 }
 function resolveExe(provider) {
     return resolveExeFor(provider, process.platform, { existsSync, npmPrefix: getNpmPrefix });
@@ -311,17 +394,6 @@ function cleanupUcSettings(agentState) {
         agentState.ucSettingsPath = undefined;
     }
 }
-// Concurrency cap accounting: only `processing` agents count against a
-// provider's cap. `stalled` agents (live but quiet past the heartbeat window) do
-// NOT count, freeing a slot while they idle.
-function countProcessing(provider) {
-    let count = 0;
-    for (const a of agents.values()) {
-        if (a.provider === provider && a.status === "processing")
-            count++;
-    }
-    return count;
-}
 // Synchronously reconcile a single agent's status against the pure transition
 // helper. Folds the live process exitCode into AgentState first so an already-
 // exited process is reported as completed/failed immediately (no monitor lag).
@@ -347,6 +419,12 @@ const reconcileInterval = setInterval(() => {
     for (const agent of agents.values()) {
         reconcileAgent(agent, now);
         refreshLiveSlotMetadata(agent, now);
+        if (agent.bgTaskResumeObservedAt && agent.bgTaskResumeObservedAt > (agent.bgTaskResumeSentAt ?? 0)) {
+            void maybeResumeAfterBackgroundTask(agent, now).then((resumed) => {
+                if (resumed)
+                    updateSlotMetadata(agent);
+            });
+        }
     }
 }, 10000);
 reconcileInterval.unref();
@@ -363,7 +441,7 @@ const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (fu
 const SUBAGENT_INSTRUCTIONS = "SUB-AGENT SESSION: you are a child process launched by subagent-mcp. Follow the parent prompt. Do not treat yourself as the orchestrator, do not re-trigger orchestration carryover, and do not launch further sub-agents unless the parent prompt explicitly assigns that.\n\nMODEL SELECTION MODE (parallel to orchestration-mode, set via the model-selection-mode tool). DEFAULT is \"smart\" and is used whenever unset: in smart, launch_agent REJECTS any call supplying provider/model/effort selectors and the server auto-picks the best model. \"user-approved-overrides\" opens a 30-MINUTE window where selectors are HONORED, enforced LAZILY (the mode reverts to smart on the next launch_agent call after 30 minutes) and re-enabling does NOT extend an active window. HONOR-BASED: you MUST NOT set \"user-approved-overrides\" without explicit interactive USER authorization via the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex); never enable it on your own initiative.";
 const server = new McpServer({
     name: "subagent-mcp",
-    version: "2.10.4",
+    version: "2.12.1",
     description: "Launches always-interactive local Claude and Codex sub-agent sessions and is the orchestrator's sole launch channel. Claude runs via the Claude Agent SDK over the local Claude Code executable; Codex via `codex app-server` over stdio. The server never calls Anthropic or OpenAI HTTP APIs directly.",
 }, {
     instructions: process.env.SUBAGENT_MCP_SUBAGENT === "1"
@@ -394,13 +472,6 @@ function cleanupUcSettingsPath(ucSettingsPath) {
 // process. Any launch-time failure cleans up and is reported so the attempt loop
 // silently advances to the next candidate.
 async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetInfo) {
-    // Concurrency cap for this provider.
-    const running = countProcessing(candidate.provider);
-    const max = candidate.provider === "claude" ? MAX_CLAUDE : MAX_CODEX;
-    if (running >= max) {
-        const reason = `Maximum ${max} concurrent ${candidate.provider} agents already running. Current: ${running}`;
-        return { reason, failure_type: "permanent" };
-    }
     // Build the command. haiku ignores effort; pass "high" placeholder for the
     // "none" sentinel (buildCommand drops it for haiku anyway).
     const effortForBuild = candidate.effort === "none" ? "high" : candidate.effort;
@@ -499,6 +570,8 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
         stderr: "",
         exitCode: null,
         exitedAt: null,
+        lastExitCode: null,
+        lastExitedAt: null,
         // Launch time is the initial heartbeat. Only PARSED VISIBLE provider stream
         // items refresh lastActivity afterwards (see the stdout handler); raw
         // stdout/stderr chunks do NOT, so `stalled` means exactly "no visible
@@ -529,6 +602,9 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
             // Accumulate all complete lines into stored stdout.
             for (const line of lines) {
                 agentState.stdout += line + "\n";
+                if (agentState.stdout.length > STDOUT_RING_BYTES) {
+                    agentState.stdout = agentState.stdout.slice(-STDOUT_RING_BYTES);
+                }
             }
             if (items.length > 0) {
                 // Heartbeat refreshes only on parsed visible provider stream items,
@@ -541,11 +617,12 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
             // logical interactive session can remain available for later messages.
             // Scan COMPLETE lines only so a marker split across chunks is matched
             // once fully assembled (never on a partial fragment).
-            if (lines.some((l) => isTurnCompletedLine(agentState.provider, l))) {
-                agentState.turnCompleted = true;
-                agentState.status = "finished";
-                if (agentState.exitedAt === null)
-                    agentState.exitedAt = at;
+            handleCompletedStdoutLines(agentState, lines, at);
+            if (agentState.bgTaskResumeObservedAt && agentState.bgTaskResumeObservedAt > (agentState.bgTaskResumeSentAt ?? 0)) {
+                void maybeResumeAfterBackgroundTask(agentState, at).then((resumed) => {
+                    if (resumed)
+                        updateSlotMetadata(agentState);
+                });
             }
         });
     }
@@ -565,15 +642,13 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
             agentState.streamBuf = "";
             for (const line of lines) {
                 agentState.stdout += line + "\n";
+                if (agentState.stdout.length > STDOUT_RING_BYTES) {
+                    agentState.stdout = agentState.stdout.slice(-STDOUT_RING_BYTES);
+                }
             }
             // A completion marker may arrive only in this final flush (no trailing
             // newline) — the grace window's success exception needs it.
-            if (lines.some((l) => isTurnCompletedLine(agentState.provider, l))) {
-                agentState.turnCompleted = true;
-                agentState.status = "finished";
-                if (agentState.exitedAt === null)
-                    agentState.exitedAt = at;
-            }
+            handleCompletedStdoutLines(agentState, lines, at);
             if (items.length > 0) {
                 agentState.lastActivity = at;
                 agentState.visibleStream = retainLastN(agentState.visibleStream, items.map((it) => ({ ...it, at })), 3);
@@ -973,13 +1048,10 @@ server.tool("poll_agent", "Get an agent's current status and output. `processing
                     model: agent.model,
                     status: agent.status,
                     exit_code: agent.exitCode,
-                    stdout_tail: stdoutTail,
-                    stderr_tail: stderrTail,
                     started_at: agent.startedAt,
                     last_activity: agent.lastActivity,
                     cwd: agent.cwd,
                     ...liveness,
-                    ...(agent.routingTier !== undefined ? { routing_tier: agent.routingTier } : {}),
                     ...(agent.rulesetApplied
                         ? {
                             ruleset_applied: true,
@@ -998,7 +1070,11 @@ server.tool("poll_agent", "Get an agent's current status and output. `processing
                         at: it.at !== undefined ? formatLocalIso(it.at) : null,
                     })),
                     ...(params.verbose
-                        ? { final_output: extractFinalTurn(agent.provider, agent.stdout) }
+                        ? {
+                            stdout_tail: stdoutTail,
+                            stderr_tail: stderrTail,
+                            final_output: extractFinalTurn(agent.provider, agent.stdout),
+                        }
                         : {}),
                 }),
             },
@@ -1119,6 +1195,8 @@ server.tool("send_message", "Enqueue a user message for an open interactive agen
         await agent.driver.send(params.message);
         const now = Date.now();
         agent.status = "processing";
+        agent.lastExitCode = agent.exitCode;
+        agent.lastExitedAt = agent.exitedAt;
         agent.exitCode = null;
         agent.exitedAt = null;
         agent.waitReported = false;
@@ -1218,7 +1296,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
             a.waitReported = true;
         const payload = { finished: unreported.map(buildFinishedEntry) };
         return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(payload) }],
         };
     }
     // Step 2: nothing alive and nothing unreported (includes stopped-but-not-yet-closed).
@@ -1233,7 +1311,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
             message: "No agents are running or waiting to finish.",
         };
         return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(payload) }],
         };
     }
     // Step 3: block-poll until a terminal agent appears or deadline passes
@@ -1246,7 +1324,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
                 a.waitReported = true;
             const payload = { finished: unreported.map(buildFinishedEntry) };
             return {
-                content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(payload) }],
             };
         }
     }
@@ -1260,7 +1338,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
         hint: "15 minutes elapsed with no agent finishing. Call wait again to block for another 15 minutes or until the next agent finishes.",
     };
     return {
-        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(payload) }],
     };
 }));
 // Tool 7: orchestration-mode
@@ -1519,6 +1597,7 @@ if (isMain) {
     // default-ON this rarely fires.
     // (the tool's enabled:false writes a disable record via writeDisable /
     // writeDisableCwd; it does not call disable().)
+    getNpmPrefix();
     startLivenessHeartbeat();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/orchestration/hook-core.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { closeSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import * as marker from "./marker.js";
 import * as reminder from "./reminder.js";
 import { cullStaleSlots, slotDir, ZOMBIE_FORCE_GRACE_MS, } from "../concurrency.js";
@@ -37,9 +37,18 @@ export const REMINDER_PERIOD = 5;
  * === <repoRoot>/directives.
  */
 export function resolveDirectivesDir(env) {
-    const root = env.CLAUDE_PLUGIN_ROOT || env.PLUGIN_ROOT;
-    if (root) {
-        return join(root, "directives");
+    const rootEnvName = env.CLAUDE_PLUGIN_ROOT !== undefined
+        ? "CLAUDE_PLUGIN_ROOT"
+        : env.PLUGIN_ROOT !== undefined
+            ? "PLUGIN_ROOT"
+            : undefined;
+    if (rootEnvName) {
+        const root = env[rootEnvName] ?? "";
+        const directivesDir = join(root, "directives");
+        if (!isAbsolute(root) || !existsSync(directivesDir)) {
+            throw new Error(`${rootEnvName} must be an absolute path with an existing directives directory: ${root}`);
+        }
+        return directivesDir;
     }
     const here = dirname(fileURLToPath(import.meta.url));
     // Compiled location is dist/orchestration/hook-core.js, so ../../directives
@@ -50,8 +59,9 @@ export function resolveDirectivesDir(env) {
 }
 /** Read a directive asset by filename. On ANY failure return '' (fail-safe). */
 export function readDirective(env, fileName) {
+    const directivesDir = resolveDirectivesDir(env);
     try {
-        return readFileSync(join(resolveDirectivesDir(env), fileName), "utf8");
+        return readFileSync(join(directivesDir, fileName), "utf8");
     }
     catch {
         return "";