fix(bootstrap): relax Read/Edit/Write path validation to match Claude Code (#9)

nnemirovsky · web-flow · commit 3060e2b87b5c · 2026-04-15T10:46:21.000+08:00
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "owner": {
     "name": "nnemirovsky"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "license": "MIT"
 }
diff --git a/README.md b/README.md
@@ -117,6 +117,13 @@ bash .../scripts/bootstrap.sh --write
 
 Regex metacharacters in the original path/prefix/name are escaped so the converted pattern matches literally. Anything that does not match one of the shapes above is skipped with a `[WARN]` line on stderr (for example, custom MCP tool patterns that do not start with `mcp__`, or a `WebFetch(...)` with a non-`domain:` argument).
 
+For `Read`, `Edit`, and `Write`, path acceptance mirrors Claude Code's own rules (`src/utils/permissions/pathValidation.ts`): redundant slash runs (`//foo`, `///foo/bar`) are collapsed to a single slash, `~/...` expands to `$HOME/...`, and paths with spaces or deep nesting are accepted. Only the shapes Claude Code itself rejects are skipped with a `[WARN]`:
+
+* shell / env expansion: `$VAR`, `${VAR}`, `$(cmd)`, `%VAR%`
+* zsh equals expansion: leading `=` (e.g. `=cmd`)
+* tilde variants other than `~/`: `~user`, `~+`, `~-`, `~N`
+* UNC paths: leading `\\server\share`
+
 Bootstrap writes to dedicated imported files so hand-curated rules in `passthru.json` stay separate:
 
 * `~/.claude/passthru.imported.json` (user scope)
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
@@ -26,6 +26,11 @@
 # Unknown shapes (rules with spaces past the prefix, unrecognized forms) are
 # skipped with a warning printed to stderr.
 #
+# Read/Edit/Write paths that use shell expansion (`$VAR`, `${VAR}`, `$(cmd)`,
+# `%VAR%`), zsh equals expansion (`=cmd`), tilde variants other than `~/`
+# (`~user`, `~+`, `~-`), or UNC (`\\server\share`) are skipped. This mirrors
+# Claude Code's own path validation rules.
+#
 # Flags:
 #   --write            actually write; default is a dry-run that prints JSON to stdout.
 #   --user-only        only scan/import user scope.
@@ -250,27 +255,90 @@ convert_rule() {
     # inner path for a trailing glob suffix (`/**` or `/*`). A glob suffix
     # means "anything under this directory"; without it the path is an
     # exact-file match.
+    #
+    # Acceptance mirrors Claude Code's actual path validation
+    # (src/utils/permissions/pathValidation.ts). Only the shapes that Claude
+    # Code itself rejects are skipped here:
+    #   * Unix shell expansion:   `$VAR`, `${VAR}`, `$(cmd)`
+    #   * Windows env expansion:  `%VAR%`
+    #   * Zsh equals expansion:   leading `=`
+    #   * Tilde variants other than `~/`: `~user`, `~+`, `~-`, bare `~`
+    #   * UNC paths:              leading `\\server\share`
+    # Everything else (including leading `//`, spaces, deeply nested paths)
+    # is accepted. Redundant `/` runs are normalized to a single `/` to
+    # mirror Node's `path.resolve()` output, which is what Claude Code
+    # ultimately compares against in the hook payload.
     local tool_name="${raw%%(*}"
     local inner="${raw#${tool_name}(}"
     inner="${inner%)}"
     if [ -z "$inner" ]; then
       printf '[WARN] skipping %s rule with empty path: %s\n' "$tool_name" "$raw" >&2
       return 0
     fi
+
+    # Shell / env expansion: `$`, `${...}`, `$(...)` anywhere in the path,
+    # or any `%...%` windows-style reference. Claude Code does not resolve
+    # these, so neither do we.
+    if [[ "$inner" == *'$'* ]] || [[ "$inner" == *'%'* ]]; then
+      printf '[WARN] skipping %s(%s): shell expansion syntax not supported\n' \
+        "$tool_name" "$inner" >&2
+      return 0
+    fi
+
+    # Zsh equals expansion: leading `=cmd` resolves against PATH, not
+    # handled by Claude Code.
+    if [[ "$inner" == =* ]]; then
+      printf '[WARN] skipping %s(%s): shell expansion syntax not supported\n' \
+        "$tool_name" "$inner" >&2
+      return 0
+    fi
+
+    # UNC paths. `containsVulnerableUncPath` in Claude Code rejects these.
+    if [[ "$inner" == '\\'* ]]; then
+      printf '[WARN] skipping %s(%s): UNC path not supported\n' \
+        "$tool_name" "$inner" >&2
+      return 0
+    fi
+
+    # Tilde variants. `~/...` and bare `~` are the only accepted forms -
+    # other variants (`~user`, `~+`, `~-`, `~N`) are left as literals by
+    # Claude Code and never match a resolved file_path in a hook payload.
+    # Convert `~/` and bare `~` to the current `$HOME` so the regex has a
+    # chance to match the already-resolved path the hook sees.
+    # NOTE: the `'~/'*` pattern below is a literal prefix match on the rule
+    # string (left-hand side), not a path we want tilde-expanded. ShellCheck's
+    # SC2088 flags any quoted `~` as "use $HOME", but here the tilde is
+    # intentional because we match the rule as the user wrote it.
+    if [[ "$inner" == '~' ]]; then
+      inner="$HOME"
+    elif [[ "${inner:0:2}" == "~/" ]]; then
+      inner="$HOME/${inner:2}"
+    elif [[ "${inner:0:1}" == "~" ]]; then
+      printf '[WARN] skipping %s(%s): tilde variant not supported\n' \
+        "$tool_name" "$inner" >&2
+      return 0
+    fi
+
+    # Collapse runs of `/` to a single `/`, matching Node's `path.resolve()`.
+    # Used on both the prefix form (before the trailing `/**`|`/*` is
+    # stripped) and the exact form.
+    local normalized
+    normalized="$(printf '%s' "$inner" | perl -pe 's|/{2,}|/|g')"
+
     local path_re
-    if [[ "$inner" == */\*\* ]]; then
-      local prefix="${inner%/\*\*}"
+    if [[ "$normalized" == */\*\* ]]; then
+      local prefix="${normalized%/\*\*}"
       local escaped
       escaped="$(regex_escape "$prefix")"
       path_re="^${escaped}(/|\$)"
-    elif [[ "$inner" == */\* ]]; then
-      local prefix="${inner%/\*}"
+    elif [[ "$normalized" == */\* ]]; then
+      local prefix="${normalized%/\*}"
       local escaped
       escaped="$(regex_escape "$prefix")"
       path_re="^${escaped}(/|\$)"
     else
       local escaped
-      escaped="$(regex_escape "$inner")"
+      escaped="$(regex_escape "$normalized")"
       path_re="^${escaped}\$"
     fi
     json="$(jq -cn \
diff --git a/tests/bootstrap.bats b/tests/bootstrap.bats
@@ -123,8 +123,8 @@ run_boot() {
   [ "$status" -eq 0 ]
   [ -f "$(proj_imported)" ]
   run jq -r '.allow | length' "$(proj_imported)"
-  # fixture has 18 entries, 1 skipped (ExactStrangeFormat) -> 17 kept
-  [ "$output" = "17" ]
+  # fixture has 19 entries, 1 skipped (ExactStrangeFormat) -> 18 kept
+  [ "$output" = "18" ]
 }
 
 @test "bootstrap: dry-run output matches --write file content (schema-wise)" {
@@ -624,3 +624,183 @@ EOF
   [[ "$output" == *'^Skill$'* ]]
   [[ "$output" == *'^mcp__context7__query\-docs$'* ]]
 }
+
+# ---------------------------------------------------------------------------
+# Read/Edit/Write path normalization: leading `//` collapses to a single `/`,
+# matching Node's `path.resolve()` behaviour in Claude Code. Previously the
+# converter treated `Read(//...)` as "unusual" and skipped it. The hook
+# payload always carries a resolved, single-slash path, so a rule generated
+# from a `//...` entry would never match unless we normalize at import time.
+# ---------------------------------------------------------------------------
+
+@test "bootstrap: Read(//private/tmp/foo/**) normalizes to single leading slash" {
+  printf '{"permissions":{"allow":["Read(//private/tmp/foo/**)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "1" ]
+  pat="$(jq -r '.allow[0].match.file_path' "$(user_imported)")"
+  # The resulting regex must NOT carry two leading slashes (`regex_escape`
+  # would emit `\/\/` for the unnormalized form).
+  [[ "$pat" != *'\/\/'* ]]
+  # Must match the single-slash form Claude Code passes to the hook after
+  # Node's `path.resolve()` normalization, and everything under it.
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/private/tmp/foo' "$pat"
+  [ "$status" -eq 0 ]
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/private/tmp/foo/bar' "$pat"
+  [ "$status" -eq 0 ]
+  # Must NOT match a sibling that only shares the prefix literally.
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/private/tmp/foobar' "$pat"
+  [ "$status" -ne 0 ]
+}
+
+@test "bootstrap: Read(///deeply/nested/**) collapses all redundant slashes" {
+  printf '{"permissions":{"allow":["Read(///deeply/nested/**)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  pat="$(jq -r '.allow[0].match.file_path' "$(user_imported)")"
+  # No repeated escaped slashes should remain - normalization happens before
+  # the path gets escaped.
+  [[ "$pat" != *'\/\/'* ]]
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/deeply/nested/x' "$pat"
+  [ "$status" -eq 0 ]
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/deeply/nested' "$pat"
+  [ "$status" -eq 0 ]
+}
+
+@test "bootstrap: Read path with embedded double slash is normalized" {
+  printf '{"permissions":{"allow":["Read(/a//b/c)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  pat="$(jq -r '.allow[0].match.file_path' "$(user_imported)")"
+  # Embedded `//` collapses to single `/` before regex escaping.
+  [[ "$pat" != *'\/\/'* ]]
+  # The resulting (exact-form) regex matches the single-slash literal path.
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/a/b/c' "$pat"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Read/Edit/Write skip cases that mirror Claude Code's own rejection rules.
+# ---------------------------------------------------------------------------
+
+@test "bootstrap: Read(~user/.ssh) skipped (tilde variant not supported)" {
+  printf '{"permissions":{"allow":["Read(~user/.ssh)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"tilde variant not supported"* ]]
+  [[ "$output" == *"~user/.ssh"* ]]
+  # --write should produce an empty allow list (rule was skipped).
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "0" ]
+}
+
+@test "bootstrap: Read(~+) and Read(~-) skipped (tilde variants)" {
+  printf '{"permissions":{"allow":["Read(~+)","Read(~-)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"tilde variant not supported"* ]]
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "0" ]
+}
+
+@test "bootstrap: Read(~/foo) expands to \$HOME/foo (bare ~/ is accepted)" {
+  printf '{"permissions":{"allow":["Read(~/foo/**)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "1" ]
+  pat="$(jq -r '.allow[0].match.file_path' "$(user_imported)")"
+  # The resolved path should start with the current HOME and end with the
+  # prefix-form suffix.
+  [[ "$pat" == "^"*"/foo(/|\$)" ]]
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' "$HOME/foo" "$pat"
+  [ "$status" -eq 0 ]
+}
+
+@test "bootstrap: Read(\$HOME/x) skipped (shell expansion syntax)" {
+  printf '{"permissions":{"allow":["Read($HOME/x)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"shell expansion syntax not supported"* ]]
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "0" ]
+}
+
+@test "bootstrap: Read(\${HOME}/x) and Read(\$(pwd)/x) skipped (shell expansion)" {
+  cat > "$USER_ROOT/.claude/settings.json" <<'EOF'
+{"permissions":{"allow":["Read(${HOME}/x)","Read($(pwd)/x)"]}}
+EOF
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"shell expansion syntax not supported"* ]]
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "0" ]
+}
+
+@test "bootstrap: Read(%APPDATA%) skipped (windows env expansion)" {
+  printf '{"permissions":{"allow":["Read(%%APPDATA%%/foo)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"shell expansion syntax not supported"* ]]
+}
+
+@test "bootstrap: Read(=cmd) skipped (zsh equals expansion)" {
+  printf '{"permissions":{"allow":["Read(=cmd)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"shell expansion syntax not supported"* ]]
+}
+
+@test "bootstrap: Read(\\\\server\\share) skipped (UNC path)" {
+  # Feed a literal two-backslash `\\server\share` via a file (bash printf is
+  # too fiddly for doubled backslashes in JSON).
+  cat > "$USER_ROOT/.claude/settings.json" <<'EOF'
+{"permissions":{"allow":["Read(\\\\server\\share)"]}}
+EOF
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"UNC path not supported"* ]]
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "0" ]
+}
+
+@test "bootstrap: Edit and Write honor the same skip rules as Read" {
+  cat > "$USER_ROOT/.claude/settings.json" <<'EOF'
+{"permissions":{"allow":["Edit($HOME/x)","Write(=foo)"]}}
+EOF
+  run bash -c "bash '$BOOTSTRAP' --user-only 2>&1 >/dev/null"
+  [[ "$output" == *"Edit("* ]]
+  [[ "$output" == *"Write("* ]]
+  [[ "$output" == *"shell expansion syntax not supported"* ]]
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "0" ]
+}
+
+@test "bootstrap: Read(/path/with spaces/**) accepted (spaces are not a reject reason)" {
+  # Claude Code accepts paths with spaces; only shell-expansion, tilde
+  # variants, and UNC are rejected. Verify the converter keeps this entry.
+  printf '{"permissions":{"allow":["Read(/path/with spaces/**)"]}}\n' \
+    > "$USER_ROOT/.claude/settings.json"
+  run_boot --user-only --write
+  [ "$status" -eq 0 ]
+  run jq -r '.allow | length' "$(user_imported)"
+  [ "$output" = "1" ]
+  pat="$(jq -r '.allow[0].match.file_path' "$(user_imported)")"
+  run perl -e 'exit(1) unless $ARGV[0] =~ /$ARGV[1]/' '/path/with spaces/file' "$pat"
+  [ "$status" -eq 0 ]
+}
diff --git a/tests/fixtures/settings-with-allow.json b/tests/fixtures/settings-with-allow.json
@@ -14,6 +14,7 @@
       "Bash(npm run test:unit)",
       "WebSearch",
       "Read(/private/tmp/ios-webkit-debug-proxy/**)",
+      "Read(//private/tmp/double-slash-normalized/**)",
       "Read(/etc/hosts)",
       "Edit(/var/log/app.log)",
       "Write(/tmp/out/**)",

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "passthru",`
`3`		`- "version": "0.3.0",`
	`3`	`+ "version": "0.3.1",`
`4`	`4`	`"description": "Regex-based permission rules for Claude Code via hooks",`
`5`	`5`	`"owner": {`
`6`	`6`	`"name": "nnemirovsky"`