opencode-swarm 5.1.8 → 5.2.0

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-5.1.5-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-5.2.0-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
   <img src="https://img.shields.io/badge/agents-7-orange" alt="Agents">
-  <img src="https://img.shields.io/badge/tests-1034-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-1101-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -334,6 +334,12 @@ bunx opencode-swarm uninstall --clean
 
 ## What's New
 
+### v5.2.0 — Per-Invocation Guardrails
+- **Per-invocation budget isolation** — Guardrail limits (tool calls, duration, errors) now reset with each agent delegation. Second invocation of the same agent gets a fresh budget, preventing false circuit breaker trips in long-running projects.
+- **Architect protocol enforcement** — New mandatory QA gate rules: every coder task must go through reviewer approval + test_engineer verification before the next coder task. Protocol violations detected at runtime with warning injection.
+- **Invocation window observability** — Circuit breaker logs now include `invocationId` and `windowKey` for precise debugging of which specific agent invocation hit limits.
+- **67 new tests** — 1101 total tests across 48 files (up from 1034 in v5.1.x).
+
 ### v5.0.0 — Verifiable Execution
 - **Canonical plan schema** — Machine-readable `plan.json` with Zod-validated `PlanSchema`/`TaskSchema`/`PhaseSchema`. Automatic migration from legacy `plan.md` format. Structured status tracking (`pending`, `in_progress`, `completed`, `blocked`).
 - **Evidence bundles** — Per-task execution evidence persisted to `.swarm/evidence/`. Five evidence types: `review`, `test`, `diff`, `approval`, `note`. Sanitized task IDs, atomic writes, configurable size limits. `/swarm evidence` to view, `/swarm archive` to manage retention.
@@ -512,6 +518,18 @@ Profiles merge with base config — only specified fields are overridden.
 
 > **Architect is exempt/unlimited by default:** The architect agent has no guardrail limits by default. To override, add a `profiles.architect` entry in your guardrails config.
 
+### Per-Invocation Budgets
+
+Guardrail limits are enforced **per-invocation**, not per-session. Each time the architect delegates to an agent, that agent gets a fresh budget of tool calls, duration, and error tolerance.
+
+**Example**: If `max_tool_calls: 200`, then:
+- Architect → Coder (task 1) → 200 calls available
+- Coder finishes → Architect → Coder (task 2) → 200 calls available again
+
+This prevents long-running projects from accumulating session-wide counters that incorrectly trip the circuit breaker on later tasks.
+
+> **Architect is unlimited**: The architect never creates invocation windows and has no guardrail limits by default.
+
 ### Disable Guardrails
 
 ```json
@@ -564,7 +582,7 @@ bun test
 bun test tests/unit/config/schema.test.ts
 ```
 
-1034 tests across 45 files covering config, tools, agents, hooks, commands, state, guardrails, evidence, plan schemas, and circuit breaker race conditions. Uses Bun's built-in test runner — zero additional test dependencies.
+1101 tests across 48 files covering config, tools, agents, hooks, commands, state, guardrails, evidence, plan schemas, circuit breaker race conditions, invocation windows, and multi-invocation isolation. Uses Bun's built-in test runner — zero additional test dependencies.
 
 ## Troubleshooting
 

package/dist/index.js

@@ -14015,7 +14015,23 @@ You THINK. Subagents DO. You have the largest context window and strongest reaso
 3. ONE task per {{AGENT_PREFIX}}coder call. Never batch.
 4. Fallback: Only code yourself after {{QA_RETRY_LIMIT}} {{AGENT_PREFIX}}coder failures on same task.
 5. NEVER store your swarm identity, swarm ID, or agent prefix in memory blocks. Your identity comes ONLY from your system prompt. Memory blocks are for project knowledge only.
