Module agent_runtime 

The runtime flags a pane’s CLI is given, decided in srv.

The runtime menu shows agent:runtime block meta; the process runs on cmd:args. The frontend keeps the two in step (buildPaneArgs), but agent.open — MCP OpenAgent, layouts, agent.define + open — builds a pane without the frontend. It wrote cmd:args from the catalog alone and no agent:runtime, so the pane’s CLI ran on its own default model (Opus 5.5 / medium on current CLIs) while the menu fell back to Sonnet / high. A pane with a session on file spawns eagerly at open, before any message, so nothing ever corrected it. docs/retro/RETRO_RESUMED_AGENT_SPAWNS_WITHOUT_RUNTIME_FLAGS_2026_09_30.md, docs/reports/REPORT_AGENT_RUNTIME_BINDINGS_2026_09_30.md (G3).

Two entry points, one decision, for the two providers whose model the menu wires (Claude, Codex):

• seed_launch — a pane agent.open is creating.
• with_runtime_flags — a pane that already exists, at the moment it spawns. srv never reads agent:runtime otherwise, and a persistent process never re-reads cmd:args, so a pane saved before the fixes (or written by any path that forgets) would run on the CLI default for its whole life. This is the backstop that makes srv authoritative at the one moment it matters.

The defaults are duplicated from the frontend by necessity and pinned to its by providers/runtime-defaults-consistency.test.ts.

Structs

AgentRuntimeEvent

The agentruntime event’s payload (mps_events::AgentRuntime). An absent value is omitted, not null; what the CLI reported is sent only while a process runs.

EffectiveRuntime

What the running CLI says it is ACTUALLY using, from its get_settings answer (applied): the alias on the command line resolved to a concrete model, and the effort in force. None for a field the CLI reports as null (Haiku has no effort).

Remembered 🔒

What the user last picked in the Runtime menu for an agent (last_runtime on db_agents), already validated. Each setting is optional: only what was picked is here, and the rest keeps coming from the definition.

SeededLaunch 🔒

SpawnRuntime

What an agent process was actually spawned with: the runtime flags in its final argv. The Runtime menu shows what was REQUESTED (agent:runtime); this is what the process was GIVEN, so the menu can say when they differ. None for a flag the argv does not carry — the CLI then uses its own default.

Constants

CONTROL_PROTOCOL_FLAG 🔒

The flag a control-protocol (persistent) agent is launched with; its presence in the catalog args is what makes bypass become default.

DEFAULT_EFFORT 🔒

DEFAULT_RUNTIME_CONFIG.effort in frontend/app/view/agent/types.ts.

DEFAULT_PERMISSION_MODE 🔒

DEFAULT_RUNTIME_CONFIG.permissionMode in frontend/app/view/agent/types.ts.

EFFORT_LEVELS 🔒

OWNED_FLAGS 🔒

Flags this module owns. Stripped from the catalog args so a base that ever grows one cannot double it.

PERMISSION_MODES 🔒

SETTINGS_REQUEST_PREFIX

Prefix of the request_id of our get_settings requests, so the answer can be told from the answers to anything else.

Functions

agent_runtime_event

The agentruntime event for one pane (persisted, so a menu that mounts late still gets the latest). running is None when no process is alive — then there is nothing for the menu to compare against. effective is what the CLI reported using, when it has (see EffectiveRuntime).

apply_remembered 🔒

Lay what the user last picked over the definition, the way the frontend’s launch does (resolveLaunchRuntime): the remembered setting beats the definition’s flag for it, and that flag is taken out of the pane’s copy.

apply_to_meta 🔒

Write the three keys that must travel together into a new pane’s meta: cmd:args (what runs), agent:runtime (what the menu shows) and agent:provider_flags (what the frontend’s per-send rebuild reapplies — it starts from the catalog and would drop the definition’s flags on the first send otherwise, #2872). One call, so no caller can write one without the others.

effective_from_control_response

The effective runtime in a get_settings answer, or None for any other frame, an error answer (a CLI that has no get_settings) or one without applied. The shape is {type: control_response, response: {subtype: success, request_id, response: {applied: {model, effort, ...}}}}.

flag_value 🔒

The value of --flag value or --flag=value in flags, if present; the last one when it repeats.

is_claude_model 🔒

Claude model names: the aliases and concrete ids. A pane carried over from before per-provider models can have one stored for a Codex agent; it must never reach Codex, which rejects it (frontend buildRuntimeArgs.ts guards the same way).

model_takes_effort 🔒

Whether --effort is passed for model. Haiku takes none (the pinned CLI drops it; older CLIs forwarded it and the API answered HTTP 400 on every turn). Matches the model id as well as the alias, case-insensitively — this was model == "haiku", so a concrete Haiku id still got the flag. Mirrors modelTakesEffort in frontend/app/view/agent/runtime-capabilities.ts.

publish_agent_runtime

seed_launch 🔒

Build cmd:args and agent:runtime for a freshly opened pane.

settings_request_line

The control request asking a running Claude CLI what it is using. Observed on CLI 2.1.285 to be answered straight after spawn, with no account and no message (docs/specs/SPEC_RUNTIME_MENU_REMAINING_GAPS_2026_10_01.md §7.3).

spawn_runtime_from_args

The runtime flags in args. The LAST occurrence of a repeated flag wins, which is how the CLI is expected to read them (unverified; it matters only when provider_flags repeats a flag the runtime already set). --dangerously-skip-permissions reads as bypass; --permission-mode X as X.

with_runtime_flags 🔒

args as stored in cmd:args, plus any runtime flag it lacks, taken from the pane’s agent:runtime (or the defaults when it has none).

without_flags 🔒

flags without the names flags (and their values), --flag=value too.

without_owned_flags 🔒

base without any of OWNED_FLAGS (and their values).

without_permission_flags 🔒

args without the permission flags (--permission-mode X, --dangerously-skip-permissions).