feat(runtime): return clarification as a per-Run structured outcome

[Notryag]

Problem

ClarificationMiddleware currently writes pending clarification data into checkpointed thread_data. A host product then reinterprets final graph state as a durable interaction. This creates two state authorities and lets checkpoint history be confused with the current Run.

Decision

Keep clarification product-neutral in North, but make it transient and per-Run:

• ask_clarification produces a versioned ToolMessage artifact with question, response kind, and bounded options.
• The middleware must not read or write thread_data and must not clear state on a later HumanMessage.
• RunExecutor collects clarification artifacts observed during its current astream() invocation and passes a structured RunExecutionResult / ClarificationRequest tuple to its completion hook before the end sentinel.
• A clarification call should terminate the current Run. Do not use LangGraph interrupt(), which changes the contract to checkpoint-resume.

Acceptance criteria

• A checkpoint containing an old clarification artifact or old thread_data cannot cause a later Run to report a clarification.
• Current-Run clarification is available to the host through a public, versioned North API.
• The model does not continue to another model turn or execute sibling write tools after clarification is requested.
• Multiple clarification calls are exposed explicitly; hosts do not silently receive only the last one.
• Artifact remains model-hidden while available to host streaming/audit.
• Runtime terminal callback receives the outcome before publish_end.
• Public API and focused middleware/runtime tests cover the behavior.

Out of scope

North must not persist product interaction state, expiry, CAS, UI choices, or resume semantics. Hosts remain responsible for durable interaction lifecycle.

[Notryag]

2026-07-29 Dayboard production evidence

The structured per-Run outcome is now consumed successfully by Dayboard, but the acceptance criterion "the model does not continue to another model turn after clarification" is still unmet at North revision bd6f65409d978b621e6d0fb8a92514104c2f045b.

Production Run b419e0e6-bb3a-4f76-91e3-2a1695d0e979 executed this sequence:

1. model call -> search_calendar_entries
2. model call -> ask_clarification
3. an additional model call after the clarification tool
4. clarification_requested typed outcome

Usage for the clarification Run was 11,139 input + 165 output = 11,304 tokens across 3 model calls. The third, unnecessary call alone used 3,932 input + 49 output tokens. The full Dayboard same-01 flow passed its REST Oracle and CAS-resume checks but required 21,677 tokens across 6 calls.

Current ClarificationMiddleware._track_clarification() returns a Command(update=...) without terminating the graph. Please make the clarification command terminate the current Run (for example with an explicit END transition, if compatible with LangGraph middleware semantics), while preserving the ToolMessage/state update needed by RuntimeExecutionResult.clarification.

Required regression test:

• model searches and receives multiple candidates;
• next model call invokes ask_clarification;
• no later model call or sibling write tool runs;
• RunExecutor still returns the typed clarification outcome before stream end.