Say where the work stands when a run ends
An agent's run can end before its work does. It may be waiting for a review, have work left for later, or be stuck. Before, a run that ended without an error counted as finished, so work like this went quiet.
Now a run of agent work ends by stating its job's state:
| State | What the run gives |
|---|---|
done | The proof: a link, an id, or what it checked. |
continue | What is left, and when it carries on. |
waiting | On whom or what, and until when. |
blocked | Why. |
This applies to work one agent gives another (a2a), scheduled jobs (cron), reminders and events. Chat answers to a person are not checked.
How an agent states it
There are two ways. The agent can call the agentx_job_state tool before it ends the run:
{ "state": "waiting", "on": "devops review", "until": "2026-11-14T21:00:00Z" }Or it can end its reply with one line:
State: done — https://github.com/acme/app/pull/9The line may sit in backticks, behind a list bullet or behind a quote mark (>): it is read the same way.
On a waiting line, what comes after until is read as the time: State: waiting — devops review, until 2026-11-14T21:00:00Z. On a continue line, a time in brackets at the end, or an ISO date after the last comma, is read as when the work carries on: State: continue — the docs (tomorrow).
agentx_waiting also counts: a run that called it ends waiting.
Every run on these channels starts with one line that reminds the agent of the rule.
When a run states nothing
- AgentX asks the agent once, in the same conversation, for one line with the state. The asking agent still gets the run's own answer, not the reply to this question.
- If the agent still gives no state, or the question fails, the job is stalled. A line is added to the answer:
[Job stalled] <agent> ended its run without saying whether the work is done, continuing, waiting or blocked…. The agent that asked reads it with the answer. Onejob_stalledfailure signal is recorded.
A state given with the tool, or when asked, is added to the end of the answer as [Job state] …, so the agent that asked sees it too. A state already on the answer's last line is not repeated. Only answers that go back to an agent (a2a, events) get the line. A scheduled job's or a reminder's answer goes to a person, so its state is kept on the job only: no [Job state] or [Job stalled] line is added, the run's own State: line is taken off, and a schedule's exit-code line stays last.
A schedule that reports only exceptions stays quiet. If its answer is NOTHING_TO_REPORT, the job is done and AgentX asks nothing. Any State: line is taken off the answer, and no [Job state] line is added, so nothing is posted.
What the asking agent is told
When one agent handed the work to another, the state decides how the answer comes back. Only done is reported as finished.
| State | Status on the answer | What the asking agent reads |
|---|---|---|
done | done | The work finished. |
continue | waiting | The work is not finished: the helper has work left. |
waiting | waiting | The work is not finished, what it waits for, and until when if the time is an ISO date. |
blocked | error | The work is not finished: the helper says it is blocked, and why. |
| stalled | error | The work is not finished: the helper did not say whether it is done. |
For every state except done, the state line is moved to the top of the answer. A very long answer is cut at the end on its way back, and the state must not be cut with it. A long done answer gets the same treatment, so its proof stays in sight.
The question for a state is a turn of its own. It does not change the result recorded for the run, and the ask stays marked on the job until a run takes the work up again.
On the job
When the run belongs to a job in the jobs ledger, the state is written on that job:
donecloses the job with its proof.continuestores what is left and when to wake it. A time that is not an ISO date (such as "tonight") is kept in the note, and the job is looked at again after one hour.waitingstores who it waits on and until when. With no readable time, it is due after one hour.blockedstores why.- A stalled job is marked
stalled, and its requester counts as told: the answer they received says so. - On these channels, a run that ends cleanly without a state is no longer closed as done ("the run ended without error"). It stays working until the question is answered, or it stalls.
The time the run was asked for a state is also stored on the job.
Settings
| Key | Default | What it does |
|---|---|---|
jobState.enabled | true | Turns the check on or off. |
jobState.channels | ["a2a", "cron", "reminder", "events"] | Channels whose runs must state a job's state. Workflow steps are not on the list: the workflow engine already asks each step for done or failed. |
Check it worked
- Terminal: send an agent a task from another agent, with
agentx daemon sendoragentx_send_agent. Ask it to end withState: done — <a link>. The answer that comes back ends with that line, and the daemon log shows[job-state] <agent> a2a …: done — <the link>. Then ask it to end withState: blocked — <a reason>: the log line for the hand-off ends witherror, and the answer the asking agent gets says the work is not finished and starts with[Job state] blocked. - Terminal: send a task and ask the agent not to state anything, twice. The log shows
ended with no state; asking once, thenstalled. The answer ends with[Job stalled], andagentx improve signals --kind job_stalledlists one row. - Terminal: send a person's chat message on Telegram. Its run gets no reminder line and no question.
If something is wrong
- Every agent-to-agent answer ends with
[Job stalled]: the agents do not state a state yet. Check thatagentx_job_stateis in their tool list (session.lean.agentxToolskeeps it), and that the daemon was restarted after the update. - An answer has an extra turn you did not expect: that is the one question for a state. Ask the agent to end with a
State:line, or turn the check off for that channel by removing it fromjobState.channels. - An answer comes back as failed, but the helper ran without an error: the helper stated
blocked, or stated nothing when asked. Read the first line of the answer: it starts with[Job state] blockedor[Job stalled]. - The job in the ledger did not change: the run belongs to no job. Only runs a door opened a job for are written; the answer still carries the state.
no running turn matches this call:agentx_job_stateworks only from inside the agent's own run, on its own machine.
