opencode-swarm 6.12.0 → 6.13.0

package/README.md

@@ -84,6 +84,31 @@ By default, Swarm uses whatever model OpenCode is configured with. To route diff
     "architect": { "model": "anthropic/claude-opus-4-6" },
     "coder":     { "model": "minimax-coding-plan/MiniMax-M2.5" },
     "reviewer":  { "model": "zai-coding-plan/glm-5" }
+  },
+  "guardrails": {
+    "max_tool_calls": 200,
+    "max_duration_minutes": 30,
+    "profiles": {
+      "coder": { "max_tool_calls": 500 }
+    }
+  },
+  "tool_filter": {
+    "enabled": true,
+    "overrides": {}
+  },
+  "review_passes": {
+    "always_security_review": false,
+    "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*"]
+  },
+  "automation": {
+    "mode": "manual",
+    "capabilities": {
+      "plan_sync": false,
+      "phase_preflight": false,
+      "config_doctor_on_startup": false,
+      "evidence_auto_summaries": false,
+      "decision_drift_detection": false
+    }
   }
 }
 ```
@@ -341,23 +366,99 @@ Config file location: `~/.config/opencode/opencode-swarm.json` (global) or `.ope
   "automation": {
     "mode": "manual",
     "capabilities": {
-      "plan_sync": false,
+      "plan_sync": true,
       "phase_preflight": false,
       "config_doctor_on_startup": false,
-      "evidence_auto_summaries": false,
-      "decision_drift_detection": false
+      "config_doctor_autofix": false,
+      "evidence_auto_summaries": true,
+      "decision_drift_detection": true
     }
   }
 }
 ```
 
-### Automation Modes
+### Automation
 
-| Mode | Behavior |
-|------|----------|
-| `manual` | No background automation (default) |
-| `hybrid` | Background automation for safe ops, manual for sensitive ones |
-| `auto` | Full background automation |
+## Plan Cursor (v6.13)
+
+The `plan_cursor` config compresses the plan that is injected into the LLM context.
+
+```json
+{
+  "plan_cursor": {
+    "enabled": true,
+    "max_tokens": 1500,
+    "lookahead_tasks": 2
+  }
+}
+```
+
+- **enabled** – When `true` (default) Swarm injects a compact plan cursor instead of the full `plan.md`.
+- **max_tokens** – Upper bound on the number of tokens emitted for the cursor (default 1500). The cursor contains the current phase summary, the full current task, and up to `lookahead_tasks` upcoming tasks. Earlier phases are reduced to one‑line summaries.
+- **lookahead_tasks** – Number of future tasks to include in full detail (default 2). Set to `0` to show only the current task.
+
+Disabling (`"enabled": false`) falls back to the pre‑v6.13 behavior of injecting the entire plan text.
+
+## Tool Output Truncation (v6.13)
+
+Control the size of tool outputs that are sent back to the LLM.
+
+```json
+{
+  "tool_output": {
+    "truncation_enabled": true,
+    "max_lines": 150,
+    "per_tool": {
+      "diff": 200,
+      "symbols": 100
+    }
+  }
+}
+```
+
+- **truncation_enabled** – Global switch (default true).
+- **max_lines** – Default line limit for any tool output.
+- **per_tool** – Overrides `max_lines` for specific tools. The `diff` and `symbols` tools are truncated by default because their outputs can be very large.
+
+When truncation is active, a footer is appended:
+
+```
+---
+[output truncated to {maxLines} lines – use `tool_output.per_tool.<tool>` to adjust]
+```
+
+## Mode Detection (v6.13)
+
+Swarm now explicitly distinguishes five architect modes:
+
+| Mode | When Injected |
+|------|----------------|
+| `DISCOVER` | After the explorer finishes scanning the codebase. |
+| `PLAN` | When the architect writes or updates the plan. |
+| `EXECUTE` | During task implementation (the normal pipeline). |
+| `PHASE-WRAP` | After all tasks in a phase are completed, before docs are updated. |
+| `UNKNOWN` | Fallback when the current state does not match any known mode. |
+
+Each mode determines which injection blocks are added to the LLM prompt (e.g., plan cursor is injected in `PLAN`, tool output truncation in `EXECUTE`, etc.).
+
+Default mode: `manual`. No background automation — all actions require explicit slash commands.
+
+Modes:
+
+- `manual` — No background automation. All actions via slash commands (default).
+- `hybrid` — Background automation for safe operations, manual for sensitive ones.
+- `auto` — Full background automation.
+
+Capability defaults:
+
+- `plan_sync`: `true` — Background plan synchronization using `fs.watch` with debounced writes (300ms) and 2-second polling fallback
+- `phase_preflight`: `false` — Phase preflight checks before agent execution (opt-in)
+- `config_doctor_on_startup`: `false` — Validate configuration on startup
+- `config_doctor_autofix`: `false` — Auto-fix for config doctor (opt-in, security-sensitive)
+- `evidence_auto_summaries`: `true` — Automatic summaries for evidence bundles
+- `decision_drift_detection`: `true` — Detect drift between planned and actual decisions
+
+---
 
 ### Disabling Agents
 
@@ -396,8 +497,110 @@ Config file location: `~/.config/opencode/opencode-swarm.json` (global) or `.ope
 
 ---
 
