crewship hooks

Manage the lifecycle-hook registry — shell commands, HTTP webhooks, or subagents that fire on platform events (pre_tool_call, post_agent_stop, on_approval_requested, …). See the Hooks guide for the full 15-event catalog and the three handler kinds.

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 15 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; a `block` outcome cancels the triggering operation.
`--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 on Bash and Write, for one crew (OWNER only)
crewship hooks create --event pre_tool_call --handler shell \
    --command /usr/local/bin/gate.sh \
    --matcher-tools 'Bash,Write' --crew backend-team --blocking

# Anything the convenience flags don't cover
crewship hooks create --event pre_llm_call --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_tool_call
  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, so changing the event does not quietly clear your matcher or 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, or a handler with no target. 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 (as of PR #210)

Dispatched:

pre_agent_start, post_agent_stop
on_approval_requested

The other 12 events are defined but not yet dispatched at their call sites — see the Hooks guide coverage table. Registering a hook on an undispatched event is legal but nothing will fire it.

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