Every agent developer has a version of the same story. You hand the model a task. It works for a while. You glance back at your terminal and it's doing the same thing for the twelfth time, or it printed "Done! ✅" and walked away from a project that still doesn't compile. You could prompt your way around it — add more instructions, more examples, more rules. But you've been there. More instructions just give the model more things to misapply.
0.31.0 solves this differently. Not with a better prompt. With an agent control plane.
The Supervisor
The Supervisor is a new out-of-band subsystem that runs beside every session. It never appears in your transcript. It doesn't argue with the model or show up as a message. It watches what the agent is actually doing — the tool calls, the self-reported state, the pattern of turns — and intervenes when something's wrong.
It bundles four checks that used to require you to babysit the session yourself.
Loop detection
The simplest and most common failure mode: the agent calls the same tool with the same arguments over and over. Maybe it's shell(command=cargo build) coming back with the same error message each time. Maybe it's re-reading the same file it's already read three times.
The Supervisor's loop detector runs on every turn, costs nothing (no model call — it's a deterministic check), and fires when the same tool+arguments combination repeats loop_threshold times in a row. Default is 3. When it fires, the Supervisor injects a steering note that re-anchors the agent without you having to interrupt.
Same deal for the no-progress detector. If no_progress_window turns go by without any new information entering the context, the Supervisor treats it as drift. Five turns of spinning in place and it steps in.
Both detectors are zero-cost. They run on every turn as plain pattern matching. The model only gets woken when something's actually wrong.
Self-Report Parsing
The Supervisor now injects a hidden instruction that asks the model to tag every reply with its current state: exploring, progressing, need_input, blocked, or done. That tag appears as a <sup>STATE · reason</sup> token at the end of every response. The Supervisor strips it before you see it and uses the state to gate further model calls without spinning up a second LLM.
What this means in practice: if the agent self-reports need_input and you haven't responded yet, the Supervisor knows not to re-enter the loop. If it's progressing, it knows to stay out of the way. The spinner in your terminal now shows the agent's own description of what it's doing — "editing api", "running tests" — instead of the generic "Working…" it used to show. That text comes straight from the self-report.
The verify-gate
The verify-gate changes how agentic sessions end.
When the model self-reports done, the Supervisor doesn't trust it. It runs an independent verifier against the original request and the session result. The verifier produces either a PASS or a list of specific gaps — things the agent claimed but didn't actually do, or outcomes that don't match what you asked for.
On gaps, the Supervisor injects an advisory and re-enters the loop. The agent continues from there with explicit context about what's still missing. This is bounded by gate.max_iterations (default: 2) so you don't end up in a verification loop forever.
This was built specifically around real failures on DeepSeek, Anthropic, and other providers where the model confidently declares success on partial work. The gate catches the case the model can't catch itself: it doesn't know what it doesn't know.
Orientation memory
The learning system has been folded under the Supervisor in 0.31.0. Learning still works the same way — lessons extracted from your corrections, injected into future sessions so the agent doesn't repeat your mistakes. But alongside lessons, there's now a second memory kind: orientation.
Orientation is durable understanding of the project itself. Structure, decisions, constraints. The things that don't change turn to turn but cost tokens to re-derive every time. On session start, orientation entries are recalled as working assumptions, decaying over orientation.decay_days days of disuse. The agent arrives knowing what it already knows about your project — not blank, not over-stuffed with stale context.
Both learning and orientation run under [supervisor] in your config:
[supervisor]
enabled = true
model = "anthropic:claude-haiku-4-5"
[supervisor.learning]
enabled = true
max_inject = 5
[supervisor.orientation]
enabled = true
decay_days = 90
[supervisor.gate]
enabled = true
max_iterations = 2
[supervisor.detectors]
loop_threshold = 3
no_progress_window = 5The /info command now shows a supervisor_stats block — gate runs, passes, failures, steer counts, distilled lessons. If you're debugging a session where something felt off, start there.
/agents: What Your Sub-Agents Are Actually Doing
If you use tap to delegate work to specialist sub-agents, you've been flying blind. You know something is running. You don't know if it's progressing, spinning, or done. You find out when it delivers its reply — or when it doesn't.
/agents fixes that. Run it mid-session and it lists every tap-launched agent in the current session: role, status (running/done/failed), elapsed time, live token usage, cost so far, and the last tool call it made.
/agentsAdd an agent ID for the detail view:
/agents tap-developer-general-a3f1c2Token and cost figures update live — every tool call from the sub-agent pushes state back to the parent session in real time, so /agents reflects current spend without waiting for the subprocess to finish. When it completes, the data falls back to the on-disk log.
This is the minimum viable visibility you need to run multiple agents in parallel without guesswork. You can see which one is working, which one is stuck, and what it's spending.
tap run also changed defaults in this release: background execution is now true by default. Previously you had to opt in. Most delegations return immediately now; pass background=false explicitly when you need the result inline before the next step.
What Got Fixed
The headline features are the Supervisor and /agents, but three bug fixes in this release were causing real pain.
The infinite-loop-on-OK bug. When the agent ran a check that returned a short result like [OK] No errors, the deduplication logic would elide it on the second run because it matched exactly. The model would see the placeholder, assume something was wrong, and re-run the same command with variations. Indefinitely. Fix: results shorter than 500 characters are now always kept verbatim. Short outputs are usually verdicts — the model needs to see them every time.
The 400 errors from plan compression. When context compression picked a boundary inside a chained tool-calling sequence — an assistant turn with pending tool_calls followed by their results — it left orphaned tool calls without matching results. Anthropic and DeepSeek respond to that with a 400. The new settle_boundary logic advances past those sequences one group at a time. If no safe boundary exists, compression is skipped rather than sending a corrupted message stream.
MCP restart loops. A server that failed startup or exhausted its restart budget used to get recomputed as Dead on the next health-check cycle and retried again. That retry loop filled logs and delayed every session. Now a server that's failed is permanently marked Failed and ignored. Offline servers also no longer leave placeholder tool stubs that the model could call and mistake their errors for semantic failures.
Headless Deployments: SQLite Credentials
OAuth tokens used to live in the system keychain. That worked fine on a laptop. It was a deployment problem everywhere else — headless servers, CI environments, anything that doesn't have a keychain daemon running.
The credential store is now SQLite. keystore.db in the platform data directory, mode 0700 on Unix. No system daemon dependency. Clean shutdown, portable state, and proper isolation in tests (isolated temporary keystores that never touch production).
If you've been working around keychain issues in server or CI deployments, this removes the workaround.
Upgrading
One required step: add the [supervisor] block to your config. The Supervisor won't run without it. Copy the reference section from config-templates/default.toml (lines 659–699) — or regenerate your config with octomind config and merge the new keys in.
Everything else carries forward from 0.30.0 without changes. The tap run background default flip is the only behavior change that might affect existing code; anything that relied on blocking behavior needs an explicit background=false.
The /learning command you already know still works; lessons are now part of the Supervisor subsystem internally, but the interface is unchanged.
0.30.0 built the orchestration above the session. 0.31.0 builds the control plane beside it. The agent still does the work. The Supervisor makes sure it finishes.
Octomind is a session-based AI development assistant built in Rust. Missed the last release? Read about Workflows, Guardrails, and Session Observability in 0.30.0.
