Skip to content

Commit f4b92f5

Browse files
brokemac79brokemac79
authored
fix(agents): simplify subagent completion handoff
Simplify native subagent completion handoff and remove manual subagent control surfaces. Co-authored-by: brokemac79 <[email protected]>
1 parent 2ad507c commit f4b92f5

55 files changed

Lines changed: 455 additions & 2219 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ Docs: https://docs.openclaw.ai
6666
- Twitch: keep stale message-handler cleanup callbacks from removing newer handler registrations for the same account, preserving inbound message delivery after reconnects. Fixes #83888. (#85425) Thanks @alkor2000.
6767
- Memory/LanceDB: expose public memory artifacts through the active memory provider bridge so memory-wiki imports durable memory files, daily notes, dream reports, and event logs without depending on memory-core internals. Fixes #83604. (#85060) Thanks @brokemac79.
6868
- Crabbox: keep AWS hydration compatible with local Actions replay by inlining the hydrate workflow's Node/pnpm setup instead of invoking repo-local composite actions.
69+
- Agents/subagents: simplify native sub-agent completion handoff so children report their latest visible assistant result to the requester without using `message`, while keeping parent-owned message-tool delivery policy intact. Fixes #85070. (#85089) Thanks @brokemac79.
6970
- Docker setup: stop printing the Gateway bearer token in setup logs and printed follow-up commands.
7071
- Agents: let embedded compaction fallback retries proceed when PI-compatible candidates do not need agent harness plugin preparation.
7172
- Agents/tools: honor configured custom provider API keys when deciding whether media, image-generation, video-generation, music-generation, and PDF tools are available. (#85570)

‎apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -756,6 +756,7 @@ public struct AgentParams: Codable, Sendable {
756756
public let internalevents: [[String: AnyCodable]]?
757757
public let inputprovenance: [String: AnyCodable]?
758758
public let sourcereplydeliverymode: AnyCodable?
759+
public let disablemessagetool: Bool?
759760
public let voicewaketrigger: String?
760761
public let idempotencykey: String
761762
public let label: String?
@@ -794,6 +795,7 @@ public struct AgentParams: Codable, Sendable {
794795
internalevents: [[String: AnyCodable]]?,
795796
inputprovenance: [String: AnyCodable]?,
796797
sourcereplydeliverymode: AnyCodable?,
798+
disablemessagetool: Bool?,
797799
voicewaketrigger: String?,
798800
idempotencykey: String,
799801
label: String?)
@@ -831,6 +833,7 @@ public struct AgentParams: Codable, Sendable {
831833
self.internalevents = internalevents
832834
self.inputprovenance = inputprovenance
833835
self.sourcereplydeliverymode = sourcereplydeliverymode
836+
self.disablemessagetool = disablemessagetool
834837
self.voicewaketrigger = voicewaketrigger
835838
self.idempotencykey = idempotencykey
836839
self.label = label
@@ -870,6 +873,7 @@ public struct AgentParams: Codable, Sendable {
870873
case internalevents = "internalEvents"
871874
case inputprovenance = "inputProvenance"
872875
case sourcereplydeliverymode = "sourceReplyDeliveryMode"
876+
case disablemessagetool = "disableMessageTool"
873877
case voicewaketrigger = "voiceWakeTrigger"
874878
case idempotencykey = "idempotencyKey"
875879
case label

‎docs/automation/tasks.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@ openclaw tasks notify <lookup> state_changes
257257
- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
258258
- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
259259
- Isolated cron delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it.
260-
- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary. Terminal failed runs announce failure status without replaying captured reply text.
260+
- Subagent completion delivery uses the child's latest visible assistant text only. Tool/toolResult output is not promoted into child result text. Terminal failed runs announce failure status without replaying captured reply text.
261261
- Cleanup failures do not mask the real task outcome.
262262

263263
When applying maintenance, OpenClaw also removes stale `cron:<jobId>:run:<uuid>` session registry rows older than 7 days, while preserving rows for currently running cron jobs and leaving non-cron session rows untouched.

‎docs/concepts/session-tool.md‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ summary: "Agent tools for cross-session status, recall, messaging, and sub-agent
33
read_when:
44
- You want to understand what session tools the agent has
55
- You want to configure cross-session access or sub-agent spawning
6-
- You want to inspect status or control spawned sub-agents
6+
- You want to inspect spawned sub-agent status
77
title: "Session tools"
88
---
99

@@ -19,7 +19,7 @@ orchestrate sub-agents.
1919
| `sessions_send` | Send a message to another session and optionally wait |
2020
| `sessions_spawn` | Spawn an isolated sub-agent session for background work |
2121
| `sessions_yield` | End the current turn and wait for follow-up sub-agent results |
22-
| `subagents` | List, steer, or kill spawned sub-agents for this session |
22+
| `subagents` | List spawned sub-agent status for this session |
2323
| `session_status` | Show a `/status`-style card and optionally set a per-session model override |
2424

2525
These tools are still subject to the active tool profile and allow/deny
@@ -123,12 +123,8 @@ the follow-up event you are waiting for. Use it after spawning sub-agents when
123123
you want completion results to arrive as the next message instead of building
124124
poll loops.
125125

126-
`subagents` is the control-plane helper for already spawned OpenClaw
127-
sub-agents. It supports:
128-
129-
- `action: "list"` to inspect active/recent runs
130-
- `action: "steer"` to send follow-up guidance to a running child
131-
- `action: "kill"` to stop one child or `all`
126+
`subagents` is the visibility helper for already spawned OpenClaw
127+
sub-agents. It supports `action: "list"` to inspect active/recent runs.
132128

133129
## Spawning sub-agents
134130

‎docs/help/faq.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,7 +229,7 @@ lives on the [First-run FAQ](/help/faq-first-run).
229229
- If neither a bound route nor a usable stored route exists, direct delivery can fail and the result falls back to queued session delivery instead of posting immediately to chat.
230230
- Invalid or stale targets can still force queue fallback or final delivery failure.
231231
- If the child's last visible assistant reply is the exact silent token `NO_REPLY` / `no_reply`, or exactly `ANNOUNCE_SKIP`, OpenClaw intentionally suppresses the announce instead of posting stale earlier progress.
232-
- If the child timed out after only tool calls, the announce can collapse that into a short partial-progress summary instead of replaying raw tool output.
232+
- Tool/toolResult output is not promoted into child result text; the result is the child's latest visible assistant reply.
233233

234234
Debug:
235235

‎docs/help/testing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -817,7 +817,7 @@ MCP runtime, executes the tool, then verifies `coding` and `messaging` keep
817817
`bundle-mcp` tools while `minimal` and `tools.deny: ["bundle-mcp"]` filter them.
818818
`test:docker:cron-mcp-cleanup` is deterministic and does not need a live model
819819
key. It starts a seeded Gateway with a real stdio MCP probe server, runs an
820-
isolated cron turn and a `/subagents spawn` one-shot child turn, then verifies
820+
isolated cron turn and a `sessions_spawn` one-shot child turn, then verifies
821821
the MCP child process exits after each run.
822822
823823
Manual ACP plain-language thread smoke (not CI):

‎docs/tools/slash-commands.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -169,13 +169,11 @@ Current source-of-truth:
169169

170170
</Accordion>
171171
<Accordion title="Subagents and ACP">
172-
- `/subagents list|kill|log|info|send|steer|spawn` manages sub-agent runs for the current session.
172+
- `/subagents list|log|info` inspects sub-agent runs for the current session.
173173
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` manages ACP sessions and runtime options.
174174
- `/focus <target>` binds the current Discord thread or Telegram topic/conversation to a session target.
175175
- `/unfocus` removes the current binding.
176176
- `/agents` lists thread-bound agents for the current session.
177-
- `/kill <id|#|all>` aborts one or all running sub-agents.
178-
- `/subagents steer <id|#> <message>` sends steering to a running sub-agent. See [Steer](/tools/steer).
179177

180178
</Accordion>
181179
<Accordion title="Owner-only writes and admin">

‎docs/tools/steer.md‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ summary: "Steer an active run without changing queue mode"
33
read_when:
44
- Using /steer or /tell while an agent is already running
55
- Comparing /steer with /queue modes
6-
- Deciding whether to steer the current run, a sub-agent, or an ACP session
6+
- Deciding whether to steer the current run or an ACP session
77
title: "Steer"
88
sidebarTitle: "Steer"
99
---
@@ -55,15 +55,8 @@ For queue modes and steering boundaries, see [Command queue](/concepts/queue) an
5555

5656
## Sub-agents
5757

58-
Use `/subagents steer` when the target is a child run:
59-
60-
```text
61-
/subagents steer 2 focus only on the API surface
62-
```
63-
64-
Top-level `/steer` does not select a sub-agent by id or list index. It always
65-
targets the current session's active run. See [Sub-agents](/tools/subagents) for
66-
sub-agent ids, labels, and control commands.
58+
Top-level `/steer` targets the current session's active run. Sub-agents report
59+
back to their parent/requester session; `/subagents` is for visibility only.
6760

6861
## ACP sessions
6962

0 commit comments

Comments
 (0)