Core Concepts6 min read

How the Agent Works

The agentic loop: context, tools, approvals, completion

When you type a request and press send, Nexgile Code does not answer with a wall of text — it starts a task. A task is a loop: the agent gathers context, records a plan, acts through tools (reading files, editing code, running commands), verifies the result, and formally completes. You sit at the center of that loop, because every consequential action pauses for your approval until you decide otherwise. This page explains each stage so you can predict what the agent will do next — and steer it when you disagree.

The loop at a glance

your request
     │
     ▼
1. Gather context   – read the relevant files, search the codebase
     │
     ▼
2. Plan             – record concrete work items with update_todo_list
     │
     ▼
3. Act via tools    – edit files, run commands (each call approval-gated)
     │        ▲
     │        └── tool results feed the next decision
     ▼
4. Verify           – one quick check that the work is correct
     │
     ▼
5. Complete         – attempt_completion presents the result; the task ends

Stages 3 and 4 repeat as often as needed: after every tool call, the result (file contents, diff outcome, command output, error) is fed back to the model, which decides the next step. The loop only ends at stage 5.

Stage by stage

1. Gather context

The agent starts by reading before it writes. In practice that means read_file on the files your request points at, search_files for regex hunting, list_files for orientation, and — if you have codebase indexing enabled — codebase_search for meaning-based lookup. Anything you attached with @ mentions arrives pre-loaded, so the agent skips straight past this stage for those files.

2. Plan

For any non-trivial task (multiple files, multi-step changes), the agent is required to record its plan with the update_todo_list tool before implementing. The rules it works under are strict:

Todo items are concrete deliverables the user asked for — “create add.py”, “add validation to login()” — never process steps like “Analyze” or “Verify”.
Items are worked in order, with statuses updated live in the chat, so you can watch progress tick by.
Trivial single-step requests (answer a question, run one command) may skip the todo list entirely.

This is core behavior — sometimes called Plan First — not a toggle you can turn off. It is what keeps long tasks from wandering.

3. Act via tools

Every action the agent takes on your system goes through a tool call: a structured, typed request to edit a file, run a command, or query an MCP server. Which tools are even available depends on the active mode — Ask mode has no edit tools at all; Architect can only edit Markdown. Each consequential call pauses and shows you exactly what it wants to do (a diff for edits, the exact command line for commands) with Approve/Deny controls. See How Tools Work for the full mechanics.

4. Verify

After the last work item, the agent runs one quick verification pass — typically re-reading a changed file, running the build, or executing the relevant test — and then stops checking. The system prompt explicitly forbids loops of repeated re-reads and “one more sanity check”, which is why a healthy task ends crisply instead of burning tokens on redundant confirmation.

Separately from the agent’s own pass, Nx IDE can send an automatic post-task follow-up: when the Code Review Gate or Test Runner toggles are on (both are on by default), the product asks the agent — once per task, in the same conversation — to re-review its changes against the original request and run build/tests. See Settings & Feature Flags.

5. Complete

A task ends only when the agent calls attempt_completion, which posts a final summary of what was done. This matters more than it sounds: checking off every todo does not end the task. If the result is wrong or incomplete, reply in the same chat — your feedback re-enters the loop and the agent continues from where it stopped, with all its context intact.

Where the agent’s context comes from

Each request the agent sends to the model is assembled from several layers:

Layer	What it contains
System prompt	The active mode’s persona and instructions, the tool definitions its groups allow, and the Plan First workflow rules.
Rules files	`.nexgilerules` (and `.nexgilerules-<mode>` variants, `.nexgile/rules/` directories) plus `AGENTS.md` — your project conventions, injected into every prompt. See Rules Files & AGENTS.md.
Your message	The request text, with every @ mention expanded — mentioned files arrive formatted like completed file reads.
Environment details	A live snapshot attached to each turn: visible editor files, open tabs (capped, default 20), actively running terminals and their fresh output, recently modified files, current time, running task cost, the current mode and model, and — on the first turn — a workspace file listing (capped, default 200 files).
Diagnostics	After every edit, new errors or warnings that the edit introduced are reported straight back to the agent. The full Problems panel is available on demand via the `@problems` mention.
Conversation history	Prior turns and tool results — automatically condensed when the context window fills past the threshold (default 75%). See Context Management.

Files excluded by .nexgileignore never enter any of these layers.

Approvals: your control surface

The approval prompt is where you supervise the loop. For each gated tool call you can:

Approve — the action runs. For edits the button reads Save after you have reviewed the diff; for commands it reads Run.
Deny — the action is skipped, and the agent receives a structured “the user denied this operation” result. It does not blindly retry; it re-plans.
Deny or approve with feedback — add text alongside your decision (“use the existing helper in utils/date.ts instead”). The feedback lands in the agent’s context as course correction, which is usually more productive than a bare rejection.

When you trust a category of action, you can auto-approve it — reads first, edits and commands only with guardrails in place. Hard caps on per-task cost and request count remain in force either way.

When the agent asks you questions

Instead of guessing, the agent can call ask_followup_question. You’ll see the question in chat along with 2–4 clickable suggested answers — each a complete, ready-to-use reply, so one click resumes the task. Two things worth knowing:

Some suggestions switch modes. A suggestion can carry a target mode — Architect finishing a plan will typically offer “Yes, implement it now” wired to switch into Code mode. Picking it answers the question and changes mode in one step.
Mode switches the agent requests on its own (via switch_mode) always require your approval, unless you have enabled the mode-switch auto-approve toggle.

None of the suggestions fitting is fine — type your own answer instead.

When things go wrong

Failure is part of the loop, and it is handled in-band:

Tool errors (file not found, diff didn’t match, command failed) return as structured error results. The agent reads the error and adjusts — for example, re-reading a file whose content drifted before retrying an edit.
Repeated stumbles trip a breaker. After three consecutive mistakes (the default limit), Nexgile Code stops and asks you for guidance rather than thrashing. Identical repeated tool calls are detected the same way.
Blocked access is explained. Attempts to touch .nexgileignored files come back as explicit access-denied results, so the agent works around them instead of failing mysteriously.
You always have the brakes. Stop the task from the chat at any time, and checkpoints let you roll back any file change the agent made.