Approval categories an agent can be granted

Grant approval categories on an agent’s handoff. Each decision must satisfy its grant and the card’s rules. See How permissions work.

Answering an approval

1. Call getApproval. It returns the approval's category, the decisions allowed on it, whether this session holds that category, and a decisionFingerprint.
2. Call respondToApproval with the approval id, a decision, the latest fingerprint and a unique requestId.
3. Everything is checked again immediately before anything is written: the grant, your current limits, the rules for that kind of approval, that the approval is still open, and that the fingerprint is current. A stale fingerprint is refused, so the agent reads the card again.

A response may carry checked answers. Unanswered human questions keep the card open; malformed rows are refused. Answers that change a draft send it back to its author.

Guidance, release-resume and run-recovery decisions commit carried answers with settlement. Plan and acceptance ratifications include the criteria rewrite; refinement and breakdown applications include their approved changes. Research continuation includes the research answers. If any of these settlements fails, its carried answers remain open and its changes remain unapplied. Merge-method and inline effort choices roll back too.

If the dependency-order rule refuses a response, the result is an error with a second block of JSON: pipeline_order_refused and pipelineOrder, the violations with their severity, and the fixes the board offers (hold it back, bring it forward, refine it fast). The approval stays open and nothing is written. On an approve of a refinement or breakdown, send one fix as orderChoice and it lands with the decision. The server checks it against the refusal as it stands now. Autopilot never sends one.

Decisions are approve, sendBack, sendBackToBuild, answerQuestion, recover, recoverInert, disposeFollowUps, resumeRelease and fileFix. The card and grant determine which are allowed.

What each category allows

Headings use Settings names. A rider needs the card’s own category too: changing a plan’s acceptance criteria needs both plan approval and acceptance revision.

Intake and questions (intakeAndQuestions)

A rider for answers. An agent may answer the human questions carried by an eligible approval only when it also holds that approval's own category. On its own it can send guidance on cards that ask for input, clarify a possible duplicate, or continue research. It can also admit a new item into refinement or send the request back. Admitting an item whose card carries a priority proposal needs Backlog prioritization as well when the agent accepts that proposal. Keeping the current priority, the default, needs nothing more. The observed priority choice commits with the approval and its changes; a storage failure leaves the whole decision unapplied. A newer proposal is left for a new decision.

Idea promotion (ideaPromotion)

Approves the exact set of ideas proposed for promotion into intake. It cannot add an idea the proposal did not name. Carried answers, idea moves and the approval commit together. An idea already past Ideas is skipped; a failed settlement leaves the decision unapplied.

Guidance filing (guidanceFiling)

Approves the exact guidance-task proposals still undecided on the card and consumes only the gaps they name. Task filing, gap consumption, carried answers and the approval commit together. A failed settlement leaves the whole application unapplied.

Run recovery (runRecovery)

Releases a task parked after a failed or timed-out run with one of the platform's own recoveries: a plain retry, a retry that first saves uncommitted work, or a retry with a larger memory allowance. The allowance is clamped to what the sandbox can give. Discarding work is not available. A separate decision, recoverInert, releases a task that stopped moving (the "This task stopped moving" card) with a plain retry, and only when nothing the scheduler checks still holds the task. If something does, the response is refused and names it. It applies to that card and no other. The category can also send guidance back to the seat that is resting on an exhausted or blocked build, which re-runs that seat. It does not start a coding round and it does not ratify anything. On the card for a change review that broke the same review rule on two runs, an agent can only send the review back with guidance. Withdrawing the change request stays with a person.

Build dispatch (buildDispatch)

Starts one fresh implementation round from a build that ran out of rounds, with required guidance. It answers the card and starts the round together. A plain send back would only re-run the review or QA seat on the existing code. The category does not waive objections or ship work. If recent rounds left the branch on the same commit, the request is refused for every agent, so an agent cannot keep restarting a build that provably changes nothing. A handoff created before this category existed does not include it. Create a new handoff to add it.

Follow-up filing (followupFiling)

Applies the card’s prepared file, decline and merge rulings. disposeFollowUps also accepts per-row revisions and choices; omitted rows stay pending. Unknown, settled or repeated rows, and filing overrides on a decline or merge, refuse the whole response. Filing, dependencies, carried answers and card settlement save together; a failure changes none of them. Cleanup must finish first. Editing the card’s own text remains yours.

Plan approval (planRatification)

Approves or sends back an implementation plan that has no riders. A plan that carries an acceptance change also needs Acceptance revision.

Definition approval (definitionRatification)

