openclaw/docs/plugins
Ayaan Zaidi 317f0656ac
fix(agents): keep a yielded subagent's command wakes on its task after a follow-up run (#200046)
## What Problem This Solves

Fixes: a yielded subagent's final reply sometimes never reaches its requester. The child's task stays at `waiting for external continuation; delivery=pending; requester_continuation=pending` after the child wrote its answer.

A paused subagent task continues under a new run id each time an exit wake resumes it (#199283). `adoptPausedSubagentRunForFollowUp` moves the task row, the completion custody and the settle batch to the new run. It did not move the background commands. Each command kept the run that started it as `originRunId`.

When such a command exited after a later run had yielded, the failure was:

1. Its wake carried the retired run as `inputProvenance.runId` (`bash-tools.exec-notify.ts`, `sourceRunId: session.originRunId`).
2. `prepareReplySubagentContinuation` passes that id as `pausedRunId` (`src/auto-reply/reply/agent-runner-subagent.ts:47`).
3. `reactivateCompletedSubagentSession` returns false because the paused row now carries the newer run id (`src/gateway/session-subagent-reactivation.ts:48-52`).
4. The turn runs as a separate follow-up. The task row stays paused (`pauseReason: "sessions_yield"`), and the child's final reply is not tied to the task. Nothing announces it.

The later run also could not yield on those commands: `listYieldAwaitableExecs(runId)` matches `originRunId === runId` (`bash-tools.exec-notify.ts:108-116`), so its `sessions_yield` returned `nothing_pending` or "its exit cannot resume this run", and the model started to poll.

It is intermittent because it needs a command that outlives the run that started it while another wake continues the task first. A child that waits on one command at a time, or that the parent resumes with `sessions_send`, does not hit it.

## Production evidence (read-only, copied state DB)

Child `land_cache_pair` (redacted to the shape):

- Registry row: `runId` = the second run, `generation: 3`, `pauseReason: "sessions_yield"`, `execution.endedAt` set at the second run's yield, `delivery.status: "pending"`, `requesterSettleWake.status: "pending"`.
- Transcript: the second run started a pack-smoke command and yielded. Later wakes carried the starting run ids of earlier runs (`exec` wakes named run 1 three times while run 3+ was current). Every later `sessions_yield` returned `nothing_pending` or the "cannot resume this run" error, the agent polled, and the final reply (`stopReason: stop`) went nowhere. No announce lines exist for the child.

## Why This Change Was Made

- `moveRunningSessionsToRun(previousRunId, nextRunId)` in `bash-process-registry.ts`, the owner of process sessions.
- `replaceSubagentRunAfterSteer` calls it when it replaces a `sessions_yield`-paused row, next to the existing settle-batch remap and controller-input retirement. Ordinary steers and completed-run follow-ups are unchanged.
- Docs: `docs/concepts/subagent-yield-handoff.md`, `docs/plugins/tool-plugins.md` and the `inputProvenance` doc comment now say the wake names the run that owns the command.

No new state, stored row, schema or protocol field. Production delta: +20/-2 lines in `src`, most of it comments.

## Evidence

**Real agent, isolated source Gateway** (`ocx src`, scratch state/port/HOME, `env -i`), Claude Opus through the shared Claude proxy. A UI parent spawns a hidden subagent and yields. The child starts commands A (15 s) and B (50 s) and yields. A's exit continues the task in run 2, which starts C (70 s) and yields. B (started by run 1) then exits while run 2 is the paused run. base = merge base `bef242d041`, head = this PR.

| Arm | B's wake `runId` | Run 2's next `sessions_yield` | Registry row at end | Parent got the result |
|---|---|---|---|---|
| base | run 1 (retired) | `nothing_pending` (then polls) | `generation=2 pause=sessions_yield delivery=pending wake=pending` | **no** |
| head | run 2 (current) | `yielded` | `generation=4 pause=- delivery=delivered` | **yes** (`subagent_settle`, 9 s after the child's reply) |

A first base trial with C at 110 s delivered by chance: the model polled until C finished, and C's own wake (owned by run 2) continued the task. That is the same intermittency seen in production.

**Unit regression** (`ocx test`, vitest from source): `subagent-registry.test.ts` › "moves the commands of the paused run to the follow-up that continues the task". It fails on base (`listYieldAwaitableExecs(followup)` is `[]`) and passes on head.

**Gates**: oxfmt, oxlint on changed files, `pnpm tsgo:core`, `pnpm check:test-types`. `ocx test` on `src/agents/subagents/registry/`, `openclaw-tools.requester-yield`, `bash-tools.exec-background-followup`, `bash-process-registry`: all pass.

**Full tier**: `ocx build --dts` on `d61294e737ef`, then a packed tarball: tarball integrity and the dist import graph pass.

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
2026-11-16 15:06:29 +05:30
..
architecture-internals fix(plugins): avoid blocking foreground work during reload recovery capture (#198262) 2026-11-15 18:51:07 -08:00
codex-harness refactor(agents): replace tool-loop detectors with an arguments-only repeat guard (#199591) 2026-11-16 10:29:21 +05:30
codex-harness-reference refactor(agents): replace tool-loop detectors with an arguments-only repeat guard (#199591) 2026-11-16 10:29:21 +05:30
codex-harness-runtime fix(codex): omit unavailable question-tool and redundant mode guidance (#187856) 2026-11-14 04:59:40 +08:00
google-meet fix(google-meet): follow Calendar event pagination (#194103) 2026-11-06 17:38:55 +05:30
hooks feat: let plugins attach presentation to embedded final replies (#179763) 2026-11-14 05:01:42 -08:00
knowledge fix: Scribe setup assumes a new conversation and default model (#199321) 2026-11-15 23:27:45 +00:00
manifest fix(anthropic): preserve canonical model family metadata 2026-11-13 15:41:43 -06:00
reference feat(advisor): review subagent runs too 2026-11-15 22:35:45 +05:30
sdk-agent-harness improve(ui): clarify model setup and sign-in copy (#192218) 2026-11-04 08:24:54 -06:00
sdk-channel-plugins fix(outbound): honor blockedHostnames for all outbound media downloads (#198428) 2026-11-15 09:58:38 -05:00
sdk-entrypoints improve: send compact JSON tool results to the model (#196756) 2026-11-10 21:05:04 +00:00
sdk-migration chore(release): close out 2026.11.4 on main (#199956) 2026-11-16 07:02:57 +00:00
sdk-overview fix: reduce Gateway stalls under filesystem pressure (#197510) 2026-11-15 06:47:13 -08:00
sdk-provider-plugins fix(models): read provider model kinds at one owner; unknown is not chat:false 2026-11-16 14:58:46 +05:30
sdk-runtime fix: preserve operator access when policy evaluation fails (#198245) 2026-11-13 07:17:17 -08:00
voice-call fix(voice-call): preserve Twilio greetings and resume listening after silence (#193137) 2026-11-05 17:59:51 +08:00
adding-capabilities.md
admin-http-rpc.md
agent-guidance.md improve(plugins): rename prompt permission config with Doctor migration (#192634) 2026-11-04 00:47:18 -08:00
agentsapi.md fix(agentsapi): keep prior work when switching runtimes 2026-11-10 06:13:02 +00:00
apple-fm.md improve(ui): clarify model setup and sign-in copy (#192218) 2026-11-04 08:24:54 -06:00
architecture-internals.md
architecture.md fix(agents): do not count host sleep toward the catalog stall watchdog (#198709) 2026-11-14 12:43:29 +05:30
beam.md feat(beam): preserve live logical conversation handoff (#192513) 2026-11-04 07:59:52 +00:00
building-plugins.md fix(xai): expose x_search on any model for Grok OAuth subscribers (#194583) 2026-11-07 10:34:34 +00:00
bundles.md docs: explain Python stdio bundle setup (#193561) 2026-11-12 23:11:26 +08:00
cli-backend-plugins.md fix(claude-cli): WebChat shows a second native conclusion after a final message-tool reply (#197745) 2026-11-12 19:31:44 +05:30
cloudflare.md
codex-computer-use.md fix(codex): keep marketplace discovery poll on the monotonic clock (#178986) 2026-10-24 21:20:33 -07:00
codex-harness-reference.md
codex-harness-runtime.md fix(codex): omit unavailable question-tool and redundant mode guidance (#187856) 2026-11-14 04:59:40 +08:00
codex-harness.md fix(codex): avoid Gateway freezes during app-server launch (#192543) 2026-11-04 06:04:24 +00:00
codex-native-plugins.md fix(cache): keep private cache TTLs on elapsed time (#191606) 2026-11-03 08:03:53 +05:30
codex-supervision.md fix(codex): stop interrupted session catalog reads (#197750) 2026-11-12 20:30:09 +05:30
community.md
compatibility.md
copilot.md
dependency-resolution.md fix: Code Mode rejects division after optional property access (#196785) 2026-11-12 08:11:58 +00:00
facetime-recovery.md fix(facetime): use FaceTime app for call control (#184151) 2026-10-26 03:26:51 +00:00
facetime.md fix(facetime): use FaceTime app for call control (#184151) 2026-10-26 03:26:51 +00:00
feature-plugins.md fix(plugins): allow more than 64 declared feature event types 2026-11-14 08:53:26 +00:00
geolocation.md
github.md fix(ui): show hover previews for GitHub commit links (#182224) 2026-10-24 12:50:47 +08:00
google-meet.md fix: keep unused bundled meeting plugins off by default 2026-11-12 03:56:35 +00:00
hooks.md improve(plugins): rename prompt permission config with Doctor migration (#192634) 2026-11-04 00:47:18 -08:00
install-overrides.md
knowledge.md feat(knowledge): route skills by task and keep subject pages current (#197018) 2026-11-12 01:39:53 -08:00
llama-cpp.md fix(llama-cpp): keep concurrent chats alive when recovery is canceled (#194687) 2026-11-07 16:38:45 +00:00
logbook.md fix(logbook): capture pause is reported before confirmation (#199245) 2026-11-15 02:10:34 -03:00
manage-plugins.md docs(plugins): clarify reload recovery after services and channels start stopping (#194387) 2026-11-11 19:42:34 +08:00
manifest.md fix(gateway): avoid unnecessary cold-start initialization (#192552) 2026-11-09 19:59:44 -08:00
mcp-relay.md improve(ui): move Connected apps into Settings (#199338) 2026-11-15 05:07:07 -03:00
meeting-plugins.md fix: keep unused bundled meeting plugins off by default 2026-11-12 03:56:35 +00:00
memory-lancedb.md feat(memory-lancedb): report health and serve search through the memory provider runtime (#165756) 2026-10-27 21:14:37 -07:00
memory-wiki.md fix(memory-wiki): make metadata list replacement explicit (#190641) 2026-11-12 18:32:49 +08:00
message-presentation.md
muse.md fix(muse): cancel catalog checks without closing active readers (#194924) 2026-11-08 18:11:56 +05:30
oc-path.md fix(oc-path): refuse redaction markers in JSONC +key names (#193258) 2026-11-05 13:26:53 +05:30
onepassword.md
onnx.md fix(onnx): reject pipe-backed model files without blocking (#183621) 2026-10-25 14:32:40 -04:00
plugin-inventory.md improve: use OpenClaw consistently as the app name (#199226) 2026-11-14 19:48:05 -06:00
plugin-permission-requests.md
reference.md feat: add native Celeris, Fastino, Nace and Perplexity decisions (#195641) 2026-11-12 04:27:32 +00:00
research-adapters.md feat(google): expose owned managed-research interactions (#173966) 2026-11-06 15:38:18 +08:00
runtime-compatibility.md feat(plugins): inspect runtime compatibility before activation (#182419) 2026-10-24 05:06:12 -07:00
sdk-agent-harness.md
sdk-channel-inbound.md feat: fork threaded conversations with Telegram support (#190783) 2026-11-02 17:41:38 +00:00
sdk-channel-ingress.md
sdk-channel-outbound.md fix: stop replaying messages discarded by queue caps (#193313) 2026-11-05 13:32:04 -08:00
sdk-channel-plugins.md fix: stop replaying messages discarded by queue caps (#193313) 2026-11-05 13:32:04 -08:00
sdk-entrypoints.md improve: make Telegram tool progress easier to scan (#197523) 2026-11-12 20:03:28 +05:30
sdk-gateway-ingress.md fix: keep connected apps tied to approving ID membership (#196276) 2026-11-09 16:20:54 -06:00
sdk-migration.md refactor: share channel binding session classification (#190957) 2026-11-03 17:30:44 +08:00
sdk-overview.md feat: enable native plugin UI without a Labs opt-in 2026-10-28 03:41:15 +00:00
sdk-provider-plugins.md fix(models): discovered models become "Unknown model" after restart or an ended sign-in (#197784) 2026-11-12 22:13:10 +05:30
sdk-runtime.md chore(release): close out 2026.11.4 on main (#199956) 2026-11-16 07:02:57 +00:00
sdk-setup.md fix(ci): refresh dependency references after upgrades (#193389) 2026-11-05 19:04:23 +08:00
sdk-subpaths.md feat(gateway): role definitions no longer turn on named-role enforcement without a default (#197712) 2026-11-13 11:11:32 -08:00
sdk-testing.md refactor(tests): retire unused target-resolution support (#189230) 2026-10-31 09:38:43 +00:00
session-share.md docs: consolidate team server and team setup into one Multiplayer page 2026-11-04 00:01:02 +00:00
slack-huddles.md
subq.md fix(decisions): serve SubQ, Fastino and Perplexity Decision models from the hosted catalog 2026-11-12 15:47:47 +05:30
team-reports.md fix(team-reports): reject malformed UTF-8 roster files (#186902) 2026-10-29 09:11:25 +05:30
teams-meetings.md
tool-plugins.md fix(agents): keep a yielded subagent's command wakes on its task after a follow-up run (#200046) 2026-11-16 15:06:29 +05:30
typesafe.md refactor(decisions): share one Decision HTTP executor across providers (#197615) 2026-11-12 14:25:23 +05:30
vault.md
voice-call.md
workboard.md fix(workboard): report planning state and worker-start failures (#199334) 2026-11-16 00:03:07 +00:00
zalouser.md
zoom-meetings.md