@heretyc/subagent-mcp 2.8.2 → 2.8.3

package/directives/carryover-claude.md

@@ -1,17 +1,13 @@
-<ORCHESTRATION-INVARIANT>
-Sub-agent sessions (first prompt began "<this is a request from a parent process>"): ignore this block.
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-CARRYOVER>
 
-ORCHESTRATION MODE carried over ON from a PRIOR session of this project
-(persists until disabled with permission). Not user-enabled THIS session.
+Orchestration MODE was ON at session start — carried over from PRIOR session for this project (persists until disabled with permission). Not enabled THIS session.
 
 THIS turn, ONCE:
 1. NOTIFY user it carried over.
 2. ASK keep ON? via AskUserQuestion.
-3. ADVISE fit: long-horizon context-filling → keep ON; bounded, interactive, or
-   core-bound to main-session-only MCP → propose OFF.
+3. ADVISE fit: long-horizon context-filling → keep ON; bounded/interactive/core-bound to main-session-only MCP → propose OFF.
 
-Until answered, the mandates below still bind. Declines → orchestration-mode
-enabled:false. NEVER disable on own initiative. After answer: handshake done —
-do not re-raise.
+Declines → orchestration-mode enabled:false. NEVER disable on own initiative. After answer: handshake done — do not re-raise.
 
-</ORCHESTRATION-INVARIANT>
+</ORCHESTRATION-CARRYOVER>

package/directives/carryover-codex.md

@@ -1,17 +1,13 @@
-<ORCHESTRATION-INVARIANT>
-Sub-agent sessions (first prompt began "<this is a request from a parent process>"): ignore this block.
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-CARRYOVER>
 
-ORCHESTRATION MODE carried over ON from a PRIOR session of this project
-(persists until disabled with permission). Not user-enabled THIS session.
+Orchestration MODE was ON at session start — carried over from PRIOR session for this project (persists until disabled with permission). Not enabled THIS session.
 
 THIS turn, ONCE:
 1. NOTIFY user it carried over.
 2. ASK keep ON? via request-user-input.
-3. ADVISE fit: long-horizon context-filling → keep ON; bounded, interactive, or
-   core-bound to main-session-only MCP → propose OFF.
+3. ADVISE fit: long-horizon context-filling → keep ON; bounded/interactive/core-bound to main-session-only MCP → propose OFF.
 
-Until answered, the mandates below still bind. Declines → orchestration-mode
-enabled:false. NEVER disable on own initiative. After answer: handshake done —
-do not re-raise.
+Declines → orchestration-mode enabled:false. NEVER disable on own initiative. After answer: handshake done — do not re-raise.
 
-</ORCHESTRATION-INVARIANT>
+</ORCHESTRATION-CARRYOVER>

package/directives/orchestration-claude.md

@@ -1,14 +1,22 @@
-<ORCHESTRATION-INVARIANT>
-ORCHESTRATION ON. Delegate-default through subagent-mcp; route EVERY sub-agent launch ONLY via subagent-mcp launch_agent. Inline ONLY main-session-only-capability steps (non-inheritable MCP, interactive/consent, verify reruns); temp scratch-file IPC allowed. Repo/system safety rules outrank this.
-- Ruthlessly preserve orchestrator context, NO EXCEPTIONS.
-- Subagents ask questions through the orchestrator; answers
-return to subagents.
-- Sub-agents use %TEMP%, /tmp/, /TEMP/ for all IPC.
-- NEVER DISABLE ORCHESTRATION: never on own initiative. Propose via AskUserQuestion only; disable only after explicit user permission.
-Orchestration Steps:
-1. Map out work before orchestrating.
-2. Decompose into phases which have atomic tasks that are separate subagents. Phases = understand → design → implement → review.
-3. Execute the phases, dispatching sub-agents and between EACH phase dispatch a quality-review sub-agent to validate all work done.
-
-- For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
-</ORCHESTRATION-INVARIANT>
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-INVARIANT priority="CRITICAL" override="NONE">
+SCOPE: If this session's prompt begins with "<this is a request from a parent process>", SUB-AGENT-INVARIANT does NOT apply to this session, SKIP the remainder of this directive.
+
+ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+
+INLINE BY RIGHT (no violation): steps bound to main-session-only capability —
+MCP tools sub-agents can't inherit, interactive/consent tools, tight verify
+loops. State which + why, one line.
+
+MUST DELEGATE/OFFLOAD (breach if not): pure compute (parse/aggregate/transform);
+any payload >50KB or >200 lines → scratch file, hand off the PATH.
+Mixed task = SPLIT. One MCP-bound step never makes the whole task inline.
+
+CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
+User tool-pin re-partitions work; does not suspend mode.
+
+IPC = temp scratch files ONLY. Windows: %TEMP%. POSIX: /tmp.
+Full model + governance: server MCP instructions.
+DISABLE: never on own initiative. Propose via AskUserQuestion only.
+
+</ORCHESTRATION-INVARIANT>