-6. **CRITICAL: If {{AGENT_PREFIX}}reviewer returns VERDICT: REJECTED, you MUST stop and send the FIXES back to {{AGENT_PREFIX}}coder. Do NOT proceed to test generation or mark the task complete. The review is a gate \u2014 APPROVED is required to proceed.**
+6. **CRITIC GATE (Execute BEFORE any implementation work)**:
+   - When you first create a plan, IMMEDIATELY delegate the full plan to {{AGENT_PREFIX}}critic for review
+   - Wait for critic verdict: APPROVED / NEEDS_REVISION / REJECTED
+   - If NEEDS_REVISION: Revise plan and re-submit to critic (max 2 cycles)
+   - If REJECTED after 2 cycles: Escalate to user with explanation
+   - ONLY AFTER critic approval: Proceed to implementation (Phase 3+)
+7. **MANDATORY QA GATE (Execute AFTER every coder task)**:
+   - Step A: {{AGENT_PREFIX}}coder completes implementation \u2192 STOP
+   - Step B: IMMEDIATELY delegate to {{AGENT_PREFIX}}reviewer with CHECK dimensions (security, correctness, edge-cases, etc.)
+   - Step C: Wait for reviewer verdict
+     - If VERDICT: REJECTED \u2192 Send FIXES back to {{AGENT_PREFIX}}coder (return to Step A)
+     - If VERDICT: APPROVED \u2192 Proceed to Step D
+   - Step D: IMMEDIATELY delegate to {{AGENT_PREFIX}}test_engineer to generate and run tests
+   - Step E: Wait for test verdict
+     - If VERDICT: FAIL \u2192 Send failure details back to {{AGENT_PREFIX}}coder (return to Step A)
+     - If VERDICT: PASS \u2192 Mark task complete, proceed to next task
+8. **NEVER skip the QA gate**: You cannot delegate to {{AGENT_PREFIX}}coder for a new task until the previous task passes BOTH reviewer approval AND test_engineer verification. The sequence is ALWAYS: coder \u2192 reviewer \u2192 test_engineer \u2192 next_coder.
 
 ## AGENTS
 
@@ -15049,39 +15065,33 @@ function startAgentSession(sessionId, agentName, staleDurationMs = 7200000) {
   }
   const sessionState = {
     agentName,
-    startTime: now,
     lastToolCallTime: now,
     lastAgentEventTime: now,
-    toolCallCount: 0,
-    consecutiveErrors: 0,
-    recentToolCalls: [],
-    warningIssued: false,
-    warningReason: "",
-    hardLimitHit: false,
-    lastSuccessTime: now,
-    delegationActive: false
+    delegationActive: false,
+    activeInvocationId: 0,
+    lastInvocationIdByAgent: {},
+    windows: {}
   };
   swarmState.agentSessions.set(sessionId, sessionState);
 }
