[DSP-1] Agents: port run_swarm / run_task / review_fix_loop + role+mode routing from devswarm

[justrach]

Child of #53 (DevSwarm port epic). Source: justrach/devswarm.

Tools to port (7)

DevSwarm tool	Purpose	Forge landing zone (proposed)
run_agent	Execute a single agent with role + mode routing	forge_main / SDK agents.run
run_swarm	Orchestrator → parallel workers → synthesizer	forge_app orchestrator + forge_main driver
run_task	Execute a multi-step task-chain preset	forge_app (uses chain presets from DSP-7)
review_fix_loop	Iterate reviewer→fixer until NO_ISSUES_FOUND or max-iter	forge_app
run_reviewer	Dedicated review agent	forge_repo/src/agents/ (new role)
run_explorer	Deep codebase exploration agent	forge_repo/src/agents/ (new role)
run_zig_infra	Skip — devswarm-specific. Replace with run_rust_infra only if there's a demonstrated need.

Role + mode routing

8 roles: finder, reviewer, fixer, explorer, architect, orchestrator, synthesizer, monitor.
4 modes: smart, rush, deep, free.

Each role pins a default model tier:

• Opus → architect, orchestrator
• Sonnet → finder, reviewer, fixer, explorer, synthesizer
• Haiku → monitor

Mode tunes inference strategy (smart=default, rush=cheap-fast, deep=long-context, free=cost-floor).

Acceptance criteria

• run_swarm runs N parallel workers in isolated worktrees (depends on [P2-9] ExecutionEnvironment trait + Local impl + SDK exec.registerEnvironment (route shell tools through trait) #43 ExecutionEnvironment trait and devswarm's ADR-001 / their #213).
• Workers receive only their own task text, not the orchestrator preamble — encode as a test (lesson from devswarm #389).
• Workers run the role assigned, not a default fixer (devswarm #388).
• Workers see a scoped tool set, not the full MCP tool list (devswarm #374).
• review_fix_loop terminates on NO_ISSUES_FOUND or configurable max_iter (default 5).
• Role+mode routing is configurable per-call and via .codegraff/swarm.toml.
• One end-to-end demo: spawn 3 workers on a real codegraff bug, synthesize, close the loop.

Related codegraff issues

• graff-agent: Hermes-class harness in a NEW repo, prerequisites in codegraff #34 graff-agent Hermes harness — this work likely lives inside that harness if it ships in a separate repo.
• P0: agents stuck in analysis-paralysis loop — re-read same files, never write code #27 P0 analysis-paralysis loop — role-routing + review-fix termination is the cure.
• [P2-8] Plugin lifecycle hooks: pre/post tool, pre/post LLM, session start/end (Rust HookRegistry + SDK plugins.on) #42 [P2-8] plugin lifecycle hooks — workers need pre/post tool + pre/post LLM hooks.
• [P2-9] ExecutionEnvironment trait + Local impl + SDK exec.registerEnvironment (route shell tools through trait) #43 [P2-9] ExecutionEnvironment trait — workers need worktree isolation.