Hook Event Catalog

Compozy hooks fire at named runtime points such as session creation, prompt assembly, tool execution, permission decisions, automation runs, and context compaction. Each event has a fixed payload type and a fixed patch type. A hook reads the payload from stdin, decides whether it applies, and writes a JSON patch to stdout.

Runtime Placement

Reading This Catalog

Most session-scoped payloads include common session fields:

Control patches use deny and deny_reason. A deny patch stops the sync hook chain. For pre-operation control points, Compozy returns the event-specific denial error to the caller.

Session Events

Session lifecycle patches can set session_name, session_type, agent_name, workspace_id, or workspace. Pre-create, pre-resume, and pre-stop hooks can also deny the operation.

Input And Prompt Events

input.pre_submit patches can replace message, append or replace context_blocks, or deny the submission. prompt.post_assemble patches can replace prompt, adjust context_blocks, or deny the assembled prompt.

Event Persistence Events

Event-record hooks are observation hooks. Their payload includes record_type, sequence, and raw content. Their patch type accepts labels, but the current dispatch path does not mutate the stored event record from that patch.

Automation Events

Automation pre-fire patches can replace prompt or set cancel = true. Observation patches are empty structs and are used only to record hook execution.

Autonomy Events

Autonomy hooks cover coordinator bootstrap, task-run leases, and safe child-session spawn. They do not replace the authority of task-run leases or spawn policy. A hook can deny or narrow the exposed pre-operation payload where a control patch exists, but it cannot mint raw claim tokens, complete a task run through channel messages, bypass TTL, widen permissions, or bypass child depth and child count limits.

Coordinator

CoordinatorSpawnPatch may deny coordinator spawn or replace agent_name, provider, and model. Observation patches are empty and record hook execution only.

Task

These are task-level state transitions, deliberately outside the run-level task.run.* namespace — they describe the task's blocking and escalation state, not a run's lifecycle.

TaskBlockedPayload and TaskUnblockedPayload carry block_id, kind, reason, opaque details, and (on unblock) cleared_at / clear_note. TaskNeedsAttentionPayload and TaskRecoveredPayload carry the escalation reason / recovery note plus at. All four share the TaskContext fields (task_id, workspace_id, task_status, actor/origin identity, and — when a run was parked — run_id and claim_token_hash). TaskObservationPatch is empty; these hooks may annotate or deny but cannot mint claim tokens or bypass the breaker. The raw bearer lease token never appears in these payloads. See the block lifecycle for the operator and agent surfaces that drive these transitions.

Task Run

TaskRunPreClaimPatch may deny the claim, add required capabilities, or raise priority_min. It cannot remove task-run requirements or change the selected run after the claim transaction commits. The raw bearer lease token never appears in these hook payloads.

Spawn

SpawnCreatePatch may deny the spawn or narrow the child request by replacing agent_name, spawn_role, ttl_seconds, or child_permissions. The runtime still rejects permission widening, coordinator-role spawn, cross-workspace spawn, and invalid TTL/depth/child caps.

Agent Process Events

agent.pre_start patches can replace command, args, or cwd, or deny process startup. The post-start lifecycle patches accept labels for observation.

Turn And Message Events

Turn patches can set labels and include the common deny fields. A turn deny stops the hook chain; the current turn events do not return a user-visible denial error. Message patches can replace role, delta_type, or text; only message.start and message.end can run sync hooks.

Tool Events

Tool payloads include tool_call_id, tool_name, tool_namespace, read_only, and tool_input. Pre-call patches can replace the tool name, namespace, read-only flag, or input, and can deny the tool call. Post-call and post-error patches can replace title, tool_result, or error; deny fields on post events stop the hook chain but do not undo an already completed tool result.

Permission Events

permission.request patches can set decision, decision_class, and reason, or deny the request. Compozy rejects escalation patches that try to turn a blocked, denied, or rejected decision into an allow decision; those hook runs are recorded as rejected.

Context Events

Context compaction payloads include reason, strategy, summary, and context_blocks. Patches can replace reason, strategy, or context_blocks. A pre-compact deny blocks compaction; a post-compact deny only stops the remaining hook chain because compaction has already happened.

Example Payloads And Patches

Deny a risky permission request

permission.request payload:

{
  "event": "permission.request",
  "timestamp": "2026-04-16T15:04:05Z",
  "session_id": "sess_9f4a",
  "agent_name": "coder",
  "workspace_id": "ws_checkout",
  "turn_id": "turn_42",
  "request_id": "perm_123",
  "action": "write",
  "resource": "/Users/you/src/checkout/.env",
  "decision": "ask",
  "decision_class": "write",
  "tool_input": {
    "path": "/Users/you/src/checkout/.env"
  },
  "tool_call": {
    "id": "toolu_123",
    "kind": "edit_file",
    "title": "Edit .env"
  }
}

PermissionRequestPatch denying the operation:

{
  "deny": true,
  "deny_reason": "Secrets files require manual review.",
  "decision": "deny",
  "decision_class": "write",
  "reason": "Protected file pattern matched."
}

Add workspace context to a prompt

prompt.post_assemble payload:

{
  "event": "prompt.post_assemble",
  "timestamp": "2026-04-16T15:04:05Z",
  "session_id": "sess_9f4a",
  "agent_name": "coder",
  "workspace_id": "ws_checkout",
  "workspace": "/Users/you/src/checkout",
  "turn_id": "turn_42",
  "input_class": "user",
  "prompt": "Review the current diff.",
  "context_blocks": [
    {
      "kind": "workspace",
      "text": "Repository: checkout"
    }
  ]
}

PromptPatch replacing the assembled prompt:

{
  "prompt": "[Workspace: checkout]\n\nReview the current diff."
}

Cancel an automation fire

automation.job.pre_fire payload:

{
  "job_id": "job_daily_review",
  "job_name": "weekday-review",
  "agent_name": "reviewer",
  "workspace_id": "ws_checkout",
  "prompt": "Review the repository.",
  "schedule": {
    "mode": "cron",
    "expr": "0 9 * * 1-5"
  },
  "attempt": 1
}

AutomationFirePatch canceling dispatch:

{
  "cancel": true
}

Introspection Surfaces

Use the CLI for local inspection:

compozy hooks events --family permission
compozy hooks events --sync-only -o json

Use the API when building tooling:

GET /api/hooks/events?family=permission&sync_only=true
GET /api/hooks/catalog?workspace=checkout&event=permission.request
GET /api/workspaces/ws_checkout/hooks/runs?session=sess_9f4a&event=permission.request&last=20

Related references:

• Hook Declaration Format
• Runtime Autonomy
• Hooks CLI Reference
• Automation Triggers