feat(session): expose toolChoice via PromptInput and agent config

[paperview]

Issue for this PR

Refs #37672 (my consolidation issue), closes#32465 (the still-open bug),
picks up the work from #32521 / #32518 (both closed by 1-month
auto-cleanup, not rejection).

Type of change

• Bug fix
• New feature

What does this PR do?

The internal LLM layer already accepts toolChoice ("auto" | "required" | "none") end to end (packages/core/src/aisdk.ts:421, packages/opencode/src/session/llm.ts:47,234,319, native runtime + request, per-provider lowerings). Two edges of the wire were missing:

• HTTP.PromptInput did not accept a toolChoice field, so external orchestrators calling POST /session/:id/message or POST /session/:id/prompt_async could not set it per turn.
• Config. Agent v2 config did not accept tool_choice, so an unset value was silently dropped and providers always received "auto".

This wires the missing edges:

1. Add optional toolChoice to PromptInput. When present, stored on a session-keyed in-memory Map for the duration of the turn — this avoids changing the persisted SessionV1.User schema (an earlier version of this patch persisted toolChoice on the user message, which broke MessageV2.Event.Updated decoders in share-next.ts). The map is cleared on loop exit; not persisted across daemon restart (next turn falls back to agent config or the default).
2. Add tool_choice to the v1 agent config schema and KNOWN_KEYS allowlist, and map it onto AgentInfo.toolChoice in the agent loader.
3. At the LLM request-build site in SessionPrompt.prompt (line ~1298), replace the hard-coded ternary

   toolChoice: format.type==="json_schema" ? "required" : undefined,

   with

   toolChoice:
   pendingToolChoice.get(sessionID)??agent.toolChoice??(format.type==="json_schema" ? "required" : undefined),

Behavior when unset is unchanged.toolChoice stays undefined for regular turns, "required" for json_schema output. Fully backwards compatible.

Motivation

Models like Kimi K3 that under-invoke tools under "auto" default cannot currently be forced to call MCP tools through the daemon. Reproduction (my case): a chatbot orchestrator adds an MCP entry with update_field via runtime MCP (#37308), asks Kimi K3 "record my color as blue via update_field," and Kimi answers in prose without invoking the tool. Under "required" the daemon would force the call.

This is especially painful for the runtime MCP feature — external orchestrators mediating structured flows (form-fill, tool-mediated mutation) have no way to say "this turn must produce a tool call."

Related dead PRs (both closed by 1-month auto-cleanup, not by review):

• [FEATURE]: Expose toolChoice as a configurable agent option in opencode.json #14090 (feature request, closed as completed but the fix didn't actually land)
• fix(opencode): honor agent tool_choice config #32521 and fix(agent): apply configured tool_choice to model requests #32518 (parallel fix PRs — same-day, same idea, both auto-closed)
• opencode Agent config is silently ignored — opencode always sends (1.17.7) #32465 (still-open bug report)

How did you verify your code works?

• bun turbo typecheck --filter=@opencode-ai/schema --filter=@opencode-ai/core --filter=opencode — clean.
• Boot patched daemon on 4100, POST /session/:id/prompt_async with {"toolChoice":"BOGUS", ...} → returns 400 with Expected "auto" | "required" | "none", got "BOGUS". Same call with "required" → 204.
• Set agent.build.tool_choice: "required" in ~/.config/opencode/opencode.jsonc, verify agent config parses cleanly and loader picks up the value (agent AgentInfo.toolChoice === "required" at request build).

Tests I did not run: I didn't add unit tests in this PR — I'd like a signal from a maintainer on the session-map approach vs. persisting toolChoice on the user message before investing in tests, since either shape ships different guarantees on daemon-restart behavior.

Scope / not addressed

• The legacy POST /api/session/:id/prompt endpoint (goes through SessionPending.admit + core SessionRunner) does not propagate toolChoice through the pending queue. That's a separate wiring effort and is out of scope here; direct v2 endpoints do carry it correctly. Filing a follow-up issue if this lands and there's demand.
• SessionV1.User schema is left unchanged on purpose — the session-map route avoids invalidating persisted messages and downstream share subscribers that decode existing shapes.

Screenshots / recordings

Not a UI change.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[paperview]

Deeper finding while trying to verify end-to-end

I've been trying to prove this patch works end-to-end via a runtime MCP flow (external orchestrator posts `/mcp` to add a bot-scoped MCP entry, then hits `/api/session/:id/prompt` for Kimi to invoke it). Two independent architecture splits blocked verification, and are worth calling out here — they aren't caused by this patch, but they mean the patch only fixes half of what a runtime-MCP-driven "force tool call" flow needs.

1) Two MCP services, not one.

