Adaptive orchestration

Adaptive orchestration is a default-on layer that lets BMO reshape how a session is coordinated without changing the underlying task you asked for. It is about coordination intent: choreography preset, topology, conflict strategy, isolation, coordinator style, edit-tool preference, and the opt-in model gene.

It is separate from Adaptive Context, which changes which context gets injected into a turn. Adaptive orchestration changes the set of coordination settings — preset, topology, isolation, style, edit-tool preference, and model slot hints — that shape how a run is coordinated. BMO calls this combined settings bundle the coordination genome.

flowchart LR
    config["Config baseline"] --> merge["Merge effective coordination genome"]
    classifier["Goal classifier"] --> merge
    overlay["Monitor overlay from previous finalized run"] --> merge
    merge --> run["Current root run"]
    run --> trace["Prompt trace + status summary"]
    run --> monitor["Monitor evaluates finalized run"]
    monitor --> next["Next-run overlay patch"]
    classifier:::manual
    next:::unknown
    classDef manual stroke-dasharray:6 3
    classDef unknown stroke-dasharray:2 2,opacity:0.85

When to use it

Use adaptive orchestration when you want BMO to choose better coordination shapes for different kinds of work, for example:

• staying lightweight for simple edits
• shifting toward more structured coordination for broader tasks
• reacting to token pressure or other monitor signals between root runs
• downgrading from an expensive planning model to the small model slot after a task shifts into mechanical implementation, when the model gene is enabled

Enable and merge order

Adaptive orchestration is enabled when the config section or enabled field is omitted. Set enabled = false in bmo.toml or another merged config layer to disable it. See Configuration for the full field reference.

[options.adaptive_orchestration]
enabled = true

[options.adaptive_orchestration.default]
choreography_preset = "modal"
# topology, conflict_strategy, isolation, coordinator_style,
# edit_tool_preference, and model optional

[options.adaptive_orchestration.classifier]
mode = "heuristic" # default; "llm" enables one bounded classifier call per session

[options.adaptive_orchestration.monitor]
# Cumulative run tokens (input+output+cache) before token-pressure reshapes; 0 = off
soft_total_token_budget = 0
# Optional: also evaluate the monitor after every N tool completions in the root run (0 = finalize only)
# monitor_evaluate_every_n_tool_events = 0
# Optional read-only hints (arena friction, eval-shadow aggregates); see monitor topic doc
# hints_arena_enabled = false
# hints_eval_shadow_enabled = false

[options.adaptive_orchestration.model_gene]
# Opt-in: monitor may set model = "small" after planning turns become mechanical.
enabled = false

How it works

• The config baseline provides the default coordination genome (the starting set of coordination settings).
• The optional classifier contributes a bounded patch based on the task.
• The monitor can reshape the in-memory session overlay after a finalized root run.
• The optional model gene lets the monitor record a next-run model hint, currently a one-way downgrade to the small model slot after a task-complexity drop.
• If a reshape changes choreography preset, BMO applies it at the next root run boundary, not in the middle of a live run. Model-gene changes follow the same next-boundary posture.

By default, the monitor evaluates at run finalization. When monitor_evaluate_every_n_tool_events is positive, the same evaluation can run on a background worker every N tool completions in the root run.

sequenceDiagram
    participant User
    participant Classifier
    participant Shaper
    participant RunCoordinator
    participant Monitor
    participant Overlay as NextRunOverlay

    User->>Classifier: session goal
    Classifier->>Shaper: bounded genome patch
    Shaper->>RunCoordinator: effective coordination genome
    RunCoordinator->>RunCoordinator: root run executes
    Note over RunCoordinator: live run is never mutated mid-flight
    RunCoordinator->>Monitor: finalize run telemetry
    Monitor->>Overlay: schedule overlay patch
    Overlay-->>RunCoordinator: apply at next root run boundary

Observability

You can toggle this feature in the TUI via /settings (or /config) → Advanced → Adaptive orchestration. That toggle writes options.adaptive_orchestration.enabled and applies to new runs immediately.

When enabled, the prompt trace includes an adaptive_orchestration segment with metadata such as effective_genome, classification_source (config_baseline, heuristic, llm, llm_fallback_heuristic, llm_fallback_baseline, …), last_reshape_reason, last_reshape_signal_id, whether the reshaped runtime apply is still pending, and whether the model gene has already applied in the session.

You can view this trace in the TUI by opening the Agent Debugger (/debug or ctrl+p → Debugger), selecting a run, and looking at the prompt event metadata.

The main TUI also shows a compact adaptive orchestration summary in the status bar for the current session, so you can see the effective preset, active model gene, latest reshape hint, and whether the next-run apply is still pending without opening the debugger.

