Feature: Granular control for bash command auto-approval in tool_approval plugin

[wu-changxing]

Problem

Currently, the tool_approval plugin's auto-approve feature only supports tool-level control. When you add bash to the auto-approve list, it approves all bash commands, including potentially dangerous ones.

# Current limitation - all or nothing
agent = Agent(
    "assistant",
    tools=[bash],
    auto_approve_tools=["bash"]  # ❌ Approves EVERYTHING: ls, rm -rf, git push, etc.
)

This forces users to choose between:

• ❌ Too permissive: Auto-approve all bash commands (dangerous)
• ❌ Too restrictive: Manually approve every single command (annoying)

Desired Feature

Add granular command and parameter control to auto-approval:

# Proposed syntax - granular control
agent = Agent(
    "assistant",
    tools=[bash],
    auto_approve_tools={
        "bash": {
            "commands": ["git status", "git diff", "ls", "pwd"],  # Exact commands
            "patterns": [
                r"^git log",           # Regex patterns
                r"^pytest.*--tb=short", # Allow specific flags
                r"^npm run build"
            ],
            "safe_prefixes": ["git status", "git log", "git diff"],  # Prefix matching
            "blocked_patterns": [r"rm -rf", r"git push.*--force"]    # Explicitly block
        }
    }
)

Use Cases

1. Safe git operations only

auto_approve_tools={
    "bash": {
        "commands": ["git status", "git diff", "git log"],
        "blocked_patterns": [r"git push", r"git reset --hard", r"git clean -f"]
    }
}

2. Read-only file operations

auto_approve_tools={
    "bash": {
        "commands": ["ls", "pwd", "cat", "head", "tail"],
        "patterns": [r"^grep", r"^find.*-name"],
        "blocked_patterns": [r"rm", r"mv", r"cp"]
    }
}

3. Test commands only

auto_approve_tools={
    "bash": {
        "patterns": [
            r"^pytest.*",
            r"^npm test",
            r"^python -m unittest"
        ]
    }
}

4. Directory-restricted operations

auto_approve_tools={
    "bash": {
        "patterns": [r"^cd /safe/path/"],
        "validate": lambda cmd: "/safe/path/" in cmd  # Custom validation
    }
}

Implementation Suggestions

1. Update tool_approval.py auto-approve check

Current code (simplified):

# In tool_approval.py
if tool_name in auto_approve_list:
    return  # Auto-approve

Proposed:

def should_auto_approve(tool_name: str, tool_args: dict, auto_approve_config) -> bool:
    """Check if tool execution should be auto-approved based on granular rules."""
    
    if isinstance(auto_approve_config, list):
        # Backward compatible: simple list of tool names
        return tool_name in auto_approve_config
    
    if isinstance(auto_approve_config, dict):
        if tool_name not in auto_approve_config:
            return False
        
        rules = auto_approve_config[tool_name]
        
        # For bash tool, check command
        if tool_name == "bash":
            command = tool_args.get("command", "")
            
            # Check exact commands
            if "commands" in rules and command in rules["commands"]:
                return True
            
            # Check patterns
            if "patterns" in rules:
                for pattern in rules["patterns"]:
                    if re.match(pattern, command):
                        return True
            
            # Check safe prefixes
            if "safe_prefixes" in rules:
                for prefix in rules["safe_prefixes"]:
                    if command.startswith(prefix):
                        return True
            
            # Check blocked patterns (explicit deny)
            if "blocked_patterns" in rules:
                for pattern in rules["blocked_patterns"]:
                    if re.search(pattern, command):
                        return False
            
            # Custom validation function
            if "validate" in rules and callable(rules["validate"]):
                return rules["validate"](command)
        
        # For other tools, just check if they're in the dict (simple approval)
        return True
    
    return False

2. Backward Compatibility

# Old syntax still works
auto_approve_tools=["bash", "search", "write_file"]

