crewship hooks

Manage the lifecycle-hook registry — shell commands, HTTP webhooks, or subagents that fire on platform events (pre_agent_start, post_agent_stop, on_approval_requested, …). See the Hooks guide for the full 14-event catalog and the three handler kinds. There is no pre_tool_call — the platform has no interception point before a tool runs. Every one of the 14 catalog events, including post_tool_call, now dispatches from a real call site — see Currently-dispatched events below.

crewship hooks <subcommand> [flags]
crewship hook  <subcommand> [flags]   # singular alias

Every write requires OWNER or ADMIN. Creating or editing a shell hook requires OWNER — a shell handler runs its command on the crewshipd host, outside container isolation.

Subcommands

Command	Description
`list`	List registered hooks.
`create`	Register a new hook (OWNER/ADMIN).
`update <id>`	Patch an existing hook (OWNER/ADMIN).
`delete <id>`	Remove a hook permanently (OWNER/ADMIN).
`enable <id>`	Enable a registered hook (OWNER/ADMIN).
`disable <id>`	Disable a registered hook (OWNER/ADMIN).

hooks list, create, and update honour the global --format flag (json/yaml/ndjson) — see Output Formats.

`crewship hooks list`

crewship hooks list
crewship hooks list --crew backend-team

Flag	Type	Description
`--crew`	`string`	Filter by crew slug or ID. Cross-tenant IDs return 404.

Sample output:

ID                 EVENT                     HANDLER    TARGET                                      ENABLED  BLOCKING  CREATED
hk_abc123          on_approval_requested     http       https://hooks.slack.com/services/...       yes      no        2026-03-01T09:00Z
hk_def456          post_agent_stop           shell      /usr/local/bin/after-agent.sh              yes      no        2026-03-15T14:22Z
hk_ghi789          on_budget_exceeded        subagent   oncall-router                              no       yes       2026-04-01T10:10Z

TARGET is derived from handler_config: the URL for http, the command for shell, the agent for subagent, truncated to 40 characters.

`crewship hooks create`

crewship hooks create --event <event> --handler <kind> [target flag] [flags]

Requires --event and --handler, plus a target for that handler kind. New hooks are enabled unless you pass --disabled.

Flag	Type	Description
`--event`	`string`	Lifecycle event. Validated locally against the 14 declared events — an unknown value errors before any request is sent, and the message lists the valid names.
`--handler`	`string`	`shell`, `http`, or `subagent`.
`--url`	`string`	http handler: destination URL.
`--command`	`string`	shell handler: command run on the host (`OWNER` only).
`--subagent`	`string`	subagent handler: agent slug or ID to dispatch.
`--handler-config`	`string`	Raw `handler_config` JSON. Escape hatch for keys the flags above don’t cover (`method`, `hmac_secret`, `timeout_secs`, …). Wins over `--url`/`--command`/`--subagent`.
`--crew`	`string`	Scope to one crew (slug or ID). Omit for workspace-wide.
`--matcher`	`string`	Raw matcher JSON. Wins over the `--matcher-*` flags.
`--matcher-tools`	`string`	Comma-separated tool-name regexes.
`--matcher-agents`	`string`	Comma-separated agent IDs.
`--matcher-crews`	`string`	Comma-separated crew IDs.
`--matcher-severities`	`string`	Comma-separated severities.
`--blocking`	`bool`	Run synchronously; valid only for `pre_` events that can still cancel the operation. `post_` and `on_*` events are always asynchronous observations.
`--disabled`	`bool`	Register without arming the hook.

# Slack notification on every approval request
crewship hooks create --event on_approval_requested --handler http \
    --url https://hooks.slack.com/services/XXX

# Blocking shell gate before every agent run, for one crew (OWNER only)
crewship hooks create --event pre_agent_start --handler shell \
    --command /usr/local/bin/gate.sh \
    --crew backend-team --blocking

# Anything the convenience flags don't cover
crewship hooks create --event on_guardrail_triggered --handler http \
    --handler-config '{"url":"https://x.test/h","method":"PUT","hmac_secret":"..."}' \
    --matcher '{"agent_ids":["ag_1"],"severities":["warn","error"]}'

Sample output:

Created hook hk_abc123
  event    pre_agent_start
  handler  shell → /usr/local/bin/gate.sh
  crew     crw_backend
  state    enabled, blocking

`crewship hooks update <id>`

crewship hooks update hk_abc123 --url https://new.test/hook
crewship hooks update hk_abc123 --matcher-tools 'Bash,Write'
crewship hooks update hk_abc123 --disabled

Takes the same flags as create, all optional. Only the flags you pass are sent — an omitted flag keeps its current server-side value. If a blocking pre_* hook is changed to a post_* or on_* event, explicitly pass --blocking=false; the server refuses an observation event that retains the old blocking flag. Passing no flags at all is an error rather than an empty patch. Converting a hook to --handler shell, or editing one that is already shell, requires OWNER.

`crewship hooks delete <id>`

crewship hooks delete hk_abc123 --yes

Flag	Type	Description
`--yes`	`bool`	Required. Deletion is permanent and there is no undo.

Without --yes the command refuses and points at crewship hooks disable, which stops the hook firing while keeping its definition.

`crewship hooks enable <id>`

crewship hooks enable hk_abc123

Sample output:

Hook hk_abc123: enabled

Requires OWNER or ADMIN (403 otherwise). Emits system.hook_toggled into the Crew Journal with the actor’s user ID.

`crewship hooks disable <id>`

crewship hooks disable hk_abc123

Same auth and audit semantics as enable.

Errors

Exit	Meaning
400	Unknown event or handler kind, a handler with no target, or `--blocking` on an observation event. Most of these are caught locally before a request is sent.
401	Not authenticated.
403	Logged in but not `OWNER` / `ADMIN`; or a non-`OWNER` touching a shell hook.
404	Hook ID not found in your workspace (also returned for cross-tenant IDs).

Currently-dispatched events

Which events actually fire

All 14 events in the --event catalog now dispatch from a real call site — see the Hooks guide coverage table for the call site behind each one. internal/hooks/dispatch_site_test.go enforces this as an invariant: a source-scan test fails CI if an event is ever added to AllEvents without a matching hooks.Dispatch call reachable from outside the hooks package.pre_tool_call used to be exactly the opposite trap — an event that registered cleanly and never fired, with no “wire it up” path on the roadmap — and was removed from the valid event list rather than left there: it is the one event name that is now a 400, not a silently-dead 201.

Hooks guide.
Hooks API.

Getting started

Sessions & identity

Agents & conversations

Crews, projects & workspaces

Missions & routines

Issues & triage

Skills & integrations

Inbox & notifications

Memory & journal

Observability

Cost & paymaster

Approvals & hooks

Configuration & system

Utilities

Hooks Commands

crewship hooks

Subcommands

`crewship hooks list`

`crewship hooks create`

`crewship hooks update <id>`

`crewship hooks delete <id>`

`crewship hooks enable <id>`

`crewship hooks disable <id>`

Errors

Currently-dispatched events

​crewship hooks

​Subcommands

​crewship hooks list

​crewship hooks create

​crewship hooks update <id>

​crewship hooks delete <id>

​crewship hooks enable <id>

​crewship hooks disable <id>

​Errors

​Currently-dispatched events

​Related

crewship hooks

Subcommands

`crewship hooks list`

`crewship hooks create`

`crewship hooks update <id>`

`crewship hooks delete <id>`

`crewship hooks enable <id>`

`crewship hooks disable <id>`

Errors

Currently-dispatched events

Related