Greptile Summary

This PR fixes a common LLM failure mode where streamTo: \"parent\" was being set for runtime=\"subagent\" spawns (causing 100% spawn failures) by adding an explicit description to the streamTo schema field and updating the tool's prose description with acp-only guidance — matching the existing pattern on resumeSessionId.

The schema fix and new test are clean. The one P2 concern is in the updated tool description, which lists only task, agentId, and runTimeoutSeconds as subagent-safe params; this is overly restrictive since other params (model, cwd, lightContext, attachments, etc.) are perfectly valid for subagent spawns and may now be silently skipped by models following the guidance.

Confidence Score: 5/5

Safe to merge; the core schema fix is correct and the only remaining finding is a P2 wording issue in the tool description prose.

The primary fix (adding a description to the streamTo schema field) is correct, minimal, and follows the existing resumeSessionId pattern. The new test provides adequate coverage. The single P2 comment about the overly-restrictive param allowlist in the prose description does not affect correctness or runtime behavior.

src/agents/tool-description-presets.ts — the new guidance sentence's subagent param allowlist may be too narrow.

This is a comment left during a code review.
Path: src/agents/tool-description-presets.ts
Line: 40

Comment:
**Overly restrictive subagent param list**

The guidance says "only pass `task`, `agentId`, and `runTimeoutSeconds`" for subagent spawns, but several other schema params are valid and useful for subagents — `model`, `thinking`, `cwd`, `mode`, `sandbox`, `lightContext`, `attachments`, `label`, etc. Restricting the guidance to three params may cause models to silently omit useful options like `cwd` or `model` when spawning subagents.

Consider tightening the guidance to just the "do not set" prohibition instead of an allowlist:

```suggestion
    'For subagent spawns, do not set streamTo or resumeSessionId — those require runtime="acp".',
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix(tools): add acp-only guidance to ses..." | Re-trigger Greptile}

Codex automated review: keeping this open.

Keep this PR open. Current main still lacks the proposed streamTo ACP-only schema description and still rejects streamTo on runtime="subagent"; the same-author paired issue #63120 remains open, and maintainer replacement #72331 is still the broader open fix path rather than a landed implementation.

Best possible solution:

Keep this PR open for maintainer handling. The best product path is to review and land #72331, or an equivalent maintainer-approved fix that adds clear ACP-only schema/tool guidance and tolerates ACP-only fields for native subagent calls; after that lands, explicitly close or supersede this PR while preserving SuperSupeng’s reproduction and schema-guidance contribution.

What I checked:

• Current schema still lacks streamTo guidance: On current main, resumeSessionId has an ACP-only description, but streamTo is still optionalStringEnum(SESSIONS_SPAWN_ACP_STREAM_TARGETS) with no description. (src/agents/tools/sessions-spawn-tool.ts:154, 4878d3e059ce)
• Current runtime still errors for subagent streamTo: The executor reads streamTo before runtime-specific dispatch and returns streamTo is only supported for runtime=acp; got runtime=subagent for non-ACP calls. (src/agents/tools/sessions-spawn-tool.ts:227, 4878d3e059ce)
• Existing tests assert old rejection behavior: The current regression test still expects runtime="subagent" plus streamTo: "parent" to return an error, so main has not adopted either the schema-guidance test from this PR or the tolerant behavior from the replacement path. (src/agents/tools/sessions-spawn-tool.test.ts:532, 4878d3e059ce)
• Tool prose still lacks the proposed prohibition: describeSessionsSpawnTool() explains native subagents and ACP harnesses, but it does not tell callers to omit streamTo or resumeSessionId for native subagent spawns. (src/agents/tool-description-presets.ts:35, 4878d3e059ce)
• Paired issue and maintainer replacement remain unresolved: The PR body uses closing syntax for sessions_spawn: LLMs pass streamTo for subagent runtime causing 100% spawn failures #63120, which is a same-author open issue with the concrete production reproduction. The supplied GitHub context also shows fix(sessions_spawn): tolerate ACP-only fields for subagent runtime #72331 as an open maintainer-labeled replacement that covers sessions_spawn: LLMs pass streamTo for subagent runtime causing 100% spawn failures #63120 with schema guidance plus runtime tolerance, but it has not landed on current main.

Remaining risk / open question:

• Closing this before sessions_spawn: LLMs pass streamTo for subagent runtime causing 100% spawn failures #63120 or fix(sessions_spawn): tolerate ACP-only fields for subagent runtime #72331 is resolved would drop useful contributor context for a still-present sessions_spawn failure mode.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against 4878d3e059ce.

Thanks @SuperSupeng for the focused schema-guidance PR and the paired reproduction in #63120. I am closing this as superseded by #72614 because that landed the canonical sessions_spawn fix: subagent runtime now tolerates ACP-only streamTo/resumeSessionId fields, ACP behavior is preserved, and the schema/docs path was updated alongside regression coverage.

Clownfish is carrying the attribution from this source PR in the closeout trail with #63120 and #72614. If the schema guidance in #72614 still leaves a distinct provider case uncovered, please reply here and we can reopen or split it back out.