Arcezia / Integrations / Claude Code

Claude Code hook: check each tool call before it runs

The Arcezia hook for Claude Code checks each tool call before it runs. Claude Code then runs it (ALLOW), refuses it (BLOCK) or asks you (REVIEW).

Install

pip install -U arcezia
export ARCEZIA_API_KEY="ar_live_..."
arcezia-hook install        # adds the hook to ~/.claude/settings.json
export TASK="refactor the auth module"   # optional

arcezia-hook install adds a PreToolUse hook and a SessionStart step to ~/.claude/settings.json. Run it from the environment the hook should use. arcezia-hook print-config prints the same settings without writing them.

What gets checked

Shell commands, one command at a time. The hook sends a name per command (for example git_push, terraform_apply, database_query), so each can have its own contract entry.
File writes and edits (write_file, edit_file), and reads outside the working directory.
Web access (fetch_url, web_search) and MCP tools.

The full table of tool names, how to write contracts for them, and how to grant the agent its workspace are in the Claude Code hook section of the developer docs.

Keep the key out of the agent’s reach

Keep ARCEZIA_API_KEY out of files the agent can read. Grant the workspace yourself, in your own terminal, never from the agent:

arcezia grant-workspace ~/code/my-app --for 8h    # at most 24h; grant again when it ends
arcezia grant-workspace --revoke                  # end it early

Questions

How do I stop Claude Code running rm -rf?

Install the Arcezia hook. It checks every shell command before Claude Code runs it, and a command your contract does not describe is held for you to decide.

In the coding-shell worked example in the developer docs, rm -rf of a folder inside the workspace runs only when a dry run shows nothing would be lost, and waits for you when work would be lost. rm -rf .git always waits for you.

What does the hook do with REVIEW?

ALLOW runs the tool, BLOCK refuses it, and REVIEW asks you. Set ARCEZIA_REVIEW_MODE=deny to refuse instead. No answer within 45 seconds is a refusal.

Does the hook check file reads?

Reads inside the working directory run without a round trip. The hook notes them and reports them with the next checked call, so a later send after reading a secret is still caught. Reads outside it, writes, shell commands, web access and MCP tools are checked.