> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Long runs and sub-agents

> A run is bounded by the money and time you set, stops cleanly with a reason, and is driven by the plan it writes; sub-agents work in a dock above the prompt, background jobs run as long as they need, and a session keeps working for hours and hundreds of steps.


Give Ocean Code a task that takes the afternoon, and it works the afternoon. What keeps that honest is three things: the bounds you set, the plan the agent writes, and the tideline that keeps its context from growing ([sessions that keep the thread](/ocean-code/tideline)).

## How long it runs

What has been measured: one session of 523 steps over 84 minutes finished 91 of 91 plan rows without a restart; real interactive sessions run past 400 steps in one sitting; pager windows stay open for days; a session reopened days later loads its history in a fraction of a second; the prompt cache is kept warm through waits of up to about 40 hours, so a session you leave overnight picks up without paying for its context again. A run is as long as the work and the bounds allow, not as long as a step counter.

## Bounded, not endless

A run is bounded by the **money and time you set**, not by an arbitrary step count. Set nothing and it keeps going until the work is done or the no-progress guard stops it.

| Bound | `oceancode run` flag | In the pager |
|---|---|---|
| Spend (USD) | `--max-usd 25` (`off`, or `subscription` on a Claude plan) | `/budget 25` |
| Wall clock | `--max-minutes 8h` (`45`, `90m`, `2d`, `off`) | `/limits time 8h` |
| Steps per turn | `--max-steps 100` | `/limits steps 100` |
| Tideline | `--tideline 50%` | `/tideline 50%` |

Reaching a bound is a **clean stop with a reason**, not an error: `budget-exceeded`, `time-exceeded`, `step-limit`. The step cap (300 by default) is a boundary, not a stop: a turn that reaches it continues into a fresh turn on its own. A sub-agent that reaches its own cap hands back its work with `stopped at the step cap; resume to continue`. Every variable and flag is in the [reference](/oceancode/bounding-a-long-run).

## The plan drives the run

The agent keeps its plan as a to-do list, shown in the pager's plan pane. A turn that settles while a row is still open does not end the run: the engine works off the next open rows and goes again. A run ends only when the work settles with nothing open, a bound trips, you interrupt it, or the **no-progress guard** fires, two continued turns in a row that move no row, which stops the run with a "Run stopped" toast.

**Plan mode writes a plan file.** Switch to the `plan` agent (`/plan`, or `Shift+Tab` to Plan) and the model may read, search and send out explore agents but change nothing except one file, `.oceancode/plans/<date>-<topic>-<tag>.md`: the goal, the findings with `file:line` references, the approach, a Mermaid diagram, the to-dos as one block, a check per to-do. When it is ready, the plan opens in the viewer: `a` approves it (its to-dos become the session's list and the `build` agent takes over, checking the findings against the code first), `s` sends it back with your notes, `q` abandons it. The file stays in your project to read, edit or commit. [Reference](/oceancode/plan-mode-and-todos).

**A question holds the rest.** When the agent asks you something, the tool calls after the question in the same response are not run until you answer; a typed answer in your own words reaches the model, and cancelling ends the turn.

## Sub-agents in the dock

Sub-agents, background commands, monitors, loops and queued prompts live in one dock directly above the prompt:

```
▾ Agents 2  ⸬ Working 2m31s                                     1m20s ⇣12k [stop]
 ⸬ Find every caller of resolveWorkflowAccess — Running: rg -n …   1m15s silent · 4 tools · 38k tok · 2m13s
 ✓ Map the picker code paths                                       9 tools · 52k tok · 48s
```

Each row shows the sub-agent's task, what it runs right now, its tool calls, tokens and time, and `Ns silent` once it has sent nothing for ten seconds (amber from a minute: the one to open). `↗` opens a row and shows the sub-agent's live work, its reads, edits, commands and thinking; `[stop]` stops that one sub-agent and nothing else; `Ctrl+G` hides and shows the dock. Row colours mean one thing each: sky blue running, green completed, yellow stopped on purpose, and red only for a failure.

**A waiting turn is not a finished one.** While a background sub-agent still works, a settled turn ends as *waiting* and says on what: `Worked for 6m38s · waiting for sub-agent "Build the mock" · 2 plan rows open · continues when it lands`. When the sub-agent lands, the engine starts the next turn itself and the pager draws it as it runs. A sub-agent that fails still reports, and the run goes on; one you stop does not restart the run; if the engine quit while a sub-agent worked, the next open of the session reports it and continues. A message to a finished sub-agent re-runs it in its own row.

## Background jobs have no clock of their own

A job the agent starts, a `bash` command in the background, a `monitor`, a `loop`, a `scheduler`, runs until it ends or the agent kills it; without a wall clock on the run, a build, a watch or a server runs for hours or days. A job that ends on its own reports back as a message to the session and a new turn starts, so the agent does not sleep and poll to learn a job finished. Polling is not treated as a loop either: the doom-loop guard trips only on three identical fast calls with identical results, and a poll whose output moved, or that took 30 seconds or more, resets it.

## What the agent gets right on its own

- A provider refusal (`stop_reason: refusal`) shows as a failed turn, is never retried, and the work-off does not loop into it.
- An overload reported mid-answer (Anthropic `overloaded_error`, OpenAI `server_error`, Gemini `UNAVAILABLE`) is retried with backoff on every provider; the turn reads `… — retrying`.
- A tool call cut off at the output limit is answered, not retried: the calls that parsed run, the cut-off one is told it was not executed, and the turn goes on.
- `cat`, `head`, `tail` and `sed -n` through `bash` are served by `read` in the same step; `grep -r` is rewritten to ripgrep. No refusal round-trip.
- Pasted screenshots are fitted once to the exact size the model reads, so an image can never lock a session.

## Next

- [Work modes](/ocean-code/work-modes): the shape the sub-agents take.
- [Away from the Mac](/ocean-code/slack): what a long run posts while you are elsewhere.
- Reference: [Bounding a long run](/oceancode/bounding-a-long-run), [Plan mode and todos](/oceancode/plan-mode-and-todos), [Ocean pager](/oceancode/pager).