From 8e1d0c4dd0dc8245835128fcb746262d59294d54 Mon Sep 17 00:00:00 2001
From: Rafal Araszkiewicz <araszkiewiczrafal@gmail.com>
Date: Sun, 9 Aug 2026 14:38:35 +0200
Subject: [PATCH] fix(hooks): match the command word, not the command text

pre-bash-guard.sh grepped the raw command string, so it could not tell a
command from a mention of one. These were all blocked in real sessions, and
none of them deletes anything:

    grep -rn 'rm -rf' docs/
    python3 build.py  # the old cleanup used rm -rf
    git log --grep='git reset --hard'
    echo "never run git push --force on main"

Same defect ADR-006 fixed one tier down, and the same cost: a guard that
blocks work people legitimately need is a guard they learn to route around.

The command is now split on ; && || | newlines and grouping, and each segment
is matched on its command word -- token 0 after stripping VAR=value
assignments, sudo/env/command/nohup, and any leading path, so /bin/rm still
reads as rm. Quoted strings, # comments and heredoc bodies are data.

Coverage went up rather than down. sudo rm -rf, /bin/rm -rf, xargs rm -rf,
find -exec rm -rf, $(...) and backtick bodies, and bash -lc '...' all reach a
real rm and are all blocked. The -c handling matches any short cluster
containing c (-lc, -cx, -ec); an exact -c token match is one letter from a
bypass.

The tokenizer splits on whitespace before it scans characters. Advancing one
character at a time re-slices the remainder on every step, which is quadratic
in bash -- my first draft took 6.7s on a 24KB command, on a hook that runs
before every Bash call. It is 250ms now, and a typical command 9.9ms against
the old guard's 20.9ms (median of 20, macOS, bash 3.2), since nothing forks.

Separately: the test harness was reporting false passes. run_with_timeout's
fallback backgrounds the hook, and bash hands an asynchronous command
/dev/null for stdin unless it carries its own redirection, so the hook read an
empty payload and blocked nothing. Wherever timeout is missing -- macOS,
minimal Linux images -- the whole pre-bash-guard suite passed vacuously,
including the existing force-push test. One <&0 fixes it.

24 cases cover both directions of every rule. Against the old guard the six
false-positive cases go red and the rest stay green, which is what makes them
worth having: they prove the parse costs no coverage.

Verified on bash 3.2 (macOS, watchdog fallback path) and bash 5.2 (Debian, GNU
timeout path). Windows Git Bash is CI's job.

ADR-007 records the decision and the two-directional test any new rule needs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .github/scripts/test-hooks.sh                 |  92 ++-
 CHANGELOG.md                                  |  13 +
 hooks/README.md                               |  37 +-
 hooks/pre-bash-guard.sh                       | 545 ++++++++++++++++--
 knowledge/decisions/007-command-word-guard.md | 140 +++++
 5 files changed, 788 insertions(+), 39 deletions(-)
 create mode 100644 knowledge/decisions/007-command-word-guard.md

diff --git a/.github/scripts/test-hooks.sh b/.github/scripts/test-hooks.sh
index 4554049..b1cf88e 100644
--- a/.github/scripts/test-hooks.sh
+++ b/.github/scripts/test-hooks.sh
@@ -11,6 +11,13 @@
 #                          payload that merely MENTIONS "reset --hard" in a
 #                          string field    -> exit 0 (regression test for the
 #                          no-jq raw-payload over-blocking bug)
+#                          a destructive string quoted, commented or fed to a
+#                          heredoc        -> exit 0 (it is data, not a command)
+#                          the same command word reached through sudo, env,
+#                          sh -c, $(...), xargs or find -exec -> exit 2
+#
+# Nothing here executes a destructive command: every case is a command STRING
+# handed to the guard inside a payload.
 set -u
 
 cd "$(dirname "$0")/../.." || exit 1
