Claude Code Permissions Management

Document Location

This document is located at: ~/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/SKILL.md (public repo: github.com/vtmocanu/skills)

Note: This is the source of truth. The installed copy at ~/.claude/skills/claude-permissions/SKILL.md is derived from this file by the npx skills package manager; edit here, then run npx skills update to re-pull it. Never edit the installed copy.

Dippy docs: Configuration syntax and behavior are documented at <https://github.com/ldayton/Dippy/wiki>;. If you encounter syntax you're unsure about, fetch the relevant wiki page to verify before making changes. Key pages: Configuration, MCP Tools, File Editing, Afterthoughts, Handler Model, Security Model.

Entry Point

When invoked without specific instructions, ask what the user wants to do:

1. Permit a new command or MCP tool? (Dippy config)
2. Permit a new Read/WebFetch/Skill entry? (settings.json)
3. Review current permissions?
4. Troubleshoot a permission error?
5. Clean up stale permissions?
6. Something else?

Architecture Overview

Permissions are split across two systems:

Dippy runs as a PreToolUse hook (configured in settings.json) for both Bash and mcp__.* matchers. A PostToolUse hook enables afterthoughts.

CRITICAL: Dippy is invoked through a wrapper, not directly. The settings.json hook command is ~/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/dippy-with-auto-fallback.sh, not bare dippy. The wrapper changes how ask verdicts behave in auto mode (the permission mode that autonomous runs and spawned agents/teammates use). See [Auto-mode fallback wrapper](#auto-mode-fallback-wrapper) below. This is the single most surprising part of the setup: in auto mode a plain ask rule does not prompt the human.

Auto-mode fallback wrapper

The wrapper reads permission_mode from the hook payload and branches (this is the behavior in the default ACTIVE state; see [Three states](#three-states-active--allow-only--disabled) for the two marker-file states that pre-empt it):

• Non-auto modes (default, acceptEdits, plan, etc.): the payload is handed straight to dippy. Normal behavior, ask rules surface an interactive prompt to the user.
• auto mode: the wrapper runs dippy, inspects the decision, and forwards only:

- allow / deny verdicts (the whitelist + blocklist are always enforced), and - ask verdicts whose permissionDecisionReason contains the literal token [ASK].

Any other ask (no [ASK] marker) is dropped (the wrapper emits nothing and exit 0s), which hands the decision to auto-mode's own classifier, that typically runs routine commands without prompting the human.

Consequence: in auto mode, only ask rules tagged with [ASK] in their message escalate to the user. Everything else dippy would have asked about is silently auto-handled. So the [ASK] prefix is a real, load-bearing convention, not decoration: use it on any operation you want a human prompt for even during autonomous/agent runs.

Worked example from the current config: ask git push "[ASK] Confirm push target" (has [ASK]) prompts the human even in auto mode, but ask git commit "Confirm commit" and ask git add "Confirm staging" (no [ASK]) are silently handled by the auto-classifier in auto mode, no prompt. When authoring a new ask rule, decide deliberately whether it needs [ASK]: write/destructive operations that must always reach a human should carry it.

Three states: ACTIVE / ALLOW-ONLY / DISABLED

Dippy has no enable/disable flag of its own (dippy --help, v0.2.7). The state lives in two marker files that the wrapper checks per invocation:

OFF wins if both markers exist. ~/.dippy is a symlink into the mackup repo, so the markers land at confs/.dippy/; both are gitignored on purpose (machine-local state, not synced config).

No restart is needed for any transition: Claude Code caches the hook command from settings.json at startup, but the script is re-read on every invocation, so a switch applies to the running session immediately. (Editing the hook entries in settings.json, by contrast, does require a restart.)

On this Mac, prefer mackup/scripts/dippy-toggle.sh (on PATH via ~/scripts) over touching the markers by hand. It reports state, keeps the two markers mutually exclusive, and warns if settings.json has stopped routing hooks through dippy-with-auto-fallback.sh or if the wrapper it points at is a stale clone with no ALLOW_ONLY branch (in either case the marker is a no-op):

dippy-toggle.sh              # status (default)
dippy-toggle.sh on           # ACTIVE      - full dippy (clears both markers)
dippy-toggle.sh allow-only   # ALLOW-ONLY  - whitelist only
dippy-toggle.sh off          # DISABLED    - bypass dippy
dippy-toggle.sh toggle       # flip on <-> off
dippy-toggle.sh cycle        # rotate active -> allow-only -> off -> active

ALLOW-ONLY: whitelist-only, a noise filter

The wrapper runs dippy, forwards the verdict only when it is allow, and emits nothing otherwise:

[ -f "${HOME}/.dippy/ALLOW_ONLY" ] && forward only `allow`

A hook allow short-circuits the host's permission flow, so whitelisted commands never reach the auto classifier — that is the point of the state. Everything not on the whitelist falls through to whatever the host would have done: the classifier in auto mode, an ordinary prompt in the other modes.

deny rules and [ASK] escalations do NOT fire in this state. Verified against dippy 0.2.7 on 2026-08-04:

PostToolUse afterthoughts still fire in ALLOW-ONLY (they are guidance text, not a permission decision, and the event check runs before the filter).

DISABLED: a safety-off switch, not a noise filter

While ~/.dippy/OFF exists the wrapper emits nothing and exit 0s for every event, so:

• The deny blocklist is not enforced — rm -rf, git push --force, deny-redirect secret-path guards, deny-mcp rules all stop firing.
• allow rules stop firing too, so in non-auto modes routine commands start prompting (more prompts, not fewer). In auto mode everything falls to auto-mode's own classifier, which usually runs commands without prompting.
• Afterthoughts go silent too, since the kill-switch fires before the event check.

Prefer narrower alternatives when they fit:

Verify the current state:

# which state?  (or just: dippy-toggle.sh status)
ls -la ~/.dippy/OFF ~/.dippy/ALLOW_ONLY 2>/dev/null

# end-to-end check — a denied command (empty = bypassed or allow-only; JSON deny = active)
printf '%s' '{"permission_mode":"default","tool_name":"Bash","tool_input":{"command":"helm install foo bar"}}' \
  | ~/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/dippy-with-auto-fallback.sh

# end-to-end check — a whitelisted command (JSON allow = active or allow-only; empty = bypassed)
printf '%s' '{"permission_mode":"default","tool_name":"Bash","tool_input":{"command":"cat /etc/hosts"}}' \
  | ~/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/dippy-with-auto-fallback.sh

Note: Native settings.json capabilities (for context, not to use): settings.json supports wildcards at any position since v2.1.0 (Jan 2026), has allow/ask/deny directives, per-project overrides via settings.local.json, and MCP tool permissions. Dippy's unique advantages: guidance messages on ask/deny rules, last-match-wins ordering (vs deny>ask>allow fixed priority), plain text config with comments, and file redirect controls (deny-redirect).

Key Locations

Dippy config precedence (highest to lowest):

1. $DIPPY_CONFIG env var (if set)
2. .dippy in project root (searches upward like .git)
3. ~/.dippy/config global

Within a config file: Last match wins. Broad allows first, specific denies after.

Project .dippy merges with global ~/.dippy/config. Rules from both files are evaluated together with last match wins. A project rule can override a global rule for the same command pattern.

Dippy Config Format

A ready-to-adapt starter config ships with this skill as [config.example](config.example) — generic safe-defaults (read-only allows, write/destructive ask/deny, secret-write deny-redirect guards, the no-interpreter rule, and the auto-mode [ASK] convention). Copy it to ~/.dippy/config (or a project .dippy) and tailor it to your toolchain.

Directives Reference

Pattern Matching

• Prefix match (default): allow git status matches git status, git status -s, etc.
• Exact match: Append | anchor: allow git status| matches only the literal command
• Wildcards: * (anything incl. spaces), ? (one char), [abc] (char class)
• Path patterns (redirects): ** recursive, * single directory level

**GOTCHA: Patterns with glob characters (*, ?, [) lose implicit prefix matching.** Dippy only adds a trailing for prefix matching when the pattern has NO glob characters. If your pattern contains any glob char, it must match the entire command string via fnmatch. For example, ask tea issue close matches tea issues close but NOT tea issues close 42.

v0.2.7 fix: Trailing now matches empty strings (bare commands). So ask tea issue close matches both tea issues close and tea issues close 42. Always add trailing to glob patterns that should match with or without extra args.

Corollary for curl patterns: Always use trailing after the flag you're matching: ask curl -X POST catches both curl url -X POST and curl url -X POST -d '{}'. Without trailing , the pattern only matches when POST is the last token.

**GOTCHA: pattern tokens align with command tokens, so a path rule needs a -* slot for the flags.** This is the single biggest source of rules that look right and never fire. ask rm /.git/ matches rm /repo/.git/config but NOT rm -rf /repo/.git/config — the -rf occupies a token the pattern has no slot for. Write both forms, or lead with -*:

```
ask rm /.git/ "deletes git internals" # rm <path>
ask rm - /.git/* "deletes git internals" # rm -rf <path>
```

Corollary — a path pattern token must be absolute. A token without a / (.git, objects) is a plain glob that spans the rest of the command. A token with a / is matched against one argument, and a relative one can never match an absolute argument. Inside such a token * does cross slashes, so it matches at any depth. Verified against v0.2.7 on 2026-08-02 via an isolated DIPPY_CONFIG, target rm -rf /Users/me/repo/.git/objects:

| Pattern | Matches? | Why |
|---|---|---|
| ask rm - /.git/ | yes | absolute path token, crosses / |
| ask rm - //.git/* | yes | same |
| ask rm *.git | yes | no slash → plain glob, spans the command; only when .git ends it |
| ask rm .git/ | no | has a slash → path token, but relative |
| ask rm /.git/ | no | same |
| ask rm /.git/ | no | absolute, but no -* slot for -rf |
| ask rm **/.git/* | no | ** is redirect-pattern syntax only |

Redirects are a different matcher and unaffected: deny-redirect **/.env* works as documented.

Test every rule you write, in isolation: printf 'set default allow\nask rm <pattern> "HIT"\n' > /tmp/p.dippy then pipe a hook payload through DIPPYCONFIG=/tmp/p.dippy dippy --claude. set default deny is not valid syntax (only allow/ask) and silently yields an empty ruleset, which looks exactly like "DIPPYCONFIG is ignored"; a nonexistent config path also falls back to the global file without warning.

SECURITY: Never allow interpreter commands. Rules like allow bash, allow python3, allow node are prefix matches that auto-approve bash -c '...', python3 -c '...', node -e '...', bypassing ALL inner command rules. Dippy does not trace into -c/-e arguments (single-layer execution). Remove these and let them fall through to set default ask.

MCP Tool Naming

MCP tools follow: mcp<server><action>. Examples:

• allow-mcp mcpgrafana* - all Grafana tools
• deny-mcp mcpdelete_ - all delete actions across servers
• allow-mcp mcpcontext7query-docs - specific tool

Comments

Full-line (# comment) and inline (allow git # comment) supported.

settings.json Format (Read/WebFetch/Skill only)

Permissions live in permissions.allow (array of strings):

{
  "permissions": {
    "allow": [
      "Read(*)",                       // allow reading any file
      "Read(~/**)",      // path-specific
      "WebSearch",                     // no pattern needed
      "WebFetch",
      "WebFetch(domain:github.com)",   // domain-scoped
      "Skill(docx)"                    // specific skill
    ]
  }
}

Important: Do NOT add Bash(...) or mcp__* entries to settings.json. Those are managed exclusively by Dippy.

Workflow: Permit a Bash Command

Critical rule: NEVER run the command, only update permissions.

1. Analyze the command the user wants permitted
2. Determine scope: global (~/.dippy/config) or project (.dippy)?

- Default to global if unclear

1. Check for duplicates before adding:

- Read the target Dippy config - Check if the command is already covered by a broader rule (e.g., allow git already covers git status) - Check if a more specific rule already exists that would conflict - If duplicate found, inform user and skip

1. Decompose chained commands: pipes create separate commands, each needs its own rule
2. Apply safety defaults (see Safety section below)
3. Add the rule in the correct section of the config (organized by category)
4. Show the user exactly what was added and where
5. Ask if they want to test the newly permitted command

Duplicate-Checking Logic

Before adding any rule:

1. Global covers it? If allow git is in global config, don't add allow git status anywhere
2. Project already has it? Don't add a rule that already exists in the project .dippy
3. Broader project rule? If project has allow kubectl, don't add allow kubectl get
4. Would a project rule shadow a global deny? If global has deny git push --force, adding allow git push --force to project .dippy would override it. Warn the user.

Workflow: Permit an MCP Tool

1. Identify the tool name: mcp<server><action>
2. Determine scope: global or project
3. Check for duplicates (same logic as Bash commands, using allow-mcp/deny-mcp)
4. Add the allow-mcp rule
5. Verify the mcp__.* PreToolUse hook matcher exists in settings.json (required for Dippy to intercept MCP calls)

Workflow: Permit Read/WebFetch/Skill

These still use settings.json since Dippy doesn't handle them:

1. Determine scope: global (~/mackup/confs/claude/settings.json) or project (.claude/settings.local.json)
2. Read the target settings file
3. Add the permission entry to permissions.allow
4. Validate JSON:

``bash jq . <settings-file> > /dev/null && echo "JSON valid" ``

1. Show the user what was added

Safety: Read-Only Defaults

By default, only permit read operations. For commands with write effects, ask the user to confirm.

Auto-permit (read-only, safe to allow)

Never auto-permit interpreters: bash, python3, node, sh, ruby, perl. Prefix-matching these auto-approves -c/-e flags, bypassing all inner command rules. Let them fall through to set default ask.

Require confirmation (write/destructive, use deny or ask)

• kubectl apply/delete/edit/patch/rollout restart/scale/drain
• git push/commit/rebase/reset --hard/clean -f
• helm install/upgrade/uninstall/rollback (for GitOps workflows, prefer deny with guidance: deny helm install "Use GitOps: create/edit the HelmRelease in your GitOps repo instead")
• flux suspend/resume/delete
• docker rm/rmi/system prune
• tofu apply/destroy
• rm -rf, rm -r, sudo, chown
• curl with POST/PUT/PATCH/DELETE methods, -d/--data, -F/--form, -T/--upload-file
• Important: Use wildcard to catch write flags regardless of position, with trailing to match extra args: ask curl -X POST (not ask curl -X POST). The URL often comes before the method flag, and additional flags may follow.

When a command has write effects, present options:

"This command can modify state. Recommended:
1. Add as ask rule (prompts before execution, safer)
2. Add as allow rule (auto-approves, needs your confirmation)
3. Add as deny with guidance message (blocks with reason)"

Workflow: Review Permissions

# Show global Dippy config
cat ~/.dippy/config

# Show project Dippy config (if exists)
cat .dippy 2>/dev/null || echo "No project .dippy"

# Show settings.json permissions (Read/WebFetch/Skill)
jq '.permissions.allow' ~/mackup/confs/claude/settings.json

# Show project settings.local.json
jq '.permissions.allow' .claude/settings.local.json 2>/dev/null || echo "No project settings"

# List all project .dippy files across repos
fd -H -t f '^\\.dippy$' ~/stuff/gitrepos/wxs/

Workflow: Clean Up Stale Permissions

1. Read the Dippy config (global and/or project)
2. Identify rules for tools/commands no longer used
3. Ask user before removing any entries
4. Remove confirmed entries
5. For settings.json changes, validate JSON after editing

Troubleshooting

Hook Configuration Reference

The following hooks must exist in ~/mackup/confs/claude/settings.json for Dippy to function. The PreToolUse Bash + mcp__.* matchers invoke the auto-fallback wrapper (dippy-with-auto-fallback.sh, bundled with this skill), not bare dippy, so that auto-mode ask handling works as described in [Auto-mode fallback wrapper](#auto-mode-fallback-wrapper). The PostToolUse hook (afterthoughts) calls dippy directly.

Hook command paths must be absolute. Claude Code does NOT expand ~ in hook command strings — the ~/... paths shown below are for readability; in your actual settings.json use the fully expanded path (e.g. /home/you/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/dippy-with-auto-fallback.sh). Point the hook at your local clone of this repo, not at the installed ~/.claude/skills/claude-permissions/ copy (that directory is overwritten on every npx skills update).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/dippy-with-auto-fallback.sh" }
        ]
      },
      {
        "matcher": "mcp__.*",
        "hooks": [
          { "type": "command", "command": "~/stuff/gitrepos/gh/vtmocanu/skills/claude-permissions/dippy-with-auto-fallback.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "dippy" }
        ]
      }
    ]
  }
}

The wrapper ships with this skill as ./dippy-with-auto-fallback.sh. Read that file directly when you need its exact logic — it is the source of truth for the auto-mode behavior summarized in [Auto-mode fallback wrapper](#auto-mode-fallback-wrapper) above. To use it, clone this repo locally and point both PreToolUse hook commands at your clone's copy (absolute path, per the note above).

Note: The mcp__.* matcher uses regex (not glob). Other PreToolUse hooks (zellaude, clawd, dot-agent-deck) run alongside the wrapper but are unrelated to permissions.