feat: add hook-driven agent routing

[hamza-jeddad]

What changed

• Agents get a routing block (allowed_agents, default_agent) and two new hook events, before_agent_run and after_agent_complete. Both are in pkg/config/latest and agent-schema.json, and are validated at load time: one selector per event, no routing cycles, no force_handoff together with after_agent_complete, and evaluator routes must cover every choice.
• A hook can return {"transition":{"action":"route","agent":"..."}}. Control output is always validated strictly, and a block beats a route (pkg/hooks).
• A new evaluator selector turns a choice evaluator's answer into a route through a routing_policy (routes, min_probability). It checks the whole probability distribution and falls back to default_agent on ties, low confidence, or provider failures.
• The runtime (pkg/runtime/routing.go, loop.go) keeps per-invocation state, switches agents per session instead of mutating the shared agent, selects before the model or response cache is used, and routes after cached and structured-output answers too.
• Every decision is stored in the session as a routing_decision item and emitted as an event (pkg/session/routing_decision.go). Records hold the evaluator, chosen outcome, probability, destination, and fallback reason, never the request or the answer.
• Four examples (examples/hook_routing*.yaml) and docs for hooks, evaluators and multi-agent.

Why

A hook can now choose which agent runs, without asking an LLM to call transfer_task or handoff. That makes routing deterministic and cheap, and an agent that is routed away from never calls its own model. The decision record exists so a run's routing can be audited after the fact.

How it works

before_agent_run fires once per agent activation and can replace that activation with another agent. after_agent_complete fires after a successful answer and can continue the same conversation with another agent. Both validate the target against routing.allowed_agents. Hook crashes, timeouts, malformed output, and disallowed targets stop the run instead of continuing with the wrong agent. Cancellation, budget exhaustion, and invalid usage accounting also stop the run and never use the default agent. Each user request restarts at the entry agent, and a run is capped at 100 transitions.

Testing

• New and extended tests in pkg/config, pkg/hooks, pkg/runtime, pkg/session, pkg/teamloader, pkg/cli, pkg/server, pkg/a2a, pkg/chatserver, pkg/mcp, and e2e/tui, all with fake models and evaluators and no network.
• They cover budgets and invalid or unknown accounting, structured output, evaluator scoping and imports, headless --exec and --json runs, serve api, A2A, the OpenAI-compatible chat server, and the native TUI.
• task build and task lint pass, and go test -race on the touched packages shows no failures or data races.
• task test passes except TestExtraWorkspace in pkg/sandbox. It fails on any machine whose ~/.config/cagent/config.yaml has an alias named default, because the test reads that file. It fails the same way on main and passes with an empty home directory.
• I ran examples/hook_routing_local.yaml by hand against a local AutoJEV server and confirmed the decisions were stored. The examples that use the hosted TypeSafe endpoint were not run against it.

Notes

• before_agent_run fires before session_start and user_prompt_submit, so a prompt blocked by user_prompt_submit still costs one assessment.
• A draft can stream to the user before after_agent_complete reviews it. The review does not retract it.
• Not included: isolated or nested steps, parallel branches, retries, resuming mid-route, and selectors other than choice evaluators and commands.
• ACP is not tested separately. It builds an ordinary unpinned session and uses the same run loop.
• The TUI and /export do not display decision records yet. They are in the session database and in JSON exports.
• The commits are SSH-signed but have no DCO Signed-off-by trailer. I can add them if that is required.

[dgageot]

Three correctness issues below, each reproduced with a focused regression test. The existing suite passes: task build, task test, task lint, and race tests for runtime/hooks/session/config/teamloader.