How the agent works

What runs when you send a message

1. Your prompt is attached to the current chat session.
2. That session owns one agent engine instance (conversation history + tool registry).
3. A background thread runs the agent loop so the UI stays responsive.
4. The UI receives events for new messages, tool calls, and state (thinking, executing tools, finished, error).

You can start runs in multiple sessions; each engine is independent.

The ReAct loop (reason + act)

After you send a message, the engine roughly does:

1. Build or refresh the system prompt (mode, workspace path, tool list, project rules).
2. Append your message to the conversation (including image attachments as metadata under .lca/attachments/ when you attach screenshots in chat).
3. Optionally compact history when auto-summarize is enabled and the prompt is near the configured context window.
4. Call the LLM with the message list and tool definitions. User turns with images are sent as multimodal content to OpenAI-compatible APIs; tools remain text/JSON only. If output is truncated by Max Output Tokens, the engine may retry with a higher temporary limit before continuing.
5. If the model returns tool calls, run each tool locally and append tool result messages (including JSON with an error field when a tool fails).
6. Repeat until the model answers without tool calls, you cancel, or a step limit is reached (default 20 steps).

Unexpected tool exceptions are caught at the tool boundary, converted to the same error JSON shape, and returned to the model so the loop can continue.

This pattern is often called ReAct: the model reasons in natural language, then acts via tools, then reasons again on the results.

You → system + history → (optional summarize) → LLM → (optional tools) → LLM → … → final reply

What goes into the system prompt

• Workspace mode (Ask / Plan / Agent) — controls which tools are advertised.
• Workspace root — all file paths are resolved relative to this folder.
• Tool guidance — short descriptions and JSON parameter shapes for allowed tools.
• Project rules — combined text from <workspace>/.rules/*.md (see Project rules).

The model only sees tools that are allowed in the current mode.

Modes vs file changes

Plan and Ask still use read/search/git tools to understand the tree.

What you see in the UI

• Assistant messages — model text and (in debugging mode) full tool JSON in chat.
• Activity lines — short Calling … lines when the model invokes a tool (display only; not sent back to the model).
• State — idle, thinking, executing tool, finished, or error; status bar shows step N/M during a run.
• Execution log (Tools & Logs) — per-step trace. Click a row for Execution Detail.
• Step limit — configure Max steps in Settings.
• Tool Errors — failed tools for the session, plus shared tool-errors.log under your user config folder.

With Learn mode enabled, sending a prompt switches to Tools & Logs and follows steps in Execution Detail. The trace is application-recorded activity—not hidden chain-of-thought and not a guaranteed replay export.

Safety and sandboxing

• Reads: inspection tools may use paths outside the workspace when you pass an absolute path or a relative path that leaves the project folder.
• Writes: by default, write tools, plan saves under .plan/, chat image attachments, and shell cwd values must stay inside the workspace root. Enable Allow modify outside the working directory on the chat composer (per session) to permit writes and shell cwd outside the project for that chat only.
• The git tool is read-only (status, diff, log, show).
• Shell runs with a timeout cap; use Agent mode only when you trust the workspace and model.

This is application-level path policy, not an operating-system sandbox.

Learn more

See Agent tools reference for each tool name, what it does, and which modes allow it. For a shorter site summary, see How the agent works on the website.