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: "What are the launch risks? Cite your sources.",
  overrides: {
    model: { reasoning: "high" },
    system: { mode: "append", text: `The customer is on the ${plan} plan.` }
  }
})

A disallowed override returns OverrideNotAllowed. The console disables settings that the agent's policy does not allow. The model setting controls provider, model, and fallback together; reasoning can be permitted separately.

What is stored

The session stores the requested overrides and the resulting effectiveModel:

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

Other axes

Additional settings can be allowed by the agent:

• 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.
• overrides.tools (default false): which tools the session reaches. See below.

Narrowing the tools

Open overrides.tools and a session may run with fewer capabilities than the agent has: a research session that may read source documents but not publish a brief, a demo that may not deploy, an evaluation that may not touch the network.

await client.sessions.create({
  agentId,
  overrides: {
    tools: {
      connections: ["research"],                    // drop every other MCP server
      subset: ["read_source", "read", "grep"],    // keep these tool names
      sandbox: { preset: "read-only" }             // and narrow the machine
    }
  }
})

Session tool overrides only remove capabilities. A name absent from the version returns OverrideNotAllowed, with the relevant path in field.

A subset containing sandbox tool names narrows the sandbox too. If it names no sandbox tools, the sandbox's tool set is unchanged. For an MCP entry without an allow list, use connections to narrow access; subset is not supported.

What is stored

effectiveTools records the tool set used for subsequent turns and recovery:

session.effectiveTools
// { connections?: string[], subset?: string[], sandbox?: string[] }
// absent means the version's own set, never "nothing"

Sub-agents inherit session tool restrictions, combined with their own roster restrictions.

One turn at a time

sessions.send takes the same tools shape, for the request in front of you:

await client.sessions.send({
  id: session.id,
  message: "Read the source documents and summarize the evidence. Do not publish anything.",
  tools: { subset: ["read_source", "read", "grep"] }
})

It needs the same overrides.tools open, and it is checked against this session's set rather than the version's, so a turn can never widen back to something the session gave up at sessions.create. The narrowing governs the turn that message starts and every step, fallback rung and recovery of it; the next message states its own. When several queued messages are answered by one turn, the newest one governs, because a narrowing is part of an ask and the last word is what you meant.

One cost, stated plainly: the tool array is the first thing in the cached prefix, so a turn that narrows writes a new prefix and the next un-narrowed turn writes another. Narrow at sessions.create for a whole conversation; narrow per turn when the request really is different from the last one.

A narrowed session has its own cached prefix. The prefix fingerprint is computed from the model-facing tool array, which is a different array, so it is a different hash: stable for the life of that session, and not shared with the un-narrowed ones.

System instructions and caching

system: "append" places session-specific text after the agent's stable instructions. This helps preserve prefix cache reuse. See context and caching.