Add regex-based permissions system for tool execution control

[chinmaymk]

Summary

Adds a comprehensive permissions middleware that controls what tools can do through regex-based allow/deny rules per tool and per field. This enables fine-grained security policies without stopping the agent loop — denied calls return clear error messages so the model can adjust its approach.

Key Changes

• New permissions middleware (src/agent/permissions.ts): Implements createPermissionsMiddleware() that evaluates tool calls against configurable regex rules. Deny patterns take priority over allow patterns.

• Configuration types (src/config/types.ts): Added PermissionsConfig, PermissionRule, and PermissionFieldRule interfaces supporting:

  • no_rules: Bypass all checks
  • default_action: Control behavior for tools with no rules (allow or deny)
  • rules: Array of per-tool field constraints

• Loop integration (src/agent/loop.ts): Modified AgentLoop to:

  • Add deny() callback and denied property to ToolExecutionContext
  • Capture denied tool calls and convert them to error results in the message stream
  • Allow the loop to continue after denial (no early termination)

• Type updates (src/agent/types.ts): Extended ToolExecutionContext with deny() method and denied property for permission enforcement.

• Configuration defaults (src/config/defaults.ts): Added empty permissions: {} to default config.

• Main entry point (src/index.ts): Integrated permissions middleware into the agent loop's beforeToolExecution chain.

• Comprehensive test suite (tests/agent/permissions.test.ts): 389 lines covering:

  • Allow/deny rule evaluation and priority
  • Multiple rules per tool
  • Field-specific constraints (command, path, content, url, etc.)
  • Default action behavior
  • Loop integration ensuring denied tools don't execute

• Documentation (docs/site/permissions/index.md): Full guide with examples for common use cases (safe git commands, file restrictions, secret blocking, network lockdown).

Implementation Details

• Deny priority: Deny patterns are checked first; if any match, the call is immediately rejected regardless of allow rules
• Field-level granularity: Rules target specific input fields (e.g., command for bash, path for file tools, url for web_fetch)
• Clear error messages: Denied calls include which rule was triggered, helping the model understand and adjust
• Non-blocking: Denied tool calls become error results in the message stream; the loop continues and the model can retry with different parameters
• Regex-based: All patterns are JavaScript RegExp strings, enabling flexible matching (anchors, character classes, etc.)

https://claude.ai/code/session_01WHxQAWvZarjgufPCxHhsHs