CLI Agent Loop

This document explains how the Roo Code CLI detects and tracks the agent loop state.

Overview

The CLI needs to know when the agent is:

Running (actively processing)
Streaming (receiving content from the API)
Waiting for input (needs user approval or answer)
Idle (task completed or failed)

This is accomplished by analyzing the messages the extension sends to the client.

The Message Model

All agent activity is communicated through ClineMessages - a stream of timestamped messages that represent everything the agent does.

Message Structure

typescript

interface ClineMessage {
	ts: number // Unique timestamp identifier
	type: "ask" | "say" // Message category
	ask?: ClineAsk // Specific ask type (when type="ask")
	say?: ClineSay // Specific say type (when type="say")
	text?: string // Message content
	partial?: boolean // Is this message still streaming?
}

Two Types of Messages

Type	Purpose	Blocks Agent?
say	Informational - agent is telling you something	No
ask	Interactive - agent needs something from you	Usually yes

The Key Insight

The agent loop stops whenever the last message is an ask type (with partial: false).

The specific ask value tells you exactly what the agent needs.

Ask Categories

The CLI categorizes asks into four groups:

1. Interactive Asks → `WAITING_FOR_INPUT` state

These require user action to continue:

Ask Type	What It Means	Required Response
`tool`	Wants to edit/create/delete files	Approve or Reject
`command`	Wants to run a terminal command	Approve or Reject
`followup`	Asking a question	Text answer
`browser_action_launch`	Wants to use the browser	Approve or Reject
`use_mcp_server`	Wants to use an MCP server	Approve or Reject

2. Idle Asks → `IDLE` state

These indicate the task has stopped:

Ask Type	What It Means	Response Options
`completion_result`	Task completed successfully	New task or feedback
`api_req_failed`	API request failed	Retry or new task
`mistake_limit_reached`	Too many errors	Continue anyway or new task
`auto_approval_max_req_reached`	Auto-approval limit hit	Continue manually or stop
`resume_completed_task`	Viewing completed task	New task

3. Resumable Asks → `RESUMABLE` state

Ask Type	What It Means	Response Options
`resume_task`	Task paused mid-execution	Resume or abandon

4. Non-Blocking Asks → `RUNNING` state

Ask Type	What It Means	Response Options
`command_output`	Command is running	Continue or abort

Streaming Detection

The agent is streaming when:

partial: true on the last message, OR
An api_req_started message exists with cost: undefined in its text field

typescript

// Streaming detection pseudocode
function isStreaming(messages) {
	const lastMessage = messages.at(-1)

	// Check partial flag (primary indicator)
	if (lastMessage?.partial === true) {
		return true
	}

	// Check for in-progress API request
	const apiReq = messages.findLast((m) => m.say === "api_req_started")
	if (apiReq?.text) {
		const data = JSON.parse(apiReq.text)
		if (data.cost === undefined) {
			return true // API request not yet complete
		}
	}

	return false
}

State Machine

                    ┌─────────────────┐
                    │    NO_TASK      │  (no messages)
                    └────────┬────────┘
                             │ newTask
                             ▼
              ┌─────────────────────────────┐
         ┌───▶│         RUNNING             │◀───┐
         │    └──────────┬──────────────────┘    │
         │               │                       │
         │    ┌──────────┼──────────────┐        │
         │    │          │              │        │
         │    ▼          ▼              ▼        │
         │ ┌──────┐  ┌─────────┐  ┌──────────┐   │
         │ │STREAM│  │WAITING_ │  │   IDLE   │   │
         │ │ ING  │  │FOR_INPUT│  │          │   │
         │ └──┬───┘  └────┬────┘  └────┬─────┘   │
         │    │           │            │         │
         │    │ done      │ approved   │ newTask │
         └────┴───────────┴────────────┘         │
                                                 │
         ┌──────────────┐                        │
         │  RESUMABLE   │────────────────────────┘
         └──────────────┘  resumed

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        ExtensionHost                            │
│                                                                 │
│  ┌──────────────────┐                                           │
│  │   Extension      │──── extensionWebviewMessage ─────┐        │
│  │   (Task.ts)      │                                  │        │
│  └──────────────────┘                                  │        │
│                                                        ▼        │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    ExtensionClient                        │  │
│  │                (Single Source of Truth)                   │  │
│  │                                                           │  │
│  │  ┌─────────────────┐    ┌────────────────────┐            │  │
│  │  │ MessageProcessor │───▶│    StateStore     │            │  │
│  │  │                 │    │  (clineMessages)   │            │  │
│  │  └─────────────────┘    └────────┬───────────┘            │  │
│  │                                  │                        │  │
│  │                                  ▼                        │  │
│  │                         detectAgentState()                │  │
│  │                                  │                        │  │
│  │                                  ▼                        │  │
│  │  Events: stateChange, message, waitingForInput, etc.      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                           │                                     │
│                           ▼                                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │ OutputManager  │  │  AskDispatcher │  │ PromptManager  │     │
│  │  (stdout)      │  │  (ask routing) │  │  (user input)  │     │
│  └────────────────┘  └────────────────┘  └────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

