Models, providers and reasoning

Documentation · Configuration · Media

export ANTHROPIC_API_KEY='...'
octet --safe-mode --model claude-sonnet-4-6

/model [id] picks a model, and /status shows its route and capabilities. octet uses live model discovery where the provider offers it. --offline skips optional discovery, not inference traffic. Which models you can use depends on your account and endpoint, and octet's tests don't cover every live provider.

New here? Start with first-run setup, or set your provider's variable from cloud setup.

First-run setup#

When an interactive launch has no available models and no explicit model selection, the setup menu offers, in order:

1. Add an API key. Choose a supported built-in provider, paste into a masked input and review before saving. This is a dedicated secret input, not the conversation composer, and no environment variable is required.
2. Sign in with ChatGPT / other supported OAuth subscriptions. Choose ChatGPT (OpenAI Codex) or GitHub Copilot. Codex offers browser sign-in (PKCE) or a device code, and Copilot uses device authorization. No other subscription login is implied.
3. Local/self-hosted models. Choose LM Studio or an explicit OpenAI-compatible endpoint, then discover or select a model and review the custom registry change.
4. Continue without a provider. Leave setup without saving provider data.

Existing available models and explicit model selections don't trigger this menu. In the TUI, /setup opens the same wizard on demand, even with a configured provider. A saved provider refreshes the model catalog but keeps your current session, active model and default model, so use /model to switch. If you replace the active route's stored key, reselect that model to rebuild its credential. When octet has something saved, /setup first asks whether to add or remove. Remove a provider or sign-in lists only what octet stored (ChatGPT/Codex, GitHub Copilot and other subscription sign-ins, built-in API keys, custom providers), asks you to confirm (Cancel is the default), deletes it through the same private-file path it was saved with, and refreshes the model list. It refuses to remove the provider behind your current model (switch with /model first) and never changes an environment variable, so a provider can still work through one afterwards. A credential environment variable still takes precedence, and the wizard warns before saving a fallback key. Print and RPC don't open the wizard. Subscription sign-in needs an online launch, and --offline isn't a local-inference guarantee. After a credential is saved the catalog refreshes and model selection uses the ordinary picker. Saving isn't a successful inference check, and a discovery failure can leave the saved credential in place for a retry.

Built-in API keys are saved in ~/.octet/credentials/api-keys/<provider>.json, with owner-private directories (0700) and files (0600), atomic publication and explicit consent before replacement. Environment credentials take precedence over saved keys. Native provider routes stay native: saving a key doesn't turn Anthropic, Gemini or OpenAI into a custom OpenAI-compatible endpoint.

A saved API key has to stay recoverable to authenticate provider requests, so owner-private storage is not hashing or encryption at rest. Keep the store out of repositories, support reports and shared backups. Keys aren't copied to prompts, config, model metadata or setup receipts. AWS/Bedrock, Azure, Vertex and Cloudflare need extra account, deployment, region or endpoint configuration and aren't offered as one-field API-key setup, so use their documented configuration below.

See Getting started and the CLI alternatives. This setup flow is part of the current 0.9.5 source candidate; availability in older published versions differs.

Cloud setup#

Alternatively, set the credentials for your provider, then run octet --model ID. Don't put credentials in prompts or repository config.

The built-in OpenRouter route sends fixed app-attribution defaults on model discovery, Chat Completions and Batch API requests:

These headers identify the app for OpenRouter's public rankings and app analytics. They contain no user, project or session identifiers and add no separate telemetry request. The same identity is used whether the credential comes from the environment or saved setup. Other built-in providers and custom OpenAI-compatible endpoints don't inherit these defaults. Explicit model and request header overrides keep their normal precedence. Attribution applies to new requests, not past usage.

Other built-in presets: DeepSeek, Groq, Cerebras, xAI, Together AI, Fireworks AI, NVIDIA, Hugging Face, Moonshot AI, Xiaomi, MiniMax and OpenCode Zen. A preset name doesn't promise every API of that provider. The provider declarations list what each route covers.

Bedrock takes AWS credentials in this order: an AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY pair (with an optional session token), a web-identity role, the selected AWS_PROFILE, then ECS or EC2 instance metadata. A Bedrock API key in AWS_BEARER_TOKEN_BEDROCK is sent as Authorization: Bearer … and takes precedence over SigV4, so an API-key user never needs or pays for the AWS credential chain. Model availability depends on your account and region. Quote IDs that contain shell characters: octet --model 'bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0'.

