ROADMAP-15 — P2 — Agent.run: extract a _result() helper (8 duplicated RunResult constructions) #107

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M16-T02 · Priority: P2 · Effort: medium

Problem

Agent.run is ~375 lines with 8 near-identical RunResult(...) constructions (each ~15 lines, 6 identical fields) and four finalize/raise tails, dominated by the raise_on_failure dual mode that exists mainly for tests. Also a latent trap: the nested _finalize_and_return closure closes over messages, which is defined later in the method (agent.py:198–260) — safe only by Python late binding.

Evidence

• agentkit/core/agent.py:153–527 — the method in full
• agentkit/core/agent.py:366–368, 484–486, 507–509, 525–526 — duplicated tails

Suggested fix / acceptance criteria

• One _result(status, failure_reason=..., ...) helper builds RunResult; all 8 sites funnel through it
• raise_on_failure applied at a single exit point
• Closure defined after the variables it closes over (or explicit parameters)
• ~100 lines removed with zero behaviour change; full suite green

Suggested branch / commit

refactor/agent-result-helper · refactor(core): extract RunResult construction into a helper