Skip to Content
ConfigurationLoop Mode

Loop Mode (loop_mode)

Configures structured “run until done” execution — iterative work with a NAVIGATOR_STATUS block per pass, stagnation detection, and a dual-condition exit gate. Inspired by Ralph’s autonomous loop framework.

Config block

In .agent/.nav-config.json:

{
  "loop_mode": {
    "enabled": false,
    "max_iterations": 5,
    "stagnation_threshold": 3,
    "exit_requires_explicit_signal": true,
    "iteration_approval": "none",
    "never_pause_on_stagnation": false,
    "stagnation_diversify_strategy": "combine"
  }
}

Keys

  • enabled (default false) — Master switch. Loop Mode also activates from natural-language triggers (“run until done”, “keep going until complete”, “iterate until finished”, “loop mode”).
  • max_iterations (default 5, range 1-20) — Hard cap to prevent infinite loops.
  • stagnation_threshold (default 3, range 2-5) — Same-state-hash count before the circuit breaker fires.
  • exit_requires_explicit_signal (default true) — Require an EXIT_SIGNAL: true alongside the heuristic indicators before exiting.
  • iteration_approval (default "none") — When to prompt for accept/reject between iterations: "none" (autonomous), "strict" (every iteration), "periodic" (every Nth, see periodic_interval).
  • never_pause_on_stagnation (default false) — When true, stagnation triggers auto-diversification instead of an AskUserQuestion pause. Required for true overnight runs (autoresearch’s NEVER STOP directive).
  • stagnation_diversify_strategy (default "combine") — Recovery to attempt on stagnation: "combine", "radical", or "reread".

Safety guard: never_pause_on_stagnation: true requires max_iterations to be set explicitly — without a cap an autonomous loop can spin forever on a fundamentally broken task.

Phases

Each task moves through: INIT → RESEARCH → IMPL → VERIFY → COMPLETE.

Every iteration emits a structured status so progress and exit state are visible:

NAVIGATOR_STATUS
==================================================
Phase: VERIFY
Iteration: 3/5
Progress: 75%

Completion Indicators:
  [x] Code committed
  [x] Tests passing
  [ ] Documentation updated
  [ ] Ticket closed

Exit Conditions:
  Heuristics: 2/4 (need 2+)
  EXIT_SIGNAL: false

State Hash: a7b3c9
Stagnation: 1/3
==================================================

(Example output — values vary per run.)

Dual-condition exit gate

Loop Mode exits only when both conditions hold: at least 2 heuristic completion indicators are met, AND an explicit signal is emitted (when exit_requires_explicit_signal is on):

I've completed the implementation. All requirements met.

EXIT_SIGNAL: true

This prevents premature exits when indicators look satisfied but real work remains.

As of v7.0.0, the exit gate is no longer a prose mandate: exit evaluation reuses the exit_gate.evaluate_exit indicator vocabulary and runs on Stop, enforced by the stop_state and stop_completion ops of the hook runtime (off-switches: workflow_state_hook.enabled, stop_completion.continue_enabled).

Autonomous overnight mode

For unattended runs: set iteration_approval: "none", never_pause_on_stagnation: true, and an explicit max_iterations. Stagnation then self-recovers via stagnation_diversify_strategy instead of waiting for you.

Metrics

Iteration counts, stagnation events, and exit conditions are instrumented with OpenTelemetry — run /nav:stats to see your own loop behavior rather than relying on quoted numbers.

Example

"Run until done: add isPrime function with tests"
Theory of MindTask Mode