package/directives/orchestration-codex.md

@@ -1,13 +1,22 @@
-<ORCHESTRATION-INVARIANT>
-SCOPE: this session's first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1? Sub-agent session — this ORCHESTRATION-INVARIANT does NOT apply; SKIP this block.
-ORCHESTRATION ON. Delegate-default through subagent-mcp; route EVERY sub-agent launch ONLY via subagent-mcp launch_agent. Inline ONLY main-session-only-capability steps (non-inheritable MCP, interactive/consent, verify reruns); temp scratch-file IPC allowed. Repo/system safety rules outrank this.
-- Ruthlessly preserve orchestrator context, NO EXCEPTIONS.
-- Subagents ask questions through the orchestrator; answers
-return to subagents.
-- Sub-agents use %TEMP%, /tmp/, /TEMP/ for all IPC.
-- NEVER DISABLE ORCHESTRATION: never on own initiative. Propose via request-user-input only; disable only after explicit user permission.
-Orchestration Steps:
-1. Map out work before orchestrating.
-2. Decompose into phases which have atomic tasks that are separate subagents. Phases = understand → design → implement → review.
-3. Execute the phases, dispatching sub-agents and between EACH phase dispatch a quality-review sub-agent to validate all work done.
-</ORCHESTRATION-INVARIANT>
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-INVARIANT priority="CRITICAL" override="NONE">
+SCOPE: If this session's prompt begins with "<this is a request from a parent process>", SUB-AGENT-INVARIANT does NOT apply to this session, SKIP the remainder of this directive.
+
+ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+
+INLINE BY RIGHT (no violation): steps bound to main-session-only capability —
+MCP tools sub-agents can't inherit, interactive/consent tools, tight verify
+loops. State which + why, one line.
+
+MUST DELEGATE/OFFLOAD (breach if not): pure compute (parse/aggregate/transform);
+any payload >50KB or >200 lines → scratch file, hand off the PATH.
+Mixed task = SPLIT. One MCP-bound step never makes the whole task inline.
+
+CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
+User tool-pin re-partitions work; does not suspend mode.
+
+IPC = temp scratch files ONLY. Windows: %TEMP%. POSIX: /tmp.
+Full model + governance: server MCP instructions.
+DISABLE: never on own initiative. Propose via request-user-input only.
+
+</ORCHESTRATION-INVARIANT>

package/directives/reminder-off-claude.md

@@ -1,9 +1,8 @@
+<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
 <ORCHESTRATION-INVARIANT>
-ZERO EXCEPTIONS SUBAGENT MANDATES:
-5-CALL RULE: >5 tool calls needed for this request (all turns, no reset), or >5 already spent? Count reads, greps, test runs. If yes do NOT grind on inline - STOP and ask via AskUserQuestion whether to switch orchestration ON. That STOP+ask satisfies this rule; if the user declines, inline is authorized for THIS request - do not re-ask it.
-Why this exists: agents grind through large work without ever considering orchestration.
-ORCHESTRATION OFF - still binding:
-INVARIANT ZERO EXCEPTIONS SOLE CHANNEL: ANY sub-agent launch goes ONLY via the subagent-mcp; harness-native Task/Agent tools are FORBIDDEN while this server is connected.
-Advisory: At all times, delegating via subagent-mcp auto routing is advisable - do not assume your training data is still current.
-For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+
+Orchestration OFF. 5-CALL RULE: request likely needs >5 tool calls, OR 5th call done with work remaining — STOP, ask via AskUserQuestion whether to switch Orchestration ON. Even OFF, delegating via subagent-mcp auto routing advisable for durable results — calling model not always best fit. Sub-agent sessions: ignore.
+
+WAIT-NOT-POLL: learn agent finish via `wait` — blocks until terminal exit, returns exit status (`verbose: true` for final output). Never loop `poll_agent` for completion (floods orchestrator context). `poll_agent` = single-call diagnostic on one agent (stalled stream, one-shot output). Stalled = alive, NOT dead.
+
 </ORCHESTRATION-INVARIANT>