Codex subscription login#

octet --login codex
octet --model gpt-5.6

Codex offers Sign in with your browser (recommended) and Use a device code (SSH/headless), instead of a manually managed API key. Browser sign-in opens the OpenAI authorization page, also prints its URL, and listens only on 127.0.0.1:1455 (or the registered fallback port 1457 when 1455 is busy) for up to five minutes. The browser shows a self-contained signed-in page once the credential is saved. --headless, SSH, an unavailable browser opener, or both callback ports being busy uses the hosted device-code flow, and you can choose it explicitly too.

A successful account-scoped live inventory is authoritative. octet asks your account which models you can use, and doesn't guess Ultra, collaboration or model availability from a name or plan. Codex inference follows Pi's ordinary Responses contract with parallel tool calls enabled, even when inventory prefers Responses Lite; the inventory observation is retained without selecting that serial wire contract. If the metadata is missing or unusable, octet falls back to the more limited behavior. If the live inventory omits a model, no corresponding GPT-6 Codex route is injected. When advertised, select codex/gpt-6.1-sol, codex/gpt-6-astra, codex/gpt-6-sol or codex/gpt-6-luna. These stay namespaced separately from direct OpenAI presets. When discovery is unreachable, 6.1 Sol leads the fallback suggestions.

octet --extension-dir ./extensions \
  --enable-extension octet-subagents --trust-extension octet-subagents \
  --model gpt-5.6-sol --reasoning ultra

Subscription OAuth logins#

Beyond Codex, octet signs in to paid plans directly rather than asking for a long-lived API key. Each provider gets its own owner-private credential file under ~/.octet/credentials/, and its models appear in the catalog only while that file says you are signed in.

These are separate providers from the same vendors' API-key presets, so signing in with a plan never replaces a key you already configured:

--headless prints the verification URL and code without opening a browser, so the device flows work over SSH. --logout <provider> removes only that provider's credential and never contacts the provider; for the plans, revoke access from the vendor's own account page.

Meta is worth calling out because its grant is two steps. The device flow yields an identity token that the inference surface will not accept, so octet immediately exchanges it for a short-lived Model API key. The identity token is what makes the exchange repeatable; when Meta rejects it, the session is over and octet asks you to sign in again rather than retrying. OpenRouter is the opposite: its login mints a durable API key with no refresh token, so octet never renews it and --logout only deletes the local copy. Its authorization URL is printed even when browser launch fails or an opener fails to settle promptly. Opener children are bounded and reaped; waiting for a pasted redirect is cancellable without leaving a background stdin reader behind.

Credentials are refreshed automatically. A refresh is serialized both within one octet process and across octet processes, and the credential file is re-read after the cross-process lock is taken, so two concurrent launches cannot spend the same single-use refresh token and leave you signed out. Once refresh work starts, it owns the exchange, both locks and persistence independently of the request waiting for it: cancelling that wait does not abandon an issued rotated token. This does not promise recovery from process termination, runtime shutdown or an indeterminate provider response. A provider that rotates its refresh token but does not return a new one is treated as a failure and the existing credential is left untouched, because that provider has already revoked it.

Not yet available#

• Anthropic (Claude Pro/Max). The login is a PKCE grant rather than a device code, which octet does not yet support end to end. It also needs a request-path change: the Anthropic Messages codec decides whether to send the claude-code-* and oauth-* beta headers from the credential that is bound to the route, and it currently recognizes only an environment bearer token. A privately resolved OAuth credential therefore would not receive the betas a subscription token needs. Fixing that means teaching the codec about a dynamically resolved Anthropic route, which is a change to octet-ai and is tracked separately rather than approximated here. ANTHROPIC_AUTH_TOKEN and ANTHROPIC_OAUTH_TOKEN continue to work today.
• Radius. Its login is defined against a Pi-hosted gateway that also serves Pi's own wire protocol. octet has no such codec, and adding one is a separate change.

GitHub Copilot#

octet --login copilot --headless
octet --logout copilot

github-copilot is an alias. Login uses GitHub.com's device flow, and --headless prints the verification URL and code without opening a browser. Only GitHub OAuth state is saved, in the owner-private ~/.octet/credentials/copilot.json. Inference tokens stay in memory, and no editor, Codex or environment credentials are imported.

