Effort and validation

Why each task carries a workflow, and what its three decisions change about how an agent works the task.

Every task carries a workflow: three decisions that shape how an agent works it.

  • effort: how much reasoning the task needs. A planning agent, usually the strongest model available, sets it when it reads the task, before work starts, so lower-effort work can go to a lower model such as Sonnet, and the task's cost shows what each level costs on each model. It is empty until a planner sets it.

    EffortWhen
    lowThe change and the files are known, and there's no design choice
    mediumThe design is decided, but the implementation is real work
    highThe design is open, or the work crosses services, laws or ADRs

    Each level's queue: search with search_tasks and efforts (for example efforts: ["low"]), or pick the level in the Effort filter in Search.

    Delegation by effort. For every task, the agent's session follows law plan-with-the-strongest-model-delegate-by-effort. It delegates the planning and refining (brief-back, effort, pieces, questions, draft plan), the high-effort pieces and the review of every delegated diff to a separate agent on the model the repository's effort-to-model mapping gives high (the planner), and the low- and medium-effort pieces to subagents on the models the mapping gives them (see Agents and the MCP server). The session only orchestrates: it writes the planner's output to the task, asks its questions, runs the checks once on the integrated change, commits, opens the pull request and moves the task. It records the work plan on the task, with planning as the first item, and each item's result with record_work_item; it uses record_cost only for work outside the plan. The agents it delegates to never write to Sparrow.

  • planningRequiresValidation (off unless you ask):

    • Off: the agent writes its brief-back, asks any questions it has, and finalises its plan itself. It moves the task from Planning or Refining to In Progress when it starts the work, or to Queued when it doesn't. It doesn't start work that depends on an unanswered question. Answering the last open question of a task in Planning or Refining moves it to Queued (ADR-0025).
    • On: the agent writes its brief-back, its draft plan and its questions, and moves the task to Refining. It checks the task every 10 minutes, for up to 24 hours, until every question is answered and the task is in Queued. Answering the last open question moves the task to Queued and accepts the brief-back (ADR-0025); you can also move it yourself or tell the agent, which moves it there. If you move it to Queued with a question unanswered, the agent moves it back to Refining and asks you for the rest. Work starts only once the task is in Queued with every question answered (ADR-0022).
  • reviewRequiresValidation (on unless you ask): when you turn it off, no person reviews the task's pull request. The agent still never merges it. Once every automated check passes, the repository's landing automation, which asks Sparrow itself with the project's machine credential (see Machine credentials), lands it with "Rebase and merge" and deletes its branch (passerines: root ADR-0009). Landing is the only thing this setting changes. Whoever merges a pull request, a person or that automation, the automation then moves the task to Completed once every post-merge workflow run succeeded, or to Blocked when a check or a post-merge run didn't (Sparrow ADR-0026, passerines ADR-0010). A repository without that automation leaves the landing, and moving the task, to you.

An agent creating or changing a task through the MCP server turns planning validation on, or review validation off, only when you explicitly ask it to. You can change all three in the task dialog.