Planning & Execution¶

When you submit a request to a squad, the planner agent creates a structured plan, you review and approve it, and the squad executes tasks in dependency-respecting waves.

Submitting a Request¶

Open your squad's monitoring dashboard and enter your request in the input field. Describe what you want to achieve in plain language:

"Build a REST API for user management with CRUD endpoints, input validation, and unit tests."

Optionally toggle Auto-approve if you trust the planner to create a good plan without manual review.

Before a Run Starts¶

Before the planner runs, the squad checks that the run can work: the planner and every agent, the workspace, and the container runtime. When the check finds nothing, the request goes straight to the planner. When it finds a problem, the request waits in a Before this run starts card that lists each problem with the agents and the model it concerns, one sentence on the cause, and the fix as a button. The check's own text stays under Details.

A problem that stops the run is shown as an error, and the card offers Check again and Cancel, which puts the request back in the input. When only warnings remain, the card also offers Run anyway. The card checks again by itself after you change an agent's settings or start a model from it.

The same check runs on the server for every way a run starts: a new request, approving a plan, resuming a paused run, and rerunning failed tasks. A problem that stops the run refuses each of them before any work, so a plan that waited while its model was stopped is refused with the same list instead of failing every task. Warnings never refuse a run. A router that does not answer is a warning rather than a refusal, because a router that is restarting would otherwise block a squad that works.

The Planning Phase¶

The planner agent receives your request and generates a plan containing:

• Title — A concise summary of the planned work
• Tasks — Individual units of work, each with:
  • Title and description
  • Assigned agent
  • Dependencies on other tasks
  • Priority level (low, medium, high, critical)

graph LR
    T1[Design API schema] --> T2[Implement endpoints]
    T1 --> T3[Write validation]
    T2 --> T4[Write unit tests]
    T3 --> T4
    T4 --> T5[Code review]

When the Planner Cannot Make a Plan¶