Online startup registers authenticated, eligible models as github-copilot/<id> in the ordinary picker and the shared native-host catalog. Missing credentials, failed discovery and unsupported models contribute no Copilot entries. --offline skips even Copilot-store access and advertises no cached inventory. Only explicit Chat and Responses routes are supported. Reasoning-flagged models, Anthropic-only routes, vision and structured output aren't advertised. Custom Enterprise authorities and environment endpoint overrides aren't supported.

Later credential resolution rejects local logout or replacement and rejected inference origins, but logout doesn't remotely revoke already-running requests. First-run setup offers GitHub Copilot device sign-in. The TUI /login and /logout slash commands aren't wired to Copilot yet, so use the CLI flags for later account changes and restart existing catalog owners afterward. NDJSON gains no login or logout commands or OAuth payload fields. Rust embedders keep the credential-safe SDK seam. This describes source integration, not live-provider or native-client qualification.

Local and custom endpoints#

Choose Local/self-hosted models in first-run setup for LM Studio or an OpenAI-compatible endpoint. You choose one endpoint, an optional credential source and a discovered or manual model ID, then review before saving. octet never scans localhost or the network. Compatible servers include llama.cpp, vLLM, SGLang, LM Studio and compatible gateways.

For scripts, review first, then add --yes:

# Explicit LM Studio selection permits its documented default endpoint.
octet setup --preset lm-studio --manual-model local-model

# Discover only this endpoint, then commit.
octet setup --endpoint https://models.example.test/v1/ \
  --api-key-env EXAMPLE_API_KEY --yes

# Manual/offline recovery makes no discovery request.
octet setup --endpoint http://127.0.0.1:8000/v1/ \
  --offline --manual-model Qwen3-Coder --yes

Every flag is in the CLI reference.

Setup writes nothing until you confirm. Even a review or cancel can probe the selected endpoint, so use --offline --manual-model ID when you want no probe.

Custom registry#

Keep custom endpoints together in ~/.octet/credentials/custom.json, with chmod 600. Reference keys through environment variables, never literal values.

{
  "version": 1,
  "providers": {
    "apple-fm": {
      "label": "Apple Foundation Models",
      "base_url": "http://127.0.0.1:1976/v1/",
      "auth": { "kind": "none" },
      "auto_discover": true,
      "startup_timeout_secs": 300,
      "models": [{
        "api_name": "system", "context_window": 8192,
        "max_output_tokens": 1024, "tools": true,
        "parallel_tool_calls": false, "vision": false,
        "structured_output": false, "reasoning": true,
        "reasoning_configurable": false
      }]
    },
    "home-server": {
      "label": "Home Server",
      "base_url": "http://192.168.1.20:8000/v1/",
      "auth": { "kind": "bearer_env", "var": "HOME_SERVER_API_KEY" },
      "auto_discover": true
    },
    "local": {
      "label": "Local Qwen",
      "base_url": "http://127.0.0.1:8000/v1/",
      "auth": { "kind": "none" }, "auto_discover": false,
      "models": [{
        "api_name": "Qwen/Qwen3-Coder-Next", "display_name": "Qwen3 Coder Next",
        "context_window": 131072, "max_output_tokens": 16384,
        "tools": true, "parallel_tool_calls": false, "vision": false,
        "structured_output": false, "reasoning": true,
        "reasoning_values": ["none", "default"], "reasoning_default": "default"
      }]
    }
  }
}

Each provider is discovered on its own. IDs look like custom/<provider-id>/<model-id>, and labels show in the picker and /status. Set auto_discover: false with an explicit models list to pin the registry as truth when GET /v1/models isn't useful. Old single-object files are read as custom-openai without changing existing IDs. New files should use the versioned registry above.

For providers with auto_discover: true, limits the endpoint asserts are authoritative, and the registry is a seed and fallback. Every other registry field (display name, tools and vision flags, reasoning values, pricing, presets) keeps configured-wins behavior.

Custom models count as free for cost guardrails, so local and self-hosted models can use price-dependent features such as subagents. To track spend, give per-model rates in microdollars per million tokens. Omitted rates stay zero:

{"api_name":"metered-model","pricing":{"input":75,"output":300,"cache_read":8,"cache_write_5m":19}}

Model metadata#

A pinned models.dev supplement fills in what a provider's model list leaves out: display names, pricing, input types and context and output limits. It covers only models that built-in discovery actually returns, and it's looked up per provider. It never supplies tool or structured-output flags or reasoning controls, and it never replaces a value the endpoint states.

Endpoint capability self-description#

