Repository navigation
Follow-up (#2229): expose sessions_spawn to headless/CLI OpenClaw sessions (packaging patch) #2257
Description
Follow-up to #2229 (method 2 of 3). Method 3 — the opencode-route provider front — shipped as the priority build (PR #2250, live-proven). This method was descoped by Drew on 2026-10-29 to a follow-up: sometime soon / when an OpenClaw-origin workload needs to spawn subagents from headless/CLI sessions.
What it adds
sessions_spawn exposed to headless/CLI OpenClaw sessions, so a CLI-driven agent turn can spawn subagents — including ACP-runtime targets such as the opencode-acp entry (the method-1 follow-up), whose live proof depends on this surface.
Determination (already made, 2026-10-29 — this is a packaging patch, not config)
- In the pinned OpenClaw 2026.10.7 dist,
createSessionsSpawnToolis gated by!embedded || options?.allowGatewaySubagentBinding === true(chunkopenclaw-tools-QaFYBVQi.mjs).isEmbeddedMode()is a process-local flag set only byEmbeddedTuiBackend.start(), andopenclaw agentCLI turns run through that embedded backend even when gateway-attached.allowGatewaySubagentBinding: trueis passed only by gateway/channel-side runners. No config key or tool profile feeds either flag — the tool sits in the "sessions" group with profiles["coding","messaging"]; profile is not the blocker. - Empirically absent on every surface tried: CLI via the live gateway, CLI
--local, and a server-sidechat.sendturn (the agent reported sessions_spawn is not in its loadable tool set; the deferred-tool layer answersselect:sessions_spawnwith "No deferred tool matched"). - Route: nix-openclaw's instance options expose
gatewayPath+gatewayPnpmDepsHash; whengatewayPathis set, the module builds the gateway from that source. So: commit a.patchagainst the pinned upstream source flipping the gate condition, wiregatewayPathto a patched-source derivation in the fleet config, and document plainly that it is a source patch carried by the packaging, not an upstream config option.
Proof when built
Patch a copied dist tree first for a fast mechanism proof (spawn with agentId="opencode" and agentId="opencode-acp" → check acp_sessions in the OpenClaw state plus a new row in OpenCode session_v2), then land the durable source patch.
Activity
developing-today commentedon Oct 29, 2026
CODE-1120
dezren39 commentedon Oct 30, 2026
Drew's directive (2026-10-29 21:44 CDT, main chat): "I want the other options built and functional." This issue (headless/CLI sessions_spawn exposure) is one of those options — build it and prove it functional alongside #2256. Scope note (Drew, 21:45 CDT): sessions_spawn is explicit task dispatch, so OpenCode running the task is correct there; the routing-only principle applies to the opencode-route model door (see the new follow-up issue), not to dispatch paths.
dezren39 commentedon Nov 3, 2026
Triage @ current main (2026-11-03) — still live, fix path re-confirmed
Verdict: the gap is real on the pinned package and on upstream main. Nothing has shipped since the 2026-10-29 determination; this issue is a scoped, buildable packaging task, not a config task.
Evidence (fresh at this triage)
openclaw-2026.10.7:/nix/store/f2crizywkx7d7k8831xmnhjx4kcm2ki4-openclaw-gateway-2026.10.7/lib/node_modules/openclaw/dist/openclaw-tools-QaFYBVQi.mjs:16699still reads
!embedded || options?.allowGatewaySubagentBinding === true ? createSessionsSpawnTool({…}) : null.src/agents/openclaw-tools.ts:646-647(rawmain, fetched 2026-11-03) carries the identical condition.allowGatewaySubagentBindingis an internal option param (src/plugins/tools.ts:89,111,src/agents/runtime-plugins.ts:61,86,188), not a config keyspace entry. A settings/profile workaround does not exist — as the issue body already concluded.openclawlatest is2026.10.10; pinned nix package is2026.10.7; upstream main is unchanged, so a plain bump buys nothing.nix-openclawpin4b261b08c173467dc41db7b43d8265529c435055(2026-10-30) is the repo HEAD today;gatewayPath+gatewayPnpmDepsHashremain the only source override (nix/modules/home-manager/openclaw/options-instance.nix:61-71).One design decision blocks implementation
gatewayPathis typednullOr str, documented "dev only", and consumed asbuiltins.path { path = inst.gatewayPath; }(instance.nix:60-63) — it must be a real filesystem path at evaluation time. Apkgs.applyPatches-derived store path is therefore IFD-fragile: it only exists after it is realized, sohome-manager switchwould fail on a cold store and succeed on a warm one. Options, in order of cleanliness:nix-openclaw: add agatewayPatches(orgatewaySrc) option to the instance module — then this repo carries only a.patchfile. Needs a PR toopenclaw/nix-openclaw+ a pin bump. Cleanest, slowest.nix-openclawflake input at adeveloping-todayfork carrying the patch + option, owned by us, maintained with the fork-sync discipline. No upstream dependency. Recommended for this week.gatewayPathat its store path. Works, but makes the rebuild order-dependent and rejects one-command rebuilds. Not recommended.Recommendation: (2) now, (1) as upstream follow-through. This is a packaging-mechanism call inside the worker's remit, so it is not escalated; the follow-up build task below carries the decision.
Implementation scope when built
patches/openclaw/sessions-spawn-headless.patch— one hunk onsrc/agents/openclaw-openclaw-tools.tsat the!embedded ||gate (exact hunk context:openclaw-tools.ts:646). Simplest faithful change for this fleet: drop theembeddedexclusion at build time, keepingoptions?.allowGatewaySubagentBindingintact. Patch header must state it is carried by packaging, not an upstream config, and name the upstream lines it targets.flake.nix/flake.lock+programs.openclaw.instance.gatewayPath/gatewayPnpmDepsHashinhome/openclaw/default.nix(currently neither is set).agentId="opencode"andagentId="opencode-acp"→acp_sessionsrows in OpenClaw state + new rows in OpenCodesession_v2; also confirmselect:sessions_spawnno longer answers "No deferred tool matched" and the tool appears in the CLI turn's loadable set (/tools).Ordering, blockers, risks
agentId="opencode-acp"depends on Follow-up (#2229): ACP-runtime agent entry for OpenClaw→OpenCode dispatch (opencode-acp) #2256 (ACP entry). feat(openclaw): opencode-acp ACP-runtime agent (#2229 mechanism 1) #2237 merged the entry; Follow-up (#2229): ACP-runtime agent entry for OpenClaw→OpenCode dispatch (opencode-acp) #2256 is still open and Wire OpenClaw ACP adapters to Nix runtime plugin #3275 (draft) is actively changing ACP adapter wiring — land theopencodeproof first, then publish theopencode-acphalf once Follow-up (#2229): ACP-runtime agent entry for OpenClaw→OpenCode dispatch (opencode-acp) #2256/Wire OpenClaw ACP adapters to Nix runtime plugin #3275 settle.openclaw.json/tool-profile workaround; the flag cannot be reached from config.developing-today commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 30 (priority/none). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
38 remaining items
dezren39 commentedon Nov 3, 2026
🤖 Agent note · state: picked up
sessions_spawnpackaging fix from itsimplementation_completecheckpoint.dezren39 commentedon Nov 3, 2026
🤖 Agent note · state: parked
implementation_completecheckpoint at/home/user/git/fleet/8042-2257(branchqueue/8042-2257-sessions-spawn-headless). Queue parked 30 minutes.dezren39 commentedon Nov 3, 2026
agent-note:v1 — task 8042 blocked by lane code-m, 2026-11-03. Hard stop re-verified fresh: PR #5056 (feat(openclaw): pin nix-openclaw fork carrying the sessions_spawn headless patch, branch queue/8042-2257-sessions-spawn-headless) is OPEN, non-draft, authored and assigned to Drew (dezren39). Per the runbook, a Drew-owned PR is never touched — no PR internals, branch, or worktree were inspected or modified by this lane (the OpenChamber lane reached the same verdict at 22:14Z and parked; this claim arrived after that park expired, so the task is now blocked instead of re-parked). Resume condition: ownership of PR #5056 transfers, or Drew explicitly hands the work off under fleet protocol; then continue from the saved implementation_complete checkpoint (laptop worktree /home/user/git/fleet/8042-2257).