If the planner cannot plan, because the inference router is not running, the planner agent has no model, its reply is cut off at the output limit, it answers without creating any task, or its model call fails, the squad starts nothing. The plan card shows Plan not made with the reason, the setting that fixes it (Open agent settings for the planner's model, or Open Models to run one), and two ways forward: Run anyway runs a fallback plan that gives each agent the whole request, and Cancel run ends the run. This holds with auto-approve on as well, because nobody chose the fallback plan. After you fix the cause, Reject asks the planner for a new plan, which also waits for your approval.

Approving a Plan¶

Unless auto-approve is enabled, the plan is presented for your review in the Plan Approval dialog. You can see:

• The full list of tasks with descriptions
• Agent assignments
• The dependency graph
• Estimated complexity

Click Approve to begin execution, or Reject to discard the plan and optionally provide feedback for the planner to try again.

A plan waits for approval for as long as you leave it: it does not expire, and nothing cancels it on its own. The card says how long it has waited, and after five minutes it adds that the plan does not expire and offers Cancel run. Planning has no time limit of its own either, since a large model can take several minutes per planner call: while the planner works, the chat shows how long it has been at it, and after a minute and a half it says it is still planning and offers Cancel run. When the app cannot read a run's status, the chat shows the error with Try again and Close instead of showing the run as still in progress.

Editing the Plan Before Approving¶

Edit plan turns the task list into an editor. You can retitle a task, rewrite its description, reassign it to another agent of the squad, change its priority, remove it, and add tasks of your own.

A task you add carries an id, shown on the row and derived from the task's title as you type it. Other tasks depend on the task by this id, so the field is editable. An id may hold only ASCII letters, digits and hyphens, may be at most 128 bytes, and may not be index or a Windows device name such as CON: the squad board writes each task as <id>.json beside its own index.json. Leave the field blank to let the server name the task, in which case nothing can depend on it.

Dependencies are picked from the other rows rather than typed, so a task you add can depend on another task you add, in either order. The editor refuses a plan whose ids collide (including two differing only by case) or whose dependencies form a cycle, naming the offending row, and the server applies the same rules when the edited plan arrives.

Wave Execution¶

Once approved, tasks are organized into waves based on their dependencies:

gantt
    title Execution Waves
    dateFormat X
    axisFormat %s

    section Wave 1
    Design API schema     :0, 1
    section Wave 2
    Implement endpoints   :1, 2
    Write validation      :1, 2
    section Wave 3
    Write unit tests      :2, 3
    section Wave 4
    Code review           :3, 4

• Tasks within the same wave execute in parallel
• A wave starts only after all tasks in the previous wave have completed
• If a task fails, dependent tasks in later waves are automatically skipped
• A task that uses all its tool rounds answers from what it has, so the tasks after it still run, but it is marked incomplete and the run ends Partially completed
• A task whose model tries to run a command or code while the squad's command execution is off is refused that call and carries on with files. It is marked Needed to run commands, and the run ends Partially completed: turn on command execution, or run that work in Cowork, a conversation with a folder attached
• A reply cut off at the output token limit, or an empty reply, fails the task instead of counting as its result
• A thinking model, which reasons before it answers, gets half of its context window for its reply instead of a quarter, so the reasoning leaves room for the answer. A reply the limit cuts off while the model is still reasoning is sent once more with as much room as the context window allows and, on a model that runs on this computer, with thinking turned off
• A tool call cut off at the output token limit is not run, and the agent is asked to make it again with less output

What a Task Starts From¶

Each task starts from a context sized to the agent's model, so a model with an 8K to 32K context window can run every task of a long run:

• The agent's system prompt and the task itself.
• The results of the tasks it depends on. Together they take at most a quarter of the model's context window. A longer result arrives with its start and end and a note of how much was left out, and its full text is stored under artifacts/tool-results/ in the workspace, where the agent reads it with the read_tool_result tool.
• A short background: one line for each earlier task of this agent in the same run, and the most recent part of your conversation with the agent in its chat.

Earlier task results of the agent and the rest of its chat history are not sent again. Within a task, each tool round adds the call and its result to the conversation. When the conversation fills about three quarters of the model's window, the oldest rounds are shortened before the next model call: a long result is replaced by a note, and a long argument, such as the content of a file the agent wrote, keeps only its start. The newest round stays whole, and the agent can run a tool again when it needs a result back. The log records when a task's rounds were shortened.

Execution Lifecycle¶

A run whose workspace cannot be written is refused before it starts, with an error naming the path (see Before a Run Starts). A run that gets past that check, because the workspace stopped being writable between the check and the first wave, fails before its first wave instead. Its record cannot be written to the workspace history either, so the Runs tab keeps it in the list with that reason until the app or server restarts.

Monitoring Progress¶

The squad monitoring dashboard shows real-time execution progress:

• Current wave and total wave count
• Task counts — pending, running, completed, failed, skipped
• Per-agent status — which agent is active, idle, or in error state
• Token usage — real-time consumption per agent and total
• Activity feed — chronological log of events (agent started, task completed, memory updated, etc.)
• Live work summary ticker — a compact bar at the bottom of the chat area shows a continuously updated one-line summary of what the planner or active agents are working on. The ticker is visible during the planning and execution phases and can be dismissed with the × button.

Waiting for Backends¶

When continuum-router temporarily has no healthy backend during an in-process agent's model request, the current squad run pauses and displays a warning with the next attempt number, retry limit, and delay. This happens while a local model is loading or reloading. The same model request is tried again after 1, 2, 4, and 8 seconds and then every 15 seconds, for twelve attempts and about two minutes in all. Results from completed tasks remain visible throughout the wait. Container tasks remain single-dispatch because restarting a container could repeat external side effects.

The Resume control is hidden during this automatic pause because it cannot make a backend available or safely bypass the delay. Cancel remains available. If a backend becomes available, the same run resumes automatically. Existing task and execution time limits continue to count during the automatic retries.

If every attempt fails, the run stays paused instead of failing, and its task waits with the request it was sending. The run card shows No backend available with Open Models and Resume, and a notification says the same. Load the model or check its provider, then press Resume: the same request is sent again with a fresh set of retries, and completed tasks are not run again. While the run waits for you, its time limits stop counting, as they do for any pause.

When a Task or Run Fails¶

A failed task, and a task that answered without finishing, is explained on the run card and in the run detail: a title, one sentence on the cause, which setting to change and where, and a button that opens that setting when there is one. The message from the backend stays under Details. The run's summary leads with the first problem rather than the task counts, and the chat message and the notification for a failed run use the same explanation.

Rerunning Failed Tasks¶

A run that ended Failed or Partially completed offers Rerun failed tasks on its card and in the Runs tab. The rerun runs the tasks that failed, were stopped by an emergency stop, never started, or answered without finishing, together with every task that depends on them. Completed tasks keep their results and do not run again, and a task you skipped yourself stays skipped. The rerun is the same run, so its history record is replaced when it ends. With a budget on, token usage keeps adding up across the rerun while the budget's time limit starts again. Only a run the app still holds can rerun: after the app or server restarts, submit the request again.

Cancelling an Execution¶

Click Cancel at any time to stop the current execution. Running tasks are terminated, and pending tasks are marked as cancelled. Completed task results are preserved.

Agent Conversations¶

You can also interact with individual agents directly through Agent Chat:

• Start a conversation with any agent in the squad
• Messages are streamed in real-time
• Conversations are persisted to the workspace
• Per-conversation token usage is tracked

The chat turn runs entirely on the backend, the same way squad task execution and Discussion Room turns do. The agent can use any tools listed in its configuration, within the limits below.

This is useful for ad-hoc questions, debugging an agent's behavior, or providing additional context outside of the normal planning flow.

Tools in the Squad Workspace¶

Every tool that takes a path works inside the squad workspace, in chat, in the Discussion Room, and in a run. That covers reading and writing files (read_file, write_file), listing and searching them (list_files, list_directory, search_files, search_content, diff_files), creating folders and moving or deleting files (create_directory, move_file, delete_file), and reading documents and media (pdf_reader, csv_reader, json_query, image_info, image_to_base64, view_image, and audio_transcribe on the desktop).

• A relative path starts at the workspace root. An absolute path is accepted when it is inside the workspace.
• A path that leaves the workspace is refused with a message naming the relative form to use: an absolute path elsewhere, a .. step, and a link that points outside the workspace. A move checks both ends, and the workspace folder itself cannot be deleted or moved.
• search_content does not follow links, and it skips a file that is also linked from somewhere else.
• read_file returns up to 1,000 lines per call by default; the agent reads further with offset and max_lines, and a partial page ends with a note line that is not part of the file.

MCP Tools¶

An MCP tool turned on in an agent's tools runs in chat, in the Discussion Room, and in a run, on the desktop and on a headless server. It runs the way it does in a single agent run, under the same tool policy, rate limit, and path checks, and every call is recorded in the tool audit log.

• Turning the tool on for the agent is the approval, so there is no prompt for each call. An agent cannot run an MCP tool that is not turned on in its tools, even from a server it has other tools from.
• An MCP tool is not confined to the squad workspace. It acts on whatever its server reaches, whatever the squad's Command execution setting is.
• The tool is offered only while its server is connected.
• An image the tool returns is shown to an agent whose model reads images, in the next model call only. Any other model gets a note that the tool returned an image it cannot read.

Running Commands¶

Command execution, in the squad's ⋯ menu, decides whether the squad's agents run commands and Python code: run_command and run_python, and their older names run_shell and execute_python. It applies to runs, to agent chat, and to the Discussion Room, from the next run or turn.

With Run in the workspace:

• Commands run under the same checks as code execution in a single agent run, with the squad workspace in place of the code execution sandbox folder. The workspace is where a command starts and the boundary it cannot leave: a path argument outside it is refused, and run_python code can open files inside it only.
• run_command runs one command per call. Pipes, redirects, &&, and ; are refused, so building and running a program takes two calls, for example cc main.c -o main and then ./main.
• Choosing it approves every command the squad runs, so there is no prompt for each one. Every call is recorded in the tool audit log.
• An agent runs commands only when run_command or run_python is turned on in its tools.
• On a headless server, run_python needs Python installed on the server.

With Run in a container:

• Each run_command or run_python call starts a new container from the command image and removes it when the command ends. Only the squad workspace is mounted, read-write at /workspace, which is also where the command starts; files the command writes appear in the workspace on this computer.
• run_command runs in bash, so cc main.c -o main && ./main is one call. run_python runs python3 with the code on its input.
• The container has no network unless Network in the container is on. Turn it on for commands such as pip install; with it off, a failed download says why. Packages installed with pip install --user land in /workspace/.local and stay for later commands.
• The container runs as your user (never root), with 2 CPUs, 2 GiB of memory, a process limit on Docker, and the tool's timeout. A run_python call also stops at the Execution timeout in Settings > Tools & extensions > Python sandbox, as it does on this computer. That section's Max memory does not apply in the container, whose 2 GiB is the limit.
• The command image is python:3.14.8-bookworm, published for amd64 and arm64, with bash, Python 3, git, gcc, and make. The setting squad.commandImageTag replaces its tag. The dialog shows which runtime runs the commands and whether the image is there, and Pull image downloads it.
• Docker and Apple Container are supported. Apple Container cannot start a container without a network, so with the network off the commands run on Docker when it is available.
• A run does not start without a runtime or the image: the check before the run says what is missing and offers the pull. Commands never fall back to running on this computer.

The CLI sets it with aigo squad update <squad-id> --command-execution workspace (or off, container) and --container-network on. aigo squad command-container status <squad-id> shows the runtime and the image, and aigo squad command-container pull <squad-id> pulls it. Work that needs more than one command per call runs in a Cowork conversation or a single agent run with a folder attached, under the rules in Where Files and Commands Run and Workspace mode.