[Feature Request] Add API for hooks to access resolved permissions configuration

Feature Request: Add API for hooks to access resolved permissions configuration

Problem

Currently, PreToolUse hooks need to replicate Claude Code's permission merging logic to validate commands against allow lists. This creates inconsistency risks since hooks may interpret permissions differently than Claude Code's internal system.

When building security hooks (like bash command validation), hooks must:

1. Manually read multiple configuration files (~/.claude/.claude/settings.json, ~/.claude/.claude/settings.local.json, .claude/settings.local.json)
2. Implement the same precedence/merging rules that Claude Code uses internally
3. Parse Bash(...) patterns using custom logic
4. Hope that their interpretation matches Claude Code's behavior exactly

This duplication of logic is error-prone and can lead to security gaps where:

• Hook allows a command that Claude Code would block
• Hook blocks a command that Claude Code would allow
• Changes to Claude Code's permission logic break existing hooks

Proposed Solution

Provide hooks with access to the resolved/merged permissions configuration through one or more of these approaches:

Option 1: Environment Variable

export CLAUDE_RESOLVED_PERMISSIONS='{"allow":["Bash(git:*)","Bash(cargo:*)"],"deny":[]}'

Option 2: Additional Field in Hook JSON Input

{
  "tool_name": "Bash",
  "params": {"command": "git status"},
  "session_id": "abc123",
  "resolved_permissions": {
    "allow": ["Bash(git:*)", "Bash(cargo:*)"],
    "deny": []
  }
}

Option 3: CLI Command to Query Permissions

claude --show-permissions --format=json
claude --show-permissions --tool=Bash

Option 4: Hook-Specific API

Allow hooks to request permission information:

{
  "action": "query_permissions",
  "tool": "Bash",
  "command": "git status"
}

Response:

{
  "allowed": true,
  "matching_pattern": "Bash(git:*)",
  "source": "user_settings"
}

Use Case

Building a bash safety hook that needs to:

• Validate commands against the same allow lists that Claude Code uses internally
• Ensure consistent security policy enforcement
• Prevent command injection while allowing legitimate commands
• Provide helpful error messages referencing the actual allow list patterns

This is particularly important for security hooks where consistency between the hook's validation and Claude Code's actual enforcement is critical.

Current Workaround

Manually parsing settings.json files and replicating merge logic:

# Load from multiple sources
if [[ -f "$HOME/.claude/.claude/settings.local.json" ]]; then
    patterns=$(jq -r '.permissions.allow[]?' "$HOME/.claude/.claude/settings.local.json")
fi

# Implement precedence rules (guessing at Claude Code's logic)
# Parse Bash(...) patterns with custom regex
# Hope it matches Claude Code's behavior

This approach is:

• Error-prone and hard to maintain
• May diverge from Claude Code's actual behavior
• Requires hooks to understand Claude Code's internal configuration format
• Creates security risks from implementation differences

Benefits

1. Consistency: Hooks use the exact same permissions that Claude Code enforces
2. Security: Eliminates risk of permission logic divergence
3. Maintainability: Hooks don't need to replicate complex configuration parsing
4. Reliability: Changes to Claude Code's permission system automatically work with existing hooks
5. Developer Experience: Much simpler to build reliable security hooks

Compatibility

This would be a purely additive feature - existing hooks would continue to work unchanged, while new hooks could opt-in to using the resolved permissions API.