fix: use hookSpecificOutput envelope + careful-active state guard (#1459 Bugs 2+3)

Bug 3: check-freeze.sh and check-careful.sh were returning a flat
{"permissionDecision":"deny","message":"..."} object. Claude Code requires
the hookSpecificOutput envelope:
  {"hookSpecificOutput":{"hookEventName":"PreToolUse",
    "permissionDecision":"deny","permissionDecisionReason":"..."}}
Without the wrapper the decision is silently ignored and the tool executes.

Bug 2 (careful side): check-careful.sh now checks for
~/.gstack/careful-active.txt before inspecting any command; it is a no-op
when /careful has not been invoked. careful/SKILL.md now writes that file
on activation and explains how to clear it. This makes the globally-
registered hook safe to leave in settings.json permanently.

check-freeze.sh also resolves its state-root via gstack-paths so it
honours GSTACK_HOME in addition to CLAUDE_PLUGIN_DATA / $HOME/.gstack.

Tests: all careful tests now use withCarefulActive() and pass
CLAUDE_PLUGIN_DATA to the hook. freeze and careful tests assert the new
hookSpecificOutput shape. Two new freeze tests verify the envelope format
and confirm allow responses remain plain {}.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: NikhileshNanduri

careful/SKILL.md

@@ -36,6 +36,15 @@ mkdir -p ~/.gstack/analytics
 echo '{"skill":"careful","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}'  >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
 ```
 
+Activate the careful guard (writes the state file that check-careful.sh checks):
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
+mkdir -p "$GSTACK_STATE_ROOT"
+touch "$GSTACK_STATE_ROOT/careful-active.txt"
+echo "CAREFUL_STATE: $GSTACK_STATE_ROOT/careful-active.txt"
+```
+
 ## What's protected
 
 | Pattern | Example | Risk |
@@ -60,4 +69,13 @@ The hook reads the command from the tool input JSON, checks it against the
 patterns above, and returns `permissionDecision: "ask"` with a warning message
 if a match is found. You can always override the warning and proceed.
 
-To deactivate, end the conversation or start a new one. Hooks are session-scoped.
+The hook is registered globally at install time but is a no-op unless
+`~/.gstack/careful-active.txt` exists. The file is created when `/careful` is
+invoked and deleted when the session ends or when the user explicitly removes it.
+
+To deactivate, run:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
+rm -f "$GSTACK_STATE_ROOT/careful-active.txt"
+echo "careful guardrails deactivated"
+```

careful/SKILL.md.tmpl

@@ -35,6 +35,15 @@ mkdir -p ~/.gstack/analytics
 echo '{"skill":"careful","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}'  >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
 ```
 
+Activate the careful guard (writes the state file that check-careful.sh checks):
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
+mkdir -p "$GSTACK_STATE_ROOT"
+touch "$GSTACK_STATE_ROOT/careful-active.txt"
+echo "CAREFUL_STATE: $GSTACK_STATE_ROOT/careful-active.txt"
+```
+
 ## What's protected
 
 | Pattern | Example | Risk |
@@ -59,4 +68,13 @@ The hook reads the command from the tool input JSON, checks it against the
 patterns above, and returns `permissionDecision: "ask"` with a warning message
 if a match is found. You can always override the warning and proceed.
 
-To deactivate, end the conversation or start a new one. Hooks are session-scoped.
+The hook is registered globally at install time but is a no-op unless
+`~/.gstack/careful-active.txt` exists. The file is created when `/careful` is
+invoked and deleted when the session ends or when the user explicitly removes it.
+
+To deactivate, run:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
+rm -f "$GSTACK_STATE_ROOT/careful-active.txt"
+echo "careful guardrails deactivated"
+```

careful/bin/check-careful.sh

@@ -1,9 +1,32 @@
 #!/usr/bin/env bash
 # check-careful.sh — PreToolUse hook for /careful skill
 # Reads JSON from stdin, checks Bash command for destructive patterns.
-# Returns {"permissionDecision":"ask","message":"..."} to warn, or {} to allow.
+# Returns hookSpecificOutput with permissionDecision "ask" to warn, or {} to allow.
 set -euo pipefail
 
+# Resolve state root (consistent with freeze and gstack-paths)
+_PATHS_BIN=""
+for _p in \
+    "${CLAUDE_SKILL_DIR:-}/../gstack/bin/gstack-paths" \
+    "$HOME/.claude/skills/gstack/bin/gstack-paths"; do
+  [ -x "$_p" ] && { _PATHS_BIN="$_p"; break; }
+done
+
+if [ -n "$_PATHS_BIN" ]; then
+  eval "$("$_PATHS_BIN" 2>/dev/null)" 2>/dev/null || true
+  _STATE_DIR="${GSTACK_STATE_ROOT:-${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}}"
+else
+  _STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+fi
+
+# No-op unless /careful has been activated (wrote careful-active.txt)
+# This allows the hook to be registered globally without interfering in
+# sessions where /careful was never invoked.
+if [ ! -f "$_STATE_DIR/careful-active.txt" ]; then
+  echo '{}'
+  exit 0
+fi
+
 # Read stdin (JSON with tool_input)
 INPUT=$(cat)
 
@@ -106,7 +129,7 @@ if [ -n "$WARN" ]; then
   echo '{"event":"hook_fire","skill":"careful","pattern":"'"$PATTERN"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
 
   WARN_ESCAPED=$(printf '%s' "$WARN" | sed 's/"/\\"/g')
-  printf '{"permissionDecision":"ask","message":"[careful] %s"}\n' "$WARN_ESCAPED"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"[careful] %s"}}\n' "$WARN_ESCAPED"
 else
   echo '{}'
 fi