# New syntax is opt-in
auto_approve_tools={
    "bash": {"commands": ["git status"]},
    "search": True,  # Simple approval
    "write_file": {"patterns": [r"^/tmp/.*"]}  # Path restrictions
}

3. Configuration Validation

Add validation to catch typos and invalid patterns:

def validate_auto_approve_config(config):
    """Validate auto_approve_tools configuration."""
    if isinstance(config, dict):
        for tool_name, rules in config.items():
            if isinstance(rules, dict):
                # Validate known keys
                valid_keys = {"commands", "patterns", "safe_prefixes", "blocked_patterns", "validate"}
                unknown_keys = set(rules.keys()) - valid_keys
                if unknown_keys:
                    raise ValueError(f"Unknown auto-approve keys for '{tool_name}': {unknown_keys}")
                
                # Validate regex patterns compile
                for pattern_key in ["patterns", "blocked_patterns"]:
                    if pattern_key in rules:
                        for pattern in rules[pattern_key]:
                            try:
                                re.compile(pattern)
                            except re.error as e:
                                raise ValueError(f"Invalid regex pattern '{pattern}': {e}")

Benefits

✅ Safety: Only approve specific safe commands
✅ Convenience: Auto-approve common read-only operations
✅ Flexibility: Regex patterns for complex matching
✅ Backward compatible: Existing code keeps working
✅ Explicit blocklist: Prevent dangerous operations even with broad patterns
✅ Custom validation: Lambda/function support for complex logic

Related

• Existing tool_approval docs: docs/useful_plugins/tool_approval.md
• Shell approval plugin: connectonion/useful_plugins/shell_approval.py (similar pattern could be used)

Priority

Medium-High - This would significantly improve UX for automated agents while maintaining security.

---

Additional Ideas:

• Add dry-run mode to test what would be auto-approved
• Logging of auto-approved commands for audit trail
• Rate limiting on auto-approvals (max N auto-approvals per minute)
• Time-based rules (auto-approve only during working hours)

[wu-changxing]

🔍 Summary

Add a programmatic auto_approve_tools parameter to Agent that enables granular bash command auto-approval in code (instead of YAML-only). The existing unified permission system already supports exact commands (Bash(git status)), wildcards (Bash(git *)), and parameter matching (when field). This feature adds a Python API on top of that system, plus a new blocked patterns (deny list) capability.

📊 Current vs Proposed

CURRENT (Problem):
┌──────────────────────────────────────────────────────────┐
│ User wants granular bash auto-approval                   │
│                                                          │
│ Option A: YAML only (host.yaml)                          │
│   .co/host.yaml:                                         │
│     permissions:                                         │
│       "Bash(git status)": {allowed: true, ...}          │
│                                                          │
│ Option B: All-or-nothing in code                         │
│   Agent("name", ...) → approve ALL bash or NONE          │
│                                                          │
│ ❌ No Python API for granular control                    │
│ ❌ No deny list (blocked patterns)                      │
│ ❌ YAML config requires file system setup                │
└──────────────────────────────────────────────────────────┘

PROPOSED (Solution):
┌──────────────────────────────────────────────────────────┐
│ Agent("name",                                            │
│   auto_approve_tools={                                   │
│     "bash": {                                            │
│       "commands": ["git status", "git diff"],            │
│       "patterns": ["git log *", "pytest *"],             │
│       "blocked":  ["rm *", "git push --force *"]         │
│     },                                                   │
│     "write": True,                                       │
│     "edit": {"when": {"file_path": "*.md"}}              │
│   }                                                      │
│ )                                                        │
│                                                          │
│ ✅ Programmatic API for granular control                 │
│ ✅ Deny list (blocked patterns)                          │
│ ✅ Backward compatible (list syntax still works)         │
│ ✅ Reuses existing unified permission system             │
└──────────────────────────────────────────────────────────┘

📁 Files to Change

