feat(agents): SubagentSessionPersistence capability on the wrap_run seam

[mpfaffenberger]

What

Fourteenth entry in the capability-conversion series (#828–#836, #838–#841). Promotes sub-agent session persistence — the success-path _save_session_history call and the crash/interrupt _save_partial_session calls in _invoke_agent_impl — to a first-class pydantic-ai capability, SubagentSessionPersistence, on the wrap_run seam (a previously unclaimed seam; pydantic-ai documents it as the home for cancellation-safe cleanup, and its handler task delivers both run failures and CancelledError into the wrapping coroutine).

Design

• New code_puppy/agents/_subagent_sessions.py — per-invocation dataclass capability (the sub-agent's pydantic agent is itself per-invocation, so instance state is naturally run-scoped; default for_run returns self, and one instance correctly sees every streaming_retry re-invocation — latest attempt's record wins).
  • success → full transcript from result.all_messages() saved at the run boundary (byte-identical payload to the eager save)
  • failure/cancel → partial progress saved via the same _save_partial_session helper the eager path used
  • eager triage mirrored exactly: Exception, KeyboardInterrupt, and (group-nested) CancelledError save; SystemExit/GeneratorExit pass through untouched
• Explicit-when-ours, fallback-for-guests (the feat: deliver Logfire tracing as an explicit Instrumentation capability #838/feat(agents): promote tool-call JSON repair to a ToolCallJsonRepair capability #841 split): the invocation layer reads the capability's custody records via recorded_save() and keeps its messaging/breadcrumbs; the eager saves survive only as fallback for exits the boundary never sees (guest wrappers bypassing capabilities, failures before/after the run proper).
• Test-patch compatibility: save helpers resolve through code_puppy.tools.subagent_invocation at call time, so the existing suites' patches on that module keep intercepting every write (pinned by test).

Bounded divergences (documented + pinned)

1. Transient failures that streaming_retry recovers now checkpoint partial progress per failed attempt (eager saved only when the failure escaped every retry). Final file state converges; strictly more durable.
2. The success save happens inside the run boundary, before high-mode fallback rendering and usage capture — one atomic local file write folds into invoke_agent_with_model's duration_ms.
3. A crash between a successful run and the invocation layer's bookkeeping used to overwrite the session with the older live checkpoint; the boundary save now stands, so the persisted transcript keeps the final response.

Scope notes

• Sub-agent site only: main-agent sessions are persisted by the autosave pipeline, not at the pydantic-ai run boundary (pinned by source test).
• Not spec-constructible (carries a live BaseAgent config reference): get_serialization_name() -> None, per series precedent.

Tests

18 contract tests in tests/agents/test_subagent_session_persistence_capability.py, including real-Agent success/failure/cancellation custody, triage parity, retry latest-wins, and invocation-layer wiring (boundary-save skip, guest fallback, no-clobber guard).

Full suite: 7615 passed, 0 failed (28 skipped, 1 xpassed).

Do not merge yet — review round pending.