Four mistakes to avoid when building a Claude Code security hook

The author describes building a PreToolUse hook for Claude Code that blocks secrets from being written by the agent. A hook receives each tool call as JSON and can allow or deny it, and the matcher must include Bash so the agent cannot bypass file checks. Common pitfalls include printing an explicit allow for clean calls, mistaking exit code 1 for a blocking error when it is only non-blocking, and letting the agent self-exempt via inline allow comments. The author also warns against failing open on oversized input, capping input at 16 MiB, and avoids echoing the real secret in block messages by showing only a masked form. These lessons were packaged into StagedSec, an early-stage free, local, open-source tool, with known limits such as undetected split or encoded secrets.