-function getAgentSession(sessionId) {
-  return swarmState.agentSessions.get(sessionId);
-}
 function ensureAgentSession(sessionId, agentName) {
   const now = Date.now();
   let session = swarmState.agentSessions.get(sessionId);
   if (session) {
     if (agentName && agentName !== session.agentName) {
       session.agentName = agentName;
-      session.startTime = now;
-      session.toolCallCount = 0;
-      session.consecutiveErrors = 0;
-      session.recentToolCalls = [];
-      session.warningIssued = false;
-      session.warningReason = "";
-      session.hardLimitHit = false;
-      session.lastSuccessTime = now;
       session.delegationActive = false;
       session.lastAgentEventTime = now;
+      if (!session.windows) {
+        session.activeInvocationId = 0;
+        session.lastInvocationIdByAgent = {};
+        session.windows = {};
+      }
+    }
+    if (!session.windows) {
+      session.activeInvocationId = 0;
+      session.lastInvocationIdByAgent = {};
+      session.windows = {};
     }
     session.lastToolCallTime = now;
     return session;
@@ -15099,6 +15109,58 @@ function updateAgentEventTime(sessionId) {
     session.lastAgentEventTime = Date.now();
   }
 }
+function beginInvocation(sessionId, agentName) {
+  const session = swarmState.agentSessions.get(sessionId);
+  if (!session) {
+    throw new Error(`Cannot begin invocation: session ${sessionId} does not exist`);
+  }
+  const stripped = stripKnownSwarmPrefix(agentName);
+  if (stripped === ORCHESTRATOR_NAME) {
+    return null;
+  }
+  const lastId = session.lastInvocationIdByAgent[stripped] || 0;
+  const newId = lastId + 1;
+  session.lastInvocationIdByAgent[stripped] = newId;
+  session.activeInvocationId = newId;
+  const now = Date.now();
+  const window = {
+    id: newId,
+    agentName: stripped,
+    startedAtMs: now,
+    toolCalls: 0,
+    consecutiveErrors: 0,
+    hardLimitHit: false,
+    lastSuccessTimeMs: now,
+    recentToolCalls: [],
+    warningIssued: false,
+    warningReason: ""
+  };
+  const key = `${stripped}:${newId}`;
+  session.windows[key] = window;
+  pruneOldWindows(sessionId, 24 * 60 * 60 * 1000, 50);
+  return window;
+}
+function getActiveWindow(sessionId) {
+  const session = swarmState.agentSessions.get(sessionId);
+  if (!session || !session.windows) {
+    return;
+  }
+  const stripped = stripKnownSwarmPrefix(session.agentName);
+  const key = `${stripped}:${session.activeInvocationId}`;
+  return session.windows[key];
+}
+function pruneOldWindows(sessionId, maxAgeMs = 24 * 60 * 60 * 1000, maxWindows = 50) {
+  const session = swarmState.agentSessions.get(sessionId);
+  if (!session || !session.windows) {
+    return;
+  }
+  const now = Date.now();
+  const entries = Object.entries(session.windows);
+  const validByAge = entries.filter(([_, window]) => now - window.startedAtMs < maxAgeMs);
+  const sorted = validByAge.sort((a, b) => b[1].startedAtMs - a[1].startedAtMs);
+  const toKeep = sorted.slice(0, maxWindows);
+  session.windows = Object.fromEntries(toKeep);
+}
 
 // src/commands/benchmark.ts
 var CI = {
@@ -15119,11 +15181,10 @@ async function handleBenchmarkCommand(directory, args) {
       hardLimits: 0,
       warnings: 0
     };
-    e.toolCalls += s.toolCallCount;
-    if (s.hardLimitHit)
-      e.hardLimits++;
-    if (s.warningIssued)
-      e.warnings++;
+    const windows = Object.values(s.windows);
+    e.toolCalls += windows.reduce((sum, w) => sum + w.toolCalls, 0);
+    e.hardLimits += windows.filter((w) => w.hardLimitHit).length;
+    e.warnings += windows.filter((w) => w.warningIssued).length;
     agentMap.set(s.agentName, e);
   }
   const agentHealth = Array.from(agentMap.entries()).map(([a, v]) => ({
@@ -16731,6 +16792,29 @@ function createDelegationGateHook(config2) {
     if (batchingMatches && batchingMatches.length > 0) {
       warnings.push("Batching language detected. Break compound objectives into separate coder calls.");
     }
+    const sessionID = lastUserMessage.info?.sessionID;
+    if (sessionID) {
+      const delegationChain = swarmState.delegationChains.get(sessionID);
+      if (delegationChain && delegationChain.length >= 2) {
+        const coderIndices = [];
+        for (let i = delegationChain.length - 1;i >= 0; i--) {
+          if (stripKnownSwarmPrefix(delegationChain[i].to).includes("coder")) {
+            coderIndices.unshift(i);
+            if (coderIndices.length === 2)
+              break;
+          }
+        }
+        if (coderIndices.length === 2) {
+          const prevCoderIndex = coderIndices[0];
+          const betweenCoders = delegationChain.slice(prevCoderIndex + 1);
+          const hasReviewer = betweenCoders.some((d) => stripKnownSwarmPrefix(d.to) === "reviewer");
+          const hasTestEngineer = betweenCoders.some((d) => stripKnownSwarmPrefix(d.to) === "test_engineer");
+          if (!hasReviewer || !hasTestEngineer) {
+            warnings.push(`\u26A0\uFE0F PROTOCOL VIOLATION: Previous coder task completed, but QA gate was skipped. ` + `You MUST delegate to reviewer (code review) and test_engineer (test execution) ` + `before starting a new coder task. Review RULES 7-8 in your system prompt.`);
+          }
+        }
+      }
+    }
     if (warnings.length === 0)
       return;
     const warningText = `[\u26A0\uFE0F DELEGATION GATE: Your coder delegation may be too complex. Issues:
@@ -16766,6 +16850,9 @@ function createDelegationTrackerHook(config2) {
     const isArchitect = strippedAgent === ORCHESTRATOR_NAME;
     const session = ensureAgentSession(input.sessionID, agentName);
     session.delegationActive = !isArchitect;
+    if (!isArchitect) {
+      beginInvocation(input.sessionID, agentName);
+    }
     if (config2.hooks?.delegation_tracker === true && previousAgent && previousAgent !== agentName) {
       const entry = {
         from: previousAgent,
@@ -16814,24 +16901,35 @@ function createGuardrailsHooks(config2) {
       if (agentConfig.max_duration_minutes === 0 && agentConfig.max_tool_calls === 0) {
         return;
       }
-      if (session.hardLimitHit) {
+      if (!getActiveWindow(input.sessionID)) {
+        const fallbackAgent = swarmState.activeAgent.get(input.sessionID) ?? session.agentName;
+        const stripped = stripKnownSwarmPrefix(fallbackAgent);
+        if (stripped !== ORCHESTRATOR_NAME) {
+          beginInvocation(input.sessionID, fallbackAgent);
+        }
+      }
+      const window = getActiveWindow(input.sessionID);
+      if (!window) {
+        return;
+      }
+      if (window.hardLimitHit) {
         throw new Error("\uD83D\uDED1 CIRCUIT BREAKER: Agent blocked. Hard limit was previously triggered. Stop making tool calls and return your progress summary.");
       }
-      session.toolCallCount++;
+      window.toolCalls++;
       const hash2 = hashArgs(output.args);
-      session.recentToolCalls.push({
+      window.recentToolCalls.push({
         tool: input.tool,
         argsHash: hash2,
         timestamp: Date.now()
       });
-      if (session.recentToolCalls.length > 20) {
-        session.recentToolCalls.shift();
+      if (window.recentToolCalls.length > 20) {
+        window.recentToolCalls.shift();
       }
       let repetitionCount = 0;
-      if (session.recentToolCalls.length > 0) {
-        const lastEntry = session.recentToolCalls[session.recentToolCalls.length - 1];
-        for (let i = session.recentToolCalls.length - 1;i >= 0; i--) {
-          const entry = session.recentToolCalls[i];
+      if (window.recentToolCalls.length > 0) {
+        const lastEntry = window.recentToolCalls[window.recentToolCalls.length - 1];
+        for (let i = window.recentToolCalls.length - 1;i >= 0; i--) {
+          const entry = window.recentToolCalls[i];
           if (entry.tool === lastEntry.tool && entry.argsHash === lastEntry.argsHash) {
             repetitionCount++;
           } else {
@@ -16839,54 +16937,60 @@ function createGuardrailsHooks(config2) {
           }
         }
       }
-      const elapsedMinutes = (Date.now() - session.startTime) / 60000;
-      if (agentConfig.max_tool_calls > 0 && session.toolCallCount >= agentConfig.max_tool_calls) {
-        session.hardLimitHit = true;
+      const elapsedMinutes = (Date.now() - window.startedAtMs) / 60000;
+      if (agentConfig.max_tool_calls > 0 && window.toolCalls >= agentConfig.max_tool_calls) {
+        window.hardLimitHit = true;
         warn("Circuit breaker: tool call limit hit", {
           sessionID: input.sessionID,
-          agentName: session.agentName,
+          agentName: window.agentName,
+          invocationId: window.id,
+          windowKey: `${window.agentName}:${window.id}`,
           resolvedMaxCalls: agentConfig.max_tool_calls,
-          currentCalls: session.toolCallCount
+          currentCalls: window.toolCalls
         });
-        throw new Error(`\uD83D\uDED1 LIMIT REACHED: Tool calls exhausted (${session.toolCallCount}/${agentConfig.max_tool_calls}). Finish the current operation and return your progress summary.`);
+        throw new Error(`\uD83D\uDED1 LIMIT REACHED: Tool calls exhausted (${window.toolCalls}/${agentConfig.max_tool_calls}). Finish the current operation and return your progress summary.`);
       }
       if (agentConfig.max_duration_minutes > 0 && elapsedMinutes >= agentConfig.max_duration_minutes) {
-        session.hardLimitHit = true;
+        window.hardLimitHit = true;
         warn("Circuit breaker: duration limit hit", {
           sessionID: input.sessionID,
-          agentName: session.agentName,
+          agentName: window.agentName,
+          invocationId: window.id,
+          windowKey: `${window.agentName}:${window.id}`,
           resolvedMaxMinutes: agentConfig.max_duration_minutes,
           elapsedMinutes: Math.floor(elapsedMinutes)
         });
         throw new Error(`\uD83D\uDED1 LIMIT REACHED: Duration exhausted (${Math.floor(elapsedMinutes)}/${agentConfig.max_duration_minutes} min). Finish the current operation and return your progress summary.`);
       }
       if (repetitionCount >= agentConfig.max_repetitions) {
-        session.hardLimitHit = true;
+        window.hardLimitHit = true;
         throw new Error(`\uD83D\uDED1 LIMIT REACHED: Repeated the same tool call ${repetitionCount} times. This suggests a loop. Return your progress summary.`);
       }
-      if (session.consecutiveErrors >= agentConfig.max_consecutive_errors) {
-        session.hardLimitHit = true;
-        throw new Error(`\uD83D\uDED1 LIMIT REACHED: ${session.consecutiveErrors} consecutive tool errors detected. Return your progress summary with details of what went wrong.`);
+      if (window.consecutiveErrors >= agentConfig.max_consecutive_errors) {
+        window.hardLimitHit = true;
+        throw new Error(`\uD83D\uDED1 LIMIT REACHED: ${window.consecutiveErrors} consecutive tool errors detected. Return your progress summary with details of what went wrong.`);
       }
-      const idleMinutes = (Date.now() - session.lastSuccessTime) / 60000;
+      const idleMinutes = (Date.now() - window.lastSuccessTimeMs) / 60000;
       if (idleMinutes >= agentConfig.idle_timeout_minutes) {
-        session.hardLimitHit = true;
+        window.hardLimitHit = true;
         warn("Circuit breaker: idle timeout hit", {
           sessionID: input.sessionID,
-          agentName: session.agentName,
+          agentName: window.agentName,
+          invocationId: window.id,
+          windowKey: `${window.agentName}:${window.id}`,
           idleTimeoutMinutes: agentConfig.idle_timeout_minutes,
           idleMinutes: Math.floor(idleMinutes)
         });
         throw new Error(`\uD83D\uDED1 LIMIT REACHED: No successful tool call for ${Math.floor(idleMinutes)} minutes (idle timeout: ${agentConfig.idle_timeout_minutes} min). This suggests the agent may be stuck. Return your progress summary.`);
       }
-      if (!session.warningIssued) {
-        const toolPct = agentConfig.max_tool_calls > 0 ? session.toolCallCount / agentConfig.max_tool_calls : 0;
+      if (!window.warningIssued) {
+        const toolPct = agentConfig.max_tool_calls > 0 ? window.toolCalls / agentConfig.max_tool_calls : 0;
         const durationPct = agentConfig.max_duration_minutes > 0 ? elapsedMinutes / agentConfig.max_duration_minutes : 0;
         const repPct = repetitionCount / agentConfig.max_repetitions;
-        const errorPct = session.consecutiveErrors / agentConfig.max_consecutive_errors;
+        const errorPct = window.consecutiveErrors / agentConfig.max_consecutive_errors;
         const reasons = [];
         if (agentConfig.max_tool_calls > 0 && toolPct >= agentConfig.warning_threshold) {
-          reasons.push(`tool calls ${session.toolCallCount}/${agentConfig.max_tool_calls}`);
+          reasons.push(`tool calls ${window.toolCalls}/${agentConfig.max_tool_calls}`);
         }
         if (durationPct >= agentConfig.warning_threshold) {
           reasons.push(`duration ${Math.floor(elapsedMinutes)}/${agentConfig.max_duration_minutes} min`);
@@ -16895,25 +16999,24 @@ function createGuardrailsHooks(config2) {
           reasons.push(`repetitions ${repetitionCount}/${agentConfig.max_repetitions}`);
         }
         if (errorPct >= agentConfig.warning_threshold) {
-          reasons.push(`errors ${session.consecutiveErrors}/${agentConfig.max_consecutive_errors}`);
+          reasons.push(`errors ${window.consecutiveErrors}/${agentConfig.max_consecutive_errors}`);
         }
         if (reasons.length > 0) {
-          session.warningIssued = true;
-          session.warningReason = reasons.join(", ");
+          window.warningIssued = true;
+          window.warningReason = reasons.join(", ");
         }
       }
     },
     toolAfter: async (input, output) => {
-      const session = getAgentSession(input.sessionID);
-      if (!session) {
+      const window = getActiveWindow(input.sessionID);
+      if (!window)
         return;
-      }
       const hasError = output.output === null || output.output === undefined;
       if (hasError) {
-        session.consecutiveErrors++;
+        window.consecutiveErrors++;
       } else {
-        session.consecutiveErrors = 0;
-        session.lastSuccessTime = Date.now();
+        window.consecutiveErrors = 0;
+        window.lastSuccessTimeMs = Date.now();
       }
     },
     messagesTransform: async (_input, output) => {
@@ -16923,31 +17026,30 @@ function createGuardrailsHooks(config2) {
       }
       const lastMessage = messages[messages.length - 1];
       let sessionId = lastMessage.info?.sessionID;
-      if (!sessionId) {
-        for (const [id, session2] of swarmState.agentSessions) {
-          if (session2.warningIssued || session2.hardLimitHit) {
+      let targetWindow = sessionId ? getActiveWindow(sessionId) : undefined;
+      if (!targetWindow || !targetWindow.warningIssued && !targetWindow.hardLimitHit) {
+        for (const [id] of swarmState.agentSessions) {
+          const window = getActiveWindow(id);
+          if (window && (window.warningIssued || window.hardLimitHit)) {
+            targetWindow = window;
             sessionId = id;
             break;
           }
         }
       }
-      if (!sessionId) {
-        return;
-      }
-      const session = getAgentSession(sessionId);
-      if (!session || !session.warningIssued && !session.hardLimitHit) {
+      if (!targetWindow || !targetWindow.warningIssued && !targetWindow.hardLimitHit) {
         return;
       }
       const textPart = lastMessage.parts.find((part) => part.type === "text" && typeof part.text === "string");
       if (!textPart) {
         return;
       }
-      if (session.hardLimitHit) {
+      if (targetWindow.hardLimitHit) {
         textPart.text = `[\uD83D\uDED1 LIMIT REACHED: Your resource budget is exhausted. Do not make additional tool calls. Return a summary of your progress and any remaining work.]
 
 ` + textPart.text;
-      } else if (session.warningIssued) {
-        const reasonSuffix = session.warningReason ? ` (${session.warningReason})` : "";
+      } else if (targetWindow.warningIssued) {
+        const reasonSuffix = targetWindow.warningReason ? ` (${targetWindow.warningReason})` : "";
         textPart.text = `[\u26A0\uFE0F APPROACHING LIMITS${reasonSuffix}: You still have capacity to finish your current step. Complete what you're working on, then return your results.]
 
 ` + textPart.text;

package/dist/state.d.ts

@@ -34,37 +34,56 @@ export interface DelegationEntry {
     timestamp: number;
 }
 /**
- * Represents per-session state for guardrail tracking
+ * Represents per-session state for guardrail tracking.
+ * Budget fields (toolCallCount, consecutiveErrors, etc.) have moved to InvocationWindow.
+ * This interface now tracks session-level metadata and window management.
  */
 export interface AgentSessionState {
-    /** Which agent this session belongs to */
+    /** Current agent identity for this session */
     agentName: string;
-    /** Date.now() when session started */
-    startTime: number;
-    /** Timestamp of most recent tool call (for stale session eviction) */
+    /** Timestamp of most recent tool call (for session-level stale detection) */
     lastToolCallTime: number;
-    /** Timestamp of most recent agent identity event (chat.message sets/changes identity) */
+    /** Timestamp of most recent agent identity event (chat.message) */
     lastAgentEventTime: number;
-    /** Total tool calls in this session */
-    toolCallCount: number;
-    /** Consecutive errors (reset on success) */
+    /** Whether active delegation is in progress for this session */
+    delegationActive: boolean;
+    /** Current active invocation ID for this agent */
+    activeInvocationId: number;
+    /** Last invocation ID by agent name (e.g., { "coder": 3, "reviewer": 1 }) */
+    lastInvocationIdByAgent: Record<string, number>;
+    /** Active invocation windows keyed by "${agentName}:${invId}" */
+    windows: Record<string, InvocationWindow>;
+}
+/**
+ * Represents a single agent invocation window with isolated guardrail budgets.
+ * Each time the architect delegates to an agent, a new window is created.
+ * Architect never creates windows (unlimited).
+ */
+export interface InvocationWindow {
+    /** Unique ID for this invocation (increments per agent type) */
+    id: number;
+    /** Agent name (stripped of swarm prefix) */
+    agentName: string;
+    /** Timestamp when this invocation started */
+    startedAtMs: number;
+    /** Tool calls made in this invocation */
+    toolCalls: number;
+    /** Consecutive errors in this invocation */
     consecutiveErrors: number;
-    /** Circular buffer of recent tool calls, max 20 entries */
+    /** Whether hard limit was hit for this invocation */
+    hardLimitHit: boolean;
+    /** Timestamp of most recent successful tool call */
+    lastSuccessTimeMs: number;
+    /** Circular buffer of recent tool calls (max 20) for repetition detection */
     recentToolCalls: Array<{
         tool: string;
         argsHash: number;
         timestamp: number;
     }>;
-    /** Whether a soft warning has been issued */
+    /** Whether soft warning has been issued for this invocation */
     warningIssued: boolean;
-    /** Human-readable warning reason (set when warningIssued = true) */
+    /** Human-readable warning reason */
     warningReason: string;
-    /** Whether a hard limit has been triggered */
-    hardLimitHit: boolean;
-    /** Timestamp of most recent SUCCESSFUL tool call (for idle timeout) */
-    lastSuccessTime: number;
-    /** Whether active delegation is in progress for this session */
-    delegationActive: boolean;
 }
 /**
  * Singleton state object for sharing data across hooks
@@ -122,3 +141,30 @@ export declare function ensureAgentSession(sessionId: string, agentName?: string
  * @param sessionId - The session identifier
  */
 export declare function updateAgentEventTime(sessionId: string): void;
+/**
+ * Begin a new invocation window for the given agent.
+ * Increments invocation ID, creates fresh budget counters.
+ * Returns null for architect (unlimited, no window).
+ *
+ * @param sessionId - Session identifier
+ * @param agentName - Agent name (with or without swarm prefix)
+ * @returns New window or null if architect
+ */
+export declare function beginInvocation(sessionId: string, agentName: string): InvocationWindow | null;
+/**
+ * Get the currently active invocation window for the session.
+ * Returns undefined if no window exists (e.g., architect session).
+ *
+ * @param sessionId - Session identifier
+ * @returns Active window or undefined
+ */
+export declare function getActiveWindow(sessionId: string): InvocationWindow | undefined;
+/**
+ * Prune old invocation windows to prevent unbounded memory growth.
+ * Removes windows older than maxAgeMs and keeps only the most recent maxWindows.
+ *
+ * @param sessionId - Session identifier
+ * @param maxAgeMs - Maximum age in milliseconds (default 24 hours)
+ * @param maxWindows - Maximum number of windows to keep (default 50)
+ */
+export declare function pruneOldWindows(sessionId: string, maxAgeMs?: number, maxWindows?: number): void;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "5.1.8",
+	"version": "5.2.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",