feat: role-based tool sets for agent execution

[kokevidaurre]

Context

Analysis of Claude Code internals reveals that every tool schema is sent in every API request. Our agents currently pass ~30 --allowedTools entries regardless of agent role. Scanners only need read tools; leads need read + write for state files; only workers need the full set.

Fewer tools = smaller tool schemas = token savings on every API call.

From Claude Code Source

Claude Code uses isConcurrencySafe() and tool filtering per agent type:

• ASYNC_AGENT_ALLOWED_TOOLS: whitelist for background agents
• filterToolsByDenyRules(): strips tools the model should never see
• Tool schemas are cached per session but still consume input tokens

Proposed Changes

In execution-engine.ts, replace the static --allowedTools list with role-aware tool sets:

const SCANNER_TOOLS = [
  'Read', 'Glob', 'Grep', 'WebFetch', 'WebSearch',
  'Bash(git:*)', 'Bash(gh:*)', 'Bash(curl:*)',
  'Bash(ls:*)', 'Bash(cat:*)', 'Bash(head:*)', 'Bash(tail:*)',
  'Bash(wc:*)', 'Bash(echo:*)', 'Bash(date:*)', 'Bash(squads:*)',
];

const LEAD_TOOLS = [
  ...SCANNER_TOOLS,
  'Write', 'Edit',  // leads write state/feedback
  'Bash(node:*)', 'Bash(npx:*)',
];

const WORKER_TOOLS = [ /* current full set */ ];

Implementation

1. Read agent role: from frontmatter at execution time (already parsed by parseAgentFrontmatter)
2. Map role → tool set (scanner|monitor → SCANNER, lead|coo|verifier → LEAD, default → WORKER)
3. Pass the filtered set to --allowedTools

Files to change

• src/lib/execution-engine.ts — tool set constants + role mapping + --allowedTools injection (~L737-753)

Estimated savings

With 19 squads × ~3 agents each, reducing scanner tool schemas from 30 to 13 saves ~500 tokens per API call × multiple calls per run.

Risks

• Agents may need tools we don't anticipate. Mitigation: WORKER_TOOLS stays as default, only opt-in roles get restricted sets.
• Agent tool removed from scanner set — scanners can't spawn sub-agents. If needed, add Agent to SCANNER_TOOLS.