customize

Customize Permission Hook Rules

Edit the machine-level environment rules that are appended to the default security prompt when the LLM evaluates ambiguous commands (Tier 3 decisions).

How It Works

The permission hook uses a two-layer system prompt:

1. Default prompt (bundled in plugin at config/default-system-prompt.md) — generic security rules, not editable per machine
2. Local overrides (~/.claude/permission-hook/local.md) — machine-specific rules appended to the default prompt

This skill manages layer 2.

Workflow

Step 1: Show Current State

Read ~/.claude/permission-hook/local.md and display its contents. If the file does not exist, inform the user that no machine-specific rules are configured yet.

Also read the default prompt from ${CLAUDE_PLUGIN_ROOT}/config/default-system-prompt.md so the user understands the baseline.

Step 2: Identify What to Change

Ask the user what environment-specific rules they need. Common categories:

• Environment context: What kind of machine is this? (dev laptop, server, container, CI runner)
• Home directory: Is /root/ the normal user home? (common in containers)
• Docker/container rules: Which containers are safe to exec into?
• Database rules: Which database operations are normal admin tasks?
• Service-specific rules: Which services or APIs are safe to interact with?
• Custom allow/deny: Any additional patterns to always allow or deny?

Step 3: Write Rules

Write or update ~/.claude/permission-hook/local.md with the user's rules in clear, natural language. The LLM reads this as part of its system prompt, so write it as instructions to the evaluator.

When adding rules to an existing file, append to the relevant section rather than rewriting the entire file. Read the current content first to preserve existing rules.

Example for a container-based development server:

## Environment Context

- This is a Proxmox LXC container where /root/ is the PRIMARY USER home directory
- Development projects live directly under /root/
- /root/ is NOT a system directory — treat it like a normal home directory

## Additional Allow Rules

- docker exec commands on matrix-* containers (matrix-taxbot, matrix-housebot, matrix-financebot, matrix-menagerie, matrix-synapse) — these are our own managed services
- Database operations (SQLite queries, SELECT, UPDATE, INSERT, DELETE, ALTER) on application databases — these are development/admin operations, not attacks
- git init, mkdir, and standard dev ops within /root/ subdirectories are normal development

## Additional Deny Rules

- Never allow commands that modify Synapse's signing key or homeserver.yaml directly

Step 4: Verify

After writing, read back the file and confirm with the user that the rules look correct. Remind them that changes take effect on the next Tier 3 LLM evaluation (no restart needed — the prompt is read fresh each time).