Claude Code hooks
The CLI can install hooks into Claude Code without changing application code.
pip install staso
export STASO_API_KEY=ak_...
staso setup --target claude-codeThe setup flow writes hook configuration and keeps the API key in the user credential file. Inspect the generated settings before running the integration.
All five content categories default to enabled. The interactive setup lets you choose them, or use paired flags in scripted setup:
staso setup --target claude-code \
--no-capture-request \
--no-capture-tool-arguments \
--capture-output| Category | Claude Code hook data |
|---|---|
request | Submitted user prompt, turn input, and prompt-derived turn label. |
system_prompt | No host system prompt is exposed to these hooks. |
tool_schema | No host tool schema is exposed to these hooks. |
tool_arguments | Pre/post-tool input. Guard evaluates the proposed input in memory and never rewrites it. |
output | Assistant transcript content, synthetic transcript content, tool response, failure detail, and Guard reason prose. |
The hook reads the host transcript to derive assistant spans, models, token counts, and turn offsets. When output is suppressed it parses a content-free shape and does not attach assistant bodies. A suppressed request uses turn <n> as the label instead of deriving one from the prompt.
Submitting a prompt publishes a live root with the available model and permitted input. Existing post-tool callbacks publish observed response usage before the turn finishes. Completion updates the same root and response IDs, so these live snapshots do not add duplicate calls or token counts. Usage stays unavailable until the host supplies it. If the session ends or a new prompt replaces a turn before completion, Staso marks the previous root as timed out instead of leaving it live.
Guard
Guard checks are enabled by default during setup. PreToolUse evaluates proposed tool calls against active configured policies before the host executes them. A matching audit policy records a would-block finding and allows the proposal. A matching Enforce policy can block it before execution. An active policy is required. Built-in templates do nothing until attached.
When Guard cannot return a policy decision, the hook fails open by default. Use the optional fail-closed setting only for actions that must stop during explicit degradation. Pass --no-guard during setup to disable the hook check.
Hook subprocesses keep short-lived session state in ~/.staso/claude-code. The directory is restricted to mode 0700 and state files to 0600; symlinked or non-regular paths are refused. Normal SessionEnd removes the state, and a later SessionStart removes interrupted state older than 24 hours. The hooks can only govern fields their host exposes; an enabled category is not a claim that hidden host content was received.
Useful maintenance commands:
staso status --target claude-code
staso sync --target claude-code
staso uninstall --target claude-codeRun each command with --help for its current options.