Tasks that follow their pull request
Applies to: Hosted session and Your runner.
When you hand a task to a coding agent, the task can track its own review round: a pull request that carries the task reference links itself, the task moves to In review, a changes-requested review sends it back to working with the review text attached, and a merge completes the agent's work.
This page covers what to set up, how the states move, and what to check when nothing happens.
Before you start
- The task needs a delegate. Everything here happens because the task has one. A pull request matching a task with no delegate still links and shows on the task, but no state moves. This is the first thing to check.
- Delegating needs member access. Creating an agent needs workspace admin. How many agents and runs a plan allows is in Plans and limits.
- Connect the forge. GitHub, GitLab and Bitbucket all link pull requests. The changes-requested round trip is GitHub only.
Delegate, do not assign
An agent is a delegate, not an assignee. The task still belongs to a person, and that person still answers for it. The delegate is a separate field saying who is doing the work right now.
Two kinds:
- A coding agent using an Ithura API token. It reads the task itself, including any review feedback.
- A hosted agent or a registered runner. Delegating to one starts a run immediately, and later feedback arrives as a new run. A hosted agent runs at your AI provider (see Hosted agent sessions). A runner runs on your machine (see Your runner).
How a pull request finds its task
By the task reference, in either the branch name or the pull request title. A branch named PAR-128-fix-overflow links to PAR-128, and so does a title mentioning it.
- The prefix must match a project in the same workspace.
- Case does not matter.
- One pull request can carry several references and link to all of them.
Nothing needs configuring for the matching itself.
The states
| The task's delegation says | When |
|---|---|
| Idle | You have handed the task over, nothing has started |
| Working | The agent is on it |
| In review | A pull request carrying the reference is opened, or marked ready for review |
| Working, with "Changes requested" | A reviewer asked for changes on GitHub |
| Working | The pull request is converted back to a draft, from In review |
| Done | Merged |
| Idle | The pull request is closed without merging, from In review |
| In review | A run finished having changed nothing, with an open pull request |
| Needs you | A run finished having changed nothing, with a draft pull request or none |
| Idle | A run ended because the agent's provider failed, from Working |
The state is worked out from all of the task's pull requests, not only the one that just changed. An open, non-draft pull request anywhere on the task is what puts it in review.
Three rules keep the automation from talking over a person:
- An open question wins. If the agent has asked you something, no pull request event overrides it. The question stays until you answer. The one exception is a merge that leaves nothing open, which completes the work.
- A closed pull request returns the task to idle only if it was in review. On a working task, closing a pull request changes nothing.
- A push while the agent is working does not hand the work back. See below.
What a merge does to the task
A merge completes the agent's part, and it finishes the task too, as long as the merged pull request was the last one outstanding. A task with another pull request still open, or a draft, is not finished by one merge.
Your workspace's pull-request-to-state mapping still applies first. Whether it survives depends on where it puts the task:
- A mapping that moves merged work to a state you count as finished keeps it there. A task already in a completed or a cancelled state is left exactly where it is.
- A mapping that moves merged work somewhere short of finished, a "Ready to release" that is not itself a completed state, does not hold. The task is completed anyway.
So if your team wants merged work to land somewhere other than your first completed state, that state has to be one of your completed states. Otherwise the merge moves it past it.
Finishing a task also finishes its open sub-tasks, one level down. Sub-tasks already cancelled or already done are left alone, and sub-tasks further down wait for their own parent. See Tasks.
Finishing a task ends its delegation
When a delegated task reaches a completed state by any route (you move it, a bulk edit, a connector, a restore from history, a pull request or Sentry status mapping, a GitLab issue close, auto-close, or its parent finishes), its delegation moves to Done, whatever state it was in (idle, working, waiting on your answer, or in review). A cancelled task loses its delegate. A queued run is cancelled. A run still going is asked to stop, so the agent keeps what it did on its work-in-progress branch and picks up nothing new. The delegation trail says who finished it, for example "Completed by a person", "Cancelled by its pull request" or "Completed with its parent task".
A pull request closed without a merge never cancels a delegated task, even where a status mapping says so. The delegation goes back to Idle, and idle tasks are back in the agent's work list, so the agent will start on the task again by itself, with a new run.
If that is not what you wanted, close the task or take the agent off it. Closing the pull request on its own does not say stop. It says this attempt was no good, and the agent reads that as another go.
One narrower case ends differently. If the agent was still working, with no open pull request and nothing reported for a while, the task comes back to you instead, carrying "The pull request was closed without merging. Close the task, or reply to send it back."
The agent never picks up a task that is completed or cancelled.
A push does not end the round
While the agent is working, pushing to the pull request does not move the task to In review. A push is the agent mid-round, not the agent handing the work back, and treating every push as "done, please look" would put the task in review several times while the agent was still going.
The round ends when the agent says so: a run completes, or a token agent
reports in_review or done. It also ends if a person opens the pull request
or marks it ready for review, because that is a person saying it is ready.
Once the task is already In review, a further push keeps it there.
A run can finish having changed nothing
Sometimes the agent finds there is nothing to do: the fix is already on main, or the test it was sent to write already passes. The run finishes as no change rather than failing, because nothing went wrong.
The task never stays at Working after that, since nothing else is coming to pick it up. Where it goes depends on whether there is a pull request waiting for a person:
- With an open pull request, the task moves to In review. There is work there to look at, whoever wrote it.
- With a draft pull request, or none, the task moves to Needs you, carrying the agent's own reason. The first line of what the agent reported becomes the question, followed by "Close the task, or reply to send it back." If the agent said nothing, it reads "The agent made no change."
A draft counts as no pull request here, as it does everywhere else on this page: a draft is not asking for review yet.
A run that completes and opens nothing
A run that finishes normally but opens no pull request is a different case from the one above: the agent did not report that there was nothing to do, it simply ended without producing anything to review.
The task stays with the agent for a short while rather than moving straight on, because a pull request can arrive a moment after the run ends, and pulling the task away the instant a run finishes would undo work that was about to appear.
When nothing arrives, the task is handed back to a person with "The run finished without a pull request. Close the task, or reply to send it back." It takes about half an hour, give or take a few minutes, so a task sitting with an agent shortly after its run ended is waiting, not stuck.
Two things worth knowing:
- Once the task is in Needs you, later pull request events do not move it. That is the same "an open question wins" rule as above, and it is deliberate: a person closes the task or replies, and that is what releases it.
- Only a task still Working for that same agent moves. A no-change run reported against a task that has since moved on, or been handed to someone else, records the run and changes no state.
Changes requested
A "changes requested" review on GitHub does three things:
- Sends the task back to working.
- Puts the review text on the task, so the next person sees what was asked without opening GitHub.
- Gives a runner delegate a new run carrying that feedback. A token agent reads it from the task.
That part is GitHub only. On GitLab and Bitbucket, a review will not send a task back to working, although pull requests there still link and still drive In review, merged and closed.
Asking for changes without leaving the task
You can also ask for changes by replying in the task's own thread, wherever the code lives. While a task is in review, a reply is treated as a change request: the agent is sent back to work carrying it, exactly as a review would.
The rule is the task's state, not the words you use. In review, a reply is a change request. Outside review, the same reply is guidance for later, and nothing is dispatched. That is worth knowing before you type a correction into a task that has already merged and wonder why nobody acted on it.
A reply is also kept as guidance, rather than sending the agent back, when the workspace has used up its runs for the day. Nothing is lost and nothing needs retyping: the note stays on the task, and an agent reads the task's recent comments when it next runs. On a task with a long thread, a note left well above the recent ones is worth repeating when you send the work back. See Plans and limits for what a day allows.
Changes asked for in the thread and changes asked for in a review are the same kind of thing to the agent. Ask in the thread, then add a review comment, and the agent sees both together rather than one replacing the other. Finishing the round clears both.
One round, however much feedback arrives
Feedback that arrives while the agent is working is added to the round it is already in, rather than starting another one. So two reviewers asking for different things do not produce two rounds, and a runner that finishes while new feedback is waiting is dispatched again with everything still open.
Feedback belongs to the round it was written for. It is cleared once the work is handed back for review, finished, or dropped, so an old review's text does not follow the task into its next round.
For an agent on the run protocol, new feedback makes the task appear in
agent/work with the reason feedback. An idle task that still carries
feedback is listed as feedback too, rather than as new. Only a provider
failure can leave one, because every other route to idle clears the feedback. A run that finishes succeeded while
the task is working with an open pull request hands it back for review, unless
feedback arrived after that run started: then the task stays working and is
listed as feedback again. A succeeded finish never moves a task that has no
open pull request.
Every piece of feedback is recorded once, so a webhook GitHub delivers twice does not produce two rounds.
A failing check suite also sends the task back, but only three times per pull request. See failing checks are retried three times.
If an agent goes quiet
A run holds its task while it is live, and it stays live by reporting in: starting, every event it posts, and its own check-ins all count. An agent that dies stops reporting, and a run that stops reporting stops holding the task.
How quickly depends on the agent. One that checks in regularly releases the task soon after it goes, because the silence is noticed directly. One that does not check in falls back to a timeout instead, which is slower but still ends.
Either way the task does not sit there forever looking busy, and nobody has to go and unstick it. A run ended this way is marked failed, and its reason says the runner stopped responding, so the trail shows an agent that died rather than work that was never done.
Where the task goes depends on whether there is anything to look at. With an open, non-draft pull request it goes to In review, so the pull request does not drop out of view. With no open pull request it goes back to Idle. Either way the delegation trail records why, so the task's history says what happened rather than just showing it moved.
A run that is still reporting is never treated as quiet, however long it takes. Length is not the test; silence is. A job that genuinely runs for hours is left alone as long as it keeps saying so.
When the provider fails
A run can fail for a reason that has nothing to do with the task: the agent's provider hit a usage limit, its login or key stopped working, the account ran out of credit, or the provider had an outage.
That is read as the provider's failure, not the task's, and it is handled differently from a run that genuinely failed.
This section is about an agent running on your own runner. A hosted session, which Ithura runs at the provider for you, reports a provider problem as an ordinary failed run: the task comes back to you under Needs you, as any failed run does, rather than going back to the agent's queue, and no agent alert appears on Home.
Expect such a run to say that it failed rather than why, though the provider's own words may appear among the run's steps. A key the provider rejected is named as such. Otherwise the message says how the run ended rather than what the provider did: a session the provider closed reads as having ended before the agent reported, while a provider that stays unreachable is retried until the run runs out of time, and reads as the time limit. A short outage is simply retried and costs nothing but a pause. See Hosted agent sessions.
- The run is still recorded as failed, with the reason it failed on. The trail does not pretend a run worked when it did not.
- The task goes back to Idle, carrying "Back in the queue: the provider failed, not the task".
- Nobody is asked to look at it. The person who delegated the task hears nothing, because there is nothing for them to decide. Workspace admins are told instead, as the agent's health changing, since a provider problem is theirs to fix.
- The agent takes no work at all until the problem passes, on this task or any other. While it is held it keeps asking for work and is given none, so it stays visibly alive rather than looking dead.
- A round of review feedback survives. If a reviewer had asked for changes and the agent was partway through them when the provider failed, the task comes back as that same round rather than as new work. The feedback is still on it, and the agent carries on from the branch the review was left on. Nobody has to ask for it twice.
A provider failure before any review is different only in that there is no round to resume: the task comes back as an ordinary new pickup.
An idle task is back in the agent's work list, so the agent starts the task again by itself once it is taking work again. You do not have to send it back. This is the one case where a failed run is tried again with nobody asking, and it is deliberate: the work was never really attempted.
How long an agent is held for
If the provider named a reset time, until that time. Otherwise a short wait, about five minutes for a rate limit or an outage and about fifteen for a usage limit, a login problem or credit.
Every hold has an end. An agent whose runner dies while it is held does not stay held for ever: once the time has passed the hold is dropped, whether or not anything reported in.
Two more states, which do not stop the agent
- Offline: the agent has tasks waiting and has not asked for work for a few minutes. An agent with nothing waiting for it is never called offline, since there is nothing for its silence to hold up.
- Failing: its last three runs all failed inside half an hour, for reasons of their own rather than the provider's. The agent keeps taking work, because the next run is what settles whether it is really broken. It clears itself when a run finishes any other way.
Both of these are about an agent that asks Ithura for work. A registered runner, which is handed a run rather than asking for one, is not watched this way.
Where you see all of this is Home, as an alert naming the agent. See Home.
Linked pull requests and "Status unknown"
A pull request that arrives through the GitHub webhook carries its state with it, so the task is correct from the moment it links.
A link pasted in by hand is different. Ithura asks GitHub for the real state where it can, which needs the GitHub App installed on that repository. Where it cannot ask, and that includes every GitLab and Bitbucket link, the link reads Status unknown until an event arrives to settle it.
An unknown link never moves a task into review. Assuming a pasted link is open would put a task into review on a guess, and a guess that reads like a fact is worse than an admission.
If nothing happens
| What you see | What to check |
|---|---|
| The pull request links, but the task does not move | The task has no delegate. This is the usual cause. |
| A review was requested, the task stayed In review | The repository is on GitLab or Bitbucket. The changes-requested sync is GitHub only. |
| A pasted link reads "Status unknown" | The GitHub App is not installed on that repository, or the link is GitLab or Bitbucket. It will correct itself when an event arrives. |
| The pull request did not link at all | The reference is not in the branch name or the title, or its prefix does not match a project in this workspace. |
| Delegation is refused | Delegating needs member access. The message says if the plan's agent or run limit is reached. |
| The agent pushed, but the task stayed Working | Expected. A push mid-round does not hand the work back; the round ends when the agent reports, or when a person marks the pull request ready. |
| CI keeps failing and the agent stopped trying | Three automatic fix attempts per pull request is the limit. The task says so, and it is waiting for a person. |
| The task flipped to In review on its own, with no report | The agent went quiet past its timeout and there was an open pull request. The trail says "no report before the timeout". |
| The task is in Needs you saying the agent made no change | The agent found nothing to do and said why. Close the task, or reply to send it back with more to go on. |
| A run failed saying the runner stopped responding | The agent stopped reporting, so the run was ended and the task released. Nothing was lost: whatever it had already pushed is still there. Send the task back to try again. |
| A no-change run left the task where it was | It only moves a task that is still Working for that same agent. If the task had already moved on, the run is recorded and nothing else changes. |
| A run failed and the task went back to Idle, with nobody asked to look | The agent's provider failed rather than the task: a limit, a login, credit or an outage. The agent is held until that passes and then starts the task again itself. |
| An agent is starting nothing, and its tasks are just sitting there | Its provider has a problem, or a budget has paused it. For an agent on your own runner, Home names which, and when it resumes. |
What is stored
The task keeps the pull request link, its status, and the text of a changes-requested review. Nothing else is copied from the forge.