Tool Permission Policy

Author, audit, and explain Claude Code permission policies for settings files, CLI overrides, skills, subagents, and hook-adjacent workflows. Use this skill for permission rules, permission modes, MCP wildcards, parameter matching, and safe automation boundaries. [DOC]

Do not apply Claude Code permissions.*, modes, or Bash(...) rule syntax to Claude Platform tools. Platform client-tool authorization belongs inside the application handler governed by claude-api-client-tools; server-tool request policy belongs to claude-api-server-tools. [CONFIG]

Treat current Claude Code documentation as the source of truth for runtime behavior. If the local Claude Code version or documentation date is unknown, include coverage_gap: active Claude Code version not verified. [DOC][INFERENCIA]

Supporting files:

• references/rule-syntax.md - Detailed Tool and Tool(specifier) syntax, wildcards, parameter matching, and tool-specific caveats. [CONFIG]
• references/modes-and-safety.md - Mode selection guidance for default, acceptEdits, plan, auto, dontAsk, and bypassPermissions. [CONFIG]
• references/hooks-boundary.md - How hooks interact with permission rules and why permissions remain the enforcement layer. [CONFIG]
• assets/policy-review-checklist.md - Portable checklist for reviewing a policy draft before applying it. [CONFIG]

Inputs Expected

• Target scope: user, project, local project, managed settings, CLI flag, subagent, or skill frontmatter.
• Intended operation: author, audit, explain, migrate, or troubleshoot.
• Risk posture: solo development, team repository, managed enterprise policy, CI/headless run, or isolated sandbox.
• Current policy text when available: settings.json, /permissions export, CLI flags, subagent frontmatter, or hook output.

Outputs Expected

• A permission policy draft, audit report, or explanation with explicit evidence tags.
• A precedence explanation when any allow/ask/deny rule overlaps.
• A mode recommendation with safe-use conditions.
• A validation checklist and residual coverage_gap items.

Core Rules

Policy Arrays

• Use permissions.allow to let matching tool calls proceed without manual approval. [DOC]
• Use permissions.ask to force confirmation for matching tool calls. [DOC]
• Use permissions.deny to block matching tool calls and protect sensitive files, commands, domains, tools, or MCP surfaces. [DOC]
• Evaluate rule behavior in this order: deny, then ask, then allow. The first matching behavior wins regardless of specificity. [DOC]
• Treat deny as non-exceptionable: a broad deny such as Bash(aws *) blocks a narrower allow such as Bash(aws s3 ls). [DOC]
• Treat ask as stronger than allow: a matching ask rule prompts even when a narrower allow also matches. [DOC]

Rule Shape

• Write rules as Tool to match all uses of a tool.
• Write rules as Tool(specifier) for fine-grained control.
• Treat Bash(*) as equivalent to Bash. As a deny rule, both forms remove the tool from model context. [DOC]
• Prefer canonical tool names from Claude Code docs or verbose transcripts; display labels can differ from rule names. [DOC]
• Use mcp__* only for deny or ask rules that intentionally target every MCP tool. Allow rules may use MCP globs only after a literal server prefix, such as mcp__github__get_*. [DOC]

Parameter Matching

• Use Tool(param:value) only for deny and ask rules against direct, top-level scalar tool input parameters. [DOC]
• Write one rule per parameter, for example Agent(model:opus) and Agent(isolation:worktree).
• Use * in parameter values to match any character sequence; omitted parameters never match.
• Avoid parameter matching for canonical fields with dedicated syntax, including Bash command, file tool file_path, Grep/Glob path, NotebookEdit notebook_path, and WebFetch url. Use the tool's canonical specifier syntax instead. [DOC]

Permission Modes

Use default for normal interactive work. Use acceptEdits only when file edits and common filesystem commands inside the working directory are low risk. Use plan for read-only exploration before implementation. Use dontAsk for constrained automation where explicit allow rules pre-approve all permitted actions. [DOC]

Use auto only with reviewed environment context and explicit deny/ask boundaries. Auto mode runs a classifier after the permission system; deny and explicit ask rules still run first. Shared project settings cannot grant themselves auto mode, and auto mode configuration is not read from shared project settings. [DOC]

Use bypassPermissions only in isolated containers, VMs, or disposable worktrees. It skips permission prompts, including protected project directories, while explicit ask rules and root/home deletion circuit breakers still prompt. Prefer disabling bypass in managed settings when organizational policy requires it. [DOC]

Procedure

Step 1 - Locate Authority

Identify the active source: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, managed settings, command-line flags, subagent frontmatter, skill frontmatter, hook output, or SDK settings. State which layer owns the proposed change. [DOC]

Step 2 - Classify The Change

Classify each requested rule as allow, ask, or deny. Default to deny for irreversible, secret-bearing, exfiltration-prone, or production-impacting actions. Default to ask for legitimate but high-impact operations. Default to allow only for narrow, repeatable, low-risk actions. [INFERENCIA]

Step 3 - Write Narrow Rules

Prefer exact commands, project-root paths, explicit domains, named subagents, and literal MCP server prefixes. Avoid broad allows such as Bash, WebFetch, Edit, mcp__server__*, or mcp__* unless the scope is intentionally trusted and compensating controls are documented. [DOC][INFERENCIA]

Step 4 - Check Precedence

Build an overlap table with columns: Candidate call, deny match, ask match, allow match, effective result, reason. Flag impossible allowlist exceptions caused by broad deny rules. [INFERENCIA]

Step 5 - Select Mode

Choose the least permissive mode that satisfies the workflow. Pair auto and bypassPermissions with explicit deny/ask guardrails, environment isolation, or managed disable settings. Explain why default, plan, or dontAsk is insufficient before recommending a more permissive mode. [INFERENCIA]

Step 6 - Separate Hooks From Policy

Use permission rules for durable policy enforcement. Use hooks for automation, supplemental checks, permission suggestions, logging, or runtime workflow control. Do not present a hook allow decision as overriding a matching deny or ask rule. [DOC]

Step 7 - Validate

Apply assets/policy-review-checklist.md. Include JSON parse status when reviewing settings. Include coverage_gap for unknown Claude Code version, unavailable managed settings, unavailable active /permissions view, or unverified MCP server names.

Quality Criteria

• The output distinguishes allow, ask, and deny behavior.
• The output explains deny -> ask -> allow precedence for overlapping rules.
• Every rule uses Tool or Tool(specifier) syntax.
• Parameter matching is limited to deny/ask rules and direct top-level scalar inputs.
• MCP wildcard usage distinguishes deny/ask mcp__* from allowed server-scoped globs.
• auto and bypassPermissions recommendations include safety conditions.
• Hooks are described as supplemental automation, not as the durable policy layer.

Usage

• /tool-permission-policy
• author Claude Code permissions for this repo
• audit these permissions.allow and permissions.deny rules
• explain whether this hook can bypass a deny rule
• review this bypassPermissions setup

Contract

• Aceptación: política expresada como allow/deny mínima por herramienta + MCP, sin comodines abiertos. [EXPLICIT]
• Límites: diseña la política; la aplicación efectiva la hace el runtime/hook, no esta skill. [EXPLICIT]
• Casos borde: allowed-tools NO restringe en skills (usa disallowed-tools); herramientas UI-dependientes no aplican en subagentes. [EXPLICIT]
• Supuestos: least-privilege como default (Constitution Art. 3). [SUPUESTO]
• Trade-off: denylist es más segura pero puede romper flujos que heredaban acceso — documentar la intención. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · assets/ recursos estáticos.