Tools Dispatcher & Permissions
Relevant source files
The following files were used as context for generating this wiki page:
The Tools Dispatcher & Permissions system is the central execution and security layer of M31 Autonomous. It manages the lifecycle of 18 built-in tools, ensuring that LLM-generated requests are validated, authorized, and executed within controlled resource boundaries. The system provides a unified interface for the Workflow Engine to interact with the host filesystem, shell, and external network resources while maintaining a strict security posture.
The dispatcher acts as a gatekeeper, implementing rate limiting, concurrency control, and a multi-layered permission system. This ensures that potentially destructive operations—such as shell commands or file deletions—cannot be executed without explicit user consent or pre-defined safety rules.
Sources: README.md:164-180, CONTRIBUTING.md:46-51
Tool Architecture and Dispatching
The system utilizes a central Dispatcher to handle tool execution requests. It supports 18 built-in tools categorized by their functionality, ranging from filesystem operations to web searching and code analysis.
Execution Flow
When the Workflow Engine receives a tool call from the LLM, it passes the request to the Dispatcher. The Dispatcher manages the following sequence:
- Validation: Checks if the tool is registered and the input matches the expected schema.
- Permission Check: Evaluates if the action is permitted based on the tool's risk level.
- Resource Management: Uses semaphores to limit concurrent executions (defaulting to a maximum of 8 concurrent tools).
- Rate Limiting: Applies token-bucket rate limiting based on the tool's classification.
The diagram shows the sequential safety gates a tool call must pass through before execution.
Sources: internal/engine/workflow/execute.go:277-336, README.md:200-210
Built-in Toolset
The project includes a robust set of tools for autonomous coding tasks:
| Tool | Purpose | Risk Level |
|---|---|---|
| Bash | Run shell commands (build, test, git) | High |
| FileWrite | Atomic file creation or full rewrite | Medium |
| Edit | Targeted string/line-range replacement | Medium |
| FileRead | Read file contents (max 5MB) | Low |
| WebFetch | Fetch text content from a URL | Medium |
| CodeMap | Generate codebase intelligence maps | Low |
| FileDelete | Safely delete files with backup | High |
Sources: internal/engine/workflow/prompts/tool-use.md:7-105, CONTRIBUTING.md:46-51
Permission and Security Model
The security model is layered to prevent unauthorized or dangerous actions, particularly protecting against SSRF, path traversal, and command injection.
Permission Modal Logic
Every Bash command and high-risk tool is gated by a permission system. In interactive sessions, this presents a modal to the user with four options:
- Allow: Permit the single current execution.
- Allow Always: Add the tool/command to a session-level whitelist.
- Deny: Prevent the execution (returns an error to the LLM).
- Exit: Terminate the session immediately.
Sources: README.md:200-205, scripts/validate-release.sh:424-434
Protective Mechanisms
The system implements specific technical safeguards within tool implementations:
- SSRF Protection:
WebFetchblocks private, loopback, and link-local IP addresses to prevent internal network scanning. - Path Traversal Prevention: Tool boundaries sanitize paths and restrict operations to the working directory.
- Rate Limiting: The system uses two buckets:
- Standard Tools: 20 burst / 10 sustained tokens.
- Dangerous Tools: 5 burst / 2 sustained tokens.
- Command Hardening: Normalizes shell commands to detect obfuscation attempts and blocks dangerous patterns (e.g.,
rm -rf /).
Sources: README.md:213-228, scripts/validate-release.sh:417-422
Concurrency and Loop Detection
The dispatcher includes a ToolCallTracker to prevent recursive "hallucination loops" where an LLM calls the same tool repeatedly with the same parameters.
The sequence illustrates how the tracker intercepts execution if a repetitive tool call pattern is identified.
Sources: internal/engine/workflow/execute.go:217-228, internal/engine/workflow/execute.go:303-315
Implementation Details
Parallel Execution
The Workflow Engine leverages the Dispatcher to run tools in parallel when appropriate, especially during the implementation of independent tasks using Kahn's algorithm for topological sorting.
// From internal/engine/workflow/execute.go
// Execute tool calls in parallel with bounded concurrency.
maxToolConcurrency := 4
if e.cfg != nil && e.cfg.Tools.MaxToolConcurrency > 0 {
maxToolConcurrency = e.cfg.Tools.MaxToolConcurrency
}
sem := make(chan struct{}, maxToolConcurrency)
// ... inside tool dispatch loop ...
sem <- struct{}{} // acquire
defer func() { <-sem }() // release
Sources: internal/engine/workflow/execute.go:323-335
Self-Healing Logic
If a tool execution fails, the Dispatcher returns a detailed error. The system enters a "Self-Heal" loop (up to 2 retries) where the failure reason is fed back to the LLM to diagnose and correct the parameters for a subsequent call.
Sources: internal/engine/workflow/execute.go:245-265, README.md:100-110
Conclusion
The Tools Dispatcher and Permission system provide the necessary balance between autonomy and security in M31 Autonomous. By centralizing execution logic and enforcing strict resource and safety constraints, the system allows the AI agent to interact deeply with a codebase while ensuring the user remains the ultimate authority over the execution environment.