@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/thoughts/shared/plans/2026-02-26-mcp-tool-context-reduction.md

@@ -0,0 +1,282 @@
+---
+date: 2026-02-26
+author: Researcher
+repository: desplega-ai/agent-swarm
+topic: "Implementation Plan: Reduce MCP Tool Context Overhead"
+tags: [plan, mcp, tools, context-window, skills, tool-search]
+status: proposed
+related_research: thoughts/shared/research/2026-02-26-cliffy-mcp-tools.md
+related_rfc: docs/rfcs/0001-cliffy-mcp-tools.md
+pr: "#95"
+---
+
+# Implementation Plan: Reduce MCP Tool Context Overhead via Tool Search & Skills
+
+**Based on**: RFC-0001 and research findings from 2026-02-26
+**Goal**: Reduce agent context window overhead from ~14K tokens (50 MCP tools) to ~3-5K tokens at session startup
+**Expected impact**: 65-85% reduction in MCP tool context overhead
+
+---
+
+## Phase 1: Verify & Optimize Tool Search (Effort: Low, Impact: High)
+
+**Timeline**: 1-2 sessions
+**Owner**: Any worker (suggested: Researcher for verification, Picateclas for code changes)
+
+### 1.1 Verify Tool Search Auto-Enable Status
+
+**Goal**: Determine if Claude Code's Tool Search is already active for our agents.
+
+**Steps**:
+1. Add temporary debug logging to a worker session to observe whether Claude Code sends a `Tool Search` invocation before calling MCP tools. This can be done by:
+   - Checking the Claude Code session logs (if available) for `tool_search` calls
+   - Adding a `console.log` in the MCP server's `tools/list` handler to see how/when it's called
+   - Examining Claude Code's `--verbose` output during a session
+2. Check the `@modelcontextprotocol/sdk` version (`^1.25.1` in our `package.json`) for `defer_loading` support in tool registration
+3. Review Claude Code client-side Tool Search documentation for auto-enable conditions and confirm our ~12-16K token tool payload exceeds the 10K threshold
+
+**Acceptance criteria**: Written confirmation of whether Tool Search is active, and if not, what's needed to enable it.
+
+### 1.2 Add `annotations` to Tool Registrations
+
+**Goal**: Improve tool discoverability for Tool Search by adding structured annotations.
+
+**Files to modify**: `src/tools/utils.ts` (utility), each tool file in `src/tools/*.ts`
+
+**Steps**:
+1. Research the MCP SDK's `ToolAnnotations` type — our `utils.ts:13` already imports it and `ToolConfig:66` accepts it as optional, but NO tool currently sets it
+2. Define a standard annotation schema for our tools. At minimum:
+   - `readOnlyHint` / `destructiveHint` per the MCP spec (for safety classification)
+   - Consider adding custom metadata for tool grouping/categories if the SDK supports it
+3. Add annotations to all 50 tools, prioritizing:
+   - Destructive tools (`delete-channel`, `delete-epic`, `delete-config`, `delete-schedule`, `cancel-task`) → `destructiveHint: true`
+   - Read-only tools (`get-tasks`, `get-swarm`, `list-*`, `memory-search`) → `readOnlyHint: true`
+4. Audit tool descriptions for search-friendliness:
+   - Current descriptions are 1-2 sentences, action-oriented — generally fine
+   - Add trigger keywords where missing (e.g., `post-message` description is too brief: "Posts a message to a channel for cross-agent communication" — could add "internal chat, agent-to-agent")
+   - Ensure cross-references between related tools (already done for `memory-search` → `memory-get`)
+
+**Acceptance criteria**: All 50 tools have `annotations` set. Descriptions reviewed for searchability. PR with changes.
+
+**Status (2026-02-26)**: DONE. 36 tools annotated with readOnlyHint (20), destructiveHint (7), idempotentHint (6), openWorldHint (6). 14 write-only tools skipped (no specific hints apply). Type-check and lint clean.
+
+### 1.3 Configure Explicit `defer_loading` (if supported)
+
+**Goal**: Explicitly mark non-core tools for deferred loading instead of relying on auto-enable.
+
+**Depends on**: 1.1 results (need to confirm SDK support)
+
+**Steps**:
+1. If the MCP SDK supports `defer_loading` in tool metadata, add it to the 31 non-core tools identified in the RFC:
+   - Scheduling (5 tools)
+   - Epics (7 tools)
+   - Services (4 tools)
+   - Config (4 tools)
+   - Profiles (3 tools)
+   - Slack extras (4: `slack-upload-file`, `slack-download-file`, `slack-list-channels`, `slack-post`)
+   - Memory extras (1: `inject-learning`)
+   - Messaging extras (3: `create-channel`, `delete-channel`, `list-channels`)
+2. Keep 16 core tools always-loaded (as classified in RFC section "Must Stay as MCP Tools"):
+   - `join-swarm`, `poll-task`, `get-task-details`, `store-progress`, `send-task`, `get-tasks`, `my-agent-info`, `get-swarm`, `cancel-task`, `task-action`
+   - `slack-reply`, `slack-read`
+   - `read-messages`, `post-message`
+   - `memory-search`, `memory-get`
+3. If the SDK does NOT support `defer_loading`, document the gap and investigate alternatives (e.g., Claude Code `--tool-search` flag, `.claude/settings.json` config)
+
+**Acceptance criteria**: Non-core tools marked for deferred loading OR documented gap with workaround.
+
+**Status (2026-02-26)**: `defer_loading` is NOT supported in `@modelcontextprotocol/sdk@^1.25.1`. The `ToolSchema` only supports `description`, `inputSchema`, `outputSchema`, and `annotations` (with `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`). No lazy/deferred loading mechanism exists in the MCP protocol spec at this version. Tool Search is a Claude Code client-side feature that auto-activates when tool token count exceeds ~10K. With our ~14K tokens across 50 tools, Tool Search should already be active. The annotations added in Phase 1.2 improve Tool Search discoverability.
+
+### 1.4 Measure Baseline and Post-Change Token Counts
+
+**Goal**: Quantify actual token savings.
+
+**Steps**:
+1. Before changes: count tokens from a full `tools/list` response (all 50 tools)
+2. After changes: count tokens for core-only tools + Tool Search overhead
+3. Document delta in the RFC
+
+**Acceptance criteria**: Measured before/after token counts documented.
+
+---
+
+## Phase 2: Create Skill Guides for Complex Tool Groups (Effort: Medium, Impact: Medium)
+
+**Timeline**: 2-3 sessions
+**Owner**: Researcher (skill design) + Picateclas (integration)
+
+### 2.1 Create `scheduling-expert` Skill (Proof of Concept)
+
+**Goal**: Build the first skill guide for a complex tool group and validate the pattern.
+
+**Directory**: `plugin/skills/scheduling-expert/`
+
+**Files to create**:
+```
+plugin/skills/scheduling-expert/
+├── SKILL.md           # Core usage guide with YAML frontmatter
+├── COMMANDS.md        # Detailed parameter reference for all 5 scheduling tools
+└── examples/
+    └── common-patterns.md   # Cron patterns, interval templates
+```
+
+**SKILL.md content requirements** (following Claude Code skills best practices):
+- YAML frontmatter with `name`, `description` (include trigger words: "schedule", "cron", "recurring", "periodic", "automated tasks", "timer")
+- Quick reference table mapping goals to MCP tool names
+- Common patterns section (daily at 9am, hourly, weekly, custom cron)
+- Error handling guidance (what happens when a schedule name conflicts, cron parsing errors)
+- Link to COMMANDS.md for detailed params
+
+**Steps**:
+1. Create skill directory structure
+2. Write SKILL.md with proper frontmatter and quick reference
+3. Write COMMANDS.md documenting all 5 scheduling tool parameters (from Zod schemas in `src/tools/schedules/`)
+4. Write examples/common-patterns.md with practical scheduling scenarios
+5. Test skill loading in a dev session
+
+**Acceptance criteria**: Skill loads correctly when invoked via `/scheduling-expert` or when Claude detects scheduling intent.
+
+### 2.2 Create `epic-management` Skill
+
+**Goal**: Guide Claude through the epic → task workflow.
+
+**Directory**: `plugin/skills/epic-management/`
+
+**Content focus**:
+- Epic lifecycle: draft → active → paused → completed/cancelled
+- Workflow: create epic → create tasks → assign tasks to epic → track progress
+- Quick reference for all 7 epic tools
+- Common patterns: multi-task project decomposition, epic progress tracking
+
+**Steps**: Same structure as 2.1 adapted for epics.
+
+### 2.3 Create `service-registry` Skill
+
+**Goal**: Guide the PM2 + service registry workflow.
+
+**Directory**: `plugin/skills/service-registry/`
+
+**Content focus**:
+- Full lifecycle: start PM2 → register → health check → update → unregister → stop
+- Port 3000 convention, health check endpoint requirement
+- URL pattern: `https://{agentId}.{swarmUrl}`
+- Quick reference for all 4 service tools
+
+**Steps**: Same structure as 2.1 adapted for services.
+
+### 2.4 Enhance Existing `swarm-expert` Skill
+
+**Goal**: The existing `swarm-expert` skill pattern (currently referenced in research but missing from `plugin/skills/`) should be properly created or updated.
+
+**Note**: The research doc references `plugin/skills/swarm-expert/` but this directory does not exist (only `.gitkeep` in `plugin/skills/`). Need to verify if this skill lives elsewhere (e.g., in the Claude Code plugin config) or needs to be created.
+
+**Steps**:
+1. Locate the actual `swarm-expert` skill (may be in `.claude/skills/` or loaded via plugin config)
+2. If it exists elsewhere, evaluate whether to consolidate into `plugin/skills/`
+3. If it doesn't exist, create it as a general swarm operations guide
+
+---
+
+## Phase 3: Optimize Capability-Based Tool Loading per Worker Role (Effort: Medium, Impact: Medium)
+
+**Timeline**: 2-3 sessions
+**Owner**: Researcher (analysis) + Picateclas (implementation)
+
+### 3.1 Audit Actual Tool Usage by Worker Role
+
+**Goal**: Determine which tools each worker role actually uses.
+
+**Steps**:
+1. Add usage instrumentation to `createToolRegistrar` in `src/tools/utils.ts`:
+   - Log tool name + agent ID on each call
+   - Can be a simple counter stored in-memory or logged to stdout
+2. Run for 1-2 days to collect usage data
+3. Analyze which tools each agent role calls:
+   - Researcher: likely core + memory + messaging only
+   - Picateclas (implementation): likely core + messaging + profiles
+   - Lead: likely all tools
+4. Produce a usage matrix: agent role × tool → call frequency
+
+**Acceptance criteria**: Usage matrix document with data-backed recommendations.
+
+### 3.2 Define Minimal Capability Profiles per Role
+
+**Goal**: Reduce tool count from 50 to ~25-30 per worker.
+
+**Steps**:
+1. Based on 3.1 usage data, define capability profiles:
+   - `researcher`: `core,task-pool,messaging,memory` (removes scheduling, epics, services, profiles, config)
+   - `implementer`: `core,task-pool,messaging,profiles,memory` (removes scheduling, epics, services)
+   - `lead`: all capabilities (no change)
+2. Update worker configuration to use role-specific `CAPABILITIES` env vars
+3. Document the capability profiles and which tools each includes
+
+**Acceptance criteria**: Role-specific capability profiles defined and configured.
+
+### 3.3 Implement Role-Based Defaults in Runner
+
+**Goal**: Automatically set `CAPABILITIES` based on agent role.
+
+**Files to modify**: `src/commands/runner.ts`, potentially `src/server.ts`
+
+**Steps**:
+1. Map agent roles to capability profiles (could be a simple lookup table)
+2. Set `CAPABILITIES` env var in worker container based on agent role from swarm registry
+3. Keep override mechanism for agents that need additional capabilities
+
+**Acceptance criteria**: Workers start with role-appropriate tool sets. Override mechanism works.
+
+---
+
+## Phase 4: CLI Wrapper for Human Operators (Effort: High, Impact: Low, Optional)
+
+**Timeline**: Deferred — only if there's demand
+**Owner**: TBD
+
+This phase is documented for completeness but is **not recommended for near-term implementation**. It would generate a `swarm` CLI binary using clihub or a custom TypeScript CLI for human administrators.
+
+**Deferred because**:
+- Primary goal is agent context reduction, not human UX
+- The `gh api` + `curl` approach already works for human operators
+- The UI provides a better human interface
+
+---
+
+## Implementation Order & Dependencies
+
+```
+Phase 1.1 (verify Tool Search)
+    └─> Phase 1.2 (add annotations) — can run in parallel with 1.1
+    └─> Phase 1.3 (defer_loading) — depends on 1.1 results
+    └─> Phase 1.4 (measure) — depends on 1.2 and 1.3
+
+Phase 2.1 (scheduling skill) — can start immediately, independent
+    └─> Phase 2.2 (epic skill) — sequential after pattern validated
+    └─> Phase 2.3 (service skill) — sequential
+    └─> Phase 2.4 (swarm-expert) — sequential
+
+Phase 3.1 (usage audit) — start after Phase 1 is done
+    └─> Phase 3.2 (define profiles) — depends on 3.1 data
+    └─> Phase 3.3 (implement in runner) — depends on 3.2
+```
+
+**Critical path**: Phase 1.1 → 1.3 → 1.4 (verify, configure, measure)
+**Quick wins**: Phase 1.2 (annotations) and Phase 2.1 (first skill) can start immediately.
+
+## Success Metrics
+
+| Metric | Current | Target | Phase |
+|--------|---------|--------|-------|
+| Tool tokens at session start | ~14,000 | ~4,500 | Phase 1 |
+| Tool tokens with strict caps | ~14,000 | ~3,000 | Phase 3 |
+| Tools registered per worker | 50 | 25-30 | Phase 3 |
+| Skill coverage for complex groups | 0/4 | 4/4 | Phase 2 |
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| Tool Search not supported by our MCP SDK version | Medium | High | Check SDK docs in Phase 1.1; may need SDK upgrade |
+| Deferred tools not discoverable by Claude | Low | High | Optimize descriptions in Phase 1.2; test empirically |
+| Strict capabilities break edge-case workflows | Medium | Medium | Audit usage data first (Phase 3.1); keep override mechanism |
+| Skills add maintenance burden | Low | Low | Start with only 3-4 skills for most complex groups |