+## Role-Scoped Tool Filtering
+
+Swarm limits which tools each agent can access based on their role. This prevents agents from using tools that aren't appropriate for their responsibilities, reducing errors and keeping agents focused.
+
+### Default Tool Allocations
+
+| Agent | Tools | Count | Rationale |
+|-------|-------|:---:|-----------|
+| **architect** | All 17 tools | 17 | Orchestrator needs full visibility |
+| **reviewer** | diff, imports, lint, pkg_audit, pre_check_batch, secretscan, symbols, complexity_hotspots, retrieve_summary, extract_code_blocks, test_runner | 11 | Security-focused QA |
+| **coder** | diff, imports, lint, symbols, extract_code_blocks, retrieve_summary | 6 | Write-focused, minimal read tools |
+| **test_engineer** | test_runner, diff, symbols, extract_code_blocks, retrieve_summary, imports, complexity_hotspots, pkg_audit | 8 | Testing and verification |
+| **explorer** | complexity_hotspots, detect_domains, extract_code_blocks, gitingest, imports, retrieve_summary, schema_drift, symbols, todo_extract | 9 | Discovery and analysis |
+| **sme** | complexity_hotspots, detect_domains, extract_code_blocks, imports, retrieve_summary, schema_drift, symbols | 7 | Domain expertise research |
+| **critic** | complexity_hotspots, detect_domains, imports, retrieve_summary, symbols | 5 | Plan review, minimal toolset |
+| **docs** | detect_domains, extract_code_blocks, gitingest, imports, retrieve_summary, schema_drift, symbols, todo_extract | 8 | Documentation synthesis |
+| **designer** | extract_code_blocks, retrieve_summary, symbols | 3 | UI-focused, minimal toolset |
+
+### Configuration
+
+Tool filtering is enabled by default. Customize it in your config:
+
+```json
+{
+  "tool_filter": {
+    "enabled": true,
+    "overrides": {
+      "coder": ["diff", "imports", "lint", "symbols", "test_runner"],
+      "reviewer": ["diff", "secretscan", "sast_scan", "symbols"]
+    }
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable tool filtering globally |
+| `overrides` | Record<string, string[]> | `{}` | Per-agent tool whitelist. Empty array denies all tools. |
+
+### Troubleshooting: Agent Missing a Tool
+
+If an agent reports it doesn't have access to a tool it needs:
+
+1. Check if the tool is in the agent's default allocation (see table above)
+2. Add a custom override in your config:
+
+```json
+{
+  "tool_filter": {
+    "overrides": {
+      "coder": ["diff", "imports", "lint", "symbols", "extract_code_blocks", "retrieve_summary", "test_runner"]
+    }
+  }
+}
+```
+
+3. To completely disable filtering for all agents:
+
+```json
+{
+  "tool_filter": {
+    "enabled": false
+  }
+}
+```
+
+### Available Tools Reference
+
+The following tools can be assigned to agents via overrides:
+
+| Tool | Purpose |
+|------|---------|
+| `checkpoint` | Save/restore git checkpoints |
+| `complexity_hotspots` | Identify high-risk code areas |
+| `detect_domains` | Detect SME domains from text |
+| `diff` | Analyze git diffs and changes |
+| `evidence_check` | Verify task evidence |
+| `extract_code_blocks` | Extract code from markdown |
+| `gitingest` | Ingest external repositories |
+| `imports` | Analyze import relationships |
+| `lint` | Run project linters |
+| `pkg_audit` | Security audit of dependencies |
+| `pre_check_batch` | Parallel pre-checks (lint, secrets, SAST, quality) |
+| `retrieve_summary` | Retrieve summarized tool outputs |
+| `schema_drift` | Detect OpenAPI/schema drift |
+| `secretscan` | Scan for secrets in code |
+| `symbols` | Extract exported symbols |
+| `test_runner` | Run project tests |
+| `todo_extract` | Extract TODO/FIXME comments |
+
+---
+
 ## Recent Changes
 
+### v6.13.0 — Context Efficiency
+
+This release focuses on reducing context usage and improving mode-conditional behavior:
+
+- **Role-Scoped Tool Filtering**: Agent tools filtered via AGENT_TOOL_MAP
+- **Plan Cursor**: Compressed plan summary under 1,500 tokens
+- **Mode Detection**: DISCOVER/PLAN/EXECUTE/PHASE-WRAP/UNKNOWN modes
+- **Tool Output Truncation**: diff/symbols outputs truncated with footer
+- **ZodError Fixes**: Optional current_phase, 'completed' status support
+
 ### v6.12.0 — Anti-Process-Violation Hardening
 
 This release adds runtime detection hooks to catch and warn about architect workflow violations:
@@ -437,7 +640,7 @@ bun test
 
 See [CHANGELOG.md](CHANGELOG.md) for shipped features.
 
-Upcoming: v6.12 targets process violation hardening based on field testing with models that attempt to bypass QA gates.
+Upcoming: v6.14 focuses on further context optimization and agent coordination improvements.
 
 ---
 

package/dist/config/constants.d.ts

@@ -1,3 +1,4 @@
+import type { ToolName } from '../tools/tool-names';
 export declare const QA_AGENTS: readonly ["reviewer", "critic"];
 export declare const PIPELINE_AGENTS: readonly ["explorer", "coder", "test_engineer"];
 export declare const ORCHESTRATOR_NAME: "architect";
@@ -6,6 +7,7 @@ export declare const ALL_AGENT_NAMES: readonly ["architect", "sme", "docs", "des
 export type QAAgentName = (typeof QA_AGENTS)[number];
 export type PipelineAgentName = (typeof PIPELINE_AGENTS)[number];
 export type AgentName = (typeof ALL_AGENT_NAMES)[number];
+export declare const AGENT_TOOL_MAP: Record<AgentName, ToolName[]>;
 export declare const DEFAULT_MODELS: Record<string, string>;
 export declare function isQAAgent(name: string): name is QAAgentName;
 export declare function isSubagent(name: string): boolean;

package/dist/config/evidence-schema.d.ts

@@ -3,11 +3,11 @@ export declare const EVIDENCE_MAX_JSON_BYTES: number;
 export declare const EVIDENCE_MAX_PATCH_BYTES: number;
 export declare const EVIDENCE_MAX_TASK_BYTES: number;
 export declare const EvidenceTypeSchema: z.ZodEnum<{
-    placeholder: "placeholder";
+    diff: "diff";
     quality_budget: "quality_budget";
+    placeholder: "placeholder";
     review: "review";
     test: "test";
-    diff: "diff";
     approval: "approval";
     note: "note";
     retrospective: "retrospective";
@@ -28,11 +28,11 @@ export type EvidenceVerdict = z.infer<typeof EvidenceVerdictSchema>;
 export declare const BaseEvidenceSchema: z.ZodObject<{
     task_id: z.ZodString;
     type: z.ZodEnum<{
-        placeholder: "placeholder";
+        diff: "diff";
         quality_budget: "quality_budget";
+        placeholder: "placeholder";
         review: "review";
         test: "test";
-        diff: "diff";
         approval: "approval";
         note: "note";
         retrospective: "retrospective";

package/dist/config/plan-schema.d.ts

@@ -15,10 +15,23 @@ export type TaskSize = z.infer<typeof TaskSizeSchema>;
 export declare const PhaseStatusSchema: z.ZodEnum<{
     pending: "pending";
     in_progress: "in_progress";
+    completed: "completed";
     blocked: "blocked";
     complete: "complete";
 }>;
 export type PhaseStatus = z.infer<typeof PhaseStatusSchema>;
+/**
+ * Normalize phase status - 'completed' maps to 'complete'.
+ * @param status - The phase status to normalize
+ * @returns Normalized status ('completed' becomes 'complete')
+ */
+export declare function normalizePhaseStatus(status: PhaseStatus): PhaseStatus;
+/**
+ * Check if a phase status represents completion.
+ * @param status - The phase status to check
+ * @returns true if status is 'complete' or 'completed'
+ */
+export declare function isPhaseComplete(status: PhaseStatus): boolean;
 export declare const MigrationStatusSchema: z.ZodEnum<{
     native: "native";
     migrated: "migrated";
@@ -53,6 +66,7 @@ export declare const PhaseSchema: z.ZodObject<{
     status: z.ZodDefault<z.ZodEnum<{
         pending: "pending";
         in_progress: "in_progress";
+        completed: "completed";
         blocked: "blocked";
         complete: "complete";
     }>>;
@@ -83,13 +97,14 @@ export declare const PlanSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"1.0.0">;
     title: z.ZodString;
     swarm: z.ZodString;
-    current_phase: z.ZodNumber;
+    current_phase: z.ZodOptional<z.ZodNumber>;
     phases: z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
         name: z.ZodString;
         status: z.ZodDefault<z.ZodEnum<{
             pending: "pending";
             in_progress: "in_progress";
+            completed: "completed";
             blocked: "blocked";
             complete: "complete";
         }>>;
@@ -122,3 +137,15 @@ export declare const PlanSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type Plan = z.infer<typeof PlanSchema>;
+/**
+ * Find the first phase that is in progress.
+ * @param phases - Array of phases
+ * @returns Phase number of first in-progress phase, or first phase if none
+ */
+export declare function findFirstActivePhase(phases: Phase[]): number | undefined;
+/**
+ * Get the current phase from a plan, with fallback inference.
+ * @param plan - The plan object
+ * @returns The current phase number, or inferred value, or 1 as last resort
+ */
+export declare function getCurrentPhase(plan: Plan): number;

package/dist/config/schema.d.ts

@@ -1,4 +1,19 @@
 import { z } from 'zod';
+/**
+ * Strips known Swarm prefixes from agent names to get the canonical agent name.
+ *
+ * Strategy:
+ * 1. First try stripping known prefixes from the front (e.g., 'paid_architect' -> 'architect')
+ * 2. If that doesn't yield a known agent, check if the name ENDS with a known agent name
+ *    (e.g., 'not-an-architect' -> 'architect', 'team-alpha-reviewer' -> 'reviewer')
+ *
+ * Supports underscore, hyphen, and space separators.
+ * Case-insensitive matching, but returns the canonical lowercase agent name.
+ *
+ * @param agentName - The potentially prefixed agent name
+ * @returns The canonical agent name, or the original if no known agent found
+ */
+export declare function stripKnownSwarmPrefix(agentName: string): string;
 export declare const AgentOverrideConfigSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     temperature: z.ZodOptional<z.ZodNumber>;
@@ -269,32 +284,34 @@ export declare const GuardrailsConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
 /**
- * Strip any swarm prefix from an agent name to get the base agent name.
- * Works with any swarm name by checking if the name (or suffix after removing
- * a prefix) matches a known agent name from ALL_AGENT_NAMES.
+ * Resolves guardrails configuration for a specific agent.
  *
- * Normalization handles:
- * - Case-insensitive matching (e.g., "PAID_ARCHITECT" → "architect")
- * - Multiple separators: underscore, hyphen, space (e.g., "paid-architect", "paid architect")
+ * Resolution order (later values override earlier):
+ * 1. Base config values
+ * 2. Built-in agent profile defaults from DEFAULT_AGENT_PROFILES (known agents only)
+ * 3. User profile overrides - checks in order:
+ *    a. config.profiles[originalAgentName] (e.g., 'paid_coder')
+ *    b. config.profiles[canonicalName] (e.g., 'coder')
  *
- * Examples: 'local_architect' → 'architect', 'enterprise_coder' → 'coder',
- *           'paid-architect' → 'architect', 'PAID_ARCHITECT' → 'architect',
- *           'architect' → 'architect', 'unknown_thing' → 'unknown_thing'
+ * For prefixed agent names (e.g., 'local_coder'), strips prefixes using stripKnownSwarmPrefix.
+ * Unknown agent names get base config + user profile (NOT architect defaults - prevents bypass).
  *
- * @param name - The agent name (possibly prefixed)
- * @returns The base agent name if recognized, or the original name
+ * @param config - The base guardrails configuration
+ * @param agentName - Optional agent name to resolve profile for
+ * @returns Resolved configuration object
  */
-export declare function stripKnownSwarmPrefix(name: string): string;
-/**
- * Resolve guardrails configuration for a specific agent.
- * Merges the base config with built-in agent-type defaults and
- * any per-agent profile overrides. Merge order: base < built-in < user profile.
- *
- * @param base - The base guardrails configuration
- * @param agentName - Optional agent name to look up profile overrides
- * @returns The effective guardrails configuration for the agent
- */
-export declare function resolveGuardrailsConfig(base: GuardrailsConfig, agentName?: string): GuardrailsConfig;
+export declare function resolveGuardrailsConfig(config: GuardrailsConfig, agentName?: string): GuardrailsConfig;
+export declare const ToolFilterConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    overrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type ToolFilterConfig = z.infer<typeof ToolFilterConfigSchema>;
+export declare const PlanCursorConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+    lookahead_tasks: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type PlanCursorConfig = z.infer<typeof PlanCursorConfigSchema>;
 export declare const CheckpointConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     auto_checkpoint_threshold: z.ZodDefault<z.ZodNumber>;
@@ -441,6 +458,15 @@ export declare const PluginConfigSchema: z.ZodObject<{
             idle_timeout_minutes: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    tool_filter: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        overrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>;
+    plan_cursor: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_tokens: z.ZodDefault<z.ZodNumber>;
+        lookahead_tasks: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     evidence: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         max_age_days: z.ZodDefault<z.ZodNumber>;
@@ -520,6 +546,11 @@ export declare const PluginConfigSchema: z.ZodObject<{
             decision_drift_detection: boolean;
         };
     }, unknown>>>;
+    tool_output: z.ZodOptional<z.ZodObject<{
+        truncation_enabled: z.ZodDefault<z.ZodBoolean>;
+        max_lines: z.ZodDefault<z.ZodNumber>;
+        per_tool: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
 export type { AgentName, PipelineAgentName, QAAgentName, } from './constants';

package/dist/hooks/extractors.d.ts

@@ -37,3 +37,17 @@ export declare function extractCurrentTaskFromPlan(plan: Plan): string | null;
  * Extracts incomplete tasks from the current phase of a Plan object.
  */
 export declare function extractIncompleteTasksFromPlan(plan: Plan, maxChars?: number): string | null;
+/**
+ * Extracts plan cursor - a concise summary of current phase, current task,
+ * and lookahead tasks for context-aware agent communication.
+ *
+ * @param planContent - The raw plan markdown content
+ * @param options - Optional configuration
+ * @param options.maxTokens - Target max tokens (default 1500, ~6000 chars)
+ * @param options.lookaheadTasks - Number of lookahead tasks (default 2)
+ * @returns A [SWARM PLAN CURSOR] block with phase summaries and task details
+ */
+export declare function extractPlanCursor(planContent: string, options?: {
+    maxTokens?: number;
+    lookaheadTasks?: number;
+}): string;

package/dist/hooks/index.d.ts

@@ -5,6 +5,7 @@ export { createDelegationGateHook } from './delegation-gate';
 export { createDelegationTrackerHook } from './delegation-tracker';
 export { extractCurrentPhase, extractCurrentPhaseFromPlan, extractCurrentTask, extractCurrentTaskFromPlan, extractDecisions, extractIncompleteTasks, extractIncompleteTasksFromPlan, extractPatterns, } from './extractors';
 export { createGuardrailsHooks } from './guardrails';
+export { consolidateSystemMessages } from './messages-transform';
 export { createPhaseMonitorHook } from './phase-monitor';
 export { createPipelineTrackerHook } from './pipeline-tracker';
 export { createSystemEnhancerHook } from './system-enhancer';

package/dist/hooks/messages-transform.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Consolidates multiple system messages into a single system message at index 0.
+ *
+ * Note: Merged content order matches original insertion order (OpenCode base prompt
+ * first, then swarm agent prompt) - this assumes sequential message construction.
+ */
+type Message = {
+    role: string;
+    content: unknown;
+    [key: string]: unknown;
+};
+export declare function consolidateSystemMessages(messages: Message[]): Message[];
+export {};

package/dist/hooks/system-enhancer.d.ts

@@ -10,3 +10,14 @@ import type { PluginConfig } from '../config';
  * Creates the experimental.chat.system.transform hook for system enhancement.
  */
 export declare function createSystemEnhancerHook(config: PluginConfig, directory: string): Record<string, unknown>;
+/**
+ * Architect operational mode derived from plan state.
+ */
+export type ArchitectMode = 'DISCOVER' | 'PLAN' | 'EXECUTE' | 'PHASE-WRAP' | 'UNKNOWN';
+/**
+ * Detect the current architect operational mode based on plan state.
+ *
+ * @param directory - The project directory to check
+ * @returns The current architect mode based on plan state
+ */
+export declare function detectArchitectMode(directory: string): Promise<ArchitectMode>;