connectonion/
├── core/
│   └── agent.py              ← Add auto_approve_tools parameter to __init__
├── useful_plugins/
│   └── tool_approval/
│       ├── approval.py       ← Convert auto_approve_tools → unified permissions
│       │                        Add blocked pattern check in check_approval()
│       └── bash_parser.py    ← Add is_blocked() function
├── docs/
│   └── useful_plugins/
│       └── tool_approval.md  ← Document new API
tests/
├── unit/
│   └── test_tool_approval.py ← Test auto_approve_tools conversion + blocked
├── integration/
│   └── test_config_permissions.py ← Test programmatic + YAML coexistence

🏗️ Architecture

Agent.__init__(auto_approve_tools=...)
     │
     │ stores as self.auto_approve_tools
     │
     ▼
tool_approval plugin
     │
     │ @after_user_input: load_config_permissions()
     │
     ├─ 1. Load template host.yaml (safe tools) ← EXISTING
     ├─ 2. Load project .co/host.yaml (config)  ← EXISTING
     └─ 3. Convert agent.auto_approve_tools      ← NEW
          │
          ├─ List: ["bash"] → {'bash': {allowed: True, source: 'code'}}
          ├─ Dict + True: {"write": True} → {'write': {allowed: True, source: 'code'}}
          ├─ Dict + commands: {"bash": {"commands": ["git status"]}}
          │    → {'Bash(git status)': {allowed: True, source: 'code', when: {command: 'git status'}}}
          ├─ Dict + patterns: {"bash": {"patterns": ["git *"]}}
          │    → {'Bash(git *)': {allowed: True, source: 'code', when: {command: 'git *'}}}
          └─ Dict + blocked: {"bash": {"blocked": ["rm *"]}}
               → session['blocked_patterns'] = {'bash': ['rm *']}

🔄 Data Flow — Auto-Approval Check

before_each_tool fires → check_approval(agent)
     │
     ▼
1. Is bash tool with command?
     │ yes
     ▼
2. ┌─────────────────────────────┐
   │ CHECK BLOCKED (NEW)         │ ← New step: deny list
   │ session['blocked_patterns'] │
   │ for pattern in blocked:     │
   │   fnmatch(command, pattern) │
   │   → if match: SKIP to step 4│
   └──────────────┬──────────────┘
                  │ not blocked
                  ▼
3. ┌─────────────────────────────┐
   │ CHECK PERMITTED (EXISTING)  │
   │ check_bash_chain_permitted()│
   │   → bashlex parse chain     │
   │   → check each subcommand   │
   │   → fnmatch against perms   │
   │   → if ALL permitted: ✅    │
   └──────────────┬──────────────┘
                  │ not permitted
                  ▼
4. ┌─────────────────────────────┐
   │ APPROVAL REQUEST (EXISTING) │
   │ → WebSocket approval_needed │
   │ → Block for client response │
   └─────────────────────────────┘

📝 Implementation Steps

Step 1: Add auto_approve_tools to Agent

File: connectonion/core/agent.py

• Add auto_approve_tools parameter to Agent.__init__ (accept list | dict | None)
• Store as self.auto_approve_tools
• No validation here — the plugin handles interpretation

Step 2: Convert programmatic config in load_config_permissions

File: connectonion/useful_plugins/tool_approval/approval.py

Add _load_code_permissions(agent) helper called at end of load_config_permissions():