package/directives/reminder-off-codex.md

@@ -1,9 +1,8 @@
+<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
 <ORCHESTRATION-INVARIANT>
-ZERO EXCEPTIONS SUBAGENT MANDATES:
-5-CALL RULE: >5 tool calls needed for this request (all turns, no reset), or >5 already spent? Count reads, greps, test runs. If yes do NOT grind on inline - STOP and ask via request-user-input whether to switch orchestration ON. That STOP+ask satisfies this rule; if the user declines, inline is authorized for THIS request - do not re-ask it.
-Why this exists: agents grind through large work without ever considering orchestration.
-ORCHESTRATION OFF - still binding:
-INVARIANT ZERO EXCEPTIONS SOLE CHANNEL: ANY sub-agent launch goes ONLY via the subagent-mcp; harness-native Task/Agent tools are FORBIDDEN while this server is connected.
-Advisory: At all times, delegating via subagent-mcp auto routing is advisable - do not assume your training data is still current.
-For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+
+Orchestration OFF. 5-CALL RULE: request likely needs >5 tool calls, OR 5th call done with work remaining — STOP, ask via request-user-input whether to switch Orchestration ON. Even OFF, delegating via subagent-mcp auto routing advisable for durable results — calling model not always best fit. Sub-agent sessions: ignore.
+
+WAIT-NOT-POLL: learn agent finish via `wait` — blocks until terminal exit, returns exit status (`verbose: true` for final output). Never loop `poll_agent` for completion (floods orchestrator context). `poll_agent` = single-call diagnostic on one agent (stalled stream, one-shot output). Stalled = alive, NOT dead.
+
 </ORCHESTRATION-INVARIANT>

package/directives/reminder-on.md

@@ -1,15 +1,8 @@
+<!-- INJECTED PER-PROMPT REMINDER — BINDING -->
 <ORCHESTRATION-INVARIANT>
-ORCHESTRATION ON. Route EVERY sub-agent launch ONLY via subagent-mcp launch_agent. Inline ONLY main-session-only-capability steps; temp scratch-file IPC allowed. Repo/system safety rules outrank this.
-- Delegate-default. 5-CALL RULE is satisfied by delegation.
-EVERY reply starts: route: delegate|inline - <reason>
-- Ruthlessly preserve orchestrator context, NO EXCEPTIONS.
-- Subagents ask questions through the orchestrator; answers
-return to subagents.
-- Sub-agents use %TEMP%, /tmp/, /TEMP/ for all IPC.
-Orchestration Steps:
-1. Map out work before orchestrating.
-2. Decompose into phases which have atomic tasks that are separate subagents. Phases = understand → design → implement → review.
-3. Execute the phases, dispatching sub-agents and between EACH phase dispatch a quality-review sub-agent to validate all work done.
 
-- For Sub-agent sessions ONLY (first prompt began "<this is a request from a parent process>" or env SUBAGENT_MCP_SUBAGENT=1): ignore this block.
+Orchestration ON. Delegate-default: decompose, delegate, keep orchestrator context lean. 5-CALL RULE satisfied by delegation. Full model + governance: server MCP instructions. Sub-agent sessions: ignore.
+
+WAIT-NOT-POLL: learn agent finish via `wait` — blocks until terminal exit, returns exit status (`verbose: true` for final output). Never loop `poll_agent` for completion (floods orchestrator context). `poll_agent` = single-call diagnostic on one agent (stalled stream, one-shot output). Stalled = alive, NOT dead.
+
 </ORCHESTRATION-INVARIANT>

package/directives/short-off.md

@@ -0,0 +1 @@
+<SUB-AGENT-INVARIANT>Orchestration OFF. 5-CALL RULE applies this turn. Obey last <ORCHESTRATION-INVARIANT> block.</SUB-AGENT-INVARIANT>