An unchanged build can use new models on already declared Chat or Responses routes when the selected endpoint includes an octet_capabilities v1 object in its ordinary model inventory. Built-in OpenAI-compatible, DeepSeek and OpenRouter discovery and custom-registry startup use the same bounded decoder. Static-only providers, native Messages, Google, Bedrock and Conversations routes, Codex and Copilot keep their existing contracts. This creates no new discovery requests and doesn't bypass a declaration's model filter. Guided octet setup doesn't consume this object yet.

An example entry in GET /models (protocol uses the canonical Rust API spelling):

{
  "id": "future-model",
  "octet_capabilities": {
    "version": 1,
    "protocol": "open_ai_chat",
    "context_window": 131072,
    "max_output_tokens": 16384,
    "input_modalities": ["text", "image"],
    "output_modalities": ["text"],
    "tools": true,
    "parallel_tool_calls": true,
    "structured_output": true,
    "reasoning": {"values": ["none", "low", "high"], "default": "low"}
  }
}

Cold-start feedback#

Set lifecycle_feedback: true on a custom provider only if its streaming Chat Completions endpoint implements the optional readiness extension. octet then sends x-octet-lifecycle: 1. The endpoint may answer with that header, comments such as : octet-lifecycle: loading; warming model, or both. Accepted states are queued, loading and ready. Malformed values and ordinary SSE comments stay invisible. Endpoints you haven't configured get no header, and ordinary OpenAI clients ignore it.

Inference measurements (unreleased)#

Every supported conversation codec/transport shares attempt-scoped client observations, independently of billing and optional native server timing. Inference measurements defines sources, scopes, unavailability, /status, JSONL/NDJSON/RPC events and the route coverage matrix. Server timing is reported only when a recognized matching terminal count/duration pair exists; client E2E throughput is never labeled server decode speed. No live-provider timing accuracy or released availability is implied.

All live conversation routes also use the same usage-calibrated streaming decode estimator when native timing is absent. Native reporting wins; estimates are marked ~ and exclude E2E, prefill and completion-tail time. Short/buffered output, unseparated reasoning and deferred retrieval may remain unavailable. See the measurement contract for assumptions and qualification limits.

Reasoning#

octet --reasoning high
octet --reasoning budget=16000

budget=N works only for compatible models. /thinking [level] offers off, on, minimal, low, medium, high, xhigh, max or ultra, narrowed to what the selected model supports. A model's own controls (off-only, on and off, or custom named values) decide the picker and what's sent, not a generic effort guess. Built-in native discovery may use a declaration-owned token-budget table only when the whole table fits strictly below the effective output ceiling. Otherwise the inventory model keeps its limits but advertises no reasoning control: octet doesn't enlarge the ceiling or invent replacement budgets from the snapshot. Compatible endpoint choices and defaults can narrow the declared contract without changing its native codec.

ultra needs advertised Ultra/V2 metadata and the trusted, enabled, live octet-subagents service. Otherwise it's clamped to the highest ordinary effort that's safe. Child work uses the extension's subagent_* tools and the worker list in /extensions. There's no parallel native root collaboration tool. See legacy Pro configuration, context budgeting and reasoning display.

Defaults#