Component Responsibilities

ExtensionClient

The single source of truth for agent state, including the current mode. It:

Receives all messages from the extension
Stores them in the StateStore
Tracks the current mode from state messages
Computes the current state via detectAgentState()
Emits events when state changes (including mode changes)

typescript

const client = new ExtensionClient({
	sendMessage: (msg) => extensionHost.sendToExtension(msg),
	debug: true, // Writes to ~/.roo/cli-debug.log
})

// Query state at any time
const state = client.getAgentState()
if (state.isWaitingForInput) {
	console.log(`Agent needs: ${state.currentAsk}`)
}

// Query current mode
const mode = client.getCurrentMode()
console.log(`Current mode: ${mode}`) // e.g., "code", "architect", "ask"

// Subscribe to events
client.on("waitingForInput", (event) => {
	console.log(`Waiting for: ${event.ask}`)
})

// Subscribe to mode changes
client.on("modeChanged", (event) => {
	console.log(`Mode changed: ${event.previousMode} -> ${event.currentMode}`)
})

StateStore

Holds the clineMessages array, computed state, and current mode:

typescript

interface StoreState {
	messages: ClineMessage[] // The raw message array
	agentState: AgentStateInfo // Computed state
	isInitialized: boolean // Have we received any state?
	currentMode: string | undefined // Current mode (e.g., "code", "architect")
}

MessageProcessor

Handles incoming messages from the extension:

"state" messages → Update clineMessages array and track mode
"messageUpdated" messages → Update single message in array
Emits events for state transitions and mode changes

AskDispatcher

Routes asks to appropriate handlers:

Uses type guards: isIdleAsk(), isInteractiveAsk(), etc.
Coordinates between OutputManager and PromptManager
By default, the CLI auto-approves tool/command/browser/MCP actions
In --require-approval mode, those actions prompt for manual approval

OutputManager

Handles all CLI output:

Streams partial content with delta computation
Tracks what's been displayed to avoid duplicates
Writes directly to process.stdout (bypasses quiet mode)

PromptManager

Handles user input:

Yes/no prompts
Text input prompts
Timed prompts with auto-defaults

Response Messages

When the agent is waiting, send these responses:

typescript

// Approve an action (tool, command, browser, MCP)
client.sendMessage({
	type: "askResponse",
	askResponse: "yesButtonClicked",
})

// Reject an action
client.sendMessage({
	type: "askResponse",
	askResponse: "noButtonClicked",
})

// Answer a question
client.sendMessage({
	type: "askResponse",
	askResponse: "messageResponse",
	text: "My answer here",
})

// Start a new task
client.sendMessage({
	type: "newTask",
	text: "Build a web app",
})

// Cancel current task
client.sendMessage({
	type: "cancelTask",
})

Type Guards

The CLI uses type guards from @roo-code/types for categorization:

typescript

import { isIdleAsk, isInteractiveAsk, isResumableAsk, isNonBlockingAsk } from "@roo-code/types"

const ask = message.ask
if (isInteractiveAsk(ask)) {
	// Needs approval: tool, command, followup, etc.
} else if (isIdleAsk(ask)) {
	// Task stopped: completion_result, api_req_failed, etc.
} else if (isResumableAsk(ask)) {
	// Task paused: resume_task
} else if (isNonBlockingAsk(ask)) {
	// Command running: command_output
}

Debug Logging

Enable with -d flag. Logs go to ~/.roo/cli-debug.log:

bash

roo -d -P "Build something" --no-tui

View logs:

bash

tail -f ~/.roo/cli-debug.log

Example output:

[MessageProcessor] State update: {
  "messageCount": 5,
  "lastMessage": {
    "msgType": "ask:completion_result"
  },
  "stateTransition": "running → idle",
  "currentAsk": "completion_result",
  "isWaitingForInput": true
}
[MessageProcessor] EMIT waitingForInput: { "ask": "completion_result" }
[MessageProcessor] EMIT taskCompleted: { "success": true }

Summary

Agent communicates via ClineMessage stream
Last message determines state
ask messages (non-partial) block the agent
Ask category determines required action
partial: true or api_req_started without cost = streaming
ExtensionClient is the single source of truth

CLI Agent Loop

CLI Agent Loop

Overview

The Message Model

Message Structure

Two Types of Messages

The Key Insight

Ask Categories

1. Interactive Asks → WAITING_FOR_INPUT state

2. Idle Asks → IDLE state

3. Resumable Asks → RESUMABLE state

4. Non-Blocking Asks → RUNNING state

Streaming Detection

State Machine

Architecture

Component Responsibilities

ExtensionClient

StateStore

MessageProcessor

AskDispatcher

OutputManager

PromptManager

Response Messages

Type Guards

Debug Logging

Summary

1. Interactive Asks → `WAITING_FOR_INPUT` state

2. Idle Asks → `IDLE` state

3. Resumable Asks → `RESUMABLE` state

4. Non-Blocking Asks → `RUNNING` state