sessions

Report an agent activity-state signal for a session

Changed on
post/api/v1/sessions/{sessionId}/activity

Request

  • Base URL
    http://127.0.0.1:3001
  • URL
    http://127.0.0.1:3001/api/v1/sessions/{sessionId}/activity
  • Auth
    none declared

Path parameters

sessionIdstring required

Session identifier, e.g. project-1.

Request body

agentSessionIdstring

Native agent session identifier used to resume its transcript.

conversationCheckpointOrigin'human' | 'coordination'

Whether the main-turn boundary came from a human or AO coordination.

coordinationIdstring

Opaque identity of an AO-authored semantic prompt accepted by the native agent.

entrypointstring

Provider process-kind marker (Claude's CLAUDE_CODE_ENTRYPOINT) of the process that fired the hook.

eventstring

AO hook sub-command that produced this state (e.g. post-tool-use).

finalAssistantMessagestring

The agent's final message of the turn, kept for terminal turn history only.

harnessstring

The agent whose hook sent this signal. A signal from an agent the session no longer runs is ignored.

latestAssistantUpdatestring

Latest assistant update exposed by the provider hook.

latestUserPromptstring

Latest real user prompt exposed by the provider hook.

launchIdstring

AO process generation that produced the signal.

observedAtstring date-time

Time the local hook process observed the event, before delivery to the daemon.

processIdinteger

Process id of the provider process that fired the hook (Claude's CLAUDE_PID).

providerTurnIdstring

Native main-turn identity reported by the hook, when supported.

runningSubagentIdsstring[] nullable

Running Claude subagent ids observed in a parent Stop hook; empty means none, absent means no snapshot.

state'active' | 'idle' | 'waiting_input' | 'blocked' | 'exited'

Agent activity state reported by an agent hook. Optional for metadata-only hooks.

subagentIdstring

Native child agent id for this hook event.

submissionIdstring

AO prompt-hook context correlation UUID, when supported.

toolNamestring

Native tool name, for tool-use hook events.

toolUseIdstring

Native tool-use id, for tool-use hook events.

transcriptPathstring

Read-only provider-native transcript path exposed by the hook.

turnUserRequeststring

The user's request for the turn, kept for terminal turn history only.

Response

OK

okboolean required
sessionIdstring required
statestring required

Changes

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      removed the agent_switch_saga enum value from the response property for the response status

    • info

      removed the agent_switch_saga enum value from the response property for the response status

    • info

      removed the agent_switch_saga enum value from the response property for the response status

    • info

      removed the agent_switch_saga enum value from the response property for the response status

    • info

      added the new optional request property