Skip to content

Hooks

CompozyOS Hooks HTTP endpoints.

For people running agent work32 pages in this section

List the resolved hook catalog

GET
/api/hooks/catalog

Query Parameters

workspace?string

Workspace id or path

agent?string

Agent name

event?string

Hook event name

Value in"subagent.settled""session.pre_create""session.post_create""session.pre_resume""session.post_resume""session.pre_stop""session.post_stop""session.message_persisted""session.runtime_recovery.started""session.runtime_recovery.succeeded""session.runtime_recovery.exhausted""input.pre_submit""prompt.post_assemble""event.pre_record""event.post_record""automation.job.pre_fire""automation.job.post_fire""automation.trigger.pre_fire""automation.trigger.post_fire""automation.run.completed""automation.run.failed""agent.pre_start""agent.spawned""agent.crashed""agent.stopped""agent.soul.snapshot.resolved""agent.soul.mutation.after""agent.heartbeat.policy.resolved""agent.heartbeat.wake.before""agent.heartbeat.wake.after""session.health.update.after""turn.start""turn.end""message.start""message.delta""message.end""tool.pre_call""tool.post_call""tool.post_error""permission.request""permission.resolved""permission.denied""context.pre_compact""context.post_compact""coordinator.pre_spawn""coordinator.spawned""coordinator.decision""coordinator.stopped""coordinator.failed""task.blocked""task.unblocked""task.needs_attention""task.recovered""task.status_changed""task.run.enqueued""task.run.pre_claim""task.run.post_claim""task.run.lease_extended""task.run.lease_expired""task.run.lease_recovered""task.run.released""task.run.completed""task.run.failed""loop.started""loop.generation.pre""loop.generation.post""loop.gate.pre""loop.gate.post""loop.node.terminal""loop.terminal""spawn.pre_create""spawn.created""spawn.parent_stopped""spawn.ttl_expired""spawn.reaped""session.attention.changed""window_manager.layout.applied""window_manager.desktop.created""window_manager.desktop.deleted""window_manager.window.moved""window_manager.window.opened""window_manager.window.closed""window_manager.stack.grouped""window_manager.stack.ungrouped""window_manager.stack.activated""worktree.pre_create""worktree.pre_remove""worktree.created""worktree.adopted""worktree.removed""terminal.opened""terminal.closed""terminal.command_started""terminal.command_finished""terminal.input_requested""terminal.input_provided""terminal.recording_started""terminal.recording_stopped""terminal.subscriber_evicted""terminal.limit_rejected"
source?string

Hook source

Value in"native""config""agent_definition""skill"
mode?string

Hook mode

Value in"sync""async"

Response Body

OK

application/json
  1. response
hooks*array<>
curl -X GET "https://example.com/api/hooks/catalog"
{  "hooks": [    {      "event": "string",      "executor_kind": "string",      "matcher": {        "acp_event_type": "string",        "agent_name": "string",        "agent_type": "string",        "autonomy": {          "child_session_id": "string",          "coordinator_session_id": "string",          "loop_name": "string",          "loop_run_id": "string",          "node_id": "string",          "parent_session_id": "string",          "release_reason": "string",          "root_session_id": "string",          "run_id": "string",          "spawn_role": "string",          "task_id": "string",          "workflow_id": "string"        },        "compaction_trigger": "string",        "decision_class": "string",        "input_class": "string",        "message_delta_type": "string",        "message_role": "string",        "session_type": "string",        "tool_id": "string",        "tool_name": "string",        "tool_read_only": true,        "turn_id": "string",        "workspace_id": "string",        "workspace_root": "string",        "worktree_id": "string"      },      "metadata": {        "property1": "string",        "property2": "string"      },      "mode": "string",      "name": "string",      "order": 0,      "priority": 0,      "required": true,      "skill_source": "string",      "source": "string",      "timeout_ms": 0    }  ]}

List supported hook taxonomy metadata

GET
/api/hooks/events

Query Parameters

family?string

Hook event family

Value in"session""input""prompt""event""agent""turn""message""tool""permission""context""terminal"
sync_only?boolean

Only return sync-eligible events

Response Body

OK

application/json
  1. response
events*array<>
curl -X GET "https://example.com/api/hooks/events"
{  "events": [    {      "event": "string",      "family": "string",      "patch_schema": "string",      "payload_schema": "string",      "sync_eligible": true    }  ]}

List hook run history for one session

GET
/api/workspaces/{workspace_id}/hooks/runs

Path Parameters

workspace_id*string

Workspace id

Query Parameters

session*string

Session id

event?string

Hook event name

Value in"subagent.settled""session.pre_create""session.post_create""session.pre_resume""session.post_resume""session.pre_stop""session.post_stop""session.message_persisted""session.runtime_recovery.started""session.runtime_recovery.succeeded""session.runtime_recovery.exhausted""input.pre_submit""prompt.post_assemble""event.pre_record""event.post_record""automation.job.pre_fire""automation.job.post_fire""automation.trigger.pre_fire""automation.trigger.post_fire""automation.run.completed""automation.run.failed""agent.pre_start""agent.spawned""agent.crashed""agent.stopped""agent.soul.snapshot.resolved""agent.soul.mutation.after""agent.heartbeat.policy.resolved""agent.heartbeat.wake.before""agent.heartbeat.wake.after""session.health.update.after""turn.start""turn.end""message.start""message.delta""message.end""tool.pre_call""tool.post_call""tool.post_error""permission.request""permission.resolved""permission.denied""context.pre_compact""context.post_compact""coordinator.pre_spawn""coordinator.spawned""coordinator.decision""coordinator.stopped""coordinator.failed""task.blocked""task.unblocked""task.needs_attention""task.recovered""task.status_changed""task.run.enqueued""task.run.pre_claim""task.run.post_claim""task.run.lease_extended""task.run.lease_expired""task.run.lease_recovered""task.run.released""task.run.completed""task.run.failed""loop.started""loop.generation.pre""loop.generation.post""loop.gate.pre""loop.gate.post""loop.node.terminal""loop.terminal""spawn.pre_create""spawn.created""spawn.parent_stopped""spawn.ttl_expired""spawn.reaped""session.attention.changed""window_manager.layout.applied""window_manager.desktop.created""window_manager.desktop.deleted""window_manager.window.moved""window_manager.window.opened""window_manager.window.closed""window_manager.stack.grouped""window_manager.stack.ungrouped""window_manager.stack.activated""worktree.pre_create""worktree.pre_remove""worktree.created""worktree.adopted""worktree.removed""terminal.opened""terminal.closed""terminal.command_started""terminal.command_finished""terminal.input_requested""terminal.input_provided""terminal.recording_started""terminal.recording_stopped""terminal.subscriber_evicted""terminal.limit_rejected"
outcome?string

Hook execution outcome

Value in"applied""denied""failed""skipped""dropped""rejected"
since?string

Only runs recorded since this timestamp

Formatdate-time
last?integer

Maximum number of records to return

Formatint32

Response Body

OK

application/json
  1. response
runs*array<>
curl -X GET "https://example.com/api/workspaces/string/hooks/runs?session=string"
{  "runs": [    {      "dispatch_depth": 0,      "duration_ms": 0,      "error": "string",      "event": "string",      "hook_name": "string",      "mode": "string",      "outcome": "string",      "patch_applied": null,      "recorded_at": "2019-08-24T14:15:22Z",      "required": true,      "source": "string"    }  ]}

Observe

CompozyOS Observe HTTP endpoints.

Diagnostics

CompozyOS Diagnostics HTTP endpoints.