fix(hint): re-fire bootstrap hint until all settings entries imported (#12)

Author: nnemirovsky

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "owner": {
     "name": "nnemirovsky"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "license": "MIT"
 }

CLAUDE.md

@@ -31,9 +31,10 @@ hooks/
   handlers/
     pre-tool-use.sh    main hook: loads rules, matches, emits allow/deny/passthrough
     post-tool-use.sh   classifies native-dialog outcomes into asked_* events (audit only)
-    session-start.sh   one-time bootstrap hint. Gated by ~/.claude/passthru.bootstrap-hint-shown
-                       marker. Prints to stderr only when the user has no passthru files yet
-                       AND has importable entries in ~/.claude/settings.json.
+    session-start.sh   bootstrap hint. Re-fires every session while importable entries in
+                       settings.json / settings.local.json are not yet covered by
+                       _source_hash values in passthru.imported.json. Hash diff replaces
+                       the old one-shot marker. Auto-silences when migration is complete.
 scripts/
   bootstrap.sh         one-time importer from native permissions.allow into passthru.imported.json.
                        Supported shapes: Bash(prefix:*) | Bash(exact) | mcp__* | WebFetch(domain:X)

docs/plans/20260415-overlay-and-ask-support.md

@@ -304,21 +304,21 @@ No marker file needed. Hint auto-silences when all settings entries are imported
 - Modify: `docs/rule-format.md` (document `_source_hash` field on imported rules)
 - Modify: `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` (0.4.0 -> 0.4.1)
 
-- [ ] extract `is_importable_entry <raw>` predicate from `bootstrap.sh` into `common.sh`. Both converter and hint helper use it. Single source of truth for "can bootstrap convert this entry"
-- [ ] add `normalize_settings_entry <entry>` helper in `common.sh`: trim leading/trailing whitespace only. No lowercasing, no path collapsing. Match CC's native parser exactly
-- [ ] add `hash_settings_entry <entry>` that emits sha256 of normalized form
-- [ ] add `settings_importable_hashes` that scans all settings files, uses `is_importable_entry` to filter, emits hash set one per line
-- [ ] add `imported_hashes` that reads all passthru.imported.json files and emits every present `_source_hash` value (missing fields contribute no hash)
-- [ ] modify `scripts/bootstrap.sh` to embed `_source_hash` in each rule it writes during `--write`
-- [ ] modify `session-start.sh`: replace the marker-file gate with a diff (`settings_importable_hashes - imported_hashes`). Fire the hint with the un-imported count. Remove marker touch entirely. Legacy migration: rules without `_source_hash` contribute nothing to imported_hashes, so the hint fires until the user re-runs `/passthru:bootstrap` which rewrites the file with hashes
-- [ ] remove the marker-touch logic from `session-start.sh` (dead code after this change)
-- [ ] add bats: bootstrap run produces rules with `_source_hash`; re-running bootstrap is idempotent (hashes stable); settings with no matching imported entries -> hint fires with correct count; settings fully covered -> no hint; legacy imported file (rules without `_source_hash`) + settings with entries -> hint fires (honest migration); post-bootstrap run -> hint silences
-- [ ] run `bats tests/*.bats` - must pass
-- [ ] bump version to 0.4.1 in both manifests
-- [ ] update CHANGELOG or release notes text in README if it has one; otherwise rely on gh release --generate-notes
-- [ ] commit + open PR: `fix(hint): re-fire bootstrap hint until all settings entries imported`
-- [ ] **PROMPT USER** to test locally BEFORE merge: `claude --plugin-dir /Users/nemirovsky/Developer/claude-passthru` in a session with importable settings entries. Verify hint fires with correct count, re-running bootstrap silences it. User confirms or flags issues
-- [ ] after user-confirmed local verification + CI green: merge PR, tag v0.4.1, release
+- [x] extract `is_importable_entry <raw>` predicate from `bootstrap.sh` into `common.sh`. Both converter and hint helper use it. Single source of truth for "can bootstrap convert this entry"
+- [x] add `normalize_settings_entry <entry>` helper in `common.sh`: trim leading/trailing whitespace only. No lowercasing, no path collapsing. Match CC's native parser exactly
+- [x] add `hash_settings_entry <entry>` that emits sha256 of normalized form
+- [x] add `settings_importable_hashes` that scans all settings files, uses `is_importable_entry` to filter, emits hash set one per line
+- [x] add `imported_hashes` that reads all passthru.imported.json files and emits every present `_source_hash` value (missing fields contribute no hash)
+- [x] modify `scripts/bootstrap.sh` to embed `_source_hash` in each rule it writes during `--write`
+- [x] modify `session-start.sh`: replace the marker-file gate with a diff (`settings_importable_hashes - imported_hashes`). Fire the hint with the un-imported count. Remove marker touch entirely. Legacy migration: rules without `_source_hash` contribute nothing to imported_hashes, so the hint fires until the user re-runs `/passthru:bootstrap` which rewrites the file with hashes
+- [x] remove the marker-touch logic from `session-start.sh` (dead code after this change)
+- [x] add bats: bootstrap run produces rules with `_source_hash`; re-running bootstrap is idempotent (hashes stable); settings with no matching imported entries -> hint fires with correct count; settings fully covered -> no hint; legacy imported file (rules without `_source_hash`) + settings with entries -> hint fires (honest migration); post-bootstrap run -> hint silences
+- [x] run `bats tests/*.bats` - must pass
+- [x] bump version to 0.4.1 in both manifests
+- [x] update CHANGELOG or release notes text in README if it has one; otherwise rely on gh release --generate-notes
+- [x] commit + open PR: `fix(hint): re-fire bootstrap hint until all settings entries imported`
+- [x] auto-merged, user to test post-release (policy: auto-merge after CI green)
+- [x] after user-confirmed local verification + CI green: merge PR, tag v0.4.1, release
 
 ### Task 2: PostToolUseFailure handler (ship as v0.4.2 patch)
 

docs/rule-format.md

@@ -79,6 +79,12 @@ Absent `match` (or an empty object) matches any input, so the rule reduces to a
 
 Human-readable note describing why the rule exists. The hook surfaces it in the `permissionDecisionReason` field Claude Code shows. Purely documentation for you. The verifier does not check it.
 
+### `_source_hash` (string, optional)
+
+SHA-256 hex digest of the original `permissions.allow` entry that a given rule was imported from. Present only on rules written by `scripts/bootstrap.sh`. You never need to set this by hand, and you should not edit it. The session-start bootstrap hint uses this field to compute the diff between entries in `settings.json` and rules already in `passthru.imported.json`: a rule carries `_source_hash` iff bootstrap has imported the corresponding native entry.
+
+Legacy `passthru.imported.json` files from before this field existed have no hashes. In that case the hint re-fires every session until you re-run `/passthru:bootstrap`, which rewrites the file with hashes attached. After that the hint auto-silences as intended.
+
 ## Example rules
 
 **Allow `gh api /repos/*/*/forks` across any owner/repo:**

hooks/common.sh

@@ -91,6 +91,191 @@ audit_enabled() {
   [ -e "$sentinel" ]
 }
 
+# ---------------------------------------------------------------------------
+# Settings entry helpers (used by bootstrap + session-start hint)
+# ---------------------------------------------------------------------------
+#
+# is_importable_entry <raw>
+#   Returns 0 if bootstrap.sh's `convert_rule` would produce a rule for the
+#   given native permission entry. Returns 1 otherwise. Single source of
+#   truth so the session-start hash diff never drifts from what bootstrap
+#   actually imports. Intentionally silent: no stdout, no stderr.
+#
+# Shapes accepted (must match convert_rule in scripts/bootstrap.sh):
+#   Bash(<prefix>:*)                  -> importable when prefix non-empty
+#   Bash(<exact command>)             -> importable when no embedded newline
+#   WebFetch(domain:<domain>)         -> importable when domain non-empty
+#   WebSearch                         -> importable (bare)
+#   mcp__...                          -> importable when no parens
+#   Read/Edit/Write(<path>[/**|/*])   -> importable when path passes
+#                                       bootstrap's path-shape checks
+#   Skill(<name>)                     -> importable when name non-empty
+#
+# Anything else returns 1.
+is_importable_entry() {
+  local raw="$1"
+
+  # Trim whitespace (mirrors convert_rule).
+  raw="${raw#"${raw%%[![:space:]]*}"}"
+  raw="${raw%"${raw##*[![:space:]]}"}"
+
+  [ -z "$raw" ] && return 1
+
+  # Bash(...)
+  if [[ "$raw" == Bash\(*\) ]]; then
+    local inner="${raw#Bash(}"
+    inner="${inner%)}"
+    if [[ "$inner" == *:\* ]]; then
+      local prefix="${inner%:\*}"
+      [ -z "$prefix" ] && return 1
+      return 0
+    fi
+    # Exact Bash command: reject embedded newline.
+    [[ "$inner" == *$'\n'* ]] && return 1
+    return 0
+  fi
+
+  # WebFetch(domain:...)
+  if [[ "$raw" == WebFetch\(domain:*\) ]]; then
+    local domain="${raw#WebFetch(domain:}"
+    domain="${domain%)}"
+    domain="${domain#"${domain%%[![:space:]]*}"}"
+    domain="${domain%"${domain##*[![:space:]]}"}"
+    [ -z "$domain" ] && return 1
+    return 0
+  fi
+
+  # WebFetch(...) other than domain form: unsupported.
+  if [[ "$raw" == WebFetch\(*\) ]]; then
+    return 1
+  fi
+
+  # mcp__... (no parens)
+  if [[ "$raw" == mcp__* ]]; then
+    [[ "$raw" == *"("* ]] && return 1
+    [[ "$raw" == *")"* ]] && return 1
+    return 0
+  fi
+
+  # WebSearch (bare)
+  if [ "$raw" = "WebSearch" ]; then
+    return 0
+  fi
+
+  # Read/Edit/Write(<path>)
+  if [[ "$raw" == Read\(*\) ]] || [[ "$raw" == Edit\(*\) ]] || [[ "$raw" == Write\(*\) ]]; then
+    local tool_name="${raw%%(*}"
+    local inner="${raw#${tool_name}(}"
+    inner="${inner%)}"
+    [ -z "$inner" ] && return 1
+    # Shell / env expansion syntax: $, ${}, $(), %VAR%.
+    [[ "$inner" == *'$'* ]] && return 1
+    [[ "$inner" == *'%'* ]] && return 1
+    # Leading = (zsh equals expansion).
+    [[ "$inner" == =* ]] && return 1
+    # UNC path.
+    [[ "$inner" == '\\'* ]] && return 1
+    # Tilde variants other than `~/` and bare `~`.
+    if [ "$inner" = '~' ]; then
+      return 0
+    fi
+    if [ "${inner:0:2}" = "~/" ]; then
+      return 0
+    fi
+    if [ "${inner:0:1}" = "~" ]; then
+      return 1
+    fi
+    return 0
+  fi
+
+  # Skill(<name>)
+  if [[ "$raw" == Skill\(*\) ]]; then
+    local name="${raw#Skill(}"
+    name="${name%)}"
+    name="${name#"${name%%[![:space:]]*}"}"
+    name="${name%"${name##*[![:space:]]}"}"
+    [ -z "$name" ] && return 1
+    return 0
+  fi
+
+  return 1
+}
+
+# normalize_settings_entry <entry>
+#   Emits the entry with leading/trailing whitespace stripped. No lowercasing
+#   (Claude Code's permission parser is case-sensitive - `Bash` != `bash`),
+#   no path collapsing, no reformatting. The single contract: two entries
+#   that differ only by surrounding whitespace hash identically.
+normalize_settings_entry() {
+  local s="$1"
+  s="${s#"${s%%[![:space:]]*}"}"
+  s="${s%"${s##*[![:space:]]}"}"
+  printf '%s' "$s"
+}
+
+# hash_settings_entry <entry>
+#   Emits sha256 hex of normalize_settings_entry(<entry>) on stdout.
+#   Empty on error (missing hashing tools). Uses the same shasum/sha256sum
+#   detection as passthru_sha256 but hashes stdin content instead of a path.
+hash_settings_entry() {
+  local normalized
+  normalized="$(normalize_settings_entry "$1")"
+  if command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$normalized" | shasum -a 256 2>/dev/null | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$normalized" | sha256sum 2>/dev/null | awk '{print $1}'
+  fi
+}
+
+# settings_importable_hashes
+#   Scans every settings file (user + project shared/local) and emits one
+#   hash per line for each `permissions.allow[]` string that passes
+#   `is_importable_entry`. No output for missing files or empty allow
+#   arrays. Malformed JSON files are silently skipped - the session-start
+#   handler's job is nudging, not fault-reporting.
+settings_importable_hashes() {
+  local user_home project_dir
+  user_home="$(passthru_user_home)"
+  project_dir="${PASSTHRU_PROJECT_DIR:-$PWD}"
+
+  local files=(
+    "$user_home/.claude/settings.json"
+    "$project_dir/.claude/settings.json"
+    "$project_dir/.claude/settings.local.json"
+  )
+
+  local f entry
+  for f in "${files[@]}"; do
+    [ -f "$f" ] || continue
+    # Parse check is implicit: jq's error path returns no rows.
+    # Only string entries count (matches bootstrap's filter).
+    while IFS= read -r entry || [ -n "$entry" ]; do
+      [ -z "$entry" ] && continue
+      if is_importable_entry "$entry"; then
+        hash_settings_entry "$entry"
+      fi
+    done < <(jq -r '(.permissions.allow // []) | map(select(type == "string")) | .[]' "$f" 2>/dev/null)
+  done
+}
+
+# imported_hashes
+#   Scans every passthru.imported.json file (user + project) and emits each
+#   present `_source_hash` value on its own line. Rules without the field
+#   contribute nothing (legacy pre-hash files silently force the hint to
+#   re-fire until bootstrap rewrites them).
+imported_hashes() {
+  local user_imported project_imported
+  user_imported="$(passthru_user_imported_path)"
+  project_imported="$(passthru_project_imported_path)"
+
+  local f
+  for f in "$user_imported" "$project_imported"; do
+    [ -f "$f" ] || continue
+    jq -r '(.allow // []) | map(select(._source_hash != null and (._source_hash | type == "string"))) | .[]._source_hash' \
+      "$f" 2>/dev/null
+  done
+}
+
 # audit_log_path: path to ~/.claude/passthru-audit.log (may not exist).
 audit_log_path() {
   printf '%s/.claude/passthru-audit.log\n' "$(passthru_user_home)"