package/directives/short-on.md

@@ -0,0 +1 @@
+<SUB-AGENT-INVARIANT>Orchestration ON. 5-CALL RULE applies this turn. Run user request now via orchestration steps. Obey last <ORCHESTRATION-INVARIANT> block.</SUB-AGENT-INVARIANT>

package/dist/hooks/orchestration-claude.js

@@ -43,7 +43,8 @@ export const claudeAdapter = {
         return countJsonlType(transcriptPath, "user");
     },
     fullDirectiveFile: "orchestration-claude.md",
-    offTurnFile: "off-turn-reminder.md",
+    shortOnFile: "short-on.md",
+    shortOffFile: "short-off.md",
     carryoverDirectiveFile: "carryover-claude.md",
     reminderOnFile: "reminder-on.md",
     reminderOffFile: "reminder-off-claude.md",

package/dist/hooks/orchestration-codex.js

@@ -58,7 +58,8 @@ export const codexAdapter = {
         return countJsonlType(transcriptPath, "turn_context");
     },
     fullDirectiveFile: "orchestration-codex.md",
-    offTurnFile: "off-turn-reminder.md",
+    shortOnFile: "short-on.md",
+    shortOffFile: "short-off.md",
     carryoverDirectiveFile: "carryover-codex.md",
     reminderOnFile: "reminder-on.md",
     reminderOffFile: "reminder-off-codex.md",

package/dist/orchestration/hook-core.js

@@ -179,10 +179,10 @@ export function classifyClaim(owner_session, baseline_turn, current) {
  * temp dir cannot hold the state file would otherwise inject only the compact
  * rule carrier on every prompt and never refresh the LONG block.
  */
-function cadenceEmit(env, adapter, longFile, count, persisted) {
+function cadenceEmit(env, adapter, longFile, shortFile, count, persisted) {
     return !persisted || count % REMINDER_PERIOD === 0
         ? readDirective(env, longFile)
-        : readDirective(env, adapter.offTurnFile);
+        : readDirective(env, shortFile);
 }
 /**
  * Claim (or re-claim) an active marker for the current session and emit the
@@ -237,7 +237,7 @@ export function runHook(payload, env, adapter) {
         if (!marker.isActive(cwd)) {
             // 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);
+            return cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted);
         }
         const m = marker.readMarker(cwd);
         const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
@@ -247,7 +247,7 @@ export function runHook(payload, env, adapter) {
         }
         // SAME-SESSION: per-prompt reminder cadence, ON variant.
         const r = reminder.advance(cwd, current);
-        return cadenceEmit(env, adapter, adapter.reminderOnFile, r.count, r.persisted);
+        return cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.

package/dist/setup.js

@@ -232,7 +232,8 @@ export function verifyInstall(root = INSTALL_ROOT) {
         "dist/hooks/orchestration-codex.js",
         "directives/orchestration-claude.md",
         "directives/orchestration-codex.md",
-        "directives/off-turn-reminder.md",
+        "directives/short-on.md",
+        "directives/short-off.md",
         "directives/reminder-on.md",
         "directives/reminder-off-claude.md",
         "directives/reminder-off-codex.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "MCP server that launches and manages local Claude Code and Codex CLI sub-agents as child processes (no direct Anthropic/OpenAI API).",
   "type": "module",
   "main": "dist/index.js",

package/scripts/postinstall.mjs

@@ -71,7 +71,7 @@ try {
   // Detected vendors — concrete, so the user knows what setup will touch.
   if (hasClaude || hasCodex) {
     line("  Detected on this machine:");
-    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit/PreToolUse hooks)");
+    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit/PreToolUse hooks)");
     if (hasCodex) line("    - Codex CLI        (will get MCP server + SessionStart/UserPromptSubmit hooks)");
   } else {
     line("  No Claude Code or Codex CLI detected yet. Install one,");

package/directives/off-turn-reminder.md

@@ -1 +0,0 @@
-<ORCHESTRATION-INVARIANT> SUBAGENT MANDATES bind THIS turn. 5-CALL RULE APPLIES. SOLE CHANNEL: launch sub-agents ONLY via subagent-mcp. OFF: ask before enabling orchestration. ON replies must start: route: delegate|inline - <reason>. </ORCHESTRATION-INVARIANT>