Examples — Configuration & Hook Examples

Configuration & Hook Examples

Reference configurations and example hooks demonstrating Claude Code’s security model, permission engine, and customization features across three security profiles.

Files

Profiles

Python

Hooks

JSON

Settings

🔒 Security Profiles🔌 Hook Examples🛠️ Configuration🛡️ Permission Engine

📚 What is this & why does it exist?

The examples directory provides battle-tested reference configurations for deploying Claude Code with different security postures. The three settings profiles (lax, strict, and bash-sandbox) demonstrate the full spectrum from minimal restrictions to maximum lockdown. The hook example shows how to validate tool invocations before they execute, giving administrators programmatic control over what Claude Code can do. Together, these examples serve as starting points for enterprise deployments where security, compliance, and customization requirements vary.

💡 Real-world analogy

Think of these examples like the security presets on a building access control system. The “lax” profile is like a co-working space — doors are open, most areas accessible, just the server room is locked. The “strict” profile is a government facility — badge required everywhere, no personal devices, cameras in every room. The “bash-sandbox” profile is a cleanroom lab — sealed environment, no outside connections, everything monitored. And the hook example is like a custom security checkpoint where a guard inspects each package before it enters the building.

Architecture

flowchart TB
    subgraph Profiles["Settings Profiles"]
        LAX["settings-lax.json\n(Minimal Restrictions)"]
        STRICT["settings-strict.json\n(Full Lockdown)"]
        SANDBOX["settings-bash-sandbox.json\n(Network Isolated)"]
    end

    subgraph Engine["Claude Code Permission Engine"]
        LOADER["Settings Loader"]
        PERMS["Permission Resolver"]
        HOOKS["Hook Executor"]
        SANDBOX_RT["Sandbox Runtime"]
    end

    subgraph Hooks["Hook Examples"]
        BASH_HOOK["bash_command_validator_example.py\n(PreToolUse Hook)"]
    end

    subgraph Actions["Tool Execution"]
        ALLOW["✅ Allow"]
        DENY["❌ Deny"]
        SANDBOX_EXEC["🛡️ Sandboxed Exec"]
    end

    LAX --> LOADER
    STRICT --> LOADER
    SANDBOX --> LOADER
    LOADER --> PERMS
    PERMS --> HOOKS
    HOOKS --> BASH_HOOK
    BASH_HOOK --> ALLOW
    BASH_HOOK --> DENY
    PERMS --> SANDBOX_RT
    SANDBOX_RT --> SANDBOX_EXEC

    style STRICT fill:#f85149,stroke:#f85149,color:#fff
    style LAX fill:#3fb950,stroke:#3fb950,color:#fff
    style SANDBOX fill:#d29922,stroke:#d29922,color:#fff

Permission Resolution Flow

sequenceDiagram
    participant User as User / CI
    participant CC as Claude Code
    participant Settings as Settings Loader
    participant Hooks as Hook System
    participant Validator as bash_command_validator
    participant Tool as Tool Runtime

    User->>CC: Request action (e.g., run bash command)
    CC->>Settings: Load active settings profile
    Settings-->>CC: Profile config (lax/strict/sandbox)

    CC->>CC: Check permission rules
    alt Permission denied by profile
        CC-->>User: ❌ Action blocked by policy
    else Permission allowed
        CC->>Hooks: Fire PreToolUse event
        Hooks->>Validator: Execute hook script
        Validator->>Validator: Match command against regex rules
        alt Command matches deny pattern
            Validator-->>Hooks: DENY + reason
            Hooks-->>CC: Hook rejected action
            CC-->>User: ❌ Blocked by hook
        else Command allowed
            Validator-->>Hooks: ALLOW
            Hooks-->>CC: Hook approved
            CC->>Tool: Execute tool
            Tool-->>CC: Result
            CC-->>User: ✅ Action completed
        end
    end

Files Reference

Hook Examples

🔌 bash_command_validator_example.pyHOOK

