feat: subagents — filtered MCP endpoints + per-provider agent files

[YossifNassar]

Summary

Introduces named sub-agent configurations in capabilities.yaml under the subagents key. Each sub-agent gets a filtered MCP endpoint that exposes only its declared tools, plus provider-native agent definition files for Claude Code and Cursor.

What's new

subagents section in capabilities.yaml

subagents:
  - id: infra-agent
    description: AWS CDK and Terraform specialist. Use when working in backend-infra/ or user-infra/.
    skills:
      - my-iac-skill
    tools:
      - search_cdk_docs
      - validate_cfn
    instructions: |
      Work exclusively in backend-infra/ and user-infra/.

  - id: api-agent
    description: Python Lambda and FastAPI specialist. Use for Lambda function work.
    skills:
      - my-serverless-skill
    tools:
      - get_lambda_guidance
      - sam_logs

Filtered MCP endpoints

• New route /{projectId}/agents/{id}/mcp — same CapaMCPServer class, instantiated with an agentId
• tools/list returns only this agent's declared tools (resolved to qualified names, e.g. aws-iac.search_cdk_docs)
• tools/call rejects unauthorized tool calls with a clear JSON-RPC error
• Filtering applied in both handleMessage() (HTTP path) and setupHandlers() (SDK transport path)
• Server cache uses projectId:agentId key so sub-agent instances are independent

Per-provider agent files (on capa install)

Provider	File written	Format
claude-code	.claude/agents/{id}.md + CLAUDE.md block	name/description/model: inherit frontmatter
cursor	.cursor/agents/{id}.md	name/description/model/readonly/is_background frontmatter

Cursor reads .cursor/agents/*.md to auto-delegate based on the description field — no separate MCP server entry per sub-agent is needed.

Migration / cleanup

• purgeCursorSubAgentMCPEntries() removes stale capa-{id} entries from .cursor/mcp.json and stale .cursor/rules/*.mdc files from old implementations
• capa clean removes all generated agent files and MCP registrations by reading DB-tracked sub-agents

DB tracking

• New sub_agents table with CASCADE DELETE on project removal
• upsertSubAgent / getSubAgents / removeSubAgent helpers

Test plan

• src/server/__tests__/sub-agent-filter.test.ts — getQualifiedToolName + tool filtering logic (8 tests)
• src/cli/utils/__tests__/sub-agent-instructions.test.ts — agent file writing/removal for both providers, upsert idempotency, multi-agent isolation (11 tests)
• src/cli/utils/__tests__/sub-agent-mcp.test.ts — MCP registration, cursor skip, unregister, purge migration (8 tests)
• src/db/__tests__/sub-agents.test.ts — CRUD, project isolation, cascade delete (8 tests)
• All 335 tests pass (0 failures)

🤖 Generated with Claude Code