utun2/.opencode/context/openagents-repo/errors/tool-permission-errors.md

Tool Permission Errors

Purpose: Diagnose and fix tool permission issues in agents

Last Updated: 2026-01-07

---

Error: Tool Permission Denied

Symptom

{
  "type": "missing-approval",
  "severity": "error",
  "message": "Execution tool 'bash' called without requesting approval"
}

Or agent tries to use a tool but gets blocked silently (0 tool calls).

---

Cause

Agent has tool disabled or denied in frontmatter:

# In agent frontmatter
tools:
  bash: false    # ← Tool disabled

permission:
  bash:
    "*": "deny"  # ← Explicitly denied

How it works:

• bash: false means agent doesn't have access to bash tool
• Framework enforces this - agent can't use bash even if prompt says to
• NOT an approval issue - it's a permission restriction

---

Solution

Option 1: Emphasize Tool Restrictions in Prompt (Recommended)

Add critical rules section at top of agent prompt:

<critical_rules priority="absolute" enforcement="strict">
  <rule id="tool_usage">
    ONLY use: glob, read, grep, list
    NEVER use: bash, write, edit, task
    You're read-only—no modifications allowed
  </rule>
  <rule id="always_use_tools">
    ALWAYS use tools to discover files
    NEVER assume or fabricate file paths
  </rule>
</critical_rules>

Why this works: Makes tool restrictions crystal clear in first 15% of prompt.

Option 2: Enable Tool (If agent needs it)

tools:
  bash: true  # ← Enable if agent legitimately needs bash

Warning: Only enable if agent truly needs the tool. Read-only subagents should NOT have bash/write/edit.

---

Prevention

For Read-Only Subagents:

# Correct configuration for read-only subagents
tools:
  read: true
  grep: true
  glob: true
  list: true
  bash: false    # ← No execution
  edit: false    # ← No modifications
  write: false   # ← No file creation
  task: false    # ← No delegation (subagents don't delegate)

permissions:
  bash:
    "*": "deny"
  edit:
    "**/*": "deny"
  write:
    "**/*": "deny"

For Primary Agents:

# Primary agents may need execution tools
tools:
  read: true
  grep: true
  glob: true
  list: true
  bash: true     # ← May need for operations
  edit: true     # ← May need for modifications
  write: true    # ← May need for file creation
  task: true     # ← May delegate to subagents

---

Error: Subagent Approval Gate Violation

Symptom

{
  "type": "missing-approval",
  "message": "Execution tool 'bash' called without requesting approval"
}

In a subagent test.

---

Cause

Subagents should NOT have approval gates - they're delegated to by primary agents who already got approval.

The issue is usually:

1. Subagent trying to use restricted tool (bash/write/edit)
2. Test expecting approval behavior (wrong for subagents)

---

Solution

Fix 1: Remove Tool Usage

Subagents shouldn't use execution tools. Update prompt to emphasize read-only nature.

Fix 2: Update Test Configuration

Subagent tests should use auto-approve:

approvalStrategy:
  type: auto-approve  # ← No approval gates for subagents

Fix 3: Check Tool Permissions

Ensure subagent has bash: false in frontmatter.

---

Error: Tool Not Available

Symptom

Agent tries to use a tool but framework says "tool not available".

---

Cause

Tool not enabled in frontmatter:

tools:
  glob: false  # ← Tool disabled

---

Solution

Enable the tool:

tools:
  glob: true  # ← Enable

---

Verification Checklist

After fixing tool permission:

• Agent frontmatter has correct tools: configuration?
• Prompt emphasizes allowed tools in critical rules section?
• Prompt warns against restricted tools?
• Test uses auto-approve for subagents?
• Test verifies tool usage with mustUseTools?

---

Tool Permission Matrix

Agent Type	bash	write	edit	task	read	grep	glob	list
Read-only subagent	❌	❌	❌	❌	✅	✅	✅	✅
Primary agent	✅	✅	✅	✅	✅	✅	✅	✅
Orchestrator	✅	✅	✅	✅	✅	✅	✅	✅

---

Related

• concepts/subagent-testing-modes.md - Understand subagent testing
• guides/testing-subagents.md - How to test subagents
• examples/subagent-prompt-structure.md - Prompt structure with tool emphasis

Reference: .opencode/agent/ContextScout.md (lines 14-28, tool configuration)