ai-coding-agents-permissions

AI Coding Agents Permissions

Use this skill to design or review the approval system for a coding-agent runtime: tool permission modes, plan-mode entry and exit, sandbox escalation, background-agent auto-deny behavior, and leader-worker permission routing.

This skill owns approval architecture for coding agents. For general hooks or callback automation, use ../agents-hooks/SKILL.md.

ASCII Flow

tool/action request
  |
  v
permission context
  mode + actor + sandbox + tool + path + remote/local + worker role
  |
  v
policy route
  allowlist | ask rule | deny rule | managed policy | plan-mode gate
  |
  v
decision
  allow -> execute
  ask   -> prompt owner or lead session
  deny  -> return structured refusal
  log   -> trace permission reason

Quick Reference

When To Use

• Design a permission model for a coding-agent CLI or runtime
• Add tool approval prompts, ask/allow/deny rules, or sandbox escalation
• Model plan-mode entry and exit as part of the permission system
• Route worker approvals through a lead agent or remote bridge
• Decide what background agents should auto-deny instead of prompting for

Use Other Skills

Default Workflow

1. Model permission as runtime state, not scattered booleans. Keep a single host-owned permission context with mode, rule sources, and special-case flags.
2. Separate policy layers. Distinguish always-allow, always-deny, always-ask, org policy, and session-local overrides.
3. Define promptability. Background workers, headless sessions, or remote viewers may need auto-deny or delegated approval instead of local dialogs.
4. Treat plan mode as a permission transition. Entering or exiting plan mode should preserve the prior mode so the runtime can safely restore it.
5. Route approvals by execution topology. Local REPL, remote session, and swarm worker flows should share semantics but not transport.
6. Keep pending approvals as first-class runtime objects. Prompt IDs, tool-use IDs, cancellation state, and approval outcomes should be tracked explicitly so remote cancellation and reconnect behavior cannot desynchronize the UI.
7. Bridge remote requests into local renderables. Remote approval prompts may reference tools unknown to the local client; normalize them through synthetic assistant messages or tool stubs so the UI can still explain what is being approved.
8. Keep tool-specific rendering separate from host policy. A tool can explain its request, but the host decides how approval is enforced and remembered.
9. Lint persisted rules. Detect unreachable or shadowed allow rules before they enter the active policy set.
10. Test hostile paths. Verify denied prompts, cancelled prompts, remote unknown-tool approvals, worker poll timeouts, bypass-mode restrictions, and over-broad shell rules.

Host Rules

• Keep one canonical permission context for the session.
• Let tools contribute request detail, not the final allow/deny policy.
• Background agents that cannot show UI should auto-deny or escalate to a controller instead of hanging.
• Await automated checks before showing dialogs when coordinator workers depend on classifier or hook output.
• Remote and worker approval flows should return structured approval results, not implicit UI side effects.
• Permission prompts should have stable request IDs and explicit cancellation behavior.
• Unknown remote tools should still be approvable through synthetic local rendering paths rather than becoming unrenderable errors.
• Over-broad persisted shell rules should be sanitized or refused before they are admitted into the active permission context.
• Record enough metadata to explain why a request was allowed, denied, or never prompted.
• Shared policy sources and personal policy sources may need different sanitization or auto-allow behavior. Preserve source class through evaluation.

Build Order

1. Define one canonical permission context for the host runtime.
2. Model permission modes and rule sources explicitly.
3. Implement request IDs, approval results, and cancellation semantics.
4. Route approval by topology: local, remote, worker, or non-interactive.
5. Add persistence or session-local memory for approved rules.
6. Add sanitization and shadowed-rule detection for dangerous or over-broad rule proposals.
7. Add source-aware handling for shared versus personal policy layers.

Core Invariants

• The host owns allow, deny, ask, and persistence policy.
• Tools describe requests; they do not decide approval policy.
• Non-interactive actors must never hang waiting for a prompt they cannot answer.
• Every prompt must end in exactly one terminal outcome: approved, denied, cancelled, or expired.
• Plan mode is a reversible permission transition, not a separate permission system.
• Persisted rules must be linted for reachability and dangerous breadth before activation.

Failure Modes

• Prompt IDs that cannot be matched to cancellations or late results.
• Remote approvals that reference unknown tools and therefore become unrenderable.
• Persisted shell rules that silently become broader than intended.
• Workers blocking forever while waiting for interactive approval.
• Plan-mode exit failing to restore the preexisting permission state.
• Lower-precedence allow rules that are unreachable because an earlier ask or deny rule shadows them.