• `packages/opencode/src/mcp/index.ts` is `@opencode/MCP` — the target of the runtime `POST /mcp` endpoint. Instance-scoped via `InstanceState`.
• `packages/core/src/mcp/index.ts` is `@opencode/v2/MCP` — what the core `SessionModelRequest.prepare` reads. Its `runtime` map is initialized from config `documents` at layer construction time only (`index.ts:184-192`), and I couldn't find a runtime-add code path into it.

Runtime-added MCP entries (via the endpoint from #37308) land in the opencode service, but the SessionRunner uses the core service — so those tools never reach `registry.materialize` and never appear in the LLM request's tools list. Verified by watching `sync-bot-63` show "connected" in the daemon MCP status (queried with the same `?directory=`) while Kimi's assistant response enumerated exactly the built-ins (`read/write/edit/grep/glob/shell/websearch/webfetch/question/skill/subagent/execute`) with no MCP entry.

2) Two prompt code paths, not one.

• `packages/opencode/src/session/prompt.ts` (`SessionPrompt.prompt`) — reached by `POST /session/:id/message` and `POST /session/:id/prompt_async`. This is the file this PR patches.
• `packages/core/src/session/runner/llm.ts` + `packages/core/src/session/model-request.ts` (`SessionRunner` + `SessionModelRequest.prepare`) — reached by `POST /api/session/:id/prompt` via `SessionPending.admit`.

The second path also hard-codes `toolChoice`, at `model-request.ts:90`:
```ts
toolChoice: stepLimitReached ? "none" : undefined,
```

So even after this PR lands, orchestrators using the legacy `/api/session/:id/prompt` route (which is currently the working streaming path for external clients — the direct v2 endpoints emit a "share subscriber failed: Expected string, got undefined" on message.updated and never produce an assistant reply on the current v2-test build) still get `toolChoice: undefined`.

Suggested follow-up scope (either as a review comment I can address in this PR, or as separate issues):

1. Mirror the same three-way precedence at `packages/core/src/session/model-request.ts:90`, threading toolChoice from `Session.prompt` (core service) via a new field on `SessionPending` through to `PrepareInput`.
2. Bridge runtime-added MCP entries from `@opencode/MCP` into `@opencode/v2/MCP`, so tools registered via feat(core): add runtime MCP controls #37308's endpoint reach `SessionModelRequest.prepare.executableTools`.
3. Fix the v2 direct endpoints' "Expected string, got undefined" on message.updated so orchestrators can migrate off the legacy `/api` path.

Happy to take any/all of these as follow-up PRs if there's interest, but wanted to flag the shape of it here in case a maintainer already has a preferred design (the runner is under active refactor).

The core PR still stands as-is — it's the correct fix for the direct-endpoint code path, and it's the one this PR's title/description claims.

[github-actions]

Automated PR Cleanup

Thank you for contributing to opencode.

Due to the high volume of PRs from users and AI agents, we periodically close older PRs using automated criteria so maintainers can focus review time on the most active and community-supported contributions.

This PR was closed because it matched the following cleanup criteria:

• The PR was created more than 1 month ago
• The PR had fewer than 2 positive reactions
• Positive reactions are counted as thumbs-up, heart, celebration, or rocket reactions on the PR

PRs created within the last month are not affected by this cleanup.

If you believe this PR was closed incorrectly, or if you are still actively working on it, please leave a comment explaining why it should be reopened. A maintainer can review and reopen it if appropriate.

Thanks again for taking the time to contribute.