A snapshot of the session's aggregate foreground activity.
Foreground work is the agent's active response or workflow in the session,
including model processing, tool execution, and waiting for user action needed
to continue that work. It can start with a prompt or be agent-initiated, for
example to pursue an ongoing goal or follow up on a completed background task.
Either way, the agent MUST report running when foreground work starts,
or requires_action if it starts blocked on user action, and idle when it
ends. The agent SHOULD include a stop reason on that idle update.
Agent-initiated work does not require a prompt request or a synthetic user
message.
running may precede user-message insertion, for example during a foreground
hook. It is not acknowledgment of insertion, and rejecting a prompt does not
itself end foreground work.
Background activity can continue and emit other session/update notifications
while idle. Those notifications, including a detached task's progress or
completion, do not by themselves change this state. A permission request only
warrants requires_action when foreground work is blocked on user action.
The agent SHOULD report requires_action when the foreground workflow as a
whole cannot progress without user action, including permissions or elicitations.
Once reported, it MUST report running when progress resumes, or idle when
work ends without resuming.
If other foreground work can progress, the state remains running. Resolving
one of several requests does not itself change the state. Agents SHOULD ignore
responses for work that has already ended rather than use them to resume it.
A new session defaults to idle until a state update reports otherwise.
Resume MUST send a current-state snapshot after any replay and before its
response. The snapshot reports foreground state after resuming.
The response alone does not imply idle.
Repeated snapshots are idempotent, not additional work, completions, or usage.
A repeated state may carry updated information without another state transition.
The agent MUST report idle when no foreground activity remains. Completing
an individual activity while other foreground work continues does not require
an idle boundary. Local commands use the same lifecycle even without model work.
A snapshot of the session's aggregate foreground activity.
Foreground work is the agent's active response or workflow in the session, including model processing, tool execution, and waiting for user action needed to continue that work. It can start with a prompt or be agent-initiated, for example to pursue an ongoing goal or follow up on a completed background task. Either way, the agent MUST report
runningwhen foreground work starts, orrequires_actionif it starts blocked on user action, andidlewhen it ends. The agent SHOULD include a stop reason on that idle update. Agent-initiated work does not require a prompt request or a synthetic user message.runningmay precede user-message insertion, for example during a foreground hook. It is not acknowledgment of insertion, and rejecting a prompt does not itself end foreground work.Background activity can continue and emit other
session/updatenotifications whileidle. Those notifications, including a detached task's progress or completion, do not by themselves change this state. A permission request only warrantsrequires_actionwhen foreground work is blocked on user action.The agent SHOULD report
requires_actionwhen the foreground workflow as a whole cannot progress without user action, including permissions or elicitations. Once reported, it MUST reportrunningwhen progress resumes, oridlewhen work ends without resuming. If other foreground work can progress, the state remainsrunning. Resolving one of several requests does not itself change the state. Agents SHOULD ignore responses for work that has already ended rather than use them to resume it.A new session defaults to idle until a state update reports otherwise. Resume MUST send a current-state snapshot after any replay and before its response. The snapshot reports foreground state after resuming. The response alone does not imply idle. Repeated snapshots are idempotent, not additional work, completions, or usage. A repeated state may carry updated information without another state transition. The agent MUST report
idlewhen no foreground activity remains. Completing an individual activity while other foreground work continues does not require an idle boundary. Local commands use the same lifecycle even without model work.See protocol docs: Session States