Nanites

Nanites are background micro-runs: short, budget-bounded child runs that BMO can run in a separate lane from the current foreground conversation. They are useful when a task should be explored, checked, summarized, or handed off without turning the main session into a long blocking run.

A bounded micro-run works beside the foreground session and reports back through the parent workstream.

Maturity: Advanced operator surface. Use nanites after the main workflow model is clear; the Morphogen evidence described below is eval-only and does not change runtime authority.

What problem this solves

Long agent sessions often collect small follow-up tasks: inspect a risky area, summarize a branch, check a workstream, run a quick review pass, or gather supporting context. Running all of that in the main chat creates three problems:

Attention contention: the foreground conversation waits while a side task works.
Budget ambiguity: small background checks can consume the same turn budget as the main task.
Handoff loss: useful side-run results can disappear into chat text instead of becoming workstream state.

A nanite gives those tasks a small child run with its own capacity guard and a clear parent-session handoff.

Use it when

You want a quick bounded review, search, summary, or verification pass while preserving the main session.
The work belongs to the same parent session or workstream but does not need live steering.
You want the result recorded as last_nanite_* on the parent workstream when the parent is workstream-bound.
You need tighter spend or recovery behavior than a general foreground run.

Do not use it when

The task needs active conversation, iterative steering, or approval before each step.
The task may make broad edits without a separate worktree or explicit safety plan.
You need a long-running agent with its own durable plan lifecycle; use staged workflow, recipes, or a normal child agent instead.

How it behaves

Nanites are not just renamed subagents. They run through the same child-run machinery, but reserve capacity from the nanite lane rather than the regular subagent lane. That means a foreground agent can still spawn regular child agents while nanites are capped separately by configuration.

Key distinctions:

Behavior	Nanite	Spawned subagent
Typical entry	`bmo nanite run` / `bmo micro-run run`	`spawn_agent` tool
Capacity guard	`options.nanite_max_threads`	`options.agent_max_threads` and per-agent delegation caps
Default budget	`build_budget_presets.nanite`	`options.subagent_build_budget_preset` or explicit child config
Parent handoff	`workstreams.last_nanite_*` when bound	Child output remains attached to the parent run/session
Best fit	bounded background check	interactive or tool-driven delegation

Quick example

bmo nanite run --session <parent-session-id> "quickly inspect the recent diff for obvious config drift"

Use the same data directory as the TUI when you want the child run to bind to the active parent session:

bmo -D ~/.local/share/bmo nanite run --session <parent-session-id> "summarize the current workstream status"

What you should see

If the parent session is attached to a workstream, bmo workstream show <id> includes the most recent nanite handoff fields after completion:

Field	Meaning
`last_nanite_at`	Completion timestamp
`last_nanite_status`	Terminal child status
`last_nanite_child_session_id`	Child session id
`last_nanite_agent_id`	Child agent id
`last_nanite_excerpt`	Short output or error excerpt

Evaluation evidence

Nanite enqueue is also an evidence surface for BMO’s internal Morphogen signal-fabric evaluation. When workspace stigmergy and mycelial gradient context shape a nanite prompt, BMO records a bounded morphogen.signal_decision annotation in the durable run ledger. Direct CLI, HTTP, and MCP nanite enqueue paths use the same app-owned run-ledger observation path, so bmo eval morphogen can inspect persisted parent and child run evidence after the micro-run.

This evidence loop is not a user-facing control surface and it does not bypass permissions, create goals, block edits, or merge code. The annotation metadata is intentionally compact: the stable key is decision_key, and the record also includes parent session id, child session id, child agent id, decision status, evidence class, and bounded source scope for domain classification. The bounded domain is organism-docs; out-of-domain signals continue to influence ordinary gradient prompt context, but they are counted as disallowed for Morphogen evaluation rather than as successful evidence.

Configuration

[options]
nanite_max_threads = 2
nanite_recovery_fail_fast = true

[build_budget_presets.nanite]
max_turns = 8
timeout_seconds = 300

Set nanite_recovery_fail_fast = true when background micro-runs should avoid cross-provider or local last-resort recovery after same-provider recovery is exhausted. Leave it off when nanites should inherit the normal recovery chain.

Headless and integration surfaces

Surface	Entry point	Notes
CLI	`bmo nanite run`	Main operator surface; `bmo micro-run run` is an alias.
HTTP	`POST /v1/sessions/{id}/nanite`	Enqueues against the parent session id in the path.
MCP	`bmo_nanite_enqueue`	Opt-in exposed tool for coordinator-backed MCP runtime.
Workstream	`bmo workstream show`	Shows `last_nanite_*` handoff when parent is bound.

Safety and limits

A nanite is still an agent run. Tool permissions, workspace policy, and child-agent config still matter.
A foreground cancel does not automatically mean every already-started child did no work; inspect the child session or workstream handoff.
Use worktrees for side tasks that may edit the same files as the parent run.
Treat the excerpt as a compact handoff, not as the full audit log.