Agent overview

The agent is the core of 4RGE. You describe what you want in natural language; the agent gathers context from your codebase, runs tools, and edits files — pausing for your approval at the moments that matter.

Whether you are fixing a bug locally, refactoring a service, or delegating a long task to a cloud agent, the same agent loop applies: understand the request, take action through mediated tools, and verify the result before you accept changes.

Where agents run

4RGE exposes agents on two surfaces. Both use the same tool broker and approval model, but the environment differs.

On desktop, the agent works against your working tree — the repository you opened in the app or via the CLI. On cloud, it works in a remote sandbox with the network and permissions defined in Cloud agents · Security & network.

The agent loop

1. Understand

   The agent reads the relevant parts of your project — open files, search results, directory structure, and any skills or rules loaded from installed plugins — to build context for your request. It uses repository tools (read, grep, glob) rather than shelling out to cat or find.

2. Act

   It edits files and runs tools (repository, terminal, browser, MCP, and workspace tools), requesting approval before anything sensitive. File writes outside the safe set, dangerous terminal commands, and many MCP calls pause for your confirmation.

3. Verify

   It checks its work — running tests or linters when appropriate — and reports back with a reviewable diff. You accept, refine, or discard the changes before they land in your branch.

For larger tasks, ask the agent to outline an approach before it changes code. See Prompting for patterns that work well.

Context the agent uses

The agent does not see your entire repository at once. It assembles context on demand:

When a task is too large for a single pass, the agent can delegate to a subagent via the task tool. Subagents run autonomously for a bounded number of steps and return a summary — useful for focused research or scoped refactors without cluttering your main conversation.

Approvals and safety

The agent asks before running commands or touching files outside the safe set. You stay in control of what actually executes.

Organization admins can further constrain behavior; see Agent security and Model control.

A typical session

1. Open your project

   Open the repository root (or the monorepo package you are working in) so the agent's scope matches your intent.

2. Describe the outcome

   State what you want done, not just the first step. Include constraints and files to touch. See Prompting.

3. Review diffs and approvals

   Accept file changes and approve commands as they appear. Skim terminal output before approving network or destructive operations.

4. Iterate

   Refine the request if the result is close but not quite right. The agent retains conversation context within the session.

Run statuses and step limits

Cloud agent runs progress through platform-defined statuses: queued, starting, running, waiting_for_input, completed, failed, and cancelled. A run in waiting_for_input is blocked on your approval or a missing secret — common for gated terminal or MCP steps in cloud agents. The shared agent runtime in packages/agents-core caps the main conversation at 50 tool steps (AGENT_STEP_LIMIT); subagents delegated via the task tool get a separate budget of 100 steps and return only a summary to the parent thread.

Getting better results