Plumb toolChoice from an agent option to the wire — pi-ai already carries the field

[FreeBandoLano]

Headline

toolChoice is a field the SDK already carries and maps onto the wire; dsh drops it in four
hops, so no agent option can require a tool call. Please plumb the existing field from an
agent option through to the request body, and record it in the durable request header so a
resumed session rebuilds the identical request.

This asks for no new capability. The OpenAI-compatible completions entry that dsh already
calls forwards a tool choice today — dsh simply never sets one, and the allow-list in the
adapter forwards only what it names.

Why it matters

A delegation agent whose rule is "nothing is claimed to work until the simulator ran it" has
to be able to compel the call that runs the simulator. Without a wire-level requirement the
rule rests entirely on persona prose, which a model can ignore — and here one did: a model
answered with a confidently fabricated component value, finish_reason: stop, and no tool
call, twice. Prompt wording cannot distinguish "I ran it" from "I made it up"; a required tool
call can.

Evidence that the field is already carried (the negative control is clean)

The dependency was driven against a local mock endpoint over the OpenAI-compatible completions
protocol, one tool offered, a prompt telling the model to call it. Lower-cased key list of the
captured body, unrelated keys only:

[A] no tool choice given
    request keys : model, stream, stream_options, store, max_completion_tokens, tools
    tool_choice  : undefined
[B] tool choice given as "required"
    request keys : model, stream, stream_options, store, max_completion_tokens, tools, tool_choice
    tool_choice  : "required"

A is the negative control: the field is absent unless asked for, so an assertion on it cannot
pass vacuously.

The four hops that drop it, in order

1. The shipped subagent tool's configuration schema — its agent-options object accepts
   only provider, model and a token cap.
2. The agent option type the tool passes to a child loop — the same three facts.
3. The shared llm seam's call configuration and request type — no tool-choice field. This
   is also why the requirement cannot ride the durable request header today, which is the
   next section.
4. The pi-ai adapter, which forwards an explicit allow-list of options to the SDK and
   therefore forwards only what it names.

The durability constraint — why this is one change and not two

The option and the durable header are one decision. Adding the field to the request type
without adding it to the call configuration compiles, works in the happy path, and silently
loses the requirement on resume: the session restores a request that no longer compels
anything, and the failure looks like a model ignoring an instruction rather than a field that
was dropped. The header the session logs must therefore carry the requirement, so a resumed
session rebuilds the identical request — and a change to it should be a logged header change,
so "when was this agent compelled?" is answerable from the log.

The typing wrinkle that must not be papered over

The protocol's simple stream entry — the one dsh calls — is declared without a
tool-choice field, while its implementation forwards one into the full stream entry, which is
declared with it and sets the body field. So the behaviour is real but only half-declared.
dsh calls the simple entry on purpose: it is the entry that maps the harness's reasoning level
onto the protocol's effort. The fix therefore belongs in the options that the simple entry
forwards, pinned by a test that asserts the body — not in a swap to the full entry, which
would trade this bug for a reasoning-level one.

The shape that works, as shipped locally

Four hops plus one agent option (toolChoice: 'none' | 'auto' | 'required' | {function name})
carried on the subagent tool row; the requirement lands in the child's call configuration and
in the durable request header; a compelled turn that answers in prose fails with a typed,
non-retryable error handed to the delegating agent instead of being accepted as success. It
has run in this deployment for several days over the free tier.

How it is verified here — keyless, at the highest seam

The mock HTTP endpoint above is already in daily use by the adapter spec, so every assertion
runs against it with a stubbed key and no network:

• Negative control first: with no requirement, the captured body must not carry the field,
  and that assertion must be watched failing before the implementation lands.
• The wire half: with the requirement set, the captured parsed body carries the required
  tool choice; a route whose protocol cannot carry it is refused before any request exists,
  by a typed error naming the protocol, with the mock endpoint receiving nothing.
• The response half: with the requirement in force a scripted prose completion ends in the
  typed content failure; with the requirement absent the identical completion stays a success.
  That pair is what proves the failure is caused by the requirement and not by the fixture.
• The durability half: the logged request header carries the requirement.

Local commits on the deployment branch, each with its specs: 5676b24 (carry a per-agent tool
choice to the request header and the wire), e7a3c4d (a prose answer fails the compelled
turn), 3039b1f (refuse a tool choice the route's protocol cannot carry) and 9da8f42 (pin
the per-protocol capability table). Specs: packages/subagent/tool-subagent/tests/tool-choice-wire.spec.ts,
packages/llm/llm/tests/tool-choice-capability.spec.ts,
packages/llm/llm-pi-ai/tests/tool-choice-capability.spec.ts.

Adjacent, and deliberately NOT part of this request

anthropic-messages spells the same idea differently: any where the completions protocol
says required, and a flat {type: 'tool', name} where ours is
{type: 'function', function: {name}}. Plumbing the field through exposes that gap rather
than creating it, so the local change declares per protocol and per value what an
implementation forwards and refuses a declared kind the route cannot carry — safe, and a
failure that names the protocol instead of a malformed body at a paid endpoint.

The translation itself (widen the declared carrying set, map the two spellings, assert the
captured body at the same seam) is a separate change, tracked locally on its own ticket.
It is noted here only so a reviewer is not surprised by the refusal; bundling it would widen
this review for no gain, because accepting plumbing should not require deciding a
protocol-vocabulary question.

Out of scope for this request

