Repository navigation
Subagent tool: sessionID not clearly marked as optional in serialized JSON schema #55504
Description
Problem
The subagent tool's sessionID parameter is correctly defined as optional in the TypeScript source (Schema.optionalKey(SessionSchema.ID)), but some models do not reliably infer optionality from the serialized JSON schema. They see sessionID in properties and treat it as required, filling it with garbage values like "sesh" or "sesh_omit_should_not_be_here".
This results in Subagent session not found errors that confuse the model, which then retries with more garbage values in a loop.
Evidence
- Source:
packages/core/src/tool/plugin/subagent.tsline 40 —Schema.optionalKey(SessionSchema.ID) - Serialization:
packages/ai/src/tool.ts—Schema.toJsonSchemaDocument()produces a JSON schema wheresessionIDis inpropertiesbut not inrequired - The serialized schema is technically correct, but some models do not check the
requiredarray and instead pattern-match "fill in all properties"
Expected Behavior
Models should omit sessionID when starting a new subagent. The tool description already says "Calls without a sessionID start a new conversation," but models ignore this.
Actual Behavior
Models fill sessionID with fabricated values, causing Subagent session not found errors. Explicit user prompts to omit the field do not reliably fix the behavior.
Suggested Fix
Add explicit "optional": true to the serialized JSON schema for sessionID, background, model, and agent in the subagent tool definition. Alternatively, add a stronger hint in the tool description (e.g., "IMPORTANT: Do NOT include sessionID unless continuing a previous subagent").
Environment
- OpenCode version: latest (desktop)
- Model: third-party model with weaker JSON schema adherence
Activity
opencode-agent commentedon Oct 14, 2026
Thanks for the report, @throny! You're asking for the
subagenttool to make it clearer to models thatsessionID(and the other optional parameters) should be left out when starting a new subagent. Some models fill it with made-up values and then keep retrying afterSubagent session not found.The serialized schema already leaves
model,sessionIDandbackgroundout ofrequired(agentis actually required), and thesessionIDdescription says that calls without it start a new conversation. So this is a model-compatibility improvement rather than a bug. Also,"optional": trueisn't a JSON Schema keyword, so models won't recognise it. A firmer line in the description, like the one you suggest, is the more likely fix. Maintainers will consider it.In the meantime, a plugin can do this now. The session context hook can change each tool's
descriptionandinputschema before the request is sent, so it could add a stronger "do not pass sessionID unless continuing a previous subagent" line for the models that need it.Related:
sessionIDs to the subagent toolscubbo commentedon Oct 24, 2026
Reproduced on OpenCode v2.0.1, macOS Darwin 24.6.0 x86_64, using
vercel/openai/gpt-6.1-sol(xhigh). The agent-facingsubagentdeclaration in this session presentssessionIDas a required string (pattern^ses), while its description says calls withoutsessionIDstart a new conversation. The model repeatedly supplied fabricated values such asses, receivingSubagent session not found: ses, and failed to recover even after user correction. No child session was created.The repeated retries were an agent failure. However, the apparent mismatch between upstream optionality and the declaration presented to the model may help identify a provider/schema-conversion issue. We have not captured the raw provider request, so the transformation responsible is not yet confirmed.
Environment: Ghostty, zsh; builtin subagent tool active; external plugin
@hcrosse/opencode-pr-tracker0.5.1. This also occurs in foreground calls, not only background calls.tarvlad commentedon Oct 25, 2026
Reproduced on the opencode v2.1.4, ubuntu 22.04, using openai/gpt-6.1-sol:high. No plugins, facing the same issues with
Subagent session not found: ses*