Configuring Claude Code Tool Permissions, Subagent Scopes, and Execution Safeguards

Configuring Claude Code tool permissions allows developers to balance autonomous execution velocity with strict security boundaries by defining allowed tools, auto-approval glob patterns, and subagent scopes in ~/.claude/settings.json and .claude/settings.json. By establishing granular execution safeguards, teams eliminate disruptive confirmation prompts while preventing destructive terminal commands and credential exfiltration.

Where Does Claude Code Store Tool Permissions and Configuration Files?

Claude Code stores tool permissions and execution policies in two distinct configuration layers: a global user profile located at ~/.claude/settings.json on macOS and Linux, and repository-specific project configurations located at .claude/settings.json in the project root. The global configuration applies to every interactive terminal session across all local repositories, establishing your baseline auto-approved tools, default model parameters, and global ignore lists. The project-level configuration allows engineering teams to enforce repository-specific tool constraints, required review gates, and custom test execution policies that apply whenever Claude Code is initialized within that repository's directory tree.

As Anthropic details in its official Claude Code documentation: “Claude Code prompts for approval before executing commands that could alter your filesystem, spawn network connections, or run untrusted scripts, giving developers explicit oversight over terminal operations.” Understanding where these security boundaries reside on your local disk is the first step toward automating repetitive developer tasks without ceding uncontrolled root-level execution privileges to an autonomous LLM loop.

The following filesystem layout illustrates the dual-tier configuration architecture used by Claude Code:

# Claude Code Configuration & Permission Hierarchy
~/.claude/
├── settings.json              # Global user permissions, autoApprove list, and model keys
└── skills/                    # Global personal skill packages (SKILL.md)
    ├── automated-refactor/
    └── git-commit-formatter/

/path/to/project-repository/
├── .claude/
│   ├── settings.json          # Repository-scoped permissions & project autoApprove rules
│   └── skills/                # Project-specific domain skills
└── .gitignore                 # Must include .claude/settings.local.json

Claude Code resolves tool permissions hierarchically, merging global settings in ~/.claude/settings.json with repository-specific overrides in .claude/settings.json, where project-level restrictions strictly override user-level auto-approvals. This inheritance pattern ensures that an individual developer's permissive personal machine configuration cannot bypass an enterprise repository's security guardrails. For engineers organizing instructions across multiple codebases, read our guide on managing Claude skills across projects and repositories.

How Do Global and Project-Level Permission Settings Interact?

Global and project-level settings interact through a strict hierarchical merge, where project settings take precedence over global settings whenever a collision occurs. When Claude Code executes a tool call—such as writing to a source file, executing a shell command via the Bash tool, or reading an environment variable—it checks the project configuration first; if the project explicitly blocks the tool, the invocation is denied regardless of global settings. If neither file blocks the tool, Claude Code inspects the merged autoApprove array: if an exact or prefix match exists, the command executes silently; otherwise, the terminal prompts the developer for interactive confirmation.

This deterministic precedence model allows developers to configure general quality-of-life automations globally while safeguarding high-risk production repositories. Here is an example of a production-hardened global configuration in ~/.claude/settings.json:

// ~/.claude/settings.json (Global Developer Settings)
{
  "allowedTools": [
    "Bash",
    "FileRead",
    "FileWrite",
    "Glob",
    "Grep",
    "Task"
  ],
  "autoApprove": [
    "Bash(git status)",
    "Bash(git diff *)",
    "Bash(git log *)",
    "Bash(npm test)",
    "Bash(cargo check)",
    "FileRead"
  ],
  "blockedTools": [],
  "commandTimeoutSeconds": 30
}

When working inside a repository that handles sensitive financial logic or personal health data, the team can commit a defensive .claude/settings.json that restricts shell execution and forces human confirmation on all write actions:

// /repo/.claude/settings.json (Repository Security Override)
{
  "allowedTools": [
    "FileRead",
    "Glob",
    "Grep"
  ],
  "autoApprove": [
    "FileRead"
  ],
  "blockedTools": [
    "Bash"
  ]
}

By blocking Bash inside the project configuration, the team guarantees that Claude Code cannot execute arbitrary terminal scripts, pull unverified dependencies, or exfiltrate private API keys, even if the developer has configured permissive auto-approvals on their personal machine. To safeguard credentials further, review our comprehensive architectural guide to building a secure AI code prompt library.

How Do You Configure Auto-Approval for Safe Tools While Blocking Destructive Commands?

You configure auto-approval safely by specifying exact command strings or strict prefix globs in the autoApprove array, targeting idempotent, read-only utilities while excluding broad shell patterns. Commands such as git status, npm test, cargo test, and pytest tests/unit are ideal candidates for auto-approval because they inspect repository state or run sandboxed unit tests without mutating production files or deploying infrastructure. Destructive commands that modify remote branches, delete files, or alter credentials must remain strictly gated behind manual terminal confirmation prompts.

In high-frequency coding sessions, waiting for manual confirmation on every simple grep search or test run incurs between 2,000 and 8,000 tokens of redundant context window overhead per hour, as repetitive y/n terminal exchanges pollute the conversational transcript. However, attempting to eliminate this friction by granting over-permissive wildcards is dangerous.