• Any change to which model serves which agent, and any provider-failover behaviour.
• Any pi-ai change beyond forwarding a field it already carries.
• Cost, session hygiene, and compaction.

[PerryLink]

The field is genuinely absent end to end, and your four hops are the right four. Two corrections: the typing wrinkle does not hold against the pinned pi-ai, and the blast radius is wider than the pi-ai adapter if the DeepSeek route has to work too.

Where it actually breaks

1. Delegation config — the shipped subagent tool's agentOptions takes four fields, not three: provider, model, reasoningEffort, maxTokens (packages/subagent/tool-subagent/src/index.ts:113-123).
2. Child agent options — the same four (packages/core/agent/src/runtime-types.ts:26-35).
3. The llm seam — GenerateOptions (packages/llm/llm/src/types.ts:455-495) has no tool-choice field, and neither does LlmCallConfig (packages/llm/llm/src/call-config.ts:23-30), whose field-wise comparison is callConfigEquals (:49-59).
4. The pi-ai adapter — streamWithSnapshot forwards only what it names: profile options plus temperature, maxTokens, sessionId, signal, headers (packages/llm/llm-pi-ai/src/adapter.ts:380-389). Grepping the whole repo for toolChoice/tool_choice returns nothing in adapter code: the hits are two README lines (packages/llm/llm/README.md:154, packages/llm/llm-deepseek/README.md:208, both cited below), a captured model listing (packages/llm/llm-pi-ai/tests/fixtures/model-listings/openrouter-2026-09-02.json:136) and one Codex responses fixture (packages/subagent/subagent-codex/tests/responses-fixture.ts:79).

The durability half is right, and the seam is sharper than "the request type"

The loop builds each request as {...header.config, messages, tools, sessionId, signal} (packages/core/agent-loop/src/agent.ts:611-616), where header.config is an LlmCallConfig, and its invariant companion fails any loop-built request whose model/temperature/maxTokens/stop/tools diverge from the folded header (packages/core/agent-loop/src/invariant.ts:46-51). A field on GenerateOptions that is not on LlmCallConfig is therefore exactly your resume case: never logged, never asserted.

Where I have to disagree — the typing wrinkle

Against @earendil-works/pi-ai@0.85.1, which is what packages/llm/llm-pi-ai/package.json:44 pins (^0.85.1), the simple entry is declared with the field and its implementation does forward it:

• SimpleStreamOptions extends StreamOptions declares toolChoice?: ToolChoice (pi-ai/dist/types.d.ts:219-221).
• openai-completions exports streamSimple: StreamFunction<"openai-completions", SimpleStreamOptions> (pi-ai/dist/api/openai-completions.d.ts:21), and the implementation spreads it into the full entry — toolChoice: options?.toolChoice (pi-ai/dist/api/openai-completions.js:533-537) — which then writes it to the body: params.tool_choice = options.toolChoice (:626-627). Same shape in anthropic-messages (pi-ai/dist/api/anthropic-messages.js:655-659, :884-887).

(The pi-ai/ prefix above is node_modules/.pnpm/@earendil-works+pi-ai@0.85._3b628cb9573a967ca43271c0a3ead452/node_modules/@earendil-works/pi-ai/.)

So "the simple entry is declared without a tool-choice field" does not hold for this version, and nothing needs to swap to the full entry on that account.

What is true, and is the real block for your use case, is that the neutral value set is narrower than the wire: export type ToolChoice = "auto" | "none" (pi-ai/dist/types.d.ts:23), and "required" appears nowhere in that file. Each protocol spells the same idea in its own full-options type, with its own vocabulary — "auto" | "any" | "none" | {...} for anthropic-messages (pi-ai/dist/api/anthropic-messages.d.ts:58), "auto" | "any" | "none" | {...} for bedrock-converse-stream (pi-ai/dist/api/bedrock-converse-stream.d.ts:6), "auto" | "none" | "any" for google-generative-ai (pi-ai/dist/api/google-generative-ai.d.ts:4), and OpenAI.Chat.Completions.ChatCompletionToolChoiceOption — which does include "required" — for openai-completions (pi-ai/dist/api/openai-completions.d.ts:5). The implementation hands the value straight through, so "required" would reach the wire at runtime; the declared simple-options type is what refuses to let a caller say it. A per-protocol capability table is still the right answer to that, but the reason is a narrow neutral enum plus per-protocol spellings, not an undeclared field.

The route question is load-bearing

If the deployment runs the deepseek provider, the pi-ai adapter is not on the path at all: WireRequest (packages/llm/llm-deepseek/src/protocols/chat-completions/types.ts:13-30) has no tool_choice, and that package records the non-mapping as a deliberate limitation shared with its pi-ai twin (packages/llm/llm-deepseek/README.md:208). Plumbing hop 4 in llm-pi-ai alone would leave that route silently unaffected — worth stating explicitly in the proposal, since your negative control ran over the completions protocol, which both adapters speak.

Why it is missing rather than broken

packages/llm/llm/README.md:154 records it as deliberate: sampling is temperature/maxTokens/stop only, "no tool_choice, top_p, or penalty fields; the vocabulary grows when a producer lands". The honest shape of the gap is one producer-gated omission that now has a producer in your deployment, spanning those four files in three packages, plus the protocol-vocabulary question your "adjacent" section correctly keeps separate.

Not verified here: the captured-body [A]/[B] table (no mock endpoint available to me) and the four local commits you cite (5676b24, e7a3c4d, 3039b1f, 9da8f42) — the spec paths you name do not exist at ddefc45.