Permission System

Comprehensive approval and permission system for controlling LLM tool execution. Protect your system with fine-grained control over shell commands, file operations, and MCP tools.

Overview

The permission system intercepts every tool execution request before it happens, allowing you to approve or deny operations based on risk level and approval mode preferences. It provides:

Risk-based assessment - automatic classification of tools as HIGH, MEDIUM, or LOW risk
Inline permission prompts - single keypress approvals without modal interruption
Session and project approvals - remember decisions to avoid repeated prompts
Event bus integration at SECURITY priority (900) - intercepts tools before execution

Approval Modes

The system supports four approval modes, each offering a different balance between security and convenience:

CONFIRM_ALL (Default)

Safest

Require confirmation for all tool executions. Most secure mode - every operation requires explicit approval.

/permissions strict

DEFAULT

Balanced

Confirm only HIGH risk tools. Auto-approve LOW and MEDIUM risk operations like file reads and edits.

/permissions default

AUTO_APPROVE_EDITS

Convenience

Auto-approve file operations (file_write, file_edit, file_create). Shell commands still require confirmation. Enabled via inline prompt.

Press 'A' in file edit prompt

TRUST_ALL

Dangerous

Auto-approve everything. Use with extreme caution - disables all safety checks.

/permissions trust

Risk Assessment

Every tool is automatically assessed for risk level using pattern matching and tool type classification:

HIGH RISK

Requires confirmation in DEFAULT mode. Always blocked if matched as dangerous pattern.

rm -rf / or rm -rf ~ - Destructive deletions

curl ... | bash - Download and execute scripts

chmod 777 - Overly permissive permissions

mkfs.* - Filesystem creation

dd ... of=/dev/... - Device writes

MEDIUM RISK

Auto-approved in DEFAULT mode. Requires confirmation in CONFIRM_ALL mode.

Terminal commands (without dangerous patterns)

File write/create operations

MCP tool executions

git push, npm publish, pip install

LOW RISK

Auto-approved in all modes except CONFIRM_ALL.

File read operations

Search operations (grep, glob)

List directory operations

Trusted tools: read_file, list_directory, search_file_content

Permission Flow

1. LLM requests tool execution
   ↓
2. tool_executor.py emits TOOL_CALL_PRE event
   ↓
3. PermissionHook intercepts at SECURITY priority (900)
   ↓
4. RiskAssessor evaluates tool risk (pattern matching + tool type)
   ↓
5. PermissionManager checks approval rules
   ↓
6. If confirmation needed → show inline UI prompt
   ↓
7. User responds with single keypress (a/s/p/d/ESC)
   ↓
8. ResponseHandler converts to PermissionDecision
   ↓
9. If denied → event.cancelled = True
   ↓
10. tool_executor checks cancelled flag
    ↓
11. Execute or abort based on permission

The entire flow is asynchronous and non-blocking, preserving the responsive terminal experience.

Inline Permission Prompts

Permission prompts appear inline in the thinking/executing area, not as modal dialogs. Single keypress approval for minimal interruption:

Terminal command (HIGH risk):
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
   PERMISSION REQUIRED                         HIGH
   terminal(rm -rf ./node_modules)
   a approve   s session   p this cmd   d deny   c cancel
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

File edit (MEDIUM risk):
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
   PERMISSION REQUIRED                         MEDIUM
   Edit(src/config.py)
   a approve   s session   p project   A always edits   d deny
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

MCP tool (MEDIUM risk):
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
   PERMISSION REQUIRED                         MEDIUM
   MCP(puppeteer/puppeteer_navigate)
   a approve   s session   p project   t trust tool   d deny
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

Key	Action	Availability
`a`	Approve once (this execution only)	Always
`s`	Approve for session (remember until exit)	Always
`p`	Approve for project (persistent, label varies by tool)	Always
`d`	Deny (block this execution)	Always
`ESC`	Cancel (same as deny)	Always
`A`	Always approve edits (switches to AUTO_APPROVE_EDITS mode)	File operations only
`t`	Trust this tool (whitelist specific MCP tool)	MCP tools only
`c`	Cancel operation (abort entire operation)	Terminal commands only

