feat(opencode): interrupt a running subagent — steer / cancel / abort

[iceteaSA]

Issue for this PR

Closes #38966

Related: #32431 (stuck subagents can't be nudged — the steer case, but this PR does not claim to close it without demonstrating stuck-session recovery), #27511 (suspend/resume — overlapping on graceful stop, but resumable suspension is a different guarantee than cancel).

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Lets a parent agent (via tools) or the human (via TUI esc) steer, gracefully cancel, or hard-abort a single running Task subagent mid-run, without affecting the parent or sibling subagents. Off by default behind OPENCODE_EXPERIMENTAL_SUBAGENT_INTERRUPT.

A small per-instance Interrupt service holds one pending interrupt per child plus a terminal record. The child consumes it at its own runLoop turn boundary (session/prompt.ts): steer injects a <steer> frame and the child adapts and continues; cancel injects a <cancel> frame, records a terminal, and force-breaks within a small grace window; abort records a terminal and cancels the BackgroundJob immediately. Cancel is turn-boundary-soft — a child inside a long-running tool call only breaks once that tool returns, so task_abort is the hard fallback.

Surfaces:

• Tools task_steer / task_cancel / task_abort, gated by permission.interrupt.
• POST /session/:id/interrupt (subagent sessions only; rejects non-running children).
• TUI: esc on a subagent opens a Steer/Cancel/Abort menu, then a reason prompt.

Interrupt tools reach any descendant, not just direct children, through a bounded ancestry walk that fails closed off the caller's subtree — otherwise a runaway grandchild is unreachable from the only session that can see it. They also accept a slug task_id; a resolved slug still passes the same ancestry check, so a process-global handle cannot be used to reach outside the subtree.

Every interrupt drops a distinct visible marker into the subagent transcript — ⊘ Steered / Cancelled / Aborted by user or by parent, with the reason — attributed to its origin (a human TUI action shows "by user"; an agent tool shows "by parent"). Untrusted reasons are XML-escaped at every sink and length-capped; both the tool task_id path and the HTTP endpoint verify the target is the caller's own subagent before doing anything.

Why it can't hang or deadlock: the child only reads a pending interrupt at a turn boundary and never blocks on one, so there's no new wait. Cancel always terminates (grace window → force-break, or task_abort as the hard fallback). With the flag off the tools are unregistered, the endpoint rejects, and TUI esc falls back to its existing behavior.

How did you verify your code works?

New tests (no mocks): the Interrupt registry (request/consume/terminal/clear, cancel-overrides-steer, reason escaping, length cap), the runLoop consume + frame injection, the three tools (not_found / already_finished / running, permission routing, origin attribution), the ancestry walk including its exact hop bound, slug resolution still passing the descendant check, the abort marker for a model-less subagent (model derived from the latest user message), and a frame-breakout reason that must reach the model only escaped.

• packages/opencode targeted interrupt/tool/prompt/server suites: 3242 pass / 0 fail across the full packages/opencode suite (dev baseline 3207)
• bun typecheck clean in packages/opencode and packages/tui; packages/core's pre-existing dev-baseline failures are unchanged by this branch
• regenerated the SDK with ./packages/sdk/js/script/build.ts
• live-tested end-to-end in a real build: the esc menu, Enter-to-send, markers for both user and parent origin, slug-addressed steering, and that a hard abort actually stops the child

Screenshots / recordings

Subagent controls + interrupt menu

Steer — course-correct, then the subagent continues

Cancel — graceful wrap-up within the grace window

Abort — immediate hard stop

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[tobwen]

@iceteaSA I don't think your very nice PR or my slimmer one will ever get any attention :(

[iceteaSA]

@iceteaSA I don't think your very nice PR or my slimmer one will ever get any attention :(

Yeah, I have a couple of other nice ones as well, won't hold my breath.

[bukit-kronik]

A hard stop is what we need for the subagent session, manually by user or by the lead agent.

[iceteaSA]

@bukit-kronik that's what this does — three levels, since "stop it" turns out to mean different things depending on how stuck the subagent is:

• task_steer — push a correction into a running subagent; it adapts and keeps going, keeping its work.
• task_cancel — graceful stop: it gets the reason, wraps up, summarises partial work, then stops.
• task_abort — immediate hard kill, no wrap-up.

All three are parentage-checked, so an agent can only interrupt its own descendants.

The distinction that took a while to get right: task_cancel only lands at a turn boundary, so a subagent wedged inside a long-running tool call (a 10-minute build, say) won't stop until that tool returns. task_abort is the answer there — it's the difference between "stop when you can" and "stop now."

On the lead-agent-vs-user split you raise: the tools are available to whichever agent spawned the subagent, so a lead agent can stop its own children. A user-facing hard stop is a separate surface — the TUI would need to expose it — and isn't in this PR.

Running in a fork for a while now; the abort path is the one that gets used, usually on a subagent looping without progress.

@tobwen on attention — no movement since June, but the PR's been rebased onto current dev a few times and the tests still pass, so it stays mergeable if a maintainer picks it up.