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.