Hook Health and Ingestion

Hook Health and Ingestion

Hooks provide low-latency events from Claude Code and Codex. Imports and remote mirrors complement them. Because hooks are fail-safe and non-blocking, agent work can continue even when CCAM is unavailable; monitoring may then have a gap.

Install on the producer host

npm run install-hooks

Install hooks on the machine where the provider CLI runs, not merely inside the dashboard container. The installer is interactive and provider-aware. Container installation is rejected by default because container hooks cannot normally observe host CLI sessions.

Local health check

1. Start CCAM.
2. Create a short provider session.
3. Confirm a session appears promptly.
4. Trigger a simple tool use.
5. End normally and confirm the state settles.

If historical sessions appear but live changes do not, focus on hook configuration. If neither appears, check provider paths, import discovery, and the server data directory.

Authenticated remote delivery

On the dashboard, configure an independent hook token using DASHBOARD_HOOK_TOKEN or preferably DASHBOARD_HOOK_TOKEN_FILE. On the producer host:

export CCAM_DASHBOARD_URL=https://agent-monitor.example.com
export CCAM_HOOK_TOKEN_FILE=/secure/path/hook-token
npm run install-hooks

Non-loopback destinations must use HTTPS and a hook token. Do not reuse the browser/API token as the hook token.

Diagnose by layer

Check	Healthy evidence	If unhealthy
Provider hook config	CCAM wrapper registered for expected events	Re-run installer and inspect provider config
Wrapper execution	Fast exit; no provider blockage	Check executable paths and permissions
Network/TLS	Dashboard endpoint reachable with valid certificate	Fix DNS, proxy, certificate, or firewall
Authentication	No 401/403 at hook endpoint	Match client token to dashboard hook token
Persistence	New events visible through CLI/API	Check server logs, disk, database health
Client update	Browser changes without manual refresh	Check WebSocket/proxy configuration

Recovery after a gap

Re-import or rescan provider history rather than fabricating hook events:

npx ccam import rescan

Imports are designed to be idempotent and can enrich existing sessions. For provider-specific paths and archives, use the History Import UI or hook reference.

Never make the hook wrapper block agent execution while attempting recovery.