def _load_code_permissions(agent):
    """Convert agent.auto_approve_tools to unified permission format."""
    config = getattr(agent, 'auto_approve_tools', None)
    if not config:
        return

    if isinstance(config, list):
        # ["bash", "write"] → blanket approval
        for tool_name in config:
            agent.current_session['permissions'][tool_name] = {
                'allowed': True, 'source': 'code',
                'reason': 'auto_approve_tools', 'expires': {'type': 'never'}
            }
        return

    # Dict config
    for tool_name, rules in config.items():
        if rules is True:
            # {"write": True} → blanket approval
            agent.current_session['permissions'][tool_name] = {
                'allowed': True, 'source': 'code',
                'reason': 'auto_approve_tools', 'expires': {'type': 'never'}
            }
            continue

        if isinstance(rules, dict):
            # Granular rules
            if 'commands' in rules:
                for cmd in rules['commands']:
                    key = f'Bash({cmd})'
                    agent.current_session['permissions'][key] = {
                        'allowed': True, 'source': 'code',
                        'reason': 'auto_approve_tools',
                        'when': {'command': cmd},
                        'expires': {'type': 'never'}
                    }

            if 'patterns' in rules:
                for pattern in rules['patterns']:
                    key = f'Bash({pattern})'
                    agent.current_session['permissions'][key] = {
                        'allowed': True, 'source': 'code',
                        'reason': 'auto_approve_tools',
                        'when': {'command': pattern},
                        'expires': {'type': 'never'}
                    }

            if 'when' in rules:
                agent.current_session['permissions'][tool_name] = {
                    'allowed': True, 'source': 'code',
                    'reason': 'auto_approve_tools',
                    'when': rules['when'],
                    'expires': {'type': 'never'}
                }

            if 'blocked' in rules:
                if 'blocked_patterns' not in agent.current_session:
                    agent.current_session['blocked_patterns'] = {}
                agent.current_session['blocked_patterns'][tool_name] = rules['blocked']

Step 3: Add blocked pattern check in check_approval

File: connectonion/useful_plugins/tool_approval/approval.py

In check_approval(), add a blocked check BEFORE the existing permission check:

# After getting pending tool info, before checking permissions:
blocked_patterns = agent.current_session.get('blocked_patterns', {})
if tool_name in blocked_patterns and 'command' in tool_args:
    import fnmatch
    command = tool_args['command']
    for pattern in blocked_patterns[tool_name]:
        if fnmatch.fnmatch(command, pattern):
            # Blocked — fall through to approval request
            break
    else:
        # Not blocked — continue to permit check
        pass

Also add blocked check to check_bash_chain_permitted() in bash_parser.py:

File: connectonion/useful_plugins/tool_approval/bash_parser.py

Add optional blocked_patterns parameter to check_bash_chain_permitted().

Step 4: Tests

File: tests/unit/test_tool_approval.py

class TestAutoApproveTools:
    def test_list_syntax_backward_compat(self):
        """auto_approve_tools=['bash'] approves all bash."""

    def test_dict_commands_exact_match(self):
        """commands=['git status'] only approves exact match."""

    def test_dict_patterns_wildcard(self):
        """patterns=['git *'] approves git subcommands."""

    def test_dict_blocked_denies_matching(self):
        """blocked=['rm *'] forces approval even if pattern allows."""

    def test_blocked_takes_priority_over_allowed(self):
        """blocked pattern overrides allowed pattern."""

    def test_dict_true_blanket_approval(self):
        """{"write": True} approves all write calls."""

    def test_when_parameter_matching(self):
        """{"edit": {"when": {"file_path": "*.md"}}} matches .md only."""

    def test_coexistence_with_yaml_config(self):
        """Programmatic + YAML permissions merge correctly."""

Step 5: Documentation

File: docs/useful_plugins/tool_approval.md

Add section "Programmatic Auto-Approval" with examples.

⚠️ Risks & Considerations

• Glob vs Regex: Issue proposes regex (re.match), but existing system uses fnmatch (glob). Plan uses glob for consistency. Regex can be added later if needed.
• validate callback: Issue proposes validate: lambda cmd: .... Skipped for now (YAGNI). Can add later.
• Priority: blocked > code > config > safe. User approvals (source: 'user') should still override blocked patterns.
• Bash chain + blocked: If git push --force is blocked but git status is allowed, git status && git push --force must be rejected (chain validation).

🧪 Testing Strategy

• Unit tests for each syntax variant (list, dict, commands, patterns, blocked)
• Integration tests for programmatic + YAML coexistence
• Edge cases: blocked overriding allowed, chains with mixed blocked/allowed commands
• Backward compatibility: existing tests must still pass unchanged