In this checkout, a new CLI session with no reasoning preference uses the selected model's advertised default, including an advertised Off. Without a default, a known reasoning contract uses its first supported enabled choice, and with no usable contract octet's selection stays Off without guessing a reasoning parameter. This fixes startup overriding model defaults with Off in octet 0.8.0. An endpoint that publishes its own enabled levels and default (DeepSeek's effort: {default_level, supported_levels} object) is decoded: those levels become the exact choices, the declared level is the default, and the enabled levels never remove a declaration-owned Off control. max stays selectable whenever the endpoint declares it, and an explicit selection always wins over the declared default.

The declared level is only the fallback for a user who has never chosen. The order is: this run's --model/--reasoning flag, then the selection the user saved, then the model's declared default. What is saved is the session's own record — EntryValue::Config written by append_config_if_changed and restored by persisted_session_config/launch_configuration_parts (crates/octet-coding-agent/src/app/bootstrap.rs) — and the user-level ~/.octet/config.toml values that /model, /thinking and /settings default model|reasoning persist through cli::persist_model / cli::persist_reasoning. Resume prefers the session's record over that file and an explicit --reasoning over both; the flag never rewrites the file. cargo test --locked -p octet-coding-agent --test reasoning_persistence covers each of those restarts.

An explicit CLI, environment or config choice still wins over the model default. Resume keeps the saved choice (including Off) unless --reasoning overrides it, and existing saved Off values aren't reinterpreted as unset. In the interactive UI, submit /thinking on or another supported level to change and persist that session's selection, then check /status.

A custom none/default contract's On leaves the reasoning control absent, so the server uses its default, and always-on models also get no control parameter. Unknown metadata and a lack of displayed reasoning don't establish that the server has disabled thinking. Reasoning can raise latency and token use, so use --reasoning off when the model supports it to opt out. See reasoning selection and thinking.

Protocols and transport#

Capabilities are model-specific and checked before sending: modalities, tools, structured output, output limits and reasoning. Google uses native generateContent, not an OpenAI translation. Knowing a protocol doesn't imply native audio support.

Codex inference uses ordinary Responses with parallel_tool_calls: true, like Pi. Explicit Responses Lite selection by an octet-ai SDK caller still sends parallel_tool_calls: false. Host execution is independent of the wire flag: built-in tools says which batched calls octet runs together.

GPT-6 contracts and execution#

Direct gpt-6-astra, gpt-6-sol, gpt-6.1-sol and gpt-6-luna are declared on Responses with text and image input, a 1.05M-token context window and 128K output. Astra accepts low through max (default low). Sol and Luna also accept Off/none and default to medium. 6.1 Sol defaults to medium but accepts only low through max (no none or minimal), and its tools need the Responses API. Exact public pricing and its above-272K tier are recorded in the catalog sources. New public prices aren't borrowed for Codex Sol, Luna or 6.1 Sol, whose subscription cost stays unknown.

Model and endpoint feature declarations must both opt in:

• Async tools. Qualified host-parallel observations advertise async: true. Complete calls are persisted before a bounded background job starts, the model can advance while those jobs run, and each result uses its original call ID. This isn't speculative execution of streamed arguments. Synchronous calls, effectful work, approvals and hard usage ceilings keep their barriers. Interrupted pending work isn't blindly rerun after a restart.
• Native steering. Public GPT-6 uses response.steer on the active socket, with durable admission before dispatch and separate accounting and persistence for every response segment. Provider acceptance isn't proof that an instruction was followed, and ambiguous disconnects aren't automatically replayed. Routes or input forms without qualification keep ordinary queued steering, and Codex doesn't gain native steering from its model name. Hard cumulative ceilings keep the ordinary queue boundary.
• Thinking changes. Qualified /thinking changes queue for the next response boundary without cancelling the root run. The request-level reasoning baseline stays fixed, and ordered configuration_update items carry ordinary effort changes. Off still needs an advertised none, and Ultra or delegation-mode changes aren't ordinary wire effort updates. Durable replay keeps the baseline and the effective selection. Compaction must rebase only after a successful summary, and standalone native compact rejects update histories without separate authority.

Codex currently qualifies reasoning updates from positive account inventory, not async tools or native steering. Lite and V2 don't imply either feature. Public API support and deterministic loopback tests aren't live OAuth inference or cache-hit qualification. See reasoning controls and the protocol contract.

Third-party GPT-6 inventory doesn't inherit these capabilities from a name or snapshot. OpenRouter must advertise its own images, tools and exact reasoning choices, and its ordinary Chat route doesn't become a Responses control endpoint. Provider-managed misalignment monitoring is independent of host approval: misalignment_policy_violation stops automatic retry, and already completed work isn't undone. octet doesn't provision project webhooks or safety-alert subscriptions automatically.

Declarative preset metadata#

Presets are data, never provider-name branches. The typed preset surface in octet_ai::declarations describes per-model and per-provider fields, and validation is fail-closed. It's declared plumbing: the OpenAI-compatible codecs and the streaming client that consume these fields are owned separately, so preset validation alone doesn't establish codec emission or proxy behavior.

Native Mistral Conversations (experimental codec)#

The native Conversations codec passes its deterministic request and SSE fixtures, including rejection of credential-bearing or non-TLS destinations before credential resolution (literal loopback HTTP is allowed for local testing). Only native completion settles calls: a missing conversation.response.done reports MissingFinish, never a synthesized tool-call end or successful reply. No POST is replayed. The built-in Mistral preset above still uses Chat. Conversations discovery, presets and broader native capabilities are separate work, not implied by these codec repairs.

Prompt caching#

With cache retention enabled, Anthropic Messages marks eligible tools, system and final content. Large tool batches also retain the preceding user breakpoint so it stays reachable within the provider's 20-block lookup window (at most four breakpoints total). Supported Claude Bedrock identities use native cachePoint blocks on system and user boundaries, with the same large-batch bridge. Short retention uses the native default; Long requests one hour only when the model's cache compatibility allows it. Unsupported models and opaque Bedrock application profiles receive no explicit points; Nova keeps automatic caching.

Responses caching follows the selected route's declared controls, not a model name alone. Flex is a service tier on that same codec; its existing endpoint gate is described above. Stable serialized prefixes do not prove that a provider's implicit breakpoint remains eligible when a user/tool-result group is extended. The local audit covers all builtin Responses models, including GPT-6 Luna, and declared Flex fixtures without claiming live hits or tier availability.

These annotations do not remove or reorder context. Compaction, rolling screenshot bounds, changed tools/instructions and context hooks can still invalidate earlier prefixes. Cache availability, minimum sizes, TTLs and routing remain provider-dependent. Cache warming is additional billable work, not a repair for unstable prefixes. The credential-free cache audit separates local estimates from live usage.

Provider request trace#

When a provider rejects a request with an opaque status (for example an HTTP 400 whose body is only "Bad Request"), set OCTET_PROVIDER_REQUEST_TRACE to a file path (or stderr) before starting octet. Use a fresh file for each process. Requests append JSON lines describing shape, prefix comparisons and terminal usage; a rejection adds the status and the provider's request id. Shape includes:

• transport (http or websocket), the frame type, the API model name and the body size;
• the length of every top-level array, and whether previous_response_id is set (never its value);
• for Responses requests, the count of each input item type, the trailing item type, image counts by kind (inline, URL, file id) with inline wire bytes, how many reasoning items carry encrypted_content (never its content), and how many computer_call_output items carry no screenshot.

cache_prefix events compare successive requests in the same client/session, model and endpoint lane at three stages: canonical (after agent context hooks, before model normalization), encoded (codec JSON, before payload hooks), and wire_http or wire_websocket (after hooks or continuation rewriting). HTTP bytes are the uncompressed JSON before compression/signing, not TLS bytes. Opaque host transports expose only the canonical stage. Special native steering, prewarm and standalone compact operations retain shape-only tracing where available, not this three-stage comparison contract.

Events include client-private salted digests, tools/system/message segment paths and lengths, exact raw JSON common-prefix offsets, a diagnostic annotation-free prefix view, estimated invalidated suffix tokens (bytes/4), cache-point positions and a digest of other controls. These are not provider tokenization or cache hits. Only terminal cache_usage events carry decoded provider usage, correlated by id. Efficiency is cache_read / (uncached_input + cache_write + cache_read); writes are fresh, one-hour writes are a subset, output is excluded, and zero/unreported input has no ratio. Compatible Chat usage accepts Kimi's top-level cached_tokens alias without adding it to other cached-token aliases.

Responses native prompt_cache_breakpoint positions are included for documented input-text/image/file blocks in user/system/developer messages and function/custom tool outputs. Moving only those annotations does not count as a history rewrite in the diagnostic prefix view; raw body digests still change. Schemas, arguments, unknown fields and opaque reasoning are not stripped. Tracing never adds markers to outgoing requests or changes the route's cache policy.

Comparison state is shared by client clones, never across process restarts. When enabled, raw/projection bytes stay in memory only: at most 12 snapshots, 16 MiB of retained payload bytes and 2 MiB per observed body; oversized or non-JSON bodies clear the lane/stage's prior comparison. Segment output is capped at 256 entries. TTL and account affinity cannot be inferred from a byte match, and a missing comparison is not a cache miss.

The trace never writes prompts, tool arguments or output, headers, URLs, credentials, response ids, image data or reasoning content. Digests use an unexported client-local salt, preventing cross-run correlation of content. New trace files are owner-only (0600) on Unix; existing permissions are unchanged. Review metadata before attaching a trace to an issue. Leave the variable unset to disable it. See the audit for reproducible checks and interpretation limits.

Model-visible tool-result images#

A long computer-use run produces many screenshots. Only the newest four tool-result images (MODEL_VISIBLE_TOOL_IMAGE_LIMIT) are sent to the model; older ones are replaced in the request with a short text placeholder. The session journal keeps every image, so reopening, export and audit are unchanged. Images you attach to a prompt are not affected.