Approves or sends back a refined task definition. When refinement found that the task's child tasks already carry all of its work, approving moves it to Parents, where it closes once they finish; if none of them is still open by then, it goes where any other refined task would. A refinement that carries a title or description revision, a relationship change or a repository change also needs the matching rider below. Accepting a priority proposal that the refinement carries needs Backlog prioritization too.

Breakdown approval (breakdownRatification)

Approves the proposed decomposition or sends it back. Children, dependencies, carried answers and settlement commit together or remain unapplied. Retries preserve later edge removals.

Complete reviews of existing children are operator-only. They can revise scope and relationships or close obsolete children as superseded, preserving history. Revised tasks return to Refining. Cards show before/after evidence and replacement dependencies. Changed evidence needs a fresh review; active runs and change requests must settle. Retries preserve later edits.

First breakdowns over the tree limit or with pieces at or below the minimum size need the operator. Descendant splits exceeding the live tree limit hold the tree and leave the card open, creating no children and answering no questions.

Definition revision (definitionRevision)

A rider. Applies the exact title or description revision that a refinement approval carries.

Acceptance revision (acceptanceRevision)

A rider. Applies the exact acceptance criteria proposals carried by a planning, build or QA approval.

Relationship changes (relationshipChange)

A rider. Applies the exact parent and dependency proposals carried by a refinement approval.

Repository assignment (repositoryAssignment)

A rider. Applies the registered repository that a refinement proposed.

Backlog prioritization (backlogPrioritization)

Applies a priority-only backlog proposal exactly as grooming produced it. Priority changes, carried answers and approval settlement commit together; a storage failure leaves them unapplied. Targets outside the approval’s workspace stay untouched. It is also a rider: an agent that accepts a priority proposal carried by an intake admission or a refinement approval needs this category next to the card's own.

Sprint commitment (sprintCommitment)

Applies an exact, complete sprint plan without editing its placements. Placements, accepted dependencies, carried answers and the approval commit together. If settlement fails, those changes remain unapplied.

Merge and release (mergeAndRelease)

Covers the last steps of delivery:

• Ratifies a merge, and re-ratifies a merge that was refused. Carried answers commit with that decision; a failed settlement leaves them unanswered.
• On a merge refused for a conflict, can send the work back to build. The conflict must still exist right now, so ampm reads the pull request again and refuses unless it is currently conflicted. The guidance is required, and the round is a narrow rebase.
• Approves a release. A release approval files and declines no follow-ups, so pending rows stay pending and are decided on their own card afterward.
• Continues a staged rollout, and answers a question a paused release asked, using resumeRelease with required guidance.
• A send-back commits its answers, approval and move after the live PR check. It can recover an interrupted move only for the same answer; another actor’s answer prevents it.
• Refuses to act while a run for the task is live.

Duplicate closure (duplicateClosure)

Closes a task whose matching duplicate is already finished, recording that it duplicates the other task. It never changes the surviving task. Consolidating two tasks that are both live stays with you.

Move anyway (pipelineOrderOverride)

A rider, off by default. overridePipelineOrder: true on respondToApproval, createIdea, promoteIdea, scheduleFutureTask or pullNextSprint lands the call past a dependency-order warning. It needs this category next to the tool's own, or the call is refused and writes nothing. Never send it with orderChoice. The history names the session. Autopilot is always refused when it sends it.

Base branch fix filing (baseRedFixFiling)

Files a fix task from the Base branch is red card, up to P1 or P0. Autopilot holds it at Up to P1. No agent can act on that card yet.

What always stays with you

Some approvals can be read and recommended on, but never answered by an agent. No category reaches them.

These decide things you have not delegated:

• Whether work closes, is replaced, or counts as already built.
• Merging two live tasks into one.
• How a pull request is reconciled when two are open, one was closed, or the merge state does not match.
• Which environment, repository setup or account runs the work, including switching accounts for a broken connection.
• Acknowledging factory-level warnings, such as a stalled factory, a red base branch, or an unexplained change in the workspace.
• What the factory does with a parked, stalled or rerouted task, including whether a held task tree keeps splitting ("Let breakdown continue; ask me again later") or stays together ("Stop breaking down further").
• Whether a task waits behind queued work or drops a dependency.
• Rewriting or closing ideas, filing fixes for the factory itself, and the final choice among competing semantic changes.
• Any approval ampm has not classified. These default to yours.

What no grant can do

No grant provides wildcard writes, access to secrets, destructive recovery, worker or access management, or direct moves through the build, QA and pull request stages. Those capabilities do not exist on this surface.