Minimal Viable Version

• One session-owned permission context.
• Explicit ask, allow, and deny modes.
• Stable IDs for prompts and approval results.
• Auto-deny for non-interactive workers.
• One sanitization or lint pass over persisted rules before activation.
• Approval metadata that explains why a request was allowed or denied.

What Strong Implementations Add

• Policy layering across org, repo, session, and ephemeral overrides.
• Automated checks before prompting the user.
• Synthetic local rendering for remote approval prompts.
• Cancellation, expiry, and retry-safe bookkeeping.
• Rule sanitization and explainability for persisted approvals.
• Shadowed-rule detection and source-aware behavior differences for shared versus personal policy layers.

Known Traps

• Letting multiple subsystems infer approval state independently and then diverge between the runtime, UI, and stored policy.
• Persisting shell-prefix approvals without enough narrowing to prevent future privilege creep.
• Treating remote approval as a rendering problem instead of a durable runtime object with expiry, cancellation, and retry semantics.
• Recording “prompt shown” as if it were equivalent to a valid approval outcome.
• Allowing tools or plugins to own their own approval policy and bypass central auditability.

Common Anti-Patterns

• Storing approval mode as scattered booleans instead of one context object.
• Letting tools persist their own approval policy.
• Treating remote approval as a UI problem instead of a runtime-routing problem.
• Persisting arbitrary shell prefixes without narrowing or review.
• Assuming every stored allow rule is reachable and therefore useful.
• Assuming a prompt that was shown always receives a valid response.

Claude Code: Permission Modes Quick Reference (2026)

Six named modes are the complete enumeration. All are set via --permission-mode <mode>, the defaultMode settings key, or permissionMode in subagent frontmatter. As of v2.1.200, default is labeled Manual in the CLI, --help, and the VS Code/JetBrains extensions, and manual/"manual" is accepted as an alias for default everywhere the mode is configured — treat default and manual as the same mode when writing tooling against it.

Shift+Tab cycle: default → acceptEdits → plan. Optional modes slot in after plan: bypassPermissions first (if started with --permission-mode bypassPermissions or --allow-dangerously-skip-permissions), then auto last (if eligible). dontAsk never appears in the cycle.

Protected paths