When enabled, you can inspect the live state through:

• bmo config show-adaptive-orchestration for headless effective-config posture and canonical readout surfaces
• get_adaptive_orchestration or bmo_get_adaptive_orchestration for live session parity JSON
• GET /v1/sessions/{id}/adaptive-orchestration for HTTP parity; bound callers reuse the current trusted session
• Agent Debugger prompt metadata
• the status bar summary for the current session
• the parity surfaces documented in Adaptive orchestration parity

All readouts use the same posture vocabulary: disabled, unavailable, enabled-idle, active, pending-apply, applied, degraded, and unknown. Posture evidence is metadata-only and does not expose raw prompts, tool bodies, model responses, or full regulatory digests.

stateDiagram-v2
    [*] --> disabled: feature off
    disabled --> enabledIdle: enabled, no session evidence
    enabledIdle --> active: genome or monitor evidence
    active --> pendingApply: reshape scheduled
    pendingApply --> applied: next boundary apply
    applied --> active: further evaluations
    active --> degraded: bounded failure recorded
    degraded --> active: recovery
    enabledIdle --> unknown: no snapshot
    active --> unknown: evidence missing
    unknown --> enabledIdle: snapshot available

Related: layered regulation and precedence

Adaptive orchestration is only one layer in BMO’s regulation model. Mesh, health follow-ons, workspace observation, and choreography also contribute runtime behavior, but they do not all own the same state.

Start with How BMO thinks and acts if you want the user-facing overview.

For contributors: Deep precedence rules across regulation layers are documented in the repository topic ai-organism-constitution.md.

Related

• Adaptive Context
• Workflow map
• Adaptive orchestration parity

For contributors: Classifier design and monitor signal details are covered in the repository topics adaptive-orchestrator-classifier.md and adaptive-orchestrator-monitor-signals.md.

Live, proof-based visuals

These three panels are not illustrations. Their values are captured verbatim from the surfaces BMO actually exposes and are regenerated and drift-checked by TestAdaptiveOrchestrationProofFixtures (run task docs:capture:adaptive-orchestration), so this page cannot quietly drift from the product. On the web they are interactive; in the PDF/book they show the same captured state statically.

Proof · Real · it ships and is inspectable

Captured verbatim from bmo config show-adaptive-orchestration --json — the same readout you get in the product.

state:                       enabled-idle
classifier_mode:             heuristic
default_choreography_preset: modal
monitor_soft_token_budget:   120000
model_gene_enabled:          true

Session posture — real captured snapshots

enabled-idle active pending-apply applied

enabled-idle adaptive orchestration is enabled but no active genome snapshot is present

active effective adaptive orchestration genome is present

pending-apply monitor_token_pressure

applied monitor_token_pressure

Source: docs/demo/evidence/adaptive-orchestration/status-readout.json + posture-snapshots.json.

Proof · Mechanism · how a run gets shaped

The effective coordination genome is the same MergeSession overlay the coordinator runs: config baseline, then the classifier patch, then the monitor overlay.

← Prev Step 1 / 3 · baseline Next →

1 · Baseline

Config baseline genome (default coordination settings).

choreography_preset=modal topology=single conflict_strategy=first_claim isolation=shared coordinator_style=none edit_tool_preference=balanced

2 · Classifier patch

Heuristic classifier shifts a broad task toward structured coordination.

choreography_preset=plan-execute topology=team_star conflict_strategy=first_claim isolation=shared coordinator_style=central_lead edit_tool_preference=balanced

3 · Monitor overlay

Monitor records an opt-in model downgrade after the task becomes mechanical.

choreography_preset=plan-execute topology=team_star conflict_strategy=first_claim isolation=shared coordinator_style=central_lead edit_tool_preference=balanced model=small

Source: docs/demo/evidence/adaptive-orchestration/prompt-trace-segment.json (merge_trace), built with the real orchadaptive.MergeSession.

Proof · Bounded · never mutates a live run

A monitor reshape is recorded, then waits. The runtime apply lands at the next root-run boundary — it never rewrites a run in flight.

Pending apply at the next run boundary

Live BMO TUI: the /orch advisory inspector (posture block, effective genome snapshot, runtime apply). Pair with the lifecycle track above for pending-apply semantics at the next root-run boundary; a scoped re-shoot with provider usage can land pending-apply in-frame.

active

Effective genome present; run executes.

pending-apply

Reshape recorded for monitor_token_pressure; not yet applied.

next root-run boundary

The live run is never mutated mid-flight.

applied

Effective genome applied at the safe boundary.

States from the posture vocabulary in posture-snapshots.json; adaptive orchestration is an overlay stack, not an unbounded rewrite of the task.