permission-flags-reference

Overview

When running agents in headless mode (claude -p), you may need to grant tool permissions to allow agents to read files, execute bash commands, etc.

Permission Flags

1. --permission-mode <mode>

Controls how permission requests are handled.

Available modes:

bypassPermissions (Recommended for Testing)

Automatically grants all permissions without prompting.

claude -p "Use the my-agent..." --permission-mode bypassPermissions

Use when:

• Testing agents in headless mode
• Agent needs to use Read, Write, Bash, Grep, Glob tools
• You’re in a trusted/sandboxed environment

Example:

claude -p "Use the rate-card-extractor-generator and provide its complete response. Process the rate card files." --permission-mode bypassPermissions

acceptEdits

Auto-accepts file edit operations but may still prompt for other permissions.

claude -p "..." --permission-mode acceptEdits

dontAsk

Don’t ask for permissions (may cause tool use to fail if permissions aren’t pre-granted).

claude -p "..." --permission-mode dontAsk

plan

Enters plan mode (planning without execution).

claude -p "..." --permission-mode plan

default

Normal interactive permission prompts (doesn’t work well in headless mode).

2. --dangerously-skip-permissions

⚠️ WARNING: Use with extreme caution!

Bypasses ALL permission checks completely.

claude -p "..." --dangerously-skip-permissions

Only use when:

• Running in an isolated sandbox
• No internet access
• Testing in controlled environment
• You fully trust the code being executed

Not recommended for:

• Production use
• Untrusted code
• Systems with internet access
• Shared environments

3. --allowed-tools <tools...>

Whitelist specific tools that can be used without permission prompts.

claude -p "..." --allowed-tools "Bash(git:*) Read Edit"

Syntax:

• Space or comma-separated list
• Can use patterns like Bash(git:*) to allow only git commands
• Tool names: Read, Write, Edit, Bash, Grep, Glob, etc.

Examples:

Allow only read operations:

claude -p "..." --allowed-tools "Read Grep Glob"

Allow git commands only:

claude -p "..." --allowed-tools "Bash(git:*)"

Allow read and git:

claude -p "..." --allowed-tools "Read,Grep,Bash(git:*)"

4. --tools <tools...>

Specify which tools are available (only works with --print mode).

claude -p "..." --tools "Bash,Edit,Read"

Special values:

• "" - Disable all tools
• "default" - Use all default tools
• List of tools - Only enable specified tools

Example:

# Only allow read operations
claude -p "..." --tools "Read,Grep"

# Disable all tools
claude -p "..." --tools ""

Recommended Combinations for Agents

For Rate Card Agent (Read + Write + Bash)

Option 1: Bypass all permissions (simplest)

claude -p "Use the rate-card-extractor-generator..." \
  --permission-mode bypassPermissions

Option 2: Whitelist specific tools

claude -p "Use the rate-card-extractor-generator..." \
  --allowed-tools "Read,Write,Bash,Grep,Glob"

Option 3: Dangerous skip (sandbox only!)

claude -p "Use the rate-card-extractor-generator..." \
  --dangerously-skip-permissions

For Read-Only Analysis

claude -p "Use the my-agent..." \
  --allowed-tools "Read,Grep,Glob" \
  --permission-mode bypassPermissions

For Git Operations

claude -p "Review git history..." \
  --allowed-tools "Bash(git:*),Read" \
  --permission-mode bypassPermissions

Complete Agent Testing Pattern

cd /path/to/project

# Full permissions for comprehensive agent
claude -p "Use the complex-agent and provide its complete response. Process data." \
  --permission-mode bypassPermissions

# Restricted permissions for safety
claude -p "Use the analyzer-agent and provide its complete response. Analyze files." \
  --allowed-tools "Read,Grep,Glob"

Comparison Table

Best Practices

1. Development/Testing

# Use bypassPermissions for rapid iteration
claude -p "Use the my-agent..." --permission-mode bypassPermissions

2. Production/CI

# Whitelist only required tools
claude -p "Use the my-agent..." --allowed-tools "Read,Grep"

3. Sandboxed Environment

# Can use dangerous skip if truly isolated
claude -p "Use the my-agent..." --dangerously-skip-permissions

4. Minimal Permissions

# Start restrictive, add tools as needed
claude -p "Use the my-agent..." --tools "Read" --permission-mode bypassPermissions

Troubleshooting

Issue: “Permission denied” errors

Solution: Add --permission-mode bypassPermissions

claude -p "..." --permission-mode bypassPermissions

Issue: Agent can’t use specific tool

Solution: Whitelist the tool

claude -p "..." --allowed-tools "Read,Write,Bash"

Issue: Too many permission prompts in headless mode

Solution: Use bypassPermissions or dontAsk

claude -p "..." --permission-mode bypassPermissions

Issue: Want to restrict what agent can do

Solution: Use --tools to limit available tools

claude -p "..." --tools "Read,Grep" --permission-mode bypassPermissions

Security Notes

1. Never use --dangerously-skip-permissions in production
2. Use --allowed-tools for fine-grained control
3. Test with bypassPermissions in development
4. Review agent tool usage before granting broad permissions
5. Use sandboxed environments when testing untrusted agents

Example: Complete Rate Card Agent Workflow

#!/bin/bash
# Rate card processing with proper permissions

cd /home/uptown/Projects/research/claude-code-agents

# Test the agent (bypass permissions for development)
claude -p "Use the rate-card-extractor-generator and provide its complete response. \
  Analyze files: 'Rate cards/Absorption Co 2025 - Rate Card.xlsx' and \
  'Rate cards/Stord Mapping key - Generic.xlsx'. \
  Describe what you find." \
  --permission-mode bypassPermissions

# Or with specific tool whitelist (more secure)
claude -p "Use the rate-card-extractor-generator and provide its complete response. \
  Process rate cards." \
  --allowed-tools "Read,Write,Bash(uv:*),Grep,Glob" \
  --permission-mode bypassPermissions

Summary

For agent development in headless mode:

claude -p "Use the [agent-name] and provide its complete response. [task]" \
  --permission-mode bypassPermissions

This combination:

• ✅ Explicitly invokes the agent
• ✅ Requests complete response
• ✅ Bypasses permission prompts
• ✅ Allows all tool usage
• ✅ Perfect for rapid iteration