Documentation Index

Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Lifecycle Hooks

​

Events

​

Coverage status (as of PR #210)

• pre_agent_start, post_agent_stop — orchestrator agent lifecycle. Both payloads carry mission_id since PR #210 so a hook can scope its action to the running mission without a separate join.
• on_approval_requested — fires when Harbor Master’s Gate returns Required=true, before the request lands in the approvals queue. The hook receives the same scope (workspace_id, crew_id, agent_id, mission_id), the credential ID, and the intent string. Use this to forward HITL notifications to Slack / PagerDuty / your own pager-of-choice. PR #210 finally wired this dispatch site — earlier docs claimed it fired but the call site was missing.
• on_guardrail_triggered — fires from Lookout’s InputGuard on every finding (block, sanitize, AND log mode — log isn’t “guard disabled,” it’s observability + alerting without breaking the call). Wired via a GuardListener context callback in internal/pipeline/runner_llm.go so the integration path stays decoupled (lookout has no dep on the hooks package). Payload:
  {
    "direction": "input",
    "kind": "role_override",        // role_override | system_prompt_leak | jailbreak | zero_width_unicode | rtl_override_unicode | lakera_detected
    "detail": "instruction-override request",
    "matched": "ignore previous instructions",
    "pipeline_id": "...",
    "pipeline_run": "...",
    "step_id": "...",
    "agent_slug": "..."
  }
  
  Severity on the HookEventContext is the finding’s severity (info | warn | error) so a webhook can throttle by criticality. Dispatch failures are logged but never change the guard’s verdict — a blocked call stays blocked even if the alert channel is down.

• pre_task_delegation, post_task_delegation — hook into the assignment path (orchestrator.RunAgentForAssignment).
• pre_tool_call, post_tool_call — needs orchestrator tool-call interception.
• pre_llm_call, post_llm_call — fits cleanly into llm.Middleware.
• pre_memory_write, post_memory_write — memory consolidation path.
• pre_peer_conversation, post_peer_conversation — peer bridge.
• on_budget_exceeded — Paymaster already emits journal entries; hooks are the natural next step.

​

Handler kinds

const (
    HandlerKindShell    HandlerKind = "shell"
    HandlerKindHTTP     HandlerKind = "http"
    HandlerKindSubagent HandlerKind = "subagent"
)

​

shell

const allowedShell = true // pass true only when the caller is confirmed OWNER
_, err := hooks.Register(ctx, db, h, allowedShell)
// returns hooks.ErrShellHookNotAllowed if h.HandlerKind == "shell" && !allowedShell

​

http

​

subagent

​

Blocking vs non-blocking

type Hook struct {
    ...
    Blocking bool
}

​

Matcher

​

Registration

_, err := hooks.Register(ctx, db, hooks.Hook{
    WorkspaceID: ws,
    CrewID:      crew, // empty = workspace-wide
    Event:       hooks.EventOnApprovalRequested,
    Matcher:     hooks.Matcher{Severities: []string{"high", "critical"}},
    HandlerKind: hooks.HandlerKindHTTP,
    HandlerConfig: map[string]any{
        "url":    "https://hooks.slack.com/services/...",
        "method": "POST",
    },
    Blocking: false,
    Enabled:  true,
    CreatedBy: userID,
})

​

Endpoints

• GET /api/v1/hooks[?crew_id=...] — list registered hooks (workspace-scoped).
• POST /api/v1/hooks/{id}/enable — OWNER/ADMIN only.
• POST /api/v1/hooks/{id}/disable — OWNER/ADMIN only.

​

CLI

crewship hooks list
crewship hooks list --crew backend-team
crewship hooks enable hk_abc
crewship hooks disable hk_abc

​

Journal entries

• hook.fired — every dispatch lands this. Severity escalates to warn on non-pass outcomes.
• hook.blocked — separate entry so UI filters for “what blocked” don’t have to parse payloads.
• system.hook_toggled — admin enabled/disabled a hook.

​

Gotchas

• Shell hooks bypass container isolation. They run on the host with the privileges of the crewship process. Restrict to OWNER role and audit handler_config.command carefully.
• Non-blocking goroutines use context.Background(). Cancelling the request that triggered the dispatch does NOT cancel the hook; per-handler timeouts bound runtime. If a webhook hangs, the goroutine times out but is not killable from the caller.
• Event names are stable. Renaming requires a migration on hooks_config.event — breaks every existing registration.
• Matcher regex compile is cached forever. A bad regex is cached as a nil sentinel; subsequent calls skip it silently. If a hook never fires, check the logs for hooks: compile regex failed.

​

Related

• Harbor Master — emits on_approval_requested.
• Paymaster — future on_budget_exceeded source.
• Lookout — emits on_guardrail_triggered via the GuardListener context callback.
• Crew Journal — hook.fired, hook.blocked, system.hook_toggled.
• crewship hooks, Hooks API.