Session overrides

An agent definition declares what a session is allowed to change. A session then asks.

// In the definition — these are the defaults.
overrides: {
  model: false,        // provider, model id and the fallback ladder, together
  reasoning: true,
  system: "append"     // "append" | "replace" | false
}

// At the call site.
await client.sessions.create({
  agentId,
  initialMessage: "where is my order?",
  overrides: {
    model: { reasoning: "high" },
    system: { mode: "append", text: `The customer is on the ${plan} plan.` }
  }
})

A denied override is rejected, with OverrideNotAllowed, rather than dropped. A caller that asked for a cheaper model and silently got the expensive one has no way to find out. The control plane's own "Start session" dialog renders every axis and disables the closed ones with the reason, because "you cannot change this here" is information the caller needs before it submits.

model covers provider, model and fallback together. Splitting them would let a caller redirect every turn to another provider through the fallback list while model was closed.

What is stored

The session row keeps the overrides as requested, so it replays as it ran even after the policy is tightened, and the effectiveModel they resolve to — stored rather than recomputed, because the session list renders it for every row.

const session = await client.sessions.get({ id })
session.effectiveModel   // { provider, model, reasoning }
session.overrides        // exactly what was asked for

Other axes

Two more objects can be opened to a session, both default-closed and both only in the narrowing direction:

• overrides.compaction (default false) — the compaction policy, layered per key.
• overrides.sandbox — the sandbox lifecycle. A session may ask for a shorter idle window, never a longer one.

The system prompt, and your cache bill

system: "append" appends a session's text below the agent's own prompt, and that placement is load-bearing: the appended half sits under the cache breakpoint that covers the tool schemas, so a two-line per-session note does not invalidate ten thousand tokens of tool definitions on every step. See context and caching.