One Agent loop mode

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 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:

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.
`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.
`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.

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.
recall and recall_history search your own past runs; memory keeps durable facts. See Tools.