#!/usr/bin/env bash
set -euo pipefail

# workspace-guard.sh
# Intercepts PreToolUse events to block access to sensitive paths and variables

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
INPUT_PATH=$(echo "$INPUT" | jq -r '.tool_input.path // empty')
INPUT_CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Default deny patterns (customizable via environment variables)
DENY_PATHS="${GUARD_DENY_PATHS:-\.env$|\.env\.[a-z]+$|credentials\.json|aws-credentials|ansible-vault|\.pem$|\.key$}"
DENY_VARS="${GUARD_DENY_VARS:-TOKEN|PASSWORD|SECRET|API_KEY|JWT|PRIVATE_KEY}"

BLOCKED=false
REASON=""

# Evaluate file path access
if [[ -n "$INPUT_PATH" ]]; then
  if echo "$INPUT_PATH" | grep -Eqi "$DENY_PATHS"; then
    BLOCKED=true
    REASON="Path matches sensitive pattern: $INPUT_PATH"
  fi
fi

# Evaluate command execution for credential exposure
if [[ -n "$INPUT_CMD" ]] && [[ "$TOOL_NAME" == "Bash" ]]; then
  if echo "$INPUT_CMD" | grep -Eqi "cat.*\.env|env\s+|printenv|aws\s+configure|vault\s+read"; then
    BLOCKED=true
    REASON="Command attempts to expose credentials or environment state"
  fi

fi

Evaluate environment variable references in tool input

if echo "$INPUT" | grep -Eqi "$DENY_VARS"; then BLOCKED=true REASON="Tool input contains restricted credential pattern" fi

Construct response

if [[ "$BLOCKED" == true ]]; then echo "{"allow": false, "reason": "$REASON"}" | jq . exit 1 else echo "{"allow": true}" | jq . exit 0 fi

**Rationale**: 
- `set -euo pipefail` ensures strict error handling. A failed `jq` parse or unset variable immediately halts execution, preventing silent allow decisions.
- Environment variable overrides (`GUARD_DENY_PATHS`, `GUARD_DENY_VARS`) enable project-specific tuning without modifying the script.
- Separating path evaluation from command evaluation prevents false positives on legitimate `grep` or `find` operations that don't target credential stores.
- JSON output is piped through `jq .` to guarantee valid formatting, regardless of shell quoting edge cases.

### Implementation: Workflow Completion Signal

The following script listens for the `Stop` event and dispatches a desktop notification. It includes WSL/Linux display server fallback logic and macOS native integration.

