Claude Code Hooks for Trading Bots: Block Secrets, Gate Live Orders

Three files go in your bot repo. They assume the layout from our other recipes: bot.py, risk.py, a human-edited limits.json, and tests/test_limits.py.

1. .claude/settings.json: deny rules plus the two hooks. The args form runs the script directly with no shell, which is what the docs recommend when you use ${CLAUDE_PROJECT_DIR}.

{
  "permissions": {
    "deny": [
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Bash(git push *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/bot_guard.py"],
            "timeout": 10,
            "onFailure": "block"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.venv/bin/python",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/limits_tests.py"],
            "timeout": 120
          }
        ]
      }
    ]
  }
}

On Claude Code older than v2.1.295, delete the onFailure line (and update soon, because without it a crashed guard fails open).

2. .claude/hooks/bot_guard.py: the PreToolUse guard. It never prints file contents or secrets, only a reason.

#!/usr/bin/env python3
"""BotCookery PreToolUse guard for Claude Code (also loads in Cursor and Grok Build).
Exit 0 = no objection (normal permissions still apply). Exit 2 = block; stderr goes to the agent."""
import json, re, sys

data = json.load(sys.stdin)
tool = data.get("tool_name", "")
inp = data.get("tool_input") or {}

# .env, .env.local, *.pem, *.key, SSH keys. .env.example is allowed.
SECRET = re.compile(r"(^|[/\s'\"=])(\.env(?!\.example)(\.[\w-]+)?|[\w.-]+\.pem|[\w.-]+\.key|id_rsa|id_ed25519)($|[\s'\";|&)])", re.I)

def block(msg):
    print(f"BotCookery guard: {msg}", file=sys.stderr)
    sys.exit(2)

if tool == "Bash":
    cmd = inp.get("command", "")
    if re.search(r"--live\b|BOT_MODE=live|KALSHI_ENV=prod", cmd):
        block("live trading is started by a human in their own terminal, never by the agent.")
    if SECRET.search(cmd):
        block("commands that touch .env or key files are blocked. The bot loads secrets from env vars itself.")
    if re.search(r"(^|[;&|]\s*)(printenv|env)(\s*$|\s*[|;&>])", cmd) or re.search(r"echo\s+[\"']?\$\{?\w*(KEY|SECRET|TOKEN|PASS)", cmd, re.I):
        block("printing environment secrets is blocked.")
    if re.search(r"\bgit\s+push\b", cmd):
        block("git push needs a human.")
    if "limits.json" in cmd and not re.match(r"\s*(cat|less|head|jq)\s", cmd):
        block("limits.json is human-edited only. Ask the user to change limits.")
elif tool in ("Read", "Edit", "Write"):
    path = inp.get("file_path", "")
    if SECRET.search(" " + path):
        block(f"access to {path} is blocked.")
    if tool != "Read" and re.search(r"(^|/)limits\.json$", path):
        block("limits.json is human-edited only. Ask the user to change limits.")
sys.exit(0)

3. .claude/hooks/limits_tests.py: the PostToolUse hook. A PostToolUse hook can't undo an edit, but exit 2 shows the test failure to Claude so it fixes the code right away.

#!/usr/bin/env python3
"""BotCookery PostToolUse hook: after the agent edits risk, limit or kill-switch code,
run the limit tests. Exit 2 sends the failure output back to the agent to fix."""
import json, os, re, subprocess, sys

data = json.load(sys.stdin)
path = (data.get("tool_input") or {}).get("file_path", "")
if not re.search(r"(risk|limit|kill)[\w-]*\.py$", path):
    sys.exit(0)
root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
r = subprocess.run([sys.executable, "-m", "pytest", "-q", "tests/test_limits.py"],
                   cwd=root, capture_output=True, text=True, timeout=110)
if r.returncode != 0:
    print(f"Limit tests failed after editing {path}:\n{(r.stdout + r.stderr)[-3000:]}", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

We ran both scripts against sample hook inputs before publishing: the guard blocks python bot.py --live, cat .env, env | grep KALSHI, echo $KALSHI_API_KEY_ID, git push, edits to limits.json and reads of *.pem files, and it allows python bot.py, pytest -q, cat .env.example and edits to risk.py. The test hook exits 2 when a limit test fails and 0 when it passes.

1. Start from a bot repo that already has limits in code. If you don't have one yet, cook the Kalshi AI trading bot or Polymarket paper bot first, plus the kill switch recipe.
2. Paste the prompt into Claude Code, or copy the three files from the section above.
3. Make the scripts executable if you switch to shell form: chmod +x .claude/hooks/*.py. In the args form shown here, Claude Code runs python3 script.py directly, so it isn't required.
4. Check that Claude Code sees the hooks. Type /hooks in Claude Code. It's a read-only browser that lists each hook and the file it came from.
5. Run the hook tests: pytest -q tests/test_hooks.py. They pipe sample JSON into the guard, the same way Claude Code does.
6. Try to break it on purpose. Ask Claude Code to "run the bot live" or "show me what's in .env". You should see the guard's reason come back as a blocked tool call.
7. Commit .claude/settings.json and .claude/hooks/ so the guard travels with the repo. Keep personal tweaks in .claude/settings.local.json.

Hooks don't touch your bot's trading mode. They decide what the AI agent may do while it works on the code. Keep the bot itself on Kalshi demo or local paper mode exactly as in the bot recipes. The guard adds one more rule: the agent can never be the one that starts live mode. A human types --live in their own terminal, after the paper logs look clean.

A good test run: let Claude Code work on the bot for a session in paper mode, then read your hook outcomes. Blocked calls show up in the transcript with the guard's reason, which tells you what the agent tried to do.