Subtasks & Todo Lists

Large jobs rarely fit one conversation. Nexgile Code gives you two structuring tools that work together: subtasks, where an agent delegates a piece of work to a child task running in another mode, and todo lists, the in-chat checklist every task uses to plan and track its own work items. Subtasks split the work; todos make the progress visible and enforceable.

How subtasks work

Any agent whose task calls for it can use the new_task tool to delegate. You approve the delegation (unless auto-approved — see below), and then:

1. The parent pauses. Its state and conversation are saved, and it steps aside as the delegated parent.
2. The child becomes the active task, running in whatever mode the delegation named — Code, Tester, Doc Gen, a custom mode — with that mode’s tool permissions and its own fresh context.
3. Results return on completion. When the child finishes with attempt_completion, its summary is handed back to the parent as a subtask result, and the parent resumes where it left off.

The approval card shows the target mode, the instruction message, and any starting todos, so you always see what is being spun off before it happens.

Note

The child does not see the parent’s conversation. Everything it needs — file paths, constraints, expected output — must be in the delegation message. When you write your own prompts for the Orchestrator, ask it to include specifics in each delegation.

While a child runs, you can still open the waiting parent (or any ancestor in a deeper chain) — it displays as a read-only view with a note that a sub-task is running; resume the active task to send messages.

The Orchestrator: the subtask conductor

Every mode can delegate, but 🪃 Orchestrator exists for it. It has no tool groups at all — it cannot read files, edit, or run commands. Its vocabulary is delegation (new_task, new_parallel_tasks), the shared bookkeeping tools (update_todo_list, skill), asking you a question, and reporting completion. That makes it the right place to run multi-part work:

You:  Split this into subtasks: (1) add a `slugify` util in src/utils with
      tests, (2) then update the post editor to use it. Delegate each part.
Orchestrator: → new_task(code, "Add slugify(text) to src/utils …")
              → new_task(code, "Update PostEditor to call slugify …")
              → summary of both results

Because it cannot “do the work itself”, the Orchestrator’s chats stay short and cheap — the heavy context lives in the children. This is also the engine behind Workflow Mode, where delegation to implementer, tester, reviewer, and shipper is automated.

Delegating a batch at once

new_task hands off one child. When a parent already knows it needs several — verification split across a tester and a reviewer, say — it can use new_parallel_tasks to declare the whole set in one call, passing an array of {mode, message, todos?} entries.

What you gain is a single approval covering the batch: the card lists every child’s mode and message, so you review the plan as a unit instead of approving handoffs one at a time as they trickle in. Validation is all-or-nothing — if any entry names a mode that doesn’t exist or omits its message, the entire call is rejected and nothing spawns. A batch is capped at five children, which is enough for the verification fan-outs it was built for and low enough that a confused model can’t spawn a swarm.

“Parallel” describes the declaration, not the execution. The siblings are approved together and queued on the parent, but they run one after another: the first child opens immediately and each subsequent one starts as the previous finishes. Control returns to the parent after the last child completes. Nothing runs concurrently, so don’t expect a wall-clock speedup — the benefit is fewer interruptions and a plan you can see whole.

Todo lists

Nexgile Code plans before it acts: the agent records concrete work items with the update_todo_list tool, implements them in order, and updates statuses as it goes. Each item is pending, in_progress, or completed.

The todo display sits in the task header area as a collapsible checklist. Collapsed, it shows the item currently in progress and the completion count; expanded, it lists every item with its status icon and auto-scrolls to the active one. Updating the list is always auto-approved — it is bookkeeping, not an action — so the checklist ticks along without interrupting you.

Two settings turn todos from a convention into a contract (both are VS Code settings, off by default):

Setting	Effect
nexgile-code.newTaskRequireTodos	new_task calls must include a todos parameter (a markdown checklist). Delegations without an explicit work plan are rejected, so every child task starts with a seeded todo list.
nexgile-code.preventCompletionWithOpenTodos	The agent cannot declare a task complete while unfinished todos remain on the list.

Example todos passed to new_task:
- [ ] Add slugify(text) to src/utils/slugify.ts
- [ ] Unit tests: spaces, accents, repeated dashes
- [ ] Export from src/utils/index.ts

Tip

Turn both settings on for delegation-heavy work. Required todos force the parent to think through each child’s scope; blocked completion stops a child from returning “done” with items still open.

Autonomy and auto-approval

Subtask creation is gated by the Approve subtasks toggle (alwaysAllowSubtasks) under Auto-Approve. And because auto-approve toggles are global, a child task runs with the same autonomy as its parent — if the parent auto-approves reads and writes, so do its children. Under Workflow Mode, chain delegations are approved automatically even without this toggle.

Caution

Autonomy inheritance multiplies. A parent allowed to delegate and write can create children that also delegate and write. Keep the cost and request caps (allowedMaxCost, allowedMaxRequests) configured, and review the Human-in-the-Loop Playbook before running long unattended chains.

Queueing messages while the agent works

You do not have to wait for a running task to finish before typing. Messages sent while the agent is busy are held in a Queued Messages list shown above the input box. Each queued message can be edited in place (click it) or removed (trash icon) until it is delivered, and queued images are kept with it. The queue drains automatically when the agent is ready for your input — so you can line up “also update the changelog” without interrupting the current step.

Chains in Task History

Task History understands parent–child structure:

• Chains are grouped under the root task, with an expandable “subtasks” row showing the count — expand it to see every child, each tagged as a subtask.
• Searching history shows matching child tasks in a flat list with their subtask relationship indicated.
• Deleting a parent removes its children too; the confirmation dialog tells you how many subtasks are included.

For live chains, the delegation blocks in the parent’s chat offer Go to Subtask links and inline child traces — see Workflow Mode for the full inspection UI.

When to reach for subtasks

• Context hygiene: a huge migration read 40 files into context? Delegate the next independent piece to a fresh child instead of condensing.
• Mode fit: implementation in Code, verification in Tester, documentation in Doc Gen — each child gets exactly the permissions its job needs.
• Supervision: you review one delegation card per work package instead of a hundred interleaved tool calls.

For small tasks, skip the ceremony — a single Code-mode task with a good todo list is faster than orchestration.

Related

• Workflow Mode
• Using Modes
• Auto-Approving Actions
• Context Management