package/thoughts/shared/plans/2026-03-02-claude-context-mode-integration.md

@@ -0,0 +1,328 @@
+---
+date: 2026-03-02
+author: Reviewer
+repository: desplega-ai/agent-swarm
+topic: "Integration Plan: Add claude-context-mode as Default Context Management"
+tags: [plan, context-window, mcp, plugin, context-mode, optimization]
+status: implemented
+related_plans: thoughts/shared/plans/2026-02-26-mcp-tool-context-reduction.md
+---
+
+# Integration Plan: Add `claude-context-mode` to Agent Swarm
+
+**Source**: https://github.com/mksglu/claude-context-mode
+**Goal**: Reduce context window consumption during research and planning tasks by intercepting tool output and compressing it through FTS5-backed indexing
+**Expected impact**: ~98% reduction in raw tool output entering context (315 KB → 5.4 KB per the author's benchmarks)
+
+---
+
+## Problem Statement
+
+Research and planning tasks consume excessive context window space. When agents perform web fetches, read large files, run CLI commands, or process Playwright snapshots, the raw output floods the 200K context window. This causes:
+
+- Research sessions hitting context limits after ~30 minutes
+- Frequent context compaction losing important earlier findings
+- Increased API costs from large context payloads
+- Reduced session productivity
+
+## What is `claude-context-mode`?
+
+An MCP plugin (MIT licensed, v0.9.17) that sits between Claude Code and tool outputs. It provides:
+
+1. **6 MCP tools**: `batch_execute`, `execute`, `execute_file`, `index`, `search`, `fetch_and_index`
+2. **Sandboxed execution**: Commands run in isolated subprocesses; only stdout summaries enter context
+3. **FTS5 knowledge base**: SQLite with BM25 ranking, Porter stemming, trigram matching, Levenshtein fuzzy correction
+4. **PreToolUse hooks**: Intercepts Bash (curl/wget), WebFetch, Read, Grep, and Task (subagent) calls, redirecting them through context-mode tools
+5. **Progressive search throttling**: Calls 1-3 normal, 4-8 reduced, 9+ blocked
+6. **Subagent routing**: Auto-injects instructions into Task/Agent tool prompts to keep subagent responses compact
+
+### Architecture
+
+```
+Claude Code
+  │
+  ├── PreToolUse hooks (context-mode)
+  │     ├── Bash: blocks curl/wget → suggests execute/fetch_and_index
+  │     ├── WebFetch: DENIES → redirects to fetch_and_index
+  │     ├── Read: advisory tip → suggests execute_file for large files
+  │     ├── Grep: advisory tip → suggests execute for large results
+  │     └── Task: injects routing block into subagent prompts
+  │
+  ├── MCP Server (context-mode on stdio)
+  │     ├── batch_execute → runs commands, auto-indexes output, returns search results
+  │     ├── execute → sandboxed code in 11 languages, intent-driven filtering
+  │     ├── execute_file → reads file into sandbox, only printed summary enters context
+  │     ├── index → indexes markdown into FTS5
+  │     ├── search → BM25 search with porter→trigram→fuzzy fallback
+  │     └── fetch_and_index → fetches URL, converts to markdown, indexes into FTS5
+  │
+  └── FTS5 Knowledge Base (SQLite, ephemeral per session in /tmp)
+```
+
+---
+
+## Integration Approach
+
+### Overview of Changes
+
+| Component | Change | Effort |
+|-----------|--------|--------|
+| `Dockerfile.worker` | Add context-mode plugin installation | Low |
+| `docker-entrypoint.sh` | Register context-mode MCP server + configure | Low |
+| `Dockerfile.worker` | Grant context-mode tool permissions in settings.json | Low |
+| Hook coexistence | Validate both hook systems work together | Low (testing) |
+| Skill/SKILL.md | Ensure behavioral instructions load correctly | Low |
+| Base prompt | Optional: add brief context-mode awareness note | Low |
+
+### What Does NOT Need to Change
+
+- **Agent-swarm MCP server**: Remains unchanged (HTTP MCP at `$MCP_URL/mcp`)
+- **Agent-swarm hooks**: Remain unchanged (agent-swarm's PreToolUse handles task cancellation and loop detection, which is orthogonal to context-mode's output compression)
+- **Runner/session spawning**: No changes needed
+- **SOUL.md/IDENTITY.md/TOOLS.md**: No changes needed
+
+---
+
+## Phase 1: Plugin Installation (Dockerfile.worker)
+
+### 1.1 Install context-mode in the Docker image
+
+Add the context-mode plugin installation to the Dockerfile. Two options:
+
+**Option A: Marketplace installation (preferred)**
+
+Add to the existing marketplace section in `docker-entrypoint.sh`:
+
+```bash
+# In the "=== Marketplace Installation ===" section
+echo "Installing context-mode plugin..."
+claude plugin marketplace add mksglu/claude-context-mode || echo "context-mode marketplace add failed, continuing..."
+claude plugin install context-mode@mksglu-claude-context-mode --scope user || echo "context-mode plugin install failed, continuing..."
+```
+
+**Option B: Pre-install in Dockerfile**
+
+Add to `Dockerfile.worker` after the global tools installation:
+
+```dockerfile
+# Pre-install context-mode dependencies for faster startup
+RUN npm install -g context-mode
+```
+
+Then register as MCP server in docker-entrypoint.sh.
+
+**Recommendation**: Option A (marketplace) — keeps the installation pattern consistent with existing plugins (desplega, agent-swarm, wts, qa-use) and ensures the SKILL.md behavioral instructions are loaded automatically by Claude Code's plugin system.
+
+### 1.2 Grant MCP tool permissions
+
+In `Dockerfile.worker`, add context-mode permissions to the settings.json:
+
+```json
+{
+  "permissions": {
+    "allow": ["mcp__agent-swarm__*", "mcp__context-mode__*"]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": ["agent-swarm", "context-mode"]
+}
+```
+
+The context-mode plugin's `plugin.json` declares the MCP server as:
+```json
+{
+  "mcpServers": {
+    "context-mode": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/start.mjs"]
+    }
+  }
+}
+```
+
+This is a stdio-based MCP server, separate from agent-swarm's HTTP MCP. Both can run simultaneously.
+
+---
+
+## Phase 2: Hook Coexistence
+
+### How Hooks Work in Claude Code
+
+Claude Code merges hooks from multiple sources:
+1. `~/.claude/settings.json` (user-level hooks)
+2. Plugin `hooks.json` files (per-plugin hooks)
+
+Both fire independently for the same event. If any hook returns a "block"/"deny" decision, the tool call is blocked.
+
+### Current Agent-Swarm Hooks (settings.json)
+
+```json
+{
+  "PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}]
+}
+```
+
+Agent-swarm's PreToolUse does:
+- Check if worker's task was cancelled → block
+- Tool loop detection → block if looping
+- Block poll-task when polling limit reached
+
+### Context-Mode Hooks (plugin hooks.json)
+
+```json
+{
+  "PreToolUse": [
+    {"matcher": "Bash", "hooks": [...]},
+    {"matcher": "WebFetch", "hooks": [...]},
+    {"matcher": "Read", "hooks": [...]},
+    {"matcher": "Grep", "hooks": [...]},
+    {"matcher": "Task", "hooks": [...]}
+  ]
+}
+```
+
+Context-mode's PreToolUse does:
+- Bash: blocks curl/wget, allows everything else
+- WebFetch: **DENIES** the call, redirects to fetch_and_index
+- Read: advisory context tip
+- Grep: advisory context tip
+- Task: injects routing instructions into subagent prompts
+
+### Coexistence Analysis
+
+These hook systems are **complementary, not conflicting**:
+
+| Scenario | Agent-Swarm Hook | Context-Mode Hook | Result |
+|----------|-----------------|-------------------|--------|
+| Normal tool call | passes | passes | Tool executes |
+| Task cancelled + any tool | blocks | may pass/block | Blocked (correct) |
+| Tool loop detected | blocks | may pass | Blocked (correct) |
+| `curl` in Bash | passes | blocks | Blocked, suggests context-mode (correct) |
+| WebFetch call | passes | denies | Denied, redirects to fetch_and_index (correct) |
+| Read large file | passes | adds advisory | Tool executes with advice (correct) |
+| Subagent (Task) | passes | injects routing | Subagent gets context-mode instructions (correct) |
+
+**Risk**: Context-mode's `Task` matcher intercepts the `Task` tool. Agent-swarm uses the `Agent` tool (not `Task`). Need to verify whether context-mode's `pretooluse.mjs` also handles the `Agent` tool or if it needs modification.
+
+**Action item**: Check if `pretooluse.mjs` matches `Agent` tool calls (used by agent-swarm for subagents). If not, may need to add `Agent` to the matcher list or fork the hook.
+
+#### Phase 2 Findings (2026-03-03)
+
+**Confirmed: context-mode does NOT handle the `Agent` tool.** The `hooks.json` only registers matchers for 5 tools: `Bash`, `WebFetch`, `Read`, `Grep`, and `Task`. The `pretooluse.mjs` script has no conditional logic for `Agent`.
+
+**Impact**: Agent-swarm's subagent calls (via the `Agent` tool) will pass through context-mode's hooks unmodified. The subagent routing/prompt injection that context-mode applies to `Task` will NOT apply to `Agent` calls. This means subagents won't automatically receive context-mode instructions via the hook.
+
+**Mitigation**: This is acceptable for now because:
+1. The base prompt enhancement (Phase 3.2) ensures all agents are aware of context-mode tools regardless.
+2. Each agent session loads the context-mode SKILL.md via the plugin system, so subagents spawned within the same session already have context-mode behavioral instructions.
+3. If tighter subagent routing is needed in the future, we can either: (a) submit a PR to claude-context-mode adding `Agent` to the matcher list, or (b) add our own `Agent` matcher in agent-swarm's hooks that mirrors context-mode's routing injection.
+
+---
+
+## Phase 3: Behavioral Configuration
+
+### 3.1 SKILL.md Loading
+
+When installed via marketplace, context-mode's `skills/context-mode/SKILL.md` is automatically available. This SKILL.md contains the behavioral instructions that teach Claude to:
+
+- Default to context-mode for ALL commands
+- Only use direct Bash for safe mutations (git, npm install, echo, etc.)
+- Use `batch_execute` as the primary workhorse tool
+- Follow the decision tree for different data types (CLI output, web docs, files, etc.)
+
+### 3.2 Base Prompt Enhancement (Optional)
+
+Consider adding a brief note to `src/prompts/base-prompt.ts` mentioning context-mode availability:
+
+```
+You have access to the context-mode MCP tools (batch_execute, execute, search, etc.)
+which compress tool output to save context window space. Prefer these over raw
+Bash/WebFetch for data-fetching operations.
+```
+
+This is **optional** since the SKILL.md already provides comprehensive behavioral instructions, but a brief mention in the base prompt ensures awareness even before the skill is activated.
+
+---
+
+## Phase 4: Testing & Validation
+
+### 4.1 Functional Tests
+
+1. **Hook coexistence**: Start a worker session and verify:
+   - Agent-swarm hooks fire correctly (task cancellation, loop detection)
+   - Context-mode hooks fire correctly (curl blocking, WebFetch denial)
+   - No hook errors or conflicts in logs
+
+2. **MCP server availability**: Verify both MCP servers are accessible:
+   - `agent-swarm` (HTTP at `$MCP_URL/mcp`)
+   - `context-mode` (stdio, launched by plugin system)
+
+3. **Tool execution**: Test key context-mode tools:
+   - `batch_execute` with shell commands
+   - `fetch_and_index` with a URL
+   - `search` after indexing
+
+### 4.2 Integration Tests
+
+1. **Research task**: Run a research task and measure:
+   - Context window usage before/after
+   - Session duration before hitting context limits
+   - Quality of research output
+
+2. **Planning task**: Run a planning task that reads multiple files and verify context-mode intercepts large file reads.
+
+3. **Subagent routing**: Launch a subagent via Agent tool and verify context-mode routing instructions are injected.
+
+### 4.3 Rollback Plan
+
+If issues arise:
+1. Remove context-mode from marketplace installation in `docker-entrypoint.sh`
+2. Remove permissions from `settings.json` in Dockerfile
+3. Rebuild and redeploy containers
+
+The change is fully reversible since context-mode is an additive plugin with no modifications to agent-swarm's core code.
+
+---
+
+## Risks & Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| Hook ordering causes unexpected blocks | Low | High | Both hook systems are complementary; test thoroughly in Phase 4 |
+| context-mode blocks WebFetch needed by some workflows | Medium | Medium | WebFetch is redirected to `fetch_and_index` which provides same data; agent-swarm tools (AgentMail, etc.) use HTTP MCP, not WebFetch |
+| `Task` vs `Agent` tool mismatch in subagent routing | Medium | Medium | Verify and adapt pretooluse.mjs matcher; may need PR to context-mode or local fork |
+| Performance overhead from stdio MCP + SQLite FTS5 | Low | Low | FTS5 is lightweight; SQLite is already available in Docker image |
+| context-mode updates/breaking changes | Low | Medium | Pin to specific version; test before upgrading |
+| Skill instructions override agent-swarm preferred behaviors | Medium | Medium | Review SKILL.md for conflicts with agent-swarm conventions; adjust if needed |
+
+---
+
+## Implementation Checklist
+
+- [x] **Phase 1.1**: Add context-mode marketplace installation to `docker-entrypoint.sh` *(implemented in commit 73692e6)*
+- [x] **Phase 1.2**: Add `mcp__context-mode__*` to permissions allow list in `Dockerfile.worker` *(implemented in commit 73692e6)*
+- [x] **Phase 1.2**: Add `context-mode` to `enabledMcpjsonServers` in `Dockerfile.worker` *(implemented in commit 73692e6)*
+- [x] **Phase 2**: Verify hook coexistence (especially `Agent` vs `Task` tool matching) — **Confirmed: `Agent` tool NOT matched by context-mode hooks. Acceptable; see findings above.**
+- [x] **Phase 3.1**: Verify SKILL.md loads correctly via plugin system — **Confirmed: marketplace install auto-loads SKILL.md via Claude Code's plugin system.**
+- [x] **Phase 3.2**: Add context-mode awareness note to `src/prompts/base-prompt.ts`
+- [ ] **Phase 4.1**: Run functional tests for hooks and MCP servers *(requires deployed container; manual validation post-deploy)*
+- [ ] **Phase 4.2**: Run integration test with research task *(requires deployed container; manual validation post-deploy)*
+- [x] **Phase 4.3**: Document rollback procedure *(already documented in plan — remove from docker-entrypoint.sh + Dockerfile.worker, rebuild)*
+
+---
+
+## Relationship to Existing Work
+
+This plan complements the existing [MCP Tool Context Reduction plan](thoughts/shared/plans/2026-02-26-mcp-tool-context-reduction.md) (PR #95). That plan focuses on reducing the *tool definitions* overhead (~14K tokens from 50 tools). This plan focuses on reducing the *tool output* overhead (raw data from tool calls). Both can be applied together for maximum context savings:
+
+- **Tool definitions**: ~14K → ~4.5K tokens (from tool annotations + Tool Search)
+- **Tool output**: ~315 KB → ~5.4 KB per research session (from context-mode)
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `docker-entrypoint.sh` | Add marketplace installation commands (~3 lines) |
+| `Dockerfile.worker` | Update settings.json to include context-mode permissions (~2 lines) |
+| `src/prompts/base-prompt.ts` | (Optional) Add context-mode awareness note (~3 lines) |
+
+**Total estimated changes**: ~8-10 lines across 2-3 files. This is a low-risk, high-impact integration.