refactor(agents): restrict tools allowlist on research agents (#650)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

plugins/compound-engineering/agents/ce-best-practices-researcher.agent.md

@@ -2,6 +2,7 @@
 name: ce-best-practices-researcher
 description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance."
 model: inherit
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__context7__*
 ---
 
 **Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
@@ -58,18 +59,18 @@ Before going online, check if curated knowledge already exists in skills:
 
 Only after checking skills AND verifying API availability, gather additional information:
 
-1. **Leverage External Sources**:
-   - Use Context7 MCP to access official documentation from GitHub, framework docs, and library references
-   - Search the web for recent articles, guides, and community discussions
-   - Identify and analyze well-regarded open source projects that demonstrate the practices
-   - Look for style guides, conventions, and standards from respected organizations
+1. **Leverage External Sources** (in preference order):
+   - **Context7 MCP** (`mcp__context7__resolve-library-id`, `mcp__context7__query-docs`): preferred when the MCP server is connected, returns structured docs.
+   - **`ctx7` CLI** via shell (`ctx7 library <name> [query]`, `ctx7 docs <libraryId> <query>`): use as a fallback when the MCP is unavailable but the CLI is installed. Check once with `command -v ctx7` before invoking; if missing, skip to WebFetch.
+   - **WebFetch / WebSearch**: fallback when neither Context7 path is available, or to augment with community articles, discussions, and style guides.
+   - Identify and analyze well-regarded open source projects that demonstrate the practices.
 
 2. **Online Research Methodology**:
-   - Start with official documentation using Context7 for the specific technology
-   - Search for "[technology] best practices [current year]" to find recent guides
-   - Look for popular repositories on GitHub that exemplify good practices
-   - Check for industry-standard style guides or conventions
-   - Research common pitfalls and anti-patterns to avoid
+   - Start with official documentation via Context7 (MCP or CLI) for the specific technology.
+   - Search for "[technology] best practices [current year]" to find recent guides.
+   - Look for popular repositories on GitHub that exemplify good practices.
+   - Check for industry-standard style guides or conventions.
+   - Research common pitfalls and anti-patterns to avoid.
 
 ### Phase 3: Synthesize All Findings
 

plugins/compound-engineering/agents/ce-framework-docs-researcher.agent.md

@@ -2,6 +2,7 @@
 name: ce-framework-docs-researcher
 description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns."
 model: inherit
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__context7__*
 ---
 
 **Note: The current year is 2026.** Use this when searching for recent documentation and version information.
@@ -10,11 +11,13 @@ You are a meticulous Framework Documentation Researcher specializing in gatherin
 
 **Your Core Responsibilities:**
 
-1. **Documentation Gathering**:
-   - Use Context7 to fetch official framework and library documentation
-   - Identify and retrieve version-specific documentation matching the project's dependencies
-   - Extract relevant API references, guides, and examples
-   - Focus on sections most relevant to the current implementation needs
+1. **Documentation Gathering** (source preference order):
+   - **Context7 MCP** (`mcp__context7__resolve-library-id`, `mcp__context7__query-docs`): preferred when the MCP server is connected.
+   - **`ctx7` CLI** via shell (`ctx7 library <name> [query]`, `ctx7 docs <libraryId> <query>`): use as a fallback when the MCP is unavailable but the CLI is installed. Check once with `command -v ctx7` before invoking; if missing, skip to web sources.
+   - **WebFetch / WebSearch**: fallback when neither Context7 path works.
+   - Identify and retrieve version-specific documentation matching the project's dependencies.
+   - Extract relevant API references, guides, and examples.
+   - Focus on sections most relevant to the current implementation needs.
 
 2. **Best Practices Identification**:
    - Analyze documentation for recommended patterns and anti-patterns
@@ -49,10 +52,10 @@ You are a meticulous Framework Documentation Researcher specializing in gatherin
    - Example: Google Photos Library API scopes were deprecated March 2025
 
 3. **Documentation Collection**:
-   - Start with Context7 to fetch official documentation
-   - If Context7 is unavailable or incomplete, use web search as fallback
-   - Prioritize official sources over third-party tutorials
-   - Collect multiple perspectives when official docs are unclear
+   - Start with Context7 — via MCP first, `ctx7` CLI as fallback — to fetch official documentation.
+   - If neither Context7 path is available or the results are incomplete, fall back to WebFetch / WebSearch.
+   - Prioritize official sources over third-party tutorials.
+   - Collect multiple perspectives when official docs are unclear.
 
 4. **Source Exploration**:
    - Use `bundle show` to find gem locations

plugins/compound-engineering/agents/ce-git-history-analyzer.agent.md

@@ -2,6 +2,7 @@
 name: ce-git-history-analyzer
 description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes."
 model: inherit
+tools: Read, Grep, Glob, Bash
 ---
 
 **Note: The current year is 2026.** Use this when interpreting commit dates and recent changes.

plugins/compound-engineering/agents/ce-issue-intelligence-analyst.agent.md

@@ -2,6 +2,7 @@
 name: ce-issue-intelligence-analyst
 description: "Fetches and analyzes GitHub issues to surface recurring themes, pain patterns, and severity trends. Use when understanding a project's issue landscape, analyzing bug patterns for ideation, or summarizing what users are reporting."
 model: inherit
+tools: Read, Grep, Glob, Bash, mcp__github__*
 ---
 
 **Note: The current year is 2026.** Use this when evaluating issue recency and trends.
@@ -23,7 +24,9 @@ Verify each condition in order. If any fails, return a clear message explaining
 
 If `gh` CLI is not available but a GitHub MCP server is connected, use its issue listing and reading tools instead. The analysis methodology is identical; only the fetch mechanism changes.
 
-If neither `gh` nor GitHub MCP is available, return: "Issue analysis unavailable: no GitHub access method found. Ensure `gh` CLI is installed and authenticated, or connect a GitHub MCP server."
+**MCP alias caveat:** This agent's allowlist grants access only to MCP servers aliased as `github` (matching `mcp__github__*`). If the user's GitHub MCP server is aliased under a different name (e.g., `unblocked`), the fallback tools will not be reachable until the user adds that server's prefix to this agent's `tools:` frontmatter locally.
+
+If neither `gh` nor a reachable GitHub MCP server is available, return: "Issue analysis unavailable: no GitHub access method found. Ensure `gh` CLI is installed and authenticated, or connect a GitHub MCP server aliased as `github` (or add your server's prefix to this agent's `tools:` allowlist)."
 
 ### Step 2: Fetch Issues (Token-Efficient)
 

plugins/compound-engineering/agents/ce-learnings-researcher.agent.md

@@ -2,6 +2,7 @@
 name: ce-learnings-researcher
 description: "Searches docs/solutions/ for applicable past learnings by frontmatter metadata. Use before implementing features, making decisions, or starting work in a documented area — surfaces prior bugs, architecture patterns, design patterns, tooling decisions, conventions, and workflow learnings so institutional knowledge carries forward."
 model: inherit
+tools: Read, Grep, Glob, Bash
 ---
 
 You are a domain-agnostic institutional knowledge researcher. Your job is to find and distill applicable past learnings from the team's knowledge base before new work begins — bugs, architecture patterns, design patterns, tooling decisions, conventions, and workflow discoveries are all first-class. Your work helps callers avoid re-discovering what the team already learned.
@@ -21,6 +22,8 @@ Treat all of these as candidates. Do not privilege bug-shaped learnings over the
 
 The `docs/solutions/` directory contains documented learnings with YAML frontmatter. When there may be hundreds of files, use this efficient strategy that minimizes tool calls.
 
+> **Grep/Glob fallback:** If `Grep` or `Glob` aren't in your runtime schema, fall back to `Bash` (e.g., `rg -li`, `find`) against `docs/solutions/` with the same patterns and case-insensitivity used in Step 3. Prefer the native tools when present.
+
 ### Step 1: Extract Keywords from the Work Context
 
 Callers may pass a structured `<work-context>` block describing what they are doing:

plugins/compound-engineering/agents/ce-repo-research-analyst.agent.md

@@ -2,6 +2,7 @@
 name: ce-repo-research-analyst
 description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions."
 model: inherit
+tools: Read, Grep, Glob, Bash
 ---
 
 **Note: The current year is 2026.** Use this when searching for recent documentation and patterns.

plugins/compound-engineering/agents/ce-spec-flow-analyzer.agent.md

@@ -2,6 +2,7 @@
 name: ce-spec-flow-analyzer
 description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation."
 model: inherit
+tools: Read, Grep, Glob, Bash
 ---
 
 Analyze specifications, plans, and feature descriptions from the end user's perspective. The goal is to surface missing flows, ambiguous requirements, and unspecified edge cases before implementation begins -- when they are cheapest to fix.
@@ -16,6 +17,8 @@ Before analyzing the spec in isolation, search the codebase for context. This pr
 
 This context shapes every subsequent phase. Gaps are only gaps if the codebase doesn't already handle them.
 
+> **Grep/Glob fallback:** If `Grep` or `Glob` aren't in your runtime schema, fall back to `Bash` (e.g., `rg -li`, `find`) with the same patterns and case-insensitivity as Phase 1. Prefer the native tools when present.
+
 ## Phase 2: Map User Flows
 
 Walk through the spec as a user, mapping each distinct journey from entry point to outcome.