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

# One Agent loop mode

> A bounded agentic run on one-agent. The loop command, the tool fence, the mission keys, sessions, approvals and the ways a run stops.


Loop mode is a bounded agentic run: the model calls tools inside a fence, reads the results and goes again until it calls `task_complete` or a cap stops it. It is what a `type: harness` task with `agent: one-agent` runs, and it is what every [bot](/bots/overview) runs.

## Start a loop

A task loops when it carries a loop command: `max_turns` or `max_iterations` of 1 or more, or `type: harness`. Over REST that is a workflow on the workflows plane. This run is capped at 2 iterations and injects one skill:

```bash
curl -s https://api.plungeai.com/v1/workflows/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"workflow":{"name":"cap-demo","tasks":[{"type":"harness","id":"h1","agent":"one-agent","goal":"Reply with the single word pong, then call task_complete.","mission":"You are a terse assistant. Answer in one word.","allowed_tools":["task_complete"],"max_iterations":2,"skills":["report"]}]}}'
```

Over MCP, `plungeai_run_mission` takes a `goal`, an optional `mission`, `allowed_tools`, `max_iterations` (1 to 50), `success_criteria`, `persona` and `skills`; it runs on `one-agent` and answers async by default. Unlike a harness task, it has its own defaults: `allowed_tools` is `web_search`, `web_fetch` and `task_complete`, and `max_iterations` is 8.

## The task keys

Write them flat on the harness task. The engine folds them into the mission and forwards the bot keys as written.

| Key | Meaning |
|---|---|
| `goal` or `prompt` | What the run is for. |
| `mission` | The run's purpose text. A whitespace-free string is read as the id of a pre-built agent card instead. A custom `mission` replaces the harness's own system prompt, so keep an instruction to call `task_complete`. |
| `allowed_tools` | The fence. Fail-closed: a tool not listed never runs. Without it, a task on `agent: one-agent` has [every tool in the runtime](/one-agent/tools#without-allowed_tools). |
| `max_iterations` (alias `max_turns`) | The turn cap. `effort` (`quick`, `standard`, `deep`) sets a default cap when no number is given. |
| `success_criteria` | Added to the system prompt and self-checked by the agent; there is no separate verifier. |
| `skills`, `experts`, `persona`, `backgrounds`, `plugins`, `mcp` | Capabilities injected into the run. |
| `model`, `provider`, `effort`, `max_tokens` | Model choice. `effort` reaches the provider as `reasoning_effort` only when the caller set it. |
| `allowed_agents`, `denied_agents` | Which platform agents `call_agent` may reach. |
| `permissions`, `permission_locks` | Allow, ask or deny per tool or class. See [Policy and review](/one-agent/policy-and-review). |
| `budget_usd_run` | Per-run spend cap in USD. |
| `peers`, `posture`, `review`, `max_runtime_s`, `workspace` | The always-on bot keys. See the [playbook reference](/bots/playbook-reference). |

## Sessions and pauses

- A run that needs a person pauses. `ask_user` pauses on a question and a gated tool call pauses on an approval. Answer with `POST /v1/executions/{id}/continue` or MCP `plungeai_continue`.
- A running loop can be steered: `POST /v1/executions/{id}/steer` queues a message the loop reads at its next turn. A finished run answers `409`.
- A continue (`session_id` plus a new `prompt`) resumes the session in loop mode, with its stored state.
- Long runs continue in legs of about ten minutes. What must survive a leg or a continue (the denial streak, handed-off calls, the run's taint) rides the session.

## How a run stops

| Stop | Cause |
|---|---|
| `task_complete` | The model called it with the result. |
| Turn cap | `max_iterations` reached. |
| `stop_reason: budget` | The running token cost passed `budget_usd_run`. |
| `stop_reason: timeout` | `max_runtime_s` elapsed, checked between turns. The run does not yield or resume. |
| `stop_reason: denied` | Three denied tool calls in a row on an unattended run. An interactive run pauses on a question instead. |
| `stop_reason: review` | The reviewer denied three calls in a row. |
| Cancel | `POST /v1/executions/{id}/cancel`. It also cancels the child runs the loop started. |

A loop on a provider that cannot return tool calls is refused with `outcome: needs_input` before it starts.

## Sub-agents and files

- `delegate` runs focused sub-agents in parallel, each with only the tools you grant it. A child with no `agent` or `mission_ref` runs on `one-agent`.
- The file tools (`read_file`, `write_file`, `edit_file`, `list_files`, `search_files`, `delete_file`) work on a virtual workspace. `workspace: run` starts it clean each run; `workspace: bot` keeps it across runs. See [Workspace and inbox](/bots/workspace-and-inbox).
- `recall` and `recall_history` search your own past runs; `memory` keeps durable facts. See [Tools](/one-agent/tools).