Wildcard globbing in Claude Code's autoApprove array matches command prefixes, meaning Bash(git *) grants execution permissions to both benign commands like git status and destructive actions like git reset --hard. If Claude Code hallucinates or encounters an unexpected shell error while Bash(git *) is auto-approved, it can invoke git push origin main --force or git checkout -f without pausing for developer approval.

The following configuration demonstrates an enterprise auto-approval configuration that maintains high developer velocity while blocking destructive command execution:

// Enterprise Hardened autoApprove Configuration
{
  "autoApprove": [
    // Read-only filesystem operations
    "FileRead",
    "Glob",
    "Grep",

    // Safe Git inspection commands
    "Bash(git status)",
    "Bash(git status -s)",
    "Bash(git diff)",
    "Bash(git diff --staged)",
    "Bash(git log -n *)",
    "Bash(git branch)",

    // Idempotent test runners and linters
    "Bash(npm run lint)",
    "Bash(npm test)",
    "Bash(pytest tests/unit/*)",
    "Bash(cargo check)",
    "Bash(cargo test --lib)"
  ]
}

Notice that write-heavy git actions—such as git commit, git push, and git rebase—are excluded from the autoApprove list. When Claude Code attempts to finalize a changeset, it must prompt the engineer with the exact command and commit message, maintaining human accountability in the loop. For teams standardizing instruction formatting across assistants, review our architectural specification on AGENTS.md across coding agents.

Subagent Scoping and Tool Delegation Safeguards

Subagent scoping governs the tool execution boundaries of child tasks spawned by Claude Code via the Task tool. In complex development workflows, the primary agent frequently delegates sub-tasks—such as scanning a 50,000-line codebase for architectural anti-patterns, parsing dependency vulnerabilities, or verifying API backwards compatibility—to dedicated subagents. If subagents inherit the primary session's execution permissions without boundary checks, a compromised or hallucinating child task can execute unauthorized terminal commands or flood system resources in background threads.

Subagents spawned via Claude Code's Task tool inherit parent tool permissions by default, creating privilege escalation vulnerabilities if background tasks are permitted unrestricted write access to the host shell. Under the Model Context Protocol (MCP) security specification, client applications must isolate tool capabilities by execution context to prevent lateral privilege escalation.

To safeguard subagent execution, follow three core architectural rules:

• Enforce Read-Only Tool Scopes: Subagents assigned to analytical tasks (such as code review, bug hunting, or architecture mapping) must be restricted to FileRead, Grep, and Glob. By explicitly denying Bash and FileWrite in the subagent instruction payload, you eliminate the risk of accidental filesystem modifications.
• Bound Subshell Execution Timeouts: Configure a strict commandTimeoutSeconds limit (typically 15 to 30 seconds) on any bash command executed by a worker task. This prevents runaway processes, infinite loops, or hanging network requests from deadlocking terminal sessions.
• Structured Transcript Rollups: Prohibit subagents from dumping raw compiler traces or thousands of lines of terminal output into the parent conversation. Enforce concise, structured markdown summaries to protect the primary session's 200,000-token context budget.

When building reusable subagent templates, using an automated Claude Code prompt template builder ensures that role definitions, allowed tools, and negative constraints are verified before subagents are launched in mission-critical environments.

Comparing Tool Permission Models: Claude Code vs Codex CLI vs Cursor vs Google Antigravity

Different AI coding agents implement fundamentally divergent security models to manage terminal command execution, filesystem access, and subagent delegation. Claude Code relies on interactive terminal approval gates backed by hierarchical JSON settings; OpenAI Codex CLI uses process-level shell isolation flags; Cursor IDE gates terminal commands via visual dialogs in the desktop interface; and Google Antigravity utilizes declarative tool groups combined with native Git worktree sandboxing.

The following matrix compares how each leading coding agent handles tool permissions, execution sandboxes, and multi-machine policy enforcement:

As teams operate across multiple tools, maintaining divergent configuration files across ~/.claude/settings.json, Cursor rules, and Codex skill packages leads to severe permission drift and inconsistent execution safeguards. To explore cross-tool permission translation, read our deep architectural comparison of Google Antigravity vs Codex CLI workspace architectures.

What Are the Most Critical Security Traps in Claude Code Tool Approvals?

The most critical security traps in Claude Code tool approvals are the uncritical use of the --dangerously-skip-permissions flag, prefix-glob collisions that inadvertently permit destructive operations, and repository configuration poisoning via cloned codebases. According to the OWASP Top 10 for Large Language Models (specifically LLM06: Excessive Agency), granting autonomous agents unconstrained tool access without input sanitization or verification gates represents a critical vulnerability in enterprise engineering pipelines.

Engineering teams operating Claude Code in production must guard against three primary failure modes:

