From 96cec9a08e9e19e8728d20f2a00629b0de0a02ff Mon Sep 17 00:00:00 2001 From: Joao Moura Date: Sat, 8 Aug 2026 21:18:48 -0700 Subject: [PATCH] docs(agents): document the guard's quoted-argument limitation Heredoc bodies are stripped before matching, but quoted arguments cannot be: stripping them would let a genuinely destructive quoted command through. The override marker is the intended answer, so say so where contributors will look. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01ASfWmW3RGy4qAQm6s8U9jH --- .claude/hooks/guard.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.claude/hooks/guard.py b/.claude/hooks/guard.py index b1c9fd4a4..d2764071b 100644 --- a/.claude/hooks/guard.py +++ b/.claude/hooks/guard.py @@ -11,6 +11,14 @@ exits 0 either way. No subprocess, no filesystem writes, no network. Escape hatch: include `# policy-override: ` in a Bash command to state an exception explicitly rather than working around the guard silently. + +Known limitation: rules match the command text, so a command that passes a +protected path to another program as a quoted argument — writing a commit +message or a PR comment about `docs/images`, for example — is denied even +though it changes nothing. Heredoc bodies are stripped before matching because +they are unambiguously data, but quoted arguments are not: `rm -rf "docs/..."` +is a real command, so stripping quotes would open a bypass. Use the override +marker in that case. """ from __future__ import annotations