mistri 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 820753fb8dd64f485da060568e6dbc8a7af3fa24d63a2cc7dc957b5dbfc9f1d6
-  data.tar.gz: c3e7432802801d19979c3d2906f700fbe3170a1d4950d22f0da88e01b276b905
+  metadata.gz: d46cab51a8a899ddd2e3cd0284a7e9eb4185d1362af158303adb97c2a404a657
+  data.tar.gz: 548bf1b8cdc9d22f304674eb5b876b624c16f6b3cc31839daba83909f78641a5
 SHA512:
-  metadata.gz: 78959db170082e7264a3657dec0ff1e21ebf496a2e2603fe98ca6a7b263f68f980456df3f2881d798f2a8e7a296902700b2dc4e155a9ef43f54a32df5ca75eb7
-  data.tar.gz: 565be0a187d2651d92d43e59351090e0d6623dff13d70bbd1747e5c35f5167f162a4182c111e265734eadbc9aa465be003d5704da61495af281b321036eb0f26
+  metadata.gz: 69b2758b3b137714bb2bffc170ff6520f1d38851230ba19acabbb50042d28234ce934d74555fd328d12d1e8002afe6d96bab8dd21a06567411252e4aeabac973
+  data.tar.gz: 972354e7a95bebfa4f5918efa84f13cbc6e45e9e8dabdf49a60a4d210ecf7c11425866b2ad4d8b648916477568aa2ac69915c98d241311e3778c38667d570558

data/CHANGELOG.md