```bash
#!/usr/bin/env bash
set -euo pipefail

# turn-completion-alert.sh
# Fires desktop notification when Claude Code finishes a turn

INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
TOOL_COUNT=$(echo "$INPUT" | jq -r '.tool_use_count // 0')

# Determine OS and dispatch notification
if [[ "$(uname)" == "Darwin" ]]; then
  osascript -e "display notification \"Session $SESSION_ID completed ($TOOL_COUNT tools)\" with title \"Claude Code Workflow\""
elif command -v notify-send &> /dev/null; then
  # Handle WSL display server or native Linux
  if [[ -n "${WSL_DISTRO_NAME:-}" ]]; then
    export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
  fi
  notify-send "Claude Code" "Turn complete | Session: $SESSION_ID | Tools: $TOOL_COUNT" --icon=dialog-information
else
  # Fallback: terminal bell + log
  echo -e "\a"
  echo "[ALERT] Session $SESSION_ID finished at $(date -u +%H:%M:%S)" >> ~/.claude-hooks.log
fi

exit 0

Rationale:

• WSL requires explicit DISPLAY variable configuration to route notifications to the Windows notification center. The script dynamically resolves the WSL nameserver IP.
• notify-send is wrapped in a command existence check to prevent failures on minimal containers.
• The fallback mechanism ensures visibility even in headless or restricted environments.
• Exit code 0 is mandatory for Stop events; blocking termination would break the host process lifecycle.

Pitfall Guide

1. Ignoring the stdin/stdout JSON Contract

Explanation: Hooks that print debug messages, stack traces, or unformatted text to stdout will corrupt the JSON response. Claude Code expects strictly valid JSON. Any deviation causes silent hook failure or host process termination. Fix: Always pipe output through jq . or a JSON serializer. Redirect logs to stderr (>&2) or dedicated files. Never mix diagnostic output with the response payload.

2. Overly Broad Regex Patterns

Explanation: Patterns like .*key.* or .*secret.* will match legitimate files like public-key.pem, feature-key-config.json, or secret-manager-client.ts. This creates false positives that block development workflows. Fix: Anchor patterns to file extensions and directory structures. Use negative lookahead where supported. Maintain an explicit allowlist for known safe paths and test patterns against a sample repository before deployment.

3. Missing Executable Permissions

Explanation: Claude Code invokes hooks as subprocesses. Without the execute bit set, the host process receives a permission denied error and falls back to default behavior, silently bypassing security controls. Fix: Always run chmod +x .claude/hooks/*.sh after deployment. Include permission verification in your project's setup script or CI pipeline.

4. Blocking Critical Tool Chains

Explanation: Overly aggressive PreToolUse blocks can interrupt multi-step operations. For example, blocking Read on a configuration file may prevent a subsequent Edit or Bash command from executing, leaving the workspace in an inconsistent state. Fix: Implement granular allow/deny logic. Log blocked attempts with context. Use session-scoped allowlists for temporary overrides during refactoring or migration tasks.

5. WSL/Linux Display Server Misconfiguration

Explanation: Desktop notifications fail silently in WSL2 or headless Linux environments because the D-Bus session bus or X11/Wayland display server is not accessible. Developers assume the hook failed rather than recognizing the environment limitation. Fix: Detect WSL_DISTRO_NAME and configure DISPLAY dynamically. Provide terminal-based fallbacks (bell character, log file, or webhook). Document environment requirements in project READMEs.

6. Hardcoding Absolute Paths

Explanation: Hooks that reference /home/user/project/.env break when cloned to different directories, CI runners, or containerized environments. This destroys portability and increases maintenance overhead. Fix: Use relative path resolution, environment variables, or project root detection (git rev-parse --show-toplevel). Design hooks to be workspace-agnostic.

7. Misinterpreting Exit Code Semantics

Explanation: Developers sometimes return exit 0 for blocked operations or exit 1 for allowed ones. Claude Code strictly interprets 0 as allow and non-zero as deny. Inverted logic creates security bypasses or workflow paralysis. Fix: Document exit code contracts in hook headers. Implement unit tests that verify exit codes against known inputs. Use explicit variable naming (ALLOW=true/false) to prevent cognitive inversion errors.

Production Bundle

Action Checklist

• Audit existing .env, credential, and configuration files to map sensitive paths
• Define project-specific deny patterns and export them as environment variables
• Deploy workspace-guard.sh and turn-completion-alert.sh to .claude/hooks/
• Set executable permissions: chmod +x .claude/hooks/*.sh
• Configure .claude/settings.json with PreToolUse and Stop event bindings
• Test hooks against a sandbox repository with known sensitive files
• Verify notification delivery on target OS (macOS, WSL, Linux)
• Enable JSON audit logging for compliance tracking and incident review

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo developer, low sensitivity	Prompt-based guardrails + manual review	Minimal setup, acceptable risk for non-production code	$0
Team project, shared credentials	Hook-based enforcement + centralized denylist	Deterministic blocking, audit trail, reduces credential leakage risk	Low (dev time)
Enterprise, compliance requirements	Hook enforcement + SIEM integration + policy-as-code	Meets SOC2/ISO27001 controls, enables automated compliance reporting	Medium (infrastructure)
CI/CD pipeline, automated agents	Hook enforcement + headless fallback logging	Prevents credential exposure in build logs, maintains pipeline stability	Low (logging overhead)

Configuration Template

Copy this structure into .claude/settings.json. Adjust hook paths and event bindings to match your project layout.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/workspace-guard.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/turn-completion-alert.sh"
          }
        ]
      }
    ]
  }
}

Notes:

• matcher uses regex to filter which tool invocations trigger the hook. .* applies to all operations. Narrow this to Read|Bash if you want to reduce overhead on Edit or Write operations.
• Multiple hooks can be chained per event. They execute sequentially; a deny in any hook blocks the operation.
• Environment variables (GUARD_DENY_PATHS, GUARD_DENY_VARS) should be exported in your shell profile or project .env file before launching Claude Code.

Quick Start Guide

1. Initialize hook directory: Create .claude/hooks/ in your project root.
2. Deploy scripts: Save workspace-guard.sh and turn-completion-alert.sh to the directory.
3. Set permissions: Run chmod +x .claude/hooks/*.sh.
4. Configure events: Add the JSON template to .claude/settings.json.
5. Validate: Open Claude Code, attempt to read a .env file, and verify the operation is blocked with a JSON reason response. Confirm desktop notification appears when the session completes.

Hook-driven enforcement transforms AI coding assistants from open context consumers into bounded, auditable development partners. By intercepting tool execution at the OS level, you eliminate prompt dependency, reduce credential exposure, and establish a verifiable security posture that scales across teams and compliance frameworks.