Project approval smart matching:

file_read → "all reads" (approves all file reads, gitignored files still protected)
terminal → "this cmd" (approves this specific root command)
Other tool types → "project" (exact match or wildcard)

/permissions Command

Manage permission settings and view statistics at runtime. Aliases: /perms, /security

# Show current settings and mode
/permissions

# Switch to strict mode (confirm everything)
/permissions strict

# Switch to default mode (HIGH risk only)
/permissions default

# Switch to trust mode (approve everything - DANGEROUS)
/permissions trust

# View permission statistics
/permissions stats

# Clear session approvals
/permissions clear

Configuration

Permission system configuration in ~/.kollabor-cli/config.json:

{
  "core.permissions": {
    "enabled": true,
    "approval_mode": "confirm_all",
    "audit_log_enabled": true,
    "audit_log_path": "~/.kollabor-cli/logs/permissions.log",
    "risk_assessment": {
      "high_risk_patterns": [],
      "medium_risk_patterns": [],
      "trusted_tools": [
        "read_file",
        "list_directory",
        "search_file_content",
        "glob"
      ],
      "blocked_tools": [],
      "trust_mcp_servers": false,
      "trusted_mcp_servers": []
    },
    "ui": {
      "show_risk_level": true,
      "show_matched_pattern": true,
      "confirmation_timeout": 0,
      "timeout_response": "deny"
    }
  }
}

Setting	Description	Default
`enabled`	Master switch for permission system	true
`approval_mode`	Default mode: default, confirm_all, auto_approve_edits, trust_all	confirm_all
`high_risk_patterns`	Custom regex patterns for HIGH risk classification	[]
`trusted_tools`	Tools that are always auto-approved	read_file, list_directory, search_file_content, glob
`blocked_tools`	Tools that are always denied (no confirmation offered)	[]
`confirmation_timeout`	Timeout in seconds (0 = no timeout)	0

Event Bus Integration

The permission system integrates with the event bus at SECURITY priority (900) - the highest priority level. This ensures permission checks happen before any other hooks can process tool execution events.

# Permission hook registration (core/llm/permissions/hook.py)
hook = Hook(
    plugin_name="permission_system",
    name="permission_check",
    event_type=EventType.TOOL_CALL_PRE,
    callback=self._handle_tool_pre,
    priority=HookPriority.SECURITY,  # Priority 900
    enabled=True,
)

TOOL_CALL_PRE event: Emitted by tool_executor before executing any tool. The permission hook intercepts this event and performs the permission check.

Event cancellation: If permission is denied, the hook sets event.cancelled = True to prevent tool execution.

Permission events: The system emits PERMISSION_CHECK, PERMISSION_CONFIRMATION, PERMISSION_GRANTED, and PERMISSION_DENIED events for monitoring and auditing.

Architecture

The permission system is built from modular, testable components:

PermissionManager

core/llm/permissions/manager.py (311 lines)

Central coordinator managing approval modes, session/project approvals, statistics tracking, and UI callback coordination.

RiskAssessor

core/llm/permissions/risk_assessor.py (111 lines)

Pattern-based risk assessment engine. Classifies tools as HIGH, MEDIUM, LOW, or UNKNOWN risk using regex patterns and tool type mappings.

PermissionHook

core/llm/permissions/hook.py (101 lines)

Event bus integration at SECURITY priority. Intercepts TOOL_CALL_PRE events and enforces permission checks before tool execution.

PermissionStatusView

core/io/status/permission_status_view.py (161 lines)

Inline UI component rendering permission prompts in the thinking/executing area. Uses Box design system style with single keypress handling.

Models & Config

core/llm/permissions/models.py (241 lines)
core/llm/permissions/config.py (58 lines)

Data structures (ApprovalMode, ToolRiskLevel, PermissionDecision, ApprovalRecord, RiskAssessmentRules) and configuration defaults.

Total Implementation: 1,085 lines across 7 files