freeze/SKILL.md

@@ -74,10 +74,12 @@ again. To remove it, run `/unfreeze` or end the session."
 
 The hook reads `file_path` from the Edit/Write tool input JSON, then checks
 whether the path starts with the freeze directory. If not, it returns
-`permissionDecision: "deny"` to block the operation.
+a `hookSpecificOutput` deny decision to block the operation.
 
-The freeze boundary persists for the session via the state file. The hook
-script reads it on every Edit/Write invocation.
+The hook is registered globally in `~/.claude/settings.json` by the gstack
+installer. It is a no-op when no freeze state file exists, so it does not
+interfere in sessions where `/freeze` has not been invoked. The freeze
+boundary persists via the state file; `/unfreeze` clears it.
 
 ## Notes
 

freeze/SKILL.md.tmpl

@@ -73,10 +73,12 @@ again. To remove it, run `/unfreeze` or end the session."
 
 The hook reads `file_path` from the Edit/Write tool input JSON, then checks
 whether the path starts with the freeze directory. If not, it returns
-`permissionDecision: "deny"` to block the operation.
+a `hookSpecificOutput` deny decision to block the operation.
 
-The freeze boundary persists for the session via the state file. The hook
-script reads it on every Edit/Write invocation.
+The hook is registered globally in `~/.claude/settings.json` by the gstack
+installer. It is a no-op when no freeze state file exists, so it does not
+interfere in sessions where `/freeze` has not been invoked. The freeze
+boundary persists via the state file; `/unfreeze` clears it.
 
 ## Notes
 

freeze/bin/check-freeze.sh

@@ -1,14 +1,28 @@
 #!/usr/bin/env bash
 # check-freeze.sh — PreToolUse hook for /freeze skill
 # Reads JSON from stdin, checks if file_path is within the freeze boundary.
-# Returns {"permissionDecision":"deny","message":"..."} to block, or {} to allow.
+# Returns hookSpecificOutput with permissionDecision "deny" to block, or {} to allow.
 set -euo pipefail
 
 # Read stdin
 INPUT=$(cat)
 
-# Locate the freeze directory state file
-STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+# Locate the freeze directory state file via gstack-paths for consistent resolution
+# across GSTACK_HOME / CLAUDE_PLUGIN_DATA / $HOME/.gstack fallback chain.
+_PATHS_BIN=""
+for _p in \
+    "${CLAUDE_SKILL_DIR:-}/../gstack/bin/gstack-paths" \
+    "$HOME/.claude/skills/gstack/bin/gstack-paths"; do
+  [ -x "$_p" ] && { _PATHS_BIN="$_p"; break; }
+done
+
+if [ -n "$_PATHS_BIN" ]; then
+  eval "$("$_PATHS_BIN" 2>/dev/null)" 2>/dev/null || true
+  STATE_DIR="${GSTACK_STATE_ROOT:-${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}}"
+else
+  STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+fi
+
 FREEZE_FILE="$STATE_DIR/freeze-dir.txt"
 
 # If no freeze file exists, allow everything (not yet configured)
@@ -74,6 +88,7 @@ case "$FILE_PATH" in
     mkdir -p ~/.gstack/analytics 2>/dev/null || true
     echo '{"event":"hook_fire","skill":"freeze","pattern":"boundary_deny","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
 
-    printf '{"permissionDecision":"deny","message":"[freeze] Blocked: %s is outside the freeze boundary (%s). Only edits within the frozen directory are allowed."}\n' "$FILE_PATH" "$FREEZE_DIR"
+    _REASON=$(printf '[freeze] Blocked: %s is outside the freeze boundary (%s). Only edits within the frozen directory are allowed.' "$FILE_PATH" "$FREEZE_DIR" | sed 's/"/\\"/g')
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$_REASON"
     ;;
 esac