@@ -3,7 +3,135 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.5.0] - 2026-07-08
+
+- The children registry: Session#children lists every sub-agent a session
+  has spawned as a Mistri::Child, a window onto the child's own session
+  with name, status, report, transcript(tail:) with image bytes stripped,
+  and say(text) to steer it. All of it derives from the store, so it reads
+  the same from any process, while the child runs and forever after.
+- Completion is a contract: every child ends by writing a terminal entry
+  (done with its report, stopped, or failed with the error), including
+  when the child's run raises, so a crashed child never reads as running.
+
+- Spawn policy is an object: Mistri::Spawner carries the pool, types,
+  models, headcount, and dispatcher; SubAgent.spawner and SubAgent.pack
+  stay the front doors.
+- Typed workers: the spawner takes types:, a host registry of Definitions
+  by name. A typed child takes its system prompt, tools, and model from
+  the definition; instructions appends; explicit tool and model args
+  override within the pool and allowlist. "general-purpose" stays the
+  built-in composable default. Types fail at construction, never
+  mid-spawn: a definition with unfilled placeholders or tools the pool
+  lacks is a boot-time ConfigurationError.
+- max_children (default 4) caps live workers per session; a spawn past
+  the cap answers in band and freed slots reopen.
+- SubAgent.pack returns the spawn tool plus the management console in one
+  call, the whole kit for a worker-running agent.
+
+- Background mode: spawn_agent takes mode: "background" when the spawner
+  has a dispatcher, returning a truthful receipt immediately (what the
+  child's status says after dispatch, not what the mode promised) while
+  the parent keeps working; the report arrives on its own (above). The
+  dispatcher is a seam: Dispatchers::Inline (default degrade, synchronous
+  but honest) and Dispatchers::Thread ship in the gem, and a queue host
+  plugs one lambda whose job reconstructs tools from the serializable
+  spec and calls SubAgent.run_dispatched.
+- Lifecycle is entries: subagent_dispatched and subagent_started join the
+  terminal, so status walks the store alone: queued, running, interrupted,
+  done, stopped, failed. A job that dies before starting reads :queued,
+  honestly.
+- A background child runs on its own signal: the parent's turn is over, so
+  only stop_agent and the stop flag end it early. workspace: "parent"
+  requires inline mode, enforced in band.
+
+- Report delivery: a background child's terminal outcome reports back to
+  its parent, exactly once. The report queues in the parent's inbox as a
+  typed subagent_report entry and folds at the next turn boundary the way
+  a steer does (the model sees `[Magpie finished] <report>`; failures
+  carry the error, stops say so), and a report landing as a run finishes
+  cleanly extends it one turn so the parent reacts. A :subagent_report
+  event (agent, session_id, status, content) closes the child's lane in
+  whatever UI watched the spawn. Session#pending_inbox is the
+  steers-and-reports view (hosts that wake idle sessions on steers should
+  watch it instead); Session#deliver_report is the idempotent primitive
+  underneath.
+- Dispatched runs are fenced by the child's lease, taken before the
+  run-or-not decision: a queue that redelivers a live job leaves the
+  owner alone, a retry of a finished or cancelled child is a clean no-op,
+  and a retry of a child a crashed process left mid-run runs it again
+  (previously the guard refused it, wedging the child as interrupted
+  forever). Child#finished? and Child#error are new readers.
+
+- The management console: Mistri::Console.tools returns list_agents,
+  read_agent (tail: to choose how much transcript, wait: to block for the
+  report with an in-band timeout), steer_agent, and stop_agent. Every tool
+  is a thin wrapper over Session#children and the Child facade, the same
+  functions a host UI calls, so agent and user control stay structurally
+  equal. Workers answer to name or session id uniformly in every tool;
+  duplicate names resolve to the latest spawn, ids stay unambiguous, and
+  every state answers honestly in band (already done, nothing to steer,
+  stopping needs a lock adapter).
+
+- Stop one child, keep the run: every sub-agent now runs on its own signal
+  derived from the parent's (AbortSignal#derive), so the parent's abort
+  still cascades down while Child#stop ends a single worker and the parent
+  reasons on with "[the X sub-agent was stopped]". Cross-process stops ride
+  the lock adapter's flags; the lease thread turns them into the child's
+  cooperative abort within a tick.
+- A run stopped during its tool phase now reports :aborted. The final
+  assistant message is clean in that case, so the message's stop reason
+  read :completed and a user-stopped run could claim success; the signal
+  is consulted alongside the message.
+
+- The lock adapter: Mistri.locks takes an adapter for cross-process leases
+  and flags (Locks::Memory built in; Locks::RailsCache as an opt-in require,
+  the Stores::ActiveRecord pattern). Locks.hold keeps a lease alive on a
+  heartbeat from a background thread and releases it cleanly, join and all,
+  so a mid-renewal tick can never re-stamp a released lease.
+- Children gain liveness: every child run holds a lease, and with an
+  adapter configured a child that died without writing its terminal entry
+  reads :interrupted instead of :running forever. Without an adapter
+  nothing changes.
+
+- Session#transcript reads the whole conversation back from the store:
+  entries with image bytes stripped, and with include_children every
+  sub-agent's log spliced in after its link entry, tagged with an
+  "origin" key shaped exactly like the live stream's event origins
+  (nesting joined with ">"). A UI that rebuilds from the transcript shows
+  the lanes it showed live, running children's progress-so-far included;
+  hosts stop hand-walking link entries.
+
+- Tool.define takes ends_turn: true for a tool that is the last word of
+  its turn: once it executes, the loop ends the run instead of prompting
+  the model again, so an ask_user tool hands the floor to a human
+  structurally instead of through prompt discipline. The whole batch it
+  arrived in still executes and is answered; a blocked or denied call
+  never executed, so the model keeps the floor; a parked approval outranks
+  it (the run suspends, and an approved ends_turn call ends the resumed
+  run). A pending steer stays queued for the next run. The Result says it
+  happened (Result#handed_off?), so hosts route on the handoff instead of
+  sniffing messages, and task mode returns the handoff as-is rather than
+  re-prompting for JSON while a human holds the floor.
+
+- Store appends tolerate concurrent writers. Sessions have more than one
+  appender by design (the loop, a steer from a web process, a worker's
+  report from a job), so the ActiveRecord store's unique index is now
+  concurrency control rather than a tripwire: a writer that loses the
+  position race retries at the next slot, bounded, then raises loudly.
+  The JSONL store writes each line in a single call, so concurrent
+  appenders interleave whole lines, never fragments.
+
+- The Fake provider streams tool-call arguments in chunks, and each
+  delta's partial carries the in-progress call with arguments parsed so
+  far, the same shape a real assembler builds. A consumer that renders
+  tool input as it arrives (a page preview, a code block) is now testable
+  headless.
+- Each run of a named specialist can carry its own name: the delegate
+  tool takes an optional name argument, so two parallel researchers read
+  as Corgi and Beagle in lanes, lists, and links instead of "researcher"
+  twice. SubAgent.sanitize_label is the one shared sanitizer behind
+  specialist runs and spawner labels.
 
 ## [0.4.1] - 2026-07-06
 
@@ -144,7 +272,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   keep their old arity. Events gained an origin field.
 
 - Task mode: Agent#task(input, schema:) runs an exchange that must end in
-  JSON matching the schema — tools run as usual, providers constrain the
+  JSON matching the schema: tools run as usual, providers constrain the
   final answer natively where supported (Anthropic output_config, OpenAI
   text.format strict, Gemini responseJsonSchema when no tools), and the
   answer validates client-side everywhere. A violation goes back to the
@@ -164,8 +292,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Rails integration: `rails generate mistri:install YourModel` creates a
   host-named entry model and its migration for Stores::ActiveRecord
   (MEDIUMTEXT payload on MySQL-family adapters). Streaming sinks under
-  Mistri::Sinks — ActionCable (lazy server, injectable), SSE (outbound
-  frames to any IO), and Coalesced (merges delta bursts to UI speed) — all
+  Mistri::Sinks: ActionCable (lazy server, injectable), SSE (outbound
+  frames to any IO), and Coalesced (merges delta bursts to UI speed), all
   pure Ruby, usable as `agent.run(input, &sink)`. No Railtie: generators
   auto-discover and everything else duck-types.
 

data/README.md

@@ -104,7 +104,7 @@ end
 
 Handlers and hooks can take the run's context as a second argument, and
 `context.app` carries whatever object you pass as `Mistri.agent(context:)`
-— the acting user, a tenant, a request — so tools stay authorization-aware
+(the acting user, a tenant, a request), so tools stay authorization-aware
 without closure gymnastics:
 
 ```ruby
@@ -116,6 +116,21 @@ Mistri::Tool.define("book_hotel", "Books the chosen hotel.") do |args, context|
 end
 ```
 
+A tool can also be the last word of its turn. `ends_turn: true` makes the
+loop end the run once the tool executes, instead of prompting the model
+again: an `ask_user` tool hands the floor to a human structurally, no
+"remember to stop after asking" prompt required. The result says it
+happened (`result.handed_off?`), and the answer arrives as the next run's
+input:
+
+```ruby
+ask_user = Mistri::Tool.define("ask_user", "Ask the human and wait.",
+                               ends_turn: true,
+                               schema: -> { string :question, "The question", required: true }) do |args|
+  "Question presented to the user."
+end
+```
+
 ## Human approval
 
 Mark a tool `needs_approval: true` (or a predicate on its arguments) and the
@@ -152,6 +167,10 @@ finishes cleanly extends the run so it gets answered.
 Mistri::Session.new(store:, id: session_id).steer("Make the headline blue instead.")
 ```
 
+Background workers' reports arrive through the same inbox (see Sub-agents).
+A host that wakes an idle session when a steer lands should watch
+`session.pending_inbox`, which holds both, in arrival order.
+
 ## Sessions
 
 A session is the durable record of a run: an append-only entry log over a
@@ -215,6 +234,10 @@ result = agent.task("Extract the pricing tiers from this page.", schema: schema)
 result.output # => { "tiers" => [...] }, parsed and validated
 ```
 
+A run that suspends for approval, or that an `ends_turn` tool ended,
+returns as-is: validation applies to answers, not handoffs. Route on
+`result.handed_off?` and ask again once the human's answer arrives.
+
 ## Skills
 
 Expert playbooks with progressive disclosure: each skill costs one line in
@@ -248,7 +271,9 @@ agent = Mistri.agent(definition.model,
 Delegate to a child agent with a clean context: exploration fills the
 child's window, and only the final answer returns. Children run on their own
 sessions in your store, linked in the parent transcript; their events stream
-into the parent tagged with an `origin`.
+into the parent tagged with an `origin`. Each run of a specialist can carry
+its own name, so two parallel researchers read as Corgi and Beagle in your
+UI instead of "researcher" twice.
 
 ```ruby
 researcher = Mistri::SubAgent.new(
@@ -260,12 +285,65 @@ agent = Mistri.agent("claude-opus-4-8", tools: [researcher.tool])
 ```
 
 Or hand the model an open spawn tool and let it compose its own workers:
-a name for the event stream, instructions, a tool subset, and a
-host-allowlisted model per child. Several spawns in one turn fan out in
-parallel:
+a name, instructions, a tool subset, and a host-allowlisted model per
+child. Several spawns in one turn fan out in parallel. `pack` is the whole
+kit: the spawn tool plus a management console (`list_agents`, `read_agent`,
+`steer_agent`, `stop_agent`), with curated types and an optional
+dispatcher:
 
 ```ruby
 spawn = Mistri::SubAgent.spawner(provider: provider, tools: [fetch_page, search])
+
+tools = Mistri::SubAgent.pack(
+  provider: provider, tools: [fetch_page, search],
+  types: { "researcher" => Mistri::Definition.load("agents/researcher.md") },
+  models: ["claude-haiku-4-5-20251001"],
+  dispatcher: Mistri::Dispatchers::Thread.new,      # or one lambda onto your queue
+)
+```
+
+A typed worker takes its prompt, tools, and model from the host's
+definition; `general-purpose` stays open for the model to compose.
+`max_children` (default 4) caps live workers, and every policy violation
+answers the model in band.
+
+Everything cross-process (stopping a worker from another process, the
+`:interrupted` liveness read, and the lease fence below) rides a lock
+adapter; configure one at boot. Without it, workers still run, but stops
+need the parent's own signal, a crashed child reads `:running`, and
+dispatched retries are unfenced:
+
+```ruby
+Mistri.locks = Mistri::Locks::RailsCache.new   # Locks::Memory for a single process
+```
+
+With a dispatcher, `spawn_agent` takes `mode: "background"`: the model gets
+a truthful receipt at once and keeps working while the child runs. The
+console manages the roster with the same functions a host UI calls, so
+agent and user control stay structurally equal: either can read a worker's
+transcript, steer it mid-run, or stop it, from any process. When a worker
+finishes, its report delivers itself: a typed entry queues in the parent's
+inbox and folds at the next turn boundary as `[Corgi finished] <report>`
+(failures carry the error), while a `:subagent_report` event settles the
+worker's lane in whatever UI watched the spawn. In a queue host, the job
+rebuilds tools from the serializable spec and calls
+`SubAgent.run_dispatched`, which fences on the child's lease: a redelivered
+job leaves the running owner alone, a retry of a finished child is a no-op,
+and a retry of a crashed one runs it again.
+
+Everything about a child derives from the store and reads the same from
+any process, while it runs and forever after:
+
+```ruby
+session.children               # => [#<Mistri::Child Corgi running>, ...]
+child.status                   # :queued, :running, :done, :stopped, :failed
+child.report                   # the terminal entry's report, once finished
+child.say("Check pricing too") # folds at the child's next turn boundary
+child.stop                     # cooperative, cross-process, within a tick
+
+session.transcript(include_children: true)
+# the whole conversation, each child's log spliced at its link entry and
+# origin-tagged like the live stream: a reloading UI rebuilds its lanes
 ```
 
 ## Editing documents
@@ -405,8 +483,11 @@ Mistri.agent("claude-opus-4-8", provider_options: { cache: false })
 
 ## Testing
 
-`rake test` is hermetic and fast. `rake integration` runs every feature end
-to end against real provider APIs, once per model in the matrix: an
+`rake test` is hermetic and fast. The Fake provider streams like the real
+ones, tool-call arguments included: each delta's partial carries the
+in-progress call with arguments parsed so far, so a UI that renders tool
+input as it arrives tests headless. `rake integration` runs every feature
+end to end against real provider APIs, once per model in the matrix: an
 Anthropic, an OpenAI, and a Gemini model by default. Scenarios assert that
 coined codenames (a ghost of a word like `Wraithowyn` exists in no training
 data) flowed through tool results, summaries, and child agents: proof of

data/lib/mistri/abort_signal.rb

@@ -32,6 +32,16 @@ module Mistri
       nil
     end
 
+    # A signal that trips when this one does, never the reverse: abort the
+    # derived signal alone and this one runs on. Returns [signal, handle];
+    # remove the handle when the derived work ends, so a finished child
+    # never leaks a callback into a later abort.
+    def derive
+      child = AbortSignal.new
+      handle = on_abort { child.abort!(reason) }
+      [child, handle]
+    end
+
     # Register a callback for the moment of abort. Fires immediately when the
     # signal is already tripped. Returns a handle for #remove_callback.
     def on_abort(&callback)

data/lib/mistri/agent.rb

@@ -13,8 +13,12 @@ module Mistri
   # marked needs_approval suspends the run instead of executing: the run
   # returns at once (no thread ever waits on a human), the decision arrives
   # later as a session entry from any process, and resume settles it and
-  # carries on. Session#steer queues a user message from any process while
-  # the loop runs; it folds into the transcript at the next turn boundary.
+  # carries on. A tool marked ends_turn ends the run once it executes: the
+  # model does not get another word, and whatever comes next (a human's
+  # answer to ask_user, say) arrives as the next run's input. Session#steer
+  # queues a user message from any process while the loop runs; it folds
+  # into the transcript at the next turn boundary, and a background child's
+  # report arrives through the same inbox.
   class Agent
     # compaction defaults on so long sessions survive their context window;
     # pass false to disable, or a tuned Compaction. It only ever triggers
@@ -68,7 +72,7 @@ module Mistri
               "run needs input text or images"
       end
 
-      fold_steers # steers queued while idle arrived first; keep that order
+      fold_inbox # anything queued while this session sat idle arrived first; keep that order
       @session.append_message(Message.user_with_images(input, images))
       loop_turns(signal, output_schema, &emit)
     end
@@ -76,7 +80,8 @@ module Mistri
     # Continue a suspended run. Undecided approvals return immediately, still
     # suspended. Decided ones settle first: approved calls execute, denied
     # calls answer in band so the model knows and can react. Then the loop
-    # carries on as if it never stopped.
+    # carries on as if it never stopped, unless a settled call's tool ends
+    # the turn, in which case its execution was the run's last word.
     def resume(signal: nil, &emit)
       open = @session.open_approvals
       pending = open.select { |approval| approval[:decision].nil? }
@@ -86,7 +91,12 @@ module Mistri
                           usage: Usage.zero)
       end
 
-      settle(open, signal, &emit)
+      executed = settle(open, signal, &emit)
+      if executed.any? { |call| ends_turn?(call) }
+        last = @session.messages.reverse_each.find(&:assistant?)
+        return finished(last, Usage.zero, signal, handed_off: true)
+      end
+
       loop_turns(signal, nil, &emit)
     end
 
@@ -98,21 +108,24 @@ module Mistri
     #
     # A run that suspends for approval returns as-is: validation applies to
     # completed runs only, so resume the session and re-ask if that happens
-    # mid-task.
+    # mid-task. A run an ends_turn tool ended returns as-is too: the floor
+    # belongs to whoever answers, and re-prompting for JSON would steal it
+    # back. Ask again once the answer arrives.
     def task(input, schema:, images: [], signal: nil, fixes: 1, &emit)
-      result = run(task_input(input, schema), images: images, signal: signal,
-                                              output_schema: schema, &emit)
+      result = run(TaskOutput.prompt(input, schema), images: images, signal: signal,
+                                                     output_schema: schema, &emit)
       spent = result.usage
       fixes.downto(0) do |remaining|
         result = result.with(usage: spent)
         return result unless result.completed?
+        return result if result.handed_off?
 
-        value = parse_output(result.text)
-        errors = task_errors(value, schema)
+        value = TaskOutput.parse(result.text)
+        errors = TaskOutput.errors(value, schema)
         return result.with(output: value) if errors.empty?
         raise SchemaError, "task output failed validation: #{errors.join("; ")}" if remaining.zero?
 
-        result = run(fix_prompt(errors), signal: signal, output_schema: schema, &emit)
+        result = run(TaskOutput.fix_prompt(errors), signal: signal, output_schema: schema, &emit)
         spent += result.usage
       end
     end
@@ -144,7 +157,7 @@ module Mistri
         reason = @budget.exceeded(turns: turns, usage: usage, elapsed: monotonic_now - started)
         return stop_for_budget(reason, usage, &emit) if reason
 
-        fold_steers
+        fold_inbox
         compacted = auto_compact(&emit)
         usage += compacted[:usage] if compacted&.dig(:usage)
         last = run_turn(signal, output_schema, &emit)
@@ -153,20 +166,21 @@ module Mistri
 
         # Any tool call the turn made must be answered or parked, or the
         # transcript is unpairable and replay fails.
-        parked = last.tool_calls? ? run_tools(last, signal, &emit) : []
+        parked, ended = last.tool_calls? ? run_tools(last, signal, &emit) : [[], false]
         return suspended(last, parked, usage) if parked.any?
-        return finished(last, usage) if done?(last, signal)
+        return finished(last, usage, signal, handed_off: ended) if ended || done?(last, signal)
       end
     end
 
-    # A steer that lands while the model finishes cleanly extends the run one
-    # more turn so it gets answered. Aborts, errors, and length stops always
-    # end the run; the steer stays pending for the next one.
+    # A steer or a child's report that lands while the model finishes
+    # cleanly extends the run one more turn, so it is answered rather than
+    # left dangling. Aborts, errors, and length stops always end the run;
+    # the inbox stays pending for the next one.
     def done?(last, signal)
       return false if last.stop_reason == StopReason::TOOL_USE && !signal&.aborted?
       return true if signal&.aborted? || last.stop_reason != StopReason::STOP
 
-      @session.pending_steers.empty?
+      @session.pending_inbox.empty?
     end
 
     # Compact when the context has grown into the reserve. A failed
@@ -187,13 +201,15 @@ module Mistri
       @compaction&.window || Models.find(@provider.model)&.context_window
     end
 
-    # Materialize queued steers into the transcript in arrival order. The
-    # folded message entry carries the steer id, which is what marks the steer
-    # consumed: one append is both the fold and the marker, so a crash between
-    # steers never double-delivers.
-    def fold_steers
-      @session.pending_steers.each do |steer|
-        @session.append("message", "message" => steer["message"], "steer_id" => steer["id"])
+    # Materialize the inbox, queued steers and sub-agent reports alike, into
+    # the transcript in arrival order. The folded message entry carries the
+    # source entry's id under its marker key, which is what marks the entry
+    # consumed: one append is both the fold and the marker, so a crash
+    # between folds never double-delivers.
+    def fold_inbox
+      @session.pending_inbox.each do |entry|
+        marker = Session::INBOX.fetch(entry["type"])
+        @session.append("message", "message" => entry["message"], marker => entry["id"])
       end
     end
 
@@ -258,37 +274,44 @@ module Mistri
 
     # Answer or park the assistant's tool calls. Ungated calls execute (only
     # on a genuine tool_use turn with no abort; otherwise they pair with
-    # interrupted results). Gated calls park as approval requests and are
-    # returned, so the loop can suspend. Nothing is left dangling either way.
+    # interrupted results). Gated calls park as approval requests. Nothing
+    # is left dangling either way. Returns the parked calls and whether an
+    # executed tool ends the turn; a parked call outranks an executed
+    # ends_turn, because a suspension is the stronger stop and the model
+    # regains the floor when the run resumes.
     def run_tools(assistant, signal, &emit)
       calls = assistant.tool_calls
       unless assistant.stop_reason == StopReason::TOOL_USE && !signal&.aborted?
         calls.each { |call| answer(call, ToolExecutor::INTERRUPTED, &emit) }
-        return []
+        return [[], false]
       end
 
       parked, free = screen(calls, signal, &emit).partition { |call| gated?(call) }
-      execute(free, signal, &emit)
+      executed = execute(free, signal, &emit)
       parked.each do |call|
         @session.append("approval_request", "call" => call.to_h)
         emit&.call(Event.new(type: :approval_needed, tool_call: call))
       end
-      parked
+      [parked, executed.any? { |call| ends_turn?(call) }]
     end
 
+    # Returns the calls that actually executed (denied ones only answer).
     def settle(open, signal, &emit)
       approved, denied = open.partition { |approval| approval[:decision]["approved"] }
       cleared = screen(approved.map { |approval| approval[:call] }, signal, &emit)
-      execute(cleared, signal, &emit)
+      executed = execute(cleared, signal, &emit)
       denied.each do |approval|
         note = approval[:decision]["note"]
         text = "The user denied this tool call#{note ? ": #{note}" : "."}"
         answer(approval[:call], text, &emit)
       end
+      executed
     end
 
+    # Runs the calls and answers each; returns the calls that executed
+    # (blocked and parked calls never reach here).
     def execute(calls, signal, &emit)
-      return if calls.empty?
+      return [] if calls.empty?
 
       results = ToolExecutor.call(calls, @tools_by_name, signal: signal,
                                                          max_concurrency: @max_concurrency,
@@ -299,6 +322,7 @@ module Mistri
         result = rewrite(call, result, context) if @after_tool
         answer(call, result, duration: seconds, &emit)
       end
+      calls
     end
 
     # A blocked call answers in band, so the model reads the reason and
@@ -347,10 +371,22 @@ module Mistri
       tool ? tool.needs_approval?(call.arguments) : false
     end
 
-    def finished(message, usage)
+    def ends_turn?(call)
+      tool = @tools_by_name[call.name]
+      tool ? tool.ends_turn? : false
+    end
+
+    # A run stopped during its tool phase ends with a clean assistant
+    # message, so the message's stop reason alone would read :completed;
+    # the signal is what knows the user stopped it. handed_off marks a run
+    # an ends_turn tool ended, and only a genuinely completed one: a run
+    # aborted during that same tool phase handed nothing to anyone.
+    def finished(message, usage, signal = nil, handed_off: false)
       status = { StopReason::ABORTED => :aborted, StopReason::BUDGET => :budget,
                  StopReason::ERROR => :error }.fetch(message.stop_reason, :completed)
-      Result.new(message: message, status: status, usage: usage)
+      status = :aborted if status == :completed && signal&.aborted?
+      Result.new(message: message, status: status, usage: usage,
+                 handed_off: handed_off && status == :completed)
     end
 
     def suspended(message, parked, usage)
@@ -367,35 +403,6 @@ module Mistri
       Result.new(message: message, status: :budget, usage: usage)
     end
 
-    # Distinguishable from a parsed nil: JSON "null" is a valid value.
-    PARSE_FAILED = Object.new.freeze
-    private_constant :PARSE_FAILED
-
-    def task_input(input, schema)
-      "#{input}\n\nAnswer with ONLY a JSON value matching this schema:\n" \
-        "#{JSON.generate(Schema.strict(schema))}"
-    end
-
-    def parse_output(text)
-      body = text.to_s.strip
-      body = body[/\A```(?:json)?\s*(.*?)```\z/m, 1] || body
-      JSON.parse(body)
-    rescue JSON::ParserError
-      PARSE_FAILED
-    end
-
-    def task_errors(value, schema)
-      return ["the answer is not valid JSON"] if value.equal?(PARSE_FAILED)
-
-      Schema.violations(value, schema)
-    end
-
-    def fix_prompt(errors)
-      lines = errors.map { |error| "- #{error}" }.join("\n")
-      "Your answer did not satisfy the required output schema. Problems:\n" \
-        "#{lines}\nReply with ONLY the corrected JSON."
-    end
-
     def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 end