1. The Dangerously-Skip-Permissions Trap: Developers frequently append --dangerously-skip-permissions to terminal invocations to bypass tedious prompts during large refactoring jobs. In doing so, they eliminate all safety nets. If an agent misinterprets a relative path, it can delete local files, flush uncommitted git stashes, or run unverified third-party binaries with the full permissions of the developer's user account.
2. Repository Configuration Poisoning: When cloning an open-source or untrusted repository, inspect .claude/settings.json immediately. An attacker can commit a malicious project configuration that pre-authorizes dangerous shell commands or configures malicious MCP servers that trigger upon initialization. Always add .claude/settings.local.json to your global .gitignore and audit checked-in settings files.
3. Environment Variable & Secret Exfiltration: Auto-approving commands like Bash(curl *) or Bash(env) allows an agent to transmit local environment variables, cloud credentials, or OAuth tokens to external endpoints during an unvetted script execution. Ensure that outbound network commands and environment inspection utilities are never placed on the autoApprove whitelist.

For teams deploying Model Context Protocol servers alongside Claude Code, resolve protocol handshake deadlocks and socket failures with our diagnostic guide on troubleshooting MCP prompt server errors and timeouts.

The Sprawl Moment: The New Laptop and the Unchecked Shell Script

You spend two weeks fine-tuning your Claude Code auto-approval rules on your primary MacBook Pro, whitelisting your local Docker test harnesses, linting scripts, and sanitized build targets so that you can refactor services without hitting fifty permission prompts an hour. On Thursday morning, your staging cluster throws an authentication cascade, and you grab your secondary travel laptop to investigate. You fire up Claude Code inside the incident response repo, type your familiar triage prompt, and watch in frustration as every single file search, git diff, and status probe hangs waiting for manual y/n confirmation in the terminal. Desperate to move fast during the outage, you pass --dangerously-skip-permissions to bypass the prompts—only for the agent to execute an unvalidated cleanup script that flushes your local staging cache, corrupts your local .env variables, and forces you to spend the next hour rebuilding your development environment from scratch.

How Can Teams Centralize Tool Governance and Skill Permissions with Prompttly?

Teams centralize tool governance and skill permissions by maintaining a unified, version-controlled skill library that compiles consistent execution guardrails, auto-approval lists, and tool definitions across every developer workstation. Instead of manually copying JSON snippets between laptops or committing risky configuration files to Git, a centralized skill manager ensures that approved commands, subagent constraints, and custom prompts follow the developer automatically.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Prompttly eliminates multi-machine permission drift by maintaining a synchronized registry of skill schemas, execution safeguards, and Mac menu bar hotkeys across Claude Code, Codex, and Cursor. When an engineer defines a new skill with required tool permissions, Prompttly writes the sanitized SKILL.md package into ~/.claude/skills/, updates the local allowedTools policy, and compiles equivalent rule files for Cursor and Codex in real time.

On macOS, Prompttly provides a global hotkey palette that floats above your terminal and IDE. With sub-200ms keystroke retrieval, developers can search hundreds of verified prompt templates, review parameter requirements, and inject pre-tested commands directly into Claude Code without copy-pasting or risking unvetted shell execution.

Can You Enforce Strict Read-Only Boundaries for CI/CD and Remote Environments?

You enforce strict read-only boundaries in CI/CD and remote headless environments by combining the --blocked-tools flag with an immutable project settings file that completely removes FileWrite, FileEdit, and write-capable Bash invocations. In continuous integration pipelines—such as automated PR code reviews, architectural linter checks, or security compliance scans—Claude Code should operate strictly as an analytical engine that outputs structured comments or JSON reports without modifying repository files or executing arbitrary subshell processes.

Here is a production CI/CD script that invokes Claude Code in a hardened, read-only container:

#!/usr/bin/env bash
# Hardened Read-Only CI/CD Invocation for Claude Code
set -euo pipefail

# Initialize strict read-only container environment
claude-code \
  --allowed-tools "FileRead,Glob,Grep" \
  --blocked-tools "Bash,FileWrite,FileEdit" \
  --prompt "Review pull request diff against main. Output security findings in SARIF format." \
  --output-file "./reports/claude-security-audit.json"

By explicitly defining --allowed-tools "FileRead,Glob,Grep" and blocking execution utilities, engineering teams eliminate the possibility of automated agents injecting malicious code, modifying CI scripts, or tampering with container credentials. To establish organization-wide prompt testing and policy assertion frameworks, explore our enterprise breakdown of AI prompt governance and versioning tools.

Frequently Asked Questions About Claude Code Tool Permissions

These are the most common technical questions software engineers ask when configuring, automating, and securing tool permissions in Claude Code.

Next Steps: Hardening Your AI Agent Execution Stack

Configuring granular tool permissions in Claude Code transforms an unpredictable terminal assistant into a hardened, high-velocity development partner. To expand your agent infrastructure safely, review our architectural guide on standardizing multi-agent rules across AGENTS.md, .cursor/rules, and Claude Skills, or consult our diagnostic protocol on auditing broken symlinks and filesystem traps in agent skills.

If you are building your first structured agent workflow, jumpstart your implementation with our free Claude Skill Creator and Custom Instructions Generator. When your team is ready to eliminate permission drift, secure developer skills, and access your entire prompt library in under 200ms from anywhere on macOS, explore Prompttly for Teams and download Prompttly for Mac.