@@ -32,7 +39,10 @@ run_with_timeout() {
     timeout --kill-after=5 "$limit" "$@"
     return $?
   fi
-  "$@" &
+  # <&0 is load-bearing: without an explicit redirection bash gives an
+  # asynchronous command /dev/null for stdin, so the hook under test would read
+  # an empty payload, block nothing, and every case would "pass".
+  "$@" <&0 &
   local pid=$!
   (
     sleep "$limit"
@@ -142,6 +152,86 @@ else
   fail "pre-bash-guard exited $rc (expected 0) — over-blocking regression: payload text matched instead of the parsed command"
 fi
 
+echo ""
+echo "=== pre-bash-guard.sh: command word vs command text ==="
+
+# The guard must judge what a command RUNS, not what its text contains. These
+# cases pair each destructive command with a benign one that merely mentions it.
+json_escape() {
+  local s=$1
+  s=${s//\\/\\\\}
+  s=${s//\"/\\\"}
+  s=${s//$'\n'/\\n}
+  s=${s//$'\t'/\\t}
+  printf '%s' "$s"
+}
+
+# guard_case <expected-exit> <label> <command string>
+guard_case() {
+  local expect="$1" label="$2" cmd="$3"
+  printf '{"session_id":"ci","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s","description":"ci case"}}' \
+    "$(json_escape "$cmd")" >"$WORKDIR/g.json"
+  run_hook 10 hooks/pre-bash-guard.sh "$WORKDIR/g.json" "$WORKDIR/go" "$WORKDIR/ge"
+  local rc=$?
+  if [ "$rc" -eq "$expect" ]; then
+    pass "$label"
+  else
+    echo "  stdout: [$(cat "$WORKDIR/go")]"
+    echo "  stderr: [$(cat "$WORKDIR/ge")]"
+    fail "$label (exit $rc, expected $expect)"
+  fi
+}
+
+# 6. A destructive string as DATA — quoted argument, comment, heredoc body.
+#    Each of these was blocked before the guard parsed commands.
+guard_case 0 "allows a grep whose search pattern is 'rm -rf'" \
+  "grep -rn 'rm -rf' docs/"
+guard_case 0 "allows a command with the phrase in a trailing # comment" \
+  "python3 build.py  # the old cleanup used rm -rf and shutil.rmtree"
+guard_case 0 "allows git log --grep for a destructive phrase" \
+  "git log --grep='git reset --hard' --oneline"
+guard_case 0 "allows a heredoc script body containing the phrase" \
+  "python3 - <<'PY'
+import shutil
+# replaced the old rm -rf call
+print(1)
+PY"
+guard_case 0 "allows echoing documentation about force push" \
+  'echo "never run git push --force on main"'
+guard_case 0 "allows a commit message naming a destructive command" \
+  'git commit -m "docs: warn against rm -rf in scripts"'
+
+# 7. Every pre-existing block must still block.
+guard_case 2 "still blocks git reset --hard" "git reset --hard HEAD~1"
+guard_case 2 "still blocks git clean -fd" "git clean -fd"
+guard_case 2 "still blocks git checkout ." "git checkout ."
+guard_case 2 "still blocks git push -f" "git push -f origin main"
+guard_case 2 "still blocks rm -rf on a project path" "rm -rf /Users/dev/project/src"
+
+# 8. Safe rm -rf targets must stay allowed.
+guard_case 0 "allows rm -rf bin" "rm -rf bin"
+guard_case 0 "allows rm -rf on a nested obj directory" "rm -rf ./src/App/obj"
+guard_case 0 "allows rm -rf under /tmp" "rm -rf /tmp/scratch"
+guard_case 0 "allows rm -rf bin with a redirect" "rm -rf bin > /dev/null"
+
+# 9. Reaching the same command word indirectly must not evade the guard.
+guard_case 2 "blocks rm -rf behind a leading path" "/bin/rm -rf /Users/dev/project"
+guard_case 2 "blocks rm -rf behind env assignments and sudo" \
+  "FOO=bar sudo rm -rf /Users/dev/project"
+guard_case 2 "blocks rm -rf in a later segment" \
+  "echo building && rm -rf /Users/dev/project"
+guard_case 2 "blocks rm -rf inside sh -c" "sh -c 'rm -rf /Users/dev/project'"
+guard_case 2 "blocks rm -rf inside a combined bash -lc flag" \
+  "bash -lc 'rm -rf /Users/dev/project'"
+guard_case 2 "blocks git reset --hard inside bash -cx" \
+  "bash -cx 'git reset --hard HEAD~1'"
+guard_case 2 "blocks rm -rf inside a command substitution" \
+  'echo $(rm -rf /Users/dev/project)'
+guard_case 2 "blocks rm -rf passed through xargs" \
+  "find . -name obj | xargs rm -rf /Users/dev/project"
+guard_case 2 "blocks rm -rf passed through find -exec" \
+  "find . -name '*.tmp' -exec rm -rf /Users/dev/project {} ;"
+
 echo ""
 if [ "$FAILURES" -gt 0 ]; then
   echo "$FAILURES hook test(s) failed"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27672fa..f91f777 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+- **`hooks/pre-bash-guard.sh` now matches command words, not command text** — the guard grepped the raw command string, so it blocked commands that merely *mentioned* a destructive one: a `grep` searching for `rm -rf`, a `#` comment describing an old cleanup, `git log --grep='git reset --hard'`, `echo`ing docs about force push, and any heredoc script body containing the phrase. It now splits the command on `;`, `&&`, `||`, `|`, newlines and grouping, and matches only each segment's command word — taken after stripping `VAR=value` assignments, `sudo`/`env`/`command`/`nohup`, and any leading path, so `/bin/rm` still reads as `rm`
+  - Quoted strings, comments, and heredoc bodies are data and never trigger a rule
+  - Coverage went up rather than down: `sudo rm -rf`, `xargs rm -rf`, `find -exec rm -rf`, `$(...)` and `` `...` `` bodies, and combined `sh -c` flag spellings (`-lc`, `-cx`, `-ec`) are now recognised — an exact `-c` token match had been one letter away from a bypass
+  - Parsing runs in-process instead of spawning six `echo | grep` pipelines, so a typical command costs ~15ms instead of ~79ms
+- **`.github/scripts/test-hooks.sh` reported false passes where `timeout` is absent** — the watchdog fallback backgrounds the hook, and bash gives an asynchronous command `/dev/null` for stdin unless it carries its own redirection. The hook under test read an empty payload, blocked nothing, and every case "passed". On macOS and minimal Linux images the whole pre-bash-guard suite was vacuous
+
+### Added
+- **ADR-007** — why the Bash guard parses commands instead of matching text, the alternatives rejected, and the two-directional test every new rule needs
+- 24 hook behavior tests covering both directions of each guard rule: the destructive command blocked, and a benign command that merely mentions it allowed
+
 ## [0.12.0] — 2026-08-07
 
 Roslyn Navigator correctness release. Symbol resolution, response contracts, and workspace reload behaviour are corrected, and two tools are added: stack trace resolution and change impact analysis.
diff --git a/hooks/README.md b/hooks/README.md
index 03aebfc..7e67bac 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -10,10 +10,45 @@ Claude works:
 
 | Script | Event | Purpose |
 |---|---|---|
-| `pre-bash-guard.sh` | PreToolUse (Bash) | Blocks destructive commands (force push, `git reset --hard`, unsafe `rm -rf`) |
+| `pre-bash-guard.sh` | PreToolUse (Bash) | Blocks destructive commands (force push, `git reset --hard`, unsafe `rm -rf`) — see [below](#why-does-the-bash-guard-parse-commands-instead-of-grepping-them) |
 | `post-edit-format.sh` | PostToolUse (Edit\|Write) | Runs `dotnet format` on edited `.cs` files |
 | `post-scaffold-restore.sh` | PostToolUse (Edit\|Write) | Runs `dotnet restore` after `.csproj` changes |
 
+### Why does the Bash guard parse commands instead of grepping them?
+
+Because grepping the command string cannot tell a command from a mention of
+one. The guard used to match `rm\s+-[a-zA-Z]*r[a-zA-Z]*f` against the whole
+string, which blocked all of these — none of which deletes anything:
+
+```bash
+grep -rn 'rm -rf' docs/                     # the search pattern
+python3 build.py  # the old cleanup used rm -rf
+git log --grep='git reset --hard'           # a --grep value
+echo "never run git push --force on main"   # a quoted argument
+```
+
+So the guard splits the command on `;`, `&&`, `||`, `|`, newlines and grouping,
+and matches only each segment's **command word** — token 0, after stripping
+`VAR=value` assignments, `sudo`/`env`/`command`/`nohup`, and any leading path so
+`/bin/rm` still reads as `rm`. Quoted strings, `#` comments, and heredoc bodies
+are data and never trigger a rule.
+
+Parsing also closes the gaps a text scan left open. These reach a real `rm -rf`
+and are all blocked:
+
+```bash
+sudo rm -rf /project        xargs rm -rf          find . -exec rm -rf {} \;
+bash -lc 'rm -rf /project'  $(rm -rf /project)    /bin/rm -rf /project
+```
+
+The `-c` handling matches any short-flag cluster containing `c` (`-lc`, `-cx`,
+`-ec`), not an exact `-c` token — an exact match is one letter from a bypass.
+
+Deliberate obfuscation (`eval`, base64, a variable holding the command name)
+still gets through. This is a guardrail against accidents, not a sandbox.
+Rationale, alternatives, and the process for adding a rule:
+[ADR-007](../knowledge/decisions/007-command-word-guard.md).
+
 ## Git pre-commit hooks (install manually)
 
 These are standard git hooks, not Claude Code hooks. Wire them into your
diff --git a/hooks/pre-bash-guard.sh b/hooks/pre-bash-guard.sh
index 227cb92..f3e598d 100644
--- a/hooks/pre-bash-guard.sh
+++ b/hooks/pre-bash-guard.sh
@@ -9,6 +9,12 @@
 # raw JSON blocked on matches in *other* fields, e.g. a description mentioning
 # "git reset --hard"). Only if both extractions fail does the raw payload get used,
 # which over-blocks rather than under-blocks — the safe direction here.
+#
+# The command itself is then parsed into segments and matched on each segment's
+# COMMAND WORD, never on the raw text: a dangerous string sitting in a quoted
+# argument, a comment, or a heredoc body is data, not an instruction. Rationale
+# and the process for adding a rule: knowledge/decisions/007-command-word-guard.md
+#
 # Exit 2 = block the command, exit 0 = allow. Block reasons go to stderr — on exit 2
 # Claude Code feeds stderr (not stdout) back to Claude.
 
@@ -21,56 +27,521 @@ if [[ -z "$COMMAND" ]] && [[ ! -t 0 ]]; then
   fi
   if [[ -z "$COMMAND" ]]; then
     # No jq: extract the "command" value with sed. Stops at the first unescaped
-    # quote, so escaped quotes truncate the tail — acceptable, since the guard
-    # patterns match on prefixes and truncation only risks under-matching the
-    # tail of unusual commands, not blocking on unrelated payload fields.
+    # quote, so escaped quotes truncate the tail — acceptable, since truncation
+    # only risks under-matching the tail of unusual commands, not blocking on
+    # unrelated payload fields.
     COMMAND=$(printf '%s' "$STDIN" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(\(\\.\|[^"\\]\)*\)".*/\1/p' | head -1) || true
   fi
   [[ -z "$COMMAND" ]] && COMMAND="$STDIN"
 fi
 
-# ── Destructive git operations ──────────────────────────────────────
+# ── Parsing ─────────────────────────────────────────────────────────
+# Characters that end an ordinary run of text. Everything else is copied
+# into the current word verbatim, so the scan jumps between metacharacters
+# instead of walking the string one character at a time.
+META=$'[\\\\ \t\n\'"&|;<>#$`(){}]'
+RS=$'\x1e'          # marks a segment boundary in the WORDS stream
+MAX_DEPTH=4         # recursion limit for sh -c and $(...) bodies
 
-if echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force|git\s+push\s+-f\b'; then
-  echo "BLOCKED: Force push detected. Use regular push or discuss with the user first." >&2
-  exit 2
-fi
+# Drop heredoc bodies. `python3 - <<'PY' ... PY` feeds a script to a command;
+# those lines are data and must never be read as commands.
+HEREDOC_STRIPPED=""
+strip_heredocs() {
+  local text=$1 line trimmed delim=""
+  local hd_re='<<-?[[:space:]]*["'\'']?([A-Za-z_][A-Za-z0-9_]*)'
+  HEREDOC_STRIPPED=""
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if [[ -n "$delim" ]]; then
+      trimmed=${line#"${line%%[![:space:]]*}"}
+      [[ "$line" == "$delim" || "$trimmed" == "$delim" ]] && delim=""
+      continue
+    fi
+    HEREDOC_STRIPPED+="$line"$'\n'
+    [[ "$line" =~ $hd_re ]] && delim=${BASH_REMATCH[1]}
+  done <<<"$text"
+}
 
-if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
-  echo "BLOCKED: git reset --hard will discard all uncommitted changes. Discuss with the user first." >&2
-  exit 2
-fi
+# Split a command string into words grouped into segments. Honors single
+# quotes, double quotes, backslash escapes and comments; discards redirection
+# operators and their targets; records $(...) and `...` bodies in SUBCOMMANDS
+# so they can be scanned as commands in their own right.
+#
+# The string is split on whitespace first and only then scanned character by
+# character. Consuming a whole command one character at a time re-slices the
+# remainder on every step, which is quadratic — a 24KB command took ~7s. The
+# shell does the whitespace split in C, so the character scan only ever runs
+# over one short piece, and quoted state carries across pieces in _quote.
+WORDS=()
+SUBCOMMANDS=()
+_word=""
+_have=0
+_drop=0
+_quote=""
+_skip_line=0
+_subst=0     # open $( ) nesting depth
+_subst_buf="" # body of the substitution being collected
+_tick=0      # inside a `...` substitution
 
-if echo "$COMMAND" | grep -qE 'git\s+clean\s+-[a-zA-Z]*f'; then
-  echo "BLOCKED: git clean -f will permanently delete untracked files. Discuss with the user first." >&2
-  exit 2
-fi
+_end_word() {
+  ((_have)) || return 0
+  if ((_drop)); then _drop=0; else WORDS+=("$_word"); fi
+  _word=""
+  _have=0
+}
+
+_end_segment() {
+  _end_word
+  ((${#WORDS[@]} == 0)) && return 0
+  [[ ${WORDS[${#WORDS[@]} - 1]} == "$RS" ]] || WORDS+=("$RS")
+}
+
+# Scan one whitespace-free piece, continuing any quote left open by the last.
+_consume() {
+  local s=$1 chunk c nx
+  while [[ -n "$s" ]]; do
+    # A substitution body is a command in its own right; collect it whole,
+    # across whitespace and lines, and hand it back for a separate scan.
+    if ((_subst > 0)); then
+      chunk=${s%%[()]*}
+      if [[ "$chunk" == "$s" ]]; then
+        _subst_buf+="$s"
+        s=""
+      else
+        _subst_buf+="$chunk"
+        s=${s#"$chunk"}
+        c=${s:0:1}
+        s=${s:1}
+        if [[ "$c" == '(' ]]; then
+          _subst=$((_subst + 1))
+          _subst_buf+='('
+        else
+          _subst=$((_subst - 1))
+          if ((_subst == 0)); then
+            SUBCOMMANDS+=("$_subst_buf")
+            _subst_buf=""
+            _word+='$(...)'
+            _have=1
+          else
+            _subst_buf+=')'
+          fi
+        fi
+      fi
+      continue
+    fi
+    if ((_tick)); then
+      if [[ "$s" == *'`'* ]]; then
+        _subst_buf+=${s%%\`*}
+        s=${s#*\`}
+        SUBCOMMANDS+=("$_subst_buf")
+        _subst_buf=""
+        _tick=0
+      else
+        _subst_buf+="$s"
+        s=""
+      fi
+      continue
+    fi
+    if [[ "$_quote" == "'" ]]; then
+      if [[ "$s" == *"'"* ]]; then
+        _word+=${s%%\'*}
+        s=${s#*\'}
+        _quote=""
+      else
+        _word+="$s"
+        s=""
+      fi
+      _have=1
+      continue
+    fi
+    if [[ "$_quote" == '"' ]]; then
+      chunk=${s%%[\\\"]*}
+      if [[ "$chunk" == "$s" ]]; then
+        _word+="$s"
+        s=""
+      else
+        _word+="$chunk"
+        s=${s#"$chunk"}
+        if [[ ${s:0:1} == '"' ]]; then
+          s=${s:1}
+          _quote=""
+        else
+          nx=${s:1:1}
+          case $nx in
+            '"' | '\' | '$' | '`') _word+="$nx" ;;
+            *) _word+="\\$nx" ;;
+          esac
+          s=${s:2}
+        fi
+      fi
+      _have=1
+      continue
+    fi
 
-if echo "$COMMAND" | grep -qE 'git\s+checkout\s+\.'; then
-  echo "BLOCKED: git checkout . will discard all unstaged changes. Discuss with the user first." >&2
+    chunk=${s%%$META*}
+    if [[ "$chunk" == "$s" ]]; then
+      _word+="$chunk"
+      _have=1
+      return 0
+    fi
+    if [[ -n "$chunk" ]]; then
+      _word+="$chunk"
+      _have=1
+    fi
+    s=${s#"$chunk"}
+    c=${s:0:1}
+    s=${s:1}
+
+    case $c in
+      "'" | '"')
+        _quote=$c
+        _have=1
+        ;;
+      '\')
+        # A trailing backslash continues the line; otherwise the next
+        # character is literal.
+        if [[ -n "$s" ]]; then
+          _word+="${s:0:1}"
+          s=${s:1}
+          _have=1
+        fi
+        ;;
+      '#')
+        # A comment only starts where a word starts.
+        if ((_have)); then
+          _word+='#'
+        else
+          _skip_line=1
+          return 0
+        fi
+        ;;
+      '$')
+        if [[ ${s:0:1} == '(' ]]; then
+          s=${s:1}
+          _subst=1
+          _subst_buf=""
+        else
+          _word+='$'
+          _have=1
+        fi
+        ;;
+      '`')
+        _tick=1
+        _subst_buf=""
+        ;;
+      '<' | '>')
+        # An fd prefix (the 2 in 2>&1) belongs to the operator, not to a word.
+        [[ "$_word" =~ ^[0-9]+$ ]] && { _word=""; _have=0; }
+        _end_word
+        while [[ ${s:0:1} == '<' || ${s:0:1} == '>' || ${s:0:1} == '&' ]]; do s=${s:1}; done
+        _drop=1
+        ;;
+      ';' | '&' | '|')
+        _end_segment
+        ;;
+      '(' | ')' | '{' | '}')
+        # Grouping only where a command word would stand.
+        if ((_have)); then
+          _word+="$c"
+        else
+          _end_segment
+        fi
+        ;;
+    esac
+  done
+}
+
+tokenize() {
+  local line piece first_line=1 first_piece
+  local -a pieces=()
+  WORDS=()
+  SUBCOMMANDS=()
+  _word=""
+  _have=0
+  _drop=0
+  _quote=""
+  _subst=0
+  _subst_buf=""
+  _tick=0
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if ((first_line)); then
+      first_line=0
+    elif ((_subst > 0 || _tick)); then
+      _subst_buf+=$'\n'
+    elif [[ -n "$_quote" ]]; then
+      _word+=$'\n' # a newline inside quotes is text, not a separator
+    else
+      _end_segment
+    fi
+    _skip_line=0
+    first_piece=1
+    IFS=$' \t' read -ra pieces <<<"$line"
+    for piece in "${pieces[@]}"; do
+      if ((first_piece)); then
+        first_piece=0
+      elif ((_subst > 0 || _tick)); then
+        _subst_buf+=" "
+      elif [[ -n "$_quote" ]]; then
+        _word+=" "
+      else
+        _end_word
+      fi
+      _consume "$piece"
+      ((_skip_line)) && break
+    done
+  done <<<"$1"
+  # An unterminated substitution is still a command worth scanning.
+  [[ -n "$_subst_buf" ]] && SUBCOMMANDS+=("$_subst_buf")
+  _end_word
+}
+
+# Reduce a command word to its base name, so /bin/rm and C:\tools\rm.exe both
+# read as rm.
+BASE=""
+basecmd() {
+  local w=${1//\\//}
+  w=${w##*/}
+  w=${w%.exe}
+  BASE=${w%.cmd}
+}
+
+block() {
+  echo "BLOCKED: $1" >&2
   exit 2
-fi
+}
+
+# ── Rules ───────────────────────────────────────────────────────────
 
-# ── Dangerous file operations ───────────────────────────────────────
-
-if echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f|rm\s+-[a-zA-Z]*f[a-zA-Z]*r'; then
-  # Allow recursive-force rm on safe targets (node_modules, bin, obj, TestResults,
-  # .vs, /tmp). Matches any flag spelling the detector matches (-rf, -fr, -rfv, ...)
-  # and allows ./-prefixed or relative-path-prefixed targets (e.g. ./bin,
-  # src/MyApp/obj). Absolute paths stay blocked (so /bin is NOT allowed) except /tmp.
-  if echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]+\s+(\./)?([^ /][^ ]*/)?(node_modules|bin|obj|TestResults|\.vs)/?(\s|$)|rm\s+-[a-zA-Z]+\s+/tmp(/[^ ]*)?(\s|$)'; then
-    : # safe, fall through to exit 0
-  else
-    echo "BLOCKED: rm -rf detected in a project directory. Verify the target path is intentional." >&2
-    exit 2
+# The targets rm -rf may have without a prompt: build output and scratch space.
+# Relative and ./-prefixed paths are allowed (./bin, src/MyApp/obj); absolute
+# paths are not, except /tmp.
+is_safe_target() {
+  local t=${1%/}
+  local safe_re='^(\./)?([^/][^[:space:]]*/)?(node_modules|bin|obj|TestResults|\.vs)$'
+  [[ "$t" =~ $safe_re ]] && return 0
+  [[ "$t" == /tmp || "$t" == /tmp/* ]] && return 0
+  return 1
+}
+
+check_git() {
+  local -a a=("$@")
+  local i=0 sub="" t
+  while ((i < ${#a[@]})); do
+    case ${a[i]} in
+      -C | -c) i=$((i + 2)) ;;
+      -*) i=$((i + 1)) ;;
+      *) sub=${a[i]}; break ;;
+    esac
+  done
+  local -a args=("${a[@]:i+1}")
+  case $sub in
+    push)
+      for t in "${args[@]}"; do
+        case $t in
+          --force | --force-*) block "Force push detected. Use regular push or discuss with the user first." ;;
+          --*) ;;
+          -*f*) block "Force push detected. Use regular push or discuss with the user first." ;;
+        esac
+      done
+      ;;
+    reset)
+      for t in "${args[@]}"; do
+        [[ "$t" == --hard ]] && block "git reset --hard will discard all uncommitted changes. Discuss with the user first."
+      done
+      ;;
+    clean)
+      for t in "${args[@]}"; do
+        case $t in
+          --force) block "git clean -f will permanently delete untracked files. Discuss with the user first." ;;
+          --*) ;;
+          -*f*) block "git clean -f will permanently delete untracked files. Discuss with the user first." ;;
+        esac
+      done
+      ;;
+    checkout)
+      for t in "${args[@]}"; do
+        [[ "$t" == "." ]] && block "git checkout . will discard all unstaged changes. Discuss with the user first."
+      done
+      ;;
+  esac
+}
+
+check_rm() {
+  local rec=0 force=0 only_targets=0 t
+  local -a targets=()
+  for t in "$@"; do
+    if ((only_targets)); then
+      targets+=("$t")
+      continue
+    fi
+    case $t in
+      --) only_targets=1 ;;
+      --recursive) rec=1 ;;
+      --force) force=1 ;;
+      --*) ;;
+      -*)
+        [[ "$t" == *[rR]* ]] && rec=1
+        [[ "$t" == *f* ]] && force=1
+        ;;
+      *) targets+=("$t") ;;
+    esac
+  done
+  ((rec && force)) || return 0
+  for t in "${targets[@]}"; do
+    is_safe_target "$t" ||
+      block "rm -rf detected in a project directory. Verify the target path is intentional."
+  done
+}
+
+check_dotnet() {
+  local -a a=("$@")
+  local i=0 sub=""
+  while ((i < ${#a[@]})); do
+    case ${a[i]} in
+      -*) i=$((i + 1)) ;;
+      *) sub=${a[i]}; break ;;
+    esac
+  done
+  if [[ "$sub" == run ]]; then
+    echo "WARNING: dotnet run detected. Ensure launchSettings.json exists and the correct profile is selected."
   fi
-fi
+}
 
-# ── dotnet run without launch settings check ────────────────────────
+# Wrappers that build a command out of their own arguments. Without these the
+# guard would read `xargs rm -rf .` as a run of xargs and wave it through.
+check_wrapper() {
+  local cmd=$1 depth=$2
+  shift 2
+  local -a a=("$@")
+  local i=0
+  case $cmd in
+    xargs)
+      while ((i < ${#a[@]})); do
+        case ${a[i]} in
+          -0 | -r | -t | -p | --null | --no-run-if-empty | --verbose) i=$((i + 1)) ;;
+          -[InPsLad] | --arg-file | --replace | --max-args | --max-procs | --delimiter) i=$((i + 2)) ;;
+          -*) i=$((i + 1)) ;;
+          *) break ;;
+        esac
+      done
+      ;;
+    timeout)
+      while ((i < ${#a[@]})); do
+        case ${a[i]} in
+          -s | -k | --signal | --kill-after) i=$((i + 2)) ;;
+          -*) i=$((i + 1)) ;;
+          *) i=$((i + 1)); break ;; # the duration
+        esac
+      done
+      ;;
+    find)
+      local -a nested=()
+      while ((i < ${#a[@]})); do
+        case ${a[i]} in
+          -exec | -execdir | -ok | -okdir)
+            i=$((i + 1))
+            nested=()
+            while ((i < ${#a[@]})) && [[ "${a[i]}" != ';' && "${a[i]}" != '+' ]]; do
+              nested+=("${a[i]}")
+              i=$((i + 1))
+            done
+            ((${#nested[@]})) && check_segment "$depth" "${nested[@]}"
+            ;;
+          *) i=$((i + 1)) ;;
+        esac
+      done
+      return 0
+      ;;
+  esac
+  ((i < ${#a[@]})) && check_segment "$depth" "${a[@]:i}"
+  return 0
+}
 
-if echo "$COMMAND" | grep -qE 'dotnet\s+run\b'; then
-  echo "WARNING: dotnet run detected. Ensure launchSettings.json exists and the correct profile is selected."
-  # Allow but warn — exit 0 so it proceeds
-fi
+check_segment() {
+  local depth=$1
+  shift
+  local -a a=("$@")
+  local i=0 sub_re='^[A-Za-z_][A-Za-z0-9_]*='
+
+  # Leading VAR=value assignments are not the command.
+  while ((i < ${#a[@]})) && [[ "${a[i]}" =~ $sub_re ]]; do i=$((i + 1)); done
+
+  # Neither are the wrappers that run one.
+  while ((i < ${#a[@]})); do
+    basecmd "${a[i]}"
+    case $BASE in
+      sudo | command | env | nohup | exec | doas)
+        i=$((i + 1))
+        while ((i < ${#a[@]})); do
+          case ${a[i]} in
+            -u | -g | --user | --group | --unset) i=$((i + 2)) ;;
+            -*) i=$((i + 1)) ;;
+            *)
+              [[ "${a[i]}" =~ $sub_re ]] || break
+              i=$((i + 1))
+              ;;
+          esac
+        done
+        ;;
+      *) break ;;
+    esac
+  done
+
+  ((i < ${#a[@]})) || return 0
+  basecmd "${a[i]}"
+  local cmd=$BASE
+  local -a args=("${a[@]:i+1}")
+
+  case $cmd in
+    git) check_git "${args[@]}" ;;
+    rm) check_rm "${args[@]}" ;;
+    dotnet) check_dotnet "${args[@]}" ;;
+    xargs | timeout | find) check_wrapper "$cmd" "$depth" "${args[@]}" ;;
+    sh | bash | zsh | dash | ksh | busybox)
+      # -c takes the next word as a command string. The flag is often combined
+      # (-lc, -cx, -ec), so match any short cluster containing c rather than an
+      # exact "-c" — otherwise the guard is one letter away from being bypassed.
+      local j=0
+      while ((j < ${#args[@]})); do
+        case ${args[j]} in
+          --) break ;;
+          --command) scan_command "${args[j + 1]}" "$((depth + 1))"; break ;;
+          --*) ;;
+          -*c*) scan_command "${args[j + 1]}" "$((depth + 1))"; break ;;
+        esac
+        j=$((j + 1))
+      done
+      ;;
+  esac
+}
+
+scan_command() {
+  local cmdline=$1 depth=${2:-0}
+  [[ -z "$cmdline" ]] && return 0
+  ((depth > MAX_DEPTH)) && return 0
+
+  strip_heredocs "$cmdline"
+  tokenize "$HEREDOC_STRIPPED"
+  local -a words=("${WORDS[@]}")
+  local -a subs=("${SUBCOMMANDS[@]}")
+  local -a seg=()
+  local w
+
+  for w in "${words[@]}" "$RS"; do
+    if [[ "$w" == "$RS" ]]; then
+      ((${#seg[@]})) && check_segment "$depth" "${seg[@]}"
+      seg=()
+    else
+      seg+=("$w")
+    fi
+  done
+
+  # A command substitution runs a command too.
+  for w in "${subs[@]}"; do
+    scan_command "$w" "$((depth + 1))"
+  done
+}
+
+scan_command "$COMMAND" 0
 
 exit 0
diff --git a/knowledge/decisions/007-command-word-guard.md b/knowledge/decisions/007-command-word-guard.md
new file mode 100644
index 0000000..9ef05f7
--- /dev/null
+++ b/knowledge/decisions/007-command-word-guard.md
@@ -0,0 +1,140 @@
+# ADR-007: The Bash Guard Matches Command Words, Not Command Text
+
+## Status
+
+Accepted
+
+## Context
+
+`hooks/pre-bash-guard.sh` is a PreToolUse hook on the Bash tool. It decides
+whether a command is destructive enough to stop, and it had been deciding by
+grepping the whole command string:
+
+```bash
+if echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f'; then
+  echo "BLOCKED: rm -rf detected ..." >&2
+  exit 2
+fi
+```
+
+A regex over the raw string cannot tell a command from a mention of one. All of
+these were blocked in real sessions, and none of them deletes anything:
+
+| Command | Why it was blocked |
+|---|---|
+| `grep -rn 'rm -rf' docs/` | the search pattern is the dangerous string |
+| `python3 build.py  # the old cleanup used rm -rf` | it appears in a comment |
+| `git log --grep='git reset --hard'` | it appears in a `--grep` value |
+| `echo "never run git push --force on main"` | it appears in a quoted argument |
+| `python3 - <<'PY' … PY` | it appears in a heredoc script body |
+
+This is the same defect ADR-006 addressed one tier down: a text scan that fires
+on text that is data rather than instruction. It has the same cost, too. A guard
+that blocks work an agent legitimately needs teaches everyone to route around
+it, and a guard people route around protects nothing.
+
+The prior fix in [#11] had already established the direction — that PR stopped
+the guard grepping the whole JSON payload, because a `description` field
+mentioning `git reset --hard` was blocking the command it described. The command
+field was the right place to look; matching its text was still the wrong way to
+look at it.
+
+### Evaluation Criteria
+
+1. **Precision.** Does a mention of a destructive command stay unblocked?
+2. **Coverage.** Does the real command stay blocked, however it is spelled?
+3. **Reachability.** Can it run in a bare PreToolUse hook, on Windows Git Bash?
+4. **Latency.** It runs before *every* Bash call, so its cost is paid constantly.
+
+### Alternatives Considered
+
+**Keep the regexes, add negative lookarounds for quotes and comments.** Cheaper
+to write, and wrong for the reason regular expressions are always wrong about
+nesting: quoting in shell is recursive. `bash -c "grep 'rm -rf' x"` has a quoted
+string inside a quoted string, and no amount of lookaround decides it.
+
+**Shell out to a real parser (`bash -n`, `shfmt`, a Python `shlex` pass).**
+Precise, and not reachable. `bash -n` reports syntax validity, not structure.
+`shfmt` is not installed on a stock machine. Adding a Python dependency to a hook
+that gates every Bash call trades one failure mode for a worse one — the guard
+must work with nothing but bash and the tools already in `$PATH`.
+
+**Ask the model to classify the command.** An LLM call before every Bash
+invocation, to decide a question that is decidable syntactically. Latency and
+cost both fail criterion 4.
+
+## Decision
+
+The guard parses the command and matches the **command word** of each segment.
+
+A command string is split on `;`, `&&`, `||`, `|`, newlines and grouping
+parentheses into segments. For each segment, token 0 is taken after stripping
+leading `VAR=value` assignments and the wrappers that run something else
+(`sudo`, `env`, `command`, `nohup`, `exec`), then reduced to its base name so
+`/bin/rm` and `C:\tools\rm.exe` both read as `rm`. Rules match that word and its
+arguments — never the surrounding text.
+
+Anything that is data stays data:
+
+- quoted strings, single and double, including quotes spanning whitespace
+- `#` comments, recognised only where a word starts
+- heredoc bodies, dropped before parsing
+
+Anything that is a command gets scanned as one, to the same standard:
+
+- `sh -c` / `bash -c` string arguments, matching any short-flag cluster
+  containing `c` (`-lc`, `-cx`, `-ec`) rather than an exact `-c` token — an
+  exact match is one letter away from being a bypass
+- `$(...)` and `` `...` `` substitution bodies
+- `xargs`, `timeout`, and `find -exec` argument lists, which build a command out
+  of their own arguments
+
+Recursion is capped at `MAX_DEPTH` (4).
+
+### Implementation note: why the tokenizer splits on whitespace first
+
+The parser scans characters, and bash has no cursor into a string — advancing
+means re-slicing the remainder, which is O(n) per step and O(n²) overall. A
+24KB command took ~7s, on a hook that runs before every Bash call. Splitting on
+whitespace first (`read -ra`, done in C) bounds the character scan to one short
+piece, with quote and substitution state carried across pieces in globals. The
+same command now takes ~250ms, and a typical one ~15ms — faster than the six
+`echo | grep` subprocesses it replaced.
+
+### Adding a rule
+
+Add a `check_<command>` function, dispatch to it from the `case` in
+`check_segment`, and add both directions to `.github/scripts/test-hooks.sh`: the
+command blocked, and a benign command that merely mentions it allowed. A rule
+without the second test is the defect this ADR exists to prevent.
+
+## Consequences
+
+### Positive
+
+- Mentions of destructive commands — in searches, comments, commit messages,
+  documentation, and heredoc scripts — no longer block work.
+- Coverage went up rather than down. `sudo rm -rf`, `/bin/rm -rf`,
+  `xargs rm -rf`, `find -exec rm -rf`, and `bash -lc '…'` are now recognised
+  as the commands they are.
+- Rules read as rules. `check_git`, `check_rm` and friends work on words and
+  flags, so the next rule is a `case` arm rather than another regex.
+- Faster in the common case: parsing happens in-process, with no subprocesses.
+
+### Negative
+
+- The guard is longer and is now a parser, which is a thing that can be wrong in
+  more ways than a regex can.
+- It approximates shell syntax. A `)` inside a quoted string inside a `$(...)`
+  body can still confuse the substitution scan.
+- Deliberate obfuscation still defeats it — `eval`, base64, a variable holding
+  the command name. This is a guardrail against accidents, not a sandbox.
+
+### Mitigations
+
+- `.github/scripts/test-hooks.sh` runs both directions of every rule on
+  windows-latest Git Bash, and shellcheck runs at `--severity=warning`.
+- Where the parse is uncertain the guard blocks rather than allows, keeping the
+  direction [#11] chose: over-block, never under-block.
+
+[#11]: https://github.com/codewithmukesh/dotnet-claude-kit/pull/11