Ingest Hooks CLI

agent session event -> tool hook -> provon ingest trace <source> <hook> -> parse transcript -> OTLP -> POST /v1/traces

The hook command is non-blocking: it hands the payload to a detached child process and returns immediately, so it never slows down the agent or trips a hook timeout.

Supported Tools#

Installation is idempotent: re-running ingest hooks install updates existing entries rather than duplicating them. Only hooks that invoke provon ingest trace are modified; hooks owned by other tools are left untouched.

Prerequisites#

1. Authenticate the CLI or provide a project API key:

   bashCopy

   provon auth login
   # or
   export PROVON_API_KEY="your_project_api_key"
   export PROVON_PROJECT_ID="your_project_id"

2. The provon binary must be on PATH (or the hook will bake in the absolute node directory at install time).

Quick Start#

Install hooks for every detected tool on the system:

provon ingest hooks install

The command auto-detects targets by checking for the tool's config directory or the command on PATH. Skipped tools are listed in the output with the reason.

Install for a single tool:

provon ingest hooks install --claude
provon ingest hooks install --codex --cursor

Force install even when a tool is not detected:

provon ingest hooks install --pi --skip-check

Project-Level vs Global#

By default hooks are written to the user's global config (~/.claude/, ~/.codex/, etc.), so they apply to every project. To install only for a specific project:

provon ingest hooks install --project-dir /path/to/project

This writes to <project-dir>/.claude/settings.json, <project-dir>/.cursor/hooks.json, etc. dsh has no project-level config and is skipped when --project-dir is set.

Reporting Configuration#

Reporting credentials are resolved from the global CLI options and the active auth profile:

1. Global --project <id> / --api-key <key> flags
2. The active local auth profile (provon auth login)

# Using global flags
provon --project proj_abc123 --api-key pk_live_xxx ingest hooks install

# Or after `provon auth login`, credentials are read from the profile automatically
provon ingest hooks install

All reporting config is baked into the hook command as a PROVON_TRACE_CONFIG environment variable, so hooks work in non-interactive shells and CI without extra env setup.

Filtering#

Limit which sessions are reported by adding filters at install time:

provon ingest hooks install \
  --repo my-org/my-repo \
  --path /workspace/project \
  --skill dangerous-bash \
  --mcp github \
  --keyword "deploy"

All filters are repeatable. A session is reported if it matches at least one value in each provided filter category.

Report Mode and Level#

provon ingest hooks install --mode coding_write --report-level summary

Disabled Hooks#

Install hooks in a switched-off state (registered but not reporting):

provon ingest hooks install --disable 1

Reinstall without --disable to turn reporting on.

Multiple Reporting Targets#

By default, installing for a project replaces any existing reporting target for that project in the same hooks file. To append an additional target instead:

provon --project second-project --api-key second-key ingest hooks install --append

The same project can only have one target per hooks file. If another tool already reports to the same project, installation is aborted with a TARGET_CONFLICT error to prevent double-reporting.

Uninstall#

Remove all Provon trace hooks from every tool:

provon ingest hooks uninstall

Or from specific tools:

provon ingest hooks uninstall --claude --codex

Only hooks that invoke provon ingest trace are removed. Other tools' hooks and unrelated config keys are preserved. For Codex, the trust-state entries in config.toml are also cleared.

How It Works#

Install phase#

1. Resolve project ID, API key, and endpoint from global flags or the stored auth profile.
2. Detect which tools are present (config directory or command on PATH).
3. Check for cross-tool conflicts (same project reported by another tool's hooks).
4. For each target: write hook entries (Claude, Codex, Cursor) or generate a plugin file (OpenCode, dsh, Pi) that invokes provon ingest trace <source> <hook>.
5. For Codex: compute the sha256 trust fingerprint and write it to config.toml before writing hooks.json, so Codex does not park the hook as "pending trust".

Runtime phase#

1. The tool fires the hook and pipes a JSON payload (containing transcript_path or session data) to provon ingest trace <source> <hook> on stdin.
2. The trace entry reads PROVON_TRACE_CONFIG to determine the reporting target.
3. It re-executes itself as a detached child process, hands over the payload, and returns immediately (milliseconds).
4. The detached child parses the transcript with @provon/agent-transcripts, projects it to OTel spans with @provon/observability, and POSTs to the OTLP endpoint.
5. Failures are logged to stderr only when PROVON_TRACE_DEBUG=1; they never surface to the agent.

Environment Variables#

Troubleshooting#

No traces appear after installation#

1. Confirm the tool was detected: provon ingest hooks install lists skipped targets with reasons.

2. Verify the hook entry exists in the tool's config file (see table above).

3. Run the trace entry manually with debug logging:

   bashCopy

   echo '{"transcript_path":"/path/to/session.jsonl"}' | \
     PROVON_TRACE_CONFIG='{"project_id":"...","api_key":"..."}' \
     PROVON_TRACE_DEBUG=1 PROVON_TRACE_SYNC=1 \
     provon ingest trace claude stop

4. Check that the API key has the telemetry:ingest scope.

Codex hooks show "pending trust"#

Re-run provon ingest hooks install --codex. The installer writes the trust fingerprint to ~/.codex/config.toml before updating hooks.json. If Codex was running during install, restart it to pick up the new trust state.

Hooks slow down the agent#

The hook command returns immediately after forking a detached child. If you still observe latency, set PROVON_TRACE_SYNC=0 (default) and ensure the provon binary is on PATH.

Double-reporting#

Each project can only have one reporting target per hooks file. If you see duplicate traces, run provon ingest hooks uninstall and reinstall, or check that another tool is not also reporting to the same project.