Permissions - Complete API Reference

Manage command execution approvals, tool access policies, and security controls.

Chat Commands

View Permissions

/permissions View current permissions /permissions list List all rules /permissions pending View pending approvals /permissions history View approval history

Approve/Reject

/approve Approve pending command /approve <id> Approve specific request /reject Reject pending command /reject <id> "reason" Reject with reason

Allow/Block Rules

/permissions allow "npm install" Allow pattern /permissions allow "git *" Allow with wildcard /permissions block "rm -rf" Block dangerous command /permissions remove <rule-id> Remove rule

Security Mode

/permissions mode Check current mode /permissions mode allowlist Only allowed commands /permissions mode blocklist Block specific commands /permissions mode full Allow all (dangerous)

TypeScript API Reference

Create Permissions Manager

import { createPermissionsManager } from 'clodds/permissions';

const perms = createPermissionsManager({ // Security mode mode: 'allowlist', // 'deny' | 'allowlist' | 'blocklist' | 'full'

// Default rules defaultAllow: [ 'ls *', 'cat *', 'git status', 'git diff', 'npm run *', ],

defaultBlock: [ 'rm -rf *', 'sudo *', 'chmod 777 *', ],

// Approval settings requireApproval: true, approvalTimeoutMs: 60000,

// Storage storage: 'sqlite', dbPath: './permissions.db', });

Check Permission

// Check if command is allowed const result = await perms.check({ command: 'npm install lodash', userId: 'user-123', context: 'Installing dependency', });

if (result.allowed) { console.log('Command allowed'); } else if (result.needsApproval) { console.log(Waiting for approval: ${result.requestId}); } else { console.log(Blocked: ${result.reason}); }

Request Approval

// Request approval for command const request = await perms.requestApproval({ command: 'docker build -t myapp .', userId: 'user-123', reason: 'Building application container', });

console.log(Request ID: ${request.id}); console.log(Status: ${request.status});

// Wait for approval const approved = await perms.waitForApproval(request.id, { timeoutMs: 60000, });

if (approved) { console.log('Approved! Executing...'); }

Approve/Reject

// Approve request await perms.approve({ requestId: 'req-123', approvedBy: 'admin-user', note: 'Looks safe', });

// Reject request await perms.reject({ requestId: 'req-123', rejectedBy: 'admin-user', reason: 'Command too broad', });

List Pending

// Get pending approvals const pending = await perms.listPending();

for (const req of pending) { console.log([${req.id}] ${req.command}); console.log( User: ${req.userId}); console.log( Reason: ${req.reason}); console.log( Requested: ${req.createdAt}); }

Add Rules

// Add allow rule await perms.addRule({ type: 'allow', pattern: 'npm run *', description: 'Allow npm scripts', createdBy: 'admin', });

// Add block rule await perms.addRule({ type: 'block', pattern: 'rm -rf /', description: 'Prevent root deletion', createdBy: 'admin', });

// List rules const rules = await perms.listRules();

for (const rule of rules) { console.log(${rule.type}: ${rule.pattern}); }

// Remove rule await perms.removeRule('rule-id');

Tool Policies

// Set tool policy for agent await perms.setToolPolicy({ agentId: 'trading', allow: ['execute', 'portfolio', 'markets'], deny: ['browser', 'docker', 'exec'], });

// Check tool access const canUse = perms.isToolAllowed('trading', 'execute');

// Get agent's allowed tools const tools = perms.getAllowedTools('trading');

Security Modes

Mode Behavior

deny Block all exec commands

allowlist Only explicitly allowed commands

blocklist Block specific patterns, allow rest

full Allow all (dangerous!)

Pattern Syntax

Pattern Matches

npm install

Exact command

npm *

npm with any args

git status

Exact command

• --version

Any command with --version

Built-in Safety Rules

Always blocked regardless of mode:

• rm -rf /

• sudo rm -rf

• chmod 777 /

• :(){ :|:& };: (fork bomb)

• Commands with shell injection patterns

CLI Commands

List permission rules

clodds permissions list

Add allow pattern

clodds permissions allow "npm run *"

View pending approvals

clodds permissions pending

Approve request

clodds permissions approve req-123

Best Practices

• Use allowlist mode — Most secure, explicit permissions

• Review pending regularly — Don't let requests pile up

• Specific patterns — npm install lodash over npm *

• Audit history — Review what was approved

• Tool policies — Restrict agent tool access