Loop Sessions

A LoopAgentSession handles an adaptive request when the next tool depends on the latest model decision and tool result.

Execution loop

flowchart TB
  P[Receive a new user prompt and compress old history when needed] --> D[Ask LLMAgent for the next tool decision]
  D --> A{Supervisor approval required?}
  A -->|approved or not required| T[Execute the selected tool and record its result]
  A -->|denied| E[Record the denied or failed step]
  T --> F{Final answer, clarification, or limit reached?}
  E --> F
  F -->|continue| D
  F -->|stop| R[Store the final result and session status]
  classDef session fill:#f5f1ff,stroke:#6657b8,color:#2d246b;
  classDef decision fill:#fff7e8,stroke:#b7791f,color:#633c00;
  classDef outcome fill:#eefbf4,stroke:#28875d,color:#174c38;
  class P,D,T,E session; class A,F decision; class R outcome;

Loop session decision cycle

How the cycle works

Choose the next actionThe session receives the prompt, compresses older history when necessary, and asks LLMAgent to select the next tool and its input.
Approve and executeWhen approval is required, the supervisor permits the tool or records the denial as execution context. An approved tool result is added to session history for the next decision.
Continue or stopThe cycle ends with an answer, clarification, interruption, or a configured step, error, or retry limit. Reserved tools provide explicit final-answer and cannot-complete outcomes.

Session memory

Stored value	Purpose
`history`	Conversation and execution entries used for later planner calls; validated `initialHistory` can seed a new session.
`turns`	Per-prompt turn records, including step and interruption outcomes.
`toolCalls`	Tool invocation records retained across the session.
`toolVars` and `toolVarCounter`	Named intermediate tool values and the counter used to allocate them.
`failedTurns` and `errorCount`	Failure evidence used to stop unsafe repetition and produce a cannot-complete result.
`lastAnswer` and `status`	The externally visible latest answer and lifecycle state.
`options`	Active model, tags, reasoning effort, step/error/retry limits, and history-compression settings.
`tools` and `_userTools`	The active executable surface; `replaceTools()` refreshes it after workspace skill changes.
`systemPrompt` and `baseSystemPrompt`	The stable prompt context, including the current project root.
`supervisor` and approval cache	Approval policy and remembered always-approve decisions.

Continuation and interruption

newPrompt() continues the same object and may update model options for the next turn. getConversationSnapshot() exposes a serializable type, status, last answer, and cloned history to child skill calls. Each prompt owns an abort controller throughout setup and execution. An already-aborted options.signal stops the turn before history compression, preparation, or planning starts. Cancellation during setup or execution resolves the prompt to an interruption message and marks both the session and turn interrupted, without counting a tool error or failed turn.

The signal reaches compression, preparation child sessions, planner and input-interpretation calls, and tool handlers. Cancellation prevents preparation retries and late context injection. Checks after setup, approval, and progress output prevent subsequent work from starting after cancellation. Settled prompts release their external abort listeners even when setup fails, so an old signal cannot cancel a later prompt. A fresh signal or no signal allows a subsequent prompt to reuse the interrupted session and its retained history.

Cancellation is cooperative. A provider, tool, supervisor, or output writer that ignores cancellation or never settles can delay completion; the session does not forcibly terminate it or undo tool side effects. A late tool result cannot replace the interruption with a final success. Callers serialize prompts on one session and own any queue: a queued prompt must retain its signal so cancellation while waiting is observed when it starts.