Operating mode parity

When options.operating_packs is true, the coordinator keeps a per-session active pack (name, optional preset id, manifest path) plus a metadata-only lifecycle posture. The native tool get_operating_mode, GET /v1/session-operating-mode, and MCP bmo_get_operating_mode return the same JSON object for a given session_id. They may hydrate the session’s persisted pack ref, but the response never includes prompt preambles, hook command bodies, raw policies, or secrets.

When options.operating_packs is false the wire surfaces fail closed rather than emitting a posture envelope: HTTP returns 404 with a plain-text error, MCP bmo_get_operating_mode returns a tool error response, and the native get_operating_mode tool is not registered. The disabled posture state is observable only via bmo config show-operating-mode --json, which reads effective config locally and is the supported operator path for inspecting the gate without a running session.

Canonical JSON fields

Field	Meaning
session_id	Session the snapshot refers to.
enabled	Whether options.operating_packs is enabled in effective config.
state	Lifecycle posture: enabled_inactive, active, validation_failed, persistence_unavailable, hydration_failed, disabled, mutation_unavailable, or unavailable. The disabled and unavailable states are emitted only by bmo config show-operating-mode --json; the wire surfaces (HTTP GET /v1/session-operating-mode, MCP bmo_get_operating_mode, native get_operating_mode) fail closed instead of returning these states (see opening section).
active_operating_pack	Pack name when one is active; empty string when none.
operating_mode_preset_id	Key from options.operating_mode_presets when activation used a preset; empty when activated by path/name only.
pack_manifest_path	Resolved manifest path when known; omitted when empty.
last_action	Last lifecycle action such as activate, clear, or hydrate, when known.
unavailable_reason	Redacted reason for disabled, unavailable, validation, persistence, or hydrate failure states.
diagnostics	Redacted validation diagnostics (section, field, level, message) when validation blocks activation or hydration.
last_evidence_at	UTC timestamp for the last recorded lifecycle evidence.
skills, hook_count, policy_rules, task_rules, skill_rules, choreography, has_prompt_preamble	Metadata-only active-pack summary. has_prompt_preamble is a boolean; the preamble text is not serialized.

These names match prompt-trace keys for operating pack metadata (active_operating_pack, operating_mode_preset_id).

Example (active pack):

{
  "session_id": "sess-123",
  "enabled": true,
  "state": "active",
  "active_operating_pack": "cautious",
  "operating_mode_preset_id": "cautious-preset",
  "pack_manifest_path": "optional/path/to/pack.toml",
  "last_action": "hydrate",
  "hook_count": 2,
  "has_prompt_preamble": true
}

For local operator visibility outside an active session, bmo config show-operating-mode prints the feature gate, discovery counts, preset IDs, and inactive/disabled posture. Use --json for machine-readable output: the top-level object contains posture plus discovery metadata fields such as available_packs, pack_names, and preset_ids. Use --session-id to include the session id inside posture.

Native agent tool

• get_operating_mode — Read-only; optional session_id in params, otherwise the current tool context session.

HTTP (bmo serve)

All routes below use Bearer auth (same style as other parity routes). 404 when operating packs are disabled in config. 503 when the app or coordinator is not ready, or the coordinator does not implement the required parity interface.

Read snapshot

• GET /v1/session-operating-mode?session_id=<id> — Same JSON object as get_operating_mode / MCP bmo_get_operating_mode.
• session_id is required (query parameter).
• 400 when session_id is missing or parity serialization fails (for example invalid state).

Mutations (same path as native tools)

• POST /v1/session-operating-mode — JSON body: session_id (required), pack_path_or_name (required). Same semantics as session_set_pack. 200 JSON: status: "activated", session_id, pack_name (the requested path or name).
• DELETE /v1/session-operating-mode?session_id=<id> — Same semantics as session_clear_pack. 200 JSON: status: "cleared", session_id.
• 400 when required fields are missing, JSON is invalid, or activation fails (for example validation error).
• 503 when the coordinator does not expose SessionOperatingPackMutationProvider (production bmo serve coordinators do).

The TUI /pack picker uses the same coordinator pack controller as these routes and the Fantasy tools.

MCP (bmo serve-mcp)

• bmo_get_operating_mode — Optional session_id; when omitted, uses the MCP-bound BMO session.
• Listed explicitly in options.mcp_server.exposed_tools (like bmo_get_adaptive_orchestration and workspace snapshot tools).
• Startup validation fails with a clear error if the tool is listed but options.operating_packs is false, there is no coordinator, or the coordinator does not support operating-mode parity.

Related documentation

• Technical reference: operating-pack design notes live with the internal topic index.
• How BMO thinks and acts — the broader regulation and runtime mental model
• Tools reference — get_operating_mode, session_set_pack, session_clear_pack