AGH RuntimeAPI Reference
Hooks
AGH Hooks HTTP endpoints.
- Audience
- Operators running durable agent work
- Focus
- API Reference guidance shaped for scanability, day-two clarity, and operator context.
List the resolved hook catalog
GET
/api/hooks/catalogQuery Parameters
workspace?string
Workspace id or path
agent?string
Agent name
event?string
Hook event name
Value in
"session.pre_create" | "session.post_create" | "session.pre_resume" | "session.post_resume" | "session.pre_stop" | "session.post_stop" | "sandbox.prepare" | "sandbox.ready" | "sandbox.sync.before" | "sandbox.sync.after" | "sandbox.stop" | "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.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" | "spawn.pre_create" | "spawn.created" | "spawn.parent_stopped" | "spawn.ttl_expired" | "spawn.reaped"source?string
Hook source
Value in
"native" | "config" | "agent_definition" | "skill"mode?string
Hook mode
Value in
"sync" | "async"Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://loading/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",
"coordination_channel_id": "string",
"coordinator_session_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_reason": "string",
"compaction_strategy": "string",
"decision_class": "string",
"input_class": "string",
"message_delta_type": "string",
"message_role": "string",
"sandbox_backend": "string",
"sandbox_id": "string",
"sandbox_profile": "string",
"session_type": "string",
"sync_direction": "string",
"tool_id": "string",
"tool_name": "string",
"tool_read_only": true,
"turn_id": "string",
"workspace_id": "string",
"workspace_root": "string"
},
"metadata": {
"property1": "string",
"property2": "string"
},
"mode": "string",
"name": "string",
"order": 0,
"priority": 0,
"required": true,
"skill_source": "string",
"source": "string",
"timeout_ms": 0
}
]
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty
List supported hook taxonomy metadata
GET
/api/hooks/eventsQuery Parameters
family?string
Hook event family
Value in
"session" | "input" | "prompt" | "event" | "agent" | "turn" | "message" | "tool" | "permission" | "context"sync_only?boolean
Only return sync-eligible events
Response Body
application/json
application/json
application/json
curl -X GET "https://loading/api/hooks/events"{
"events": [
{
"event": "string",
"family": "string",
"patch_schema": "string",
"payload_schema": "string",
"sync_eligible": true
}
]
}{
"error": "string"
}{
"error": "string"
}Empty
List hook run history for one session
GET
/api/hooks/runsQuery Parameters
session*string
Session id
event?string
Hook event name
Value in
"session.pre_create" | "session.post_create" | "session.pre_resume" | "session.post_resume" | "session.pre_stop" | "session.post_stop" | "sandbox.prepare" | "sandbox.ready" | "sandbox.sync.before" | "sandbox.sync.after" | "sandbox.stop" | "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.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" | "spawn.pre_create" | "spawn.created" | "spawn.parent_stopped" | "spawn.ttl_expired" | "spawn.reaped"outcome?string
Hook execution outcome
Value in
"applied" | "denied" | "failed" | "skipped" | "dropped" | "rejected"since?string
Only runs recorded since this timestamp
Format
date-timelast?integer
Maximum number of records to return
Format
int32Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://loading/api/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"
}
]
}{
"error": "string"
}{
"error": "string"
}{
"error": "string"
}Empty