A small set of paths (.git, .config/git, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn, .claude except .claude/worktrees, plus files like .gitconfig, shell rc files, and package-manager rc files) are never auto-approved in any mode except bypassPermissions, and the check runs before permissions.allow rules are evaluated — an Edit(.claude/**) allow rule does not change this. This is the pattern to copy for any runtime: repository metadata and the agent's own config directory should have a hard-coded carveout that ordinary allow rules cannot reach, independent of mode.

auto mode — model-classifier approval system:

• A server-configured classifier model (independent of the session's /model selection) evaluates each action before execution; do not hard-pin a specific classifier model name in downstream tooling — it can change without a version bump to the mode's behavior.
• Two-stage: fast single-token filter, then chain-of-thought on flagged actions
• Classifier sees user messages, tool calls, and CLAUDE.md content; tool results are stripped and separately scanned for injected instructions
• Decision order: allow/deny rules resolve first (except protected-path writes, which always route to the classifier) → read-only/in-directory edits auto-approve → everything else hits the classifier
• On entering auto, broad allow rules (Bash(*), PowerShell(*), wildcarded interpreters, package-manager run commands, Agent allow rules) are dropped and restored on exit; narrow rules like Bash(npm test) carry over
• If the classifier blocks 3 consecutive times or 20 total times, auto mode pauses and prompting resumes; in non-interactive (-p) mode there is no user to prompt, so the run aborts instead
• Eligibility (plan tier, minimum model, provider) is gated per-provider and changes over time — verify current gating in /en/permission-modes at ship time rather than trusting a cached list
• Trap: defaultMode: "auto" set in .claude/settings.json or .claude/settings.local.json is silently ignored (v2.1.142+) so a repository cannot grant itself auto mode; it must be set in user (~/.claude/settings.json) or managed settings
• permissionMode: auto in subagent frontmatter is ignored when the parent is in auto mode — the parent's auto mode applies to all subagent actions, checked at three points: before spawn (task description), during execution (each action), and after completion (a full-history review that can prepend a security warning to the result, v2.1.178+)
• Plugin subagents cannot set permissionMode
• disableAutoMode: "disable" in managed settings removes auto from the Shift+Tab cycle and rejects --permission-mode auto
• Source: code.claude.com/docs/en/permission-modes and anthropic.com/engineering/claude-code-auto-mode

dontAsk mode — named headless auto-deny: every tool call that would normally prompt is auto-denied; only allow-rule-matched tools and read-only Bash commands execute, and an MCP tool marked requiresUserInteraction is denied even when an allow rule matches it (its consent card needs an answer this mode never collects). This is the correct mode for CI scripts that must not hang waiting for approval.

Background subagents and the "auto-deny vs. escalate" judgment call: prior to v2.1.186, a background subagent that hit a tool call requiring approval was auto-denied outright, because the main session had no way to interrupt it — subagents got stuck in silent denial loops. Since v2.1.186, the denied-by-default call instead surfaces as a prompt in the parent/main session, labeled with the subagent's name; the parent can approve or deny that single call without stopping the subagent. Treat this as the reference pattern for this skill's own "promptability" principle: auto-deny is the correct answer only when no controller exists to escalate to. When a background or worker context has any reachable parent/leader session, route the pending approval there as a first-class object (see Permission Runtime Model) rather than defaulting to silent denial.

Inheritance rules: a parent session in auto overrides any permissionMode set in subagent frontmatter. Plugin-shipped agents are additionally restricted: hooks, mcpServers, and permissionMode fields in plugin agent definitions are silently ignored by the runtime.

Rule syntax an expert checks first

• Evaluation order is fixed, not precedence-weighted: deny, then ask, then allow — first match wins regardless of specificity. A broad Bash(aws *) deny still blocks a narrower Bash(aws s3 ls) allow; there is no allowlist-exception mechanism inside a deny rule.
• Parameter-matching rules (Tool(param:value), v2.1.178+) let deny/ask rules gate on any top-level scalar input field, e.g. Agent(model:opus) or Agent(isolation:worktree) or Bash(run_in_background:true). This is distinct from — and composes with — the older Agent(AgentName) subagent-identity rule. Fields a tool already canonicalizes (command for Bash, file_path for Read/Edit/Write) are excluded from this path and must use the tool's own specifier syntax; a Bash(command:rm *) rule is silently ignored with a startup warning because it would be bypassable by a compound command.
• Path-anchor bugs are the most common review finding: //path is filesystem-absolute; /path is relative to the settings file that defines the rule, not the project root or the CLI's cwd. A Read(/secrets/**) deny written into ~/.claude/settings.json blocks ~/.claude/secrets/**, not a project's secrets/ directory — reviewers should flag every single-leading-slash path rule in user settings as a likely mistake.
• Symlinks split allow/deny asymmetrically: allow rules require both the symlink path and its resolved target to match (otherwise it falls back to prompting); deny rules fire if either the symlink path or the target matches. A symlink into an allowed directory pointing outside it is not auto-approved by that fact alone.
• Hooks are best-effort, not enforcement: a PreToolUse hook's if field scopes it with permission-rule syntax (e.g. if: "Bash(rm *)"), but the filter fails open — if the Bash command can't be parsed, the hook runs anyway. Deny/ask permission rules are evaluated independently of what a hook returns, so a hook cannot be the sole enforcement point for a hard boundary; it can add checks, not replace deny/ask rules. See ../agents-hooks/SKILL.md for hook event and matcher design.

Settings precedence, briefly (permission-audit nuance only)

Full precedence chain — managed settings > CLI arguments > local project (.claude/settings.local.json) > shared project (.claude/settings.json) > user (~/.claude/settings.json) — is ../ai-coding-agents-settings-policy/SKILL.md's territory; use it for full source layering and managed-policy design.

The one nuance load-bearing for a permission audit: that precedence order governs plain settings (e.g. spinnerTipsEnabled), but permission rules do not simply follow "higher scope wins." A deny rule from any scope blocks the action regardless of scope precedence — a user-level deny blocks a project-level allow and a project-level deny blocks a user-level allow, because deny is evaluated before allow at every scope and rules merge across scopes rather than one file overriding another wholesale. Do not assume "project settings win over user settings" applies to allow-vs-deny conflicts — check which rule is a deny before applying the file-precedence mental model.

OpenAI Codex: AskForApproval Policy Enum

Source: live codex-rs/protocol/src/protocol.rs (main branch, re-verified July 2026) — re-check before shipping, since Codex's config surface has changed shape twice within a few months.

TOML key: approval_policy (type Option<AskForApproval>, in the top-level [config] section of ~/.codex/config.toml)

Correction from an earlier snapshot of this skill: a prior pinned-commit source (2026-05-22) showed UnlessTrusted serializing as "unless-trusted" and a separate deprecated OnFailure variant ("all commands auto-approved, rely on the sandbox"). The live source now serializes UnlessTrusted as "untrusted", and OnFailure is gone as a distinct variant — "on-failure" is now only a backward-compatible TOML alias that deserializes into OnRequest, so a config still carrying approval_policy = "on-failure" gets OnRequest behavior, not the old always-auto-approve behavior. Treat this as a general lesson, not just a one-time fix: pinned-commit citations for a fast-moving CLI's config surface expire faster than the rest of this skill; re-fetch the live source (or current config-reference docs) before trusting an enum-value table, and prefer on-request/never explicitly over relying on the on-failure alias.

GranularApprovalConfig lets operators selectively enable or suppress approval prompts per action class, allowing a policy like "always ask for MCP tool calls, never ask for skill-script approval."

Design rule: treat AskForApproval as the canonical approval-mode type when implementing Codex-compatible runtimes — do not invent a parallel enum. Do not write new code that branches on a standalone on-failure semantic; it is an alias, not a policy.

Cross-Platform Patterns (Goose)

Goose exposes two approval surfaces the current skill does not model: identity-aware approvals via an OIDC proxy, and ACP-bridged approvals where approvals must round-trip across a stdio boundary to a delegating agent.

Identity-aware approvals (OIDC proxy)

Goose ships an oidc-proxy/ crate that bridges agent calls to external providers through an OIDC-authenticated proxy. Approvals tied to external side-effects (deploy, merge, paid API use) can be gated on the authenticated identity, not just on "the user accepted a local prompt."

• Pattern: treat user identity as a permission-context field alongside mode and rule sources. Certain rule classes (destructive-on-prod, financial, third-party) can require fresh auth proof, not just a prior local allow.
• Anti-pattern: assuming the OS user running the CLI is the authorization principal for remote/side-effecting approvals. Shared dev machines, CI agents, and teammate-session handoff all break that assumption.
• Recipe: add an optional auth_proof field to the permission context; rules can declare require_fresh_auth: true. For those, every N minutes or per-call, the host demands re-authentication via OIDC proxy. Record the identity with the approval outcome for audit.

ACP-bridged approvals

When a session delegates work to an external ACP agent (see ai-coding-agents-remote-runtime agent-delegating mode, and ai-coding-agents-provider-runtime agent-as-provider), tool approvals requested by the delegated agent must round-trip back to the orchestrator's local UI. The skill's current worker-routing model assumes same-process workers.

• Pattern: approvals raised by an ACP-delegated agent travel back through the ACP control channel, are materialized as a pending approval object in the orchestrator, rendered in the orchestrator's UI, resolved locally, and the outcome is sent back through ACP to the delegated agent. Stable request IDs are required end-to-end.
• Anti-pattern: auto-approving everything from a "trusted" delegated agent. ACP does not bound the delegated agent's tool use; without round-trip approval, the orchestrator loses audit and policy.
• Recipe: add a third routing leg in the permission-routing reference: orchestrator ↔ ACP-delegated agent. The delegated agent's approval requests are first-class runtime objects in the orchestrator's permission context, with stable IDs, cancellation support, and cross-process cancellation on session death.

Navigation

References

• references/permission-runtime-model.md — Central permission context, plan-mode restore, and host-owned rule layers
• references/permission-routing-local-remote-and-worker.md — Approval flows for REPL, remote sessions, and swarm workers
• references/openai-codex-request-permissions-and-split-policy.md — OpenAI Codex split filesystem policy, protected metadata, request_permissions, and hostile-case tests
• references/openai-codex-execpolicy-and-network-proxy.md — OpenAI Codex executable policy engine and network proxy boundary patterns
• references/hostile-path-test-checklist.md — Adversarial path, symlink, and containment cases for permission-boundary tests

Data

• data/sources.json — Primary documentation and source references for approval-system design

Related Skills

• ../agents-hooks/SKILL.md
• ../agents-swarm-orchestration/SKILL.md
• ../ai-coding-agents-plugins/SKILL.md

Fact-Checking

• Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
• The patterns here are grounded in a local April 2026 claude_code source snapshot. Verify current permission field names, event names, and remote control schemas before shipping.
• Approval UX and sandbox semantics are runtime-specific. Preserve the architecture patterns, but re-check exact prompt behavior for the target client.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.