A PreToolUse hook that validates bash commands against configurable regex rules before execution. Demonstrates the hook API contract including JSON stdin parsing, allow/deny responses, and reason messages.

Event: PreToolUse (fires before tool runs)
Matcher: Bash tool invocations
Rules: regex allow/deny patterns
Output: JSON {"decision": "allow|deny", "reason": "..."}

Settings Profiles

🟢 settings-lax.json

Minimal restrictions — only disables the bypass mechanism. Suitable for trusted development environments where Claude Code needs maximum flexibility.

allow_bypass: false
All tools enabled
Network access unrestricted
Custom hooks allowed

🔴 settings-strict.jsonLOCKDOWN

Full restrictions — no bypass, managed-only hooks, managed-only permissions, web tools denied. Designed for regulated enterprise environments.

allow_bypass: false
hooks_only_managed: true
permissions_only_managed: true
deny_web_tools: true

🔶 settings-bash-sandbox.json

Sandbox mode — enables bash sandboxing with no network access and no unsandboxed command execution. Maximum isolation for untrusted workloads.

bash_sandbox: enabled
allow_network: false
allow_unsandboxed_commands: false
File system access restricted

📄 README.md

Settings guide — comprehensive documentation of all available settings parameters, their types, defaults, and interactions.

Parameter reference
Profile comparison matrix
Deployment recommendations

Settings Comparison Matrix

Parameter	Lax	Strict	Bash Sandbox	Description
`allow_bypass`	❌ false	❌ false	❌ false	Allow users to bypass permission checks
`hooks_only_managed`	✅ false	❌ true	✅ false	Only allow administrator-managed hooks
`permissions_only_managed`	✅ false	❌ true	✅ false	Only allow administrator-managed permissions
`deny_web_tools`	✅ false	❌ true	✅ false	Block all web-access tools (fetch, browse)
`bash_sandbox`	✅ disabled	✅ disabled	❌ enabled	Run bash commands in isolated sandbox
`allow_network`	✅ true	✅ true	❌ false	Allow outbound network connections
`allow_unsandboxed_commands`	✅ true	✅ true	❌ false	Allow commands outside the sandbox

Configuration Reference

Parameter	Type	Default	Description
`allow_bypass`	boolean	true	When `false`, users cannot skip permission prompts
`hooks_only_managed`	boolean	false	When `true`, only admin-deployed hooks are loaded
`permissions_only_managed`	boolean	false	When `true`, only admin-set permissions apply
`deny_web_tools`	boolean	false	When `true`, web fetch/browse tools are disabled
`bash_sandbox`	string	"disabled"	`"enabled"` runs bash in an isolated sandbox
`allow_network`	boolean	true	When `false`, all outbound network is blocked in sandbox
`allow_unsandboxed_commands`	boolean	true	When `false`, only sandboxed execution is permitted
`hook.event`	string	—	Hook event type: `PreToolUse`, `PostToolUse`, etc.
`hook.matcher`	regex	`*`	Tool name pattern the hook matches against
`hook.type`	string	"command"	Hook execution type: `command` or `prompt`

Interactions

Module	Interface	Data Exchanged
Claude Code Core	Settings loader	JSON config files loaded at startup
Permission Engine	Runtime checks	Tool invocations validated against active profile
Hook System	PreToolUse / PostToolUse	JSON payloads with tool name, arguments, context
Sandbox Runtime	Process isolation	Sandboxed bash environment with restricted syscalls
Enterprise Admin	Managed deployment	Profiles deployed via organization settings

Directory Map

Source tree for Examples

examples/
├── hooks/
│   └── bash_command_validator_example.py  ← PreToolUse hook: regex bash validation
└── settings/
    ├── README.md                          ← Settings configuration guide
    ├── settings-lax.json                  ← Minimal restrictions (bypass disabled)
    ├── settings-strict.json               ← Full lockdown (managed-only everything)
    └── settings-bash-sandbox.json         ← Sandbox: no network, no unsandboxed cmds