Bug: sessions_spawn(runtime="subagent") can fail on GPT/OpenRouter because unified tool schema exposes ACP-only streamTo

Summary

sessions_spawn currently exposes a unified tool schema that includes streamTo, even though streamTo is only valid for runtime="acp".

In GPT/OpenRouter sessions, the model/tool-calling path may emit streamTo:"parent" for runtime:"subagent" calls. The server then rejects the request with:

streamTo is only supported for runtime=acp; got runtime=subagent

This makes sessions_spawn(runtime="subagent") unreliable on some model/provider combinations, even when the caller intent is a plain sub-agent spawn.

Environment

• OpenClaw runtime: main agent session
• Model route observed: GPT via OpenRouter (aiproxy/gpt in this environment)
• Channel: Feishu group
• Workspace: /home/jihua/openclaw/workspace

Observed behavior

When attempting a minimal sub-agent spawn, the request fails with:

{
  "status": "error",
  "error": "streamTo is only supported for runtime=acp; got runtime=subagent"
}

This is especially confusing because the public docs for subagents do not list streamTo as a supported subagent parameter.

Code evidence

1) Unified tool schema includes streamTo for all runtimes

File:

• /usr/lib/node_modules/openclaw/dist/auth-profiles-B5ypC5S-.js#L180350-L180372

Relevant excerpt:

const SessionsSpawnToolSchema = Type.Object({
  task: Type.String(),
  label: Type.Optional(Type.String()),
  runtime: optionalStringEnum(SESSIONS_SPAWN_RUNTIMES),
  agentId: Type.Optional(Type.String()),
  resumeSessionId: Type.Optional(Type.String()),
  model: Type.Optional(Type.String()),
  thinking: Type.Optional(Type.String()),
  cwd: Type.Optional(Type.String()),
  runTimeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
  timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
  thread: Type.Optional(Type.Boolean()),
  mode: optionalStringEnum(SUBAGENT_SPAWN_MODES),
  cleanup: optionalStringEnum(["delete", "keep"]),
  sandbox: optionalStringEnum(SESSIONS_SPAWN_SANDBOX_MODES),
  streamTo: optionalStringEnum(ACP_SPAWN_STREAM_TARGETS),
  attachments: Type.Optional(Type.Array(...)),
  attachAs: Type.Optional(Type.Object({ mountPath: Type.Optional(Type.String()) }))
});

2) Execution explicitly rejects streamTo unless runtime is acp

File:

• /usr/lib/node_modules/openclaw/dist/auth-profiles-B5ypC5S-.js#L180395-L180403

Relevant excerpt:

const streamTo = params.streamTo === "parent" ? "parent" : void 0;
...
if (streamTo && runtime !== "acp") return jsonResult({
  status: "error",
  error: `streamTo is only supported for runtime=acp; got runtime=${runtime}`
});

3) Subagent docs do not advertise streamTo as a subagent parameter

File:

• /usr/lib/node_modules/openclaw/docs/tools/subagents.md#L71-L96

The documented subagent params include task, label, agentId, model, thinking, runTimeoutSeconds, thread, mode, cleanup, sandbox, etc., but not streamTo.

Likely root cause

This appears to be a schema/tool-calling compatibility bug rather than a subagent-runtime bug:

1. sessions_spawn uses a single unified schema for both runtime="subagent" and runtime="acp".
2. That schema exposes ACP-only fields like streamTo to the model.
3. Some model/provider tool-calling paths (observed here with GPT via OpenRouter) may opportunistically emit optional fields that are present in the schema, even when they are semantically invalid for the chosen runtime.
4. The server then rejects the call instead of ignoring the irrelevant field.

In short:

The schema invites the model to emit streamTo; the executor then rejects it for subagents.

Why this matters

This creates model/provider-specific instability:

• Some models may omit streamTo and appear fine.
• Others may emit it and fail consistently.
• Users experience this as “GPT tool calling is flaky”, even though the server-side schema design is a major contributing factor.

Suggested fixes

Preferred fix: runtime-specific tool schemas

Expose different tool schemas depending on runtime, e.g. one of:

• Separate tools (sessions_spawn_subagent, sessions_spawn_acp), or
• Conditional schema / discriminated union where:
  • runtime="subagent" does not expose streamTo or resumeSessionId
  • runtime="acp" does expose ACP-only fields

This prevents the model from seeing invalid fields in the first place.

Pragmatic fix: ignore incompatible ACP-only fields for subagent runtime

If runtime !== "acp", silently ignore:

• streamTo
• resumeSessionId

instead of returning a hard error.

That would make the API more robust to imperfect tool-call generation.

Optional hardening

• Mark tool/function schemas as strict where supported, and/or
• Add provider-specific defensive normalization to strip incompatible fields before dispatch

Minimal repro idea

Ask the model to call:

{
  "task": "Reply with exactly: subagent-ok",
  "runtime": "subagent",
  "agentId": "main",
  "mode": "run"
}

On affected GPT/OpenRouter routes, the actual tool call may still include:

{
  "streamTo": "parent"
}

which then triggers the runtime guard.

Expected behavior

A plain runtime="subagent" spawn should succeed without being vulnerable to ACP-only optional fields leaking into the request.

Actual behavior

A runtime="subagent" call may fail because the schema advertises streamTo, and the executor rejects it when present.