> ## Documentation Index > Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt > Use this file to discover all available pages before exploring further. # Tool Runtime and Execution Subsystems
Relevant source files The following files were used as context for generating this wiki page: * crates/palyra-common/src/tool\_catalog.rs * crates/palyra-daemon/src/application/channel\_turn/mod.rs * crates/palyra-daemon/src/application/context\_engine.rs * crates/palyra-daemon/src/application/context\_references.rs * crates/palyra-daemon/src/application/mcp\_broker.rs * crates/palyra-daemon/src/application/provider\_events.rs * crates/palyra-daemon/src/application/route\_message/orchestration.rs * crates/palyra-daemon/src/application/run\_stream/agent\_loop.rs * crates/palyra-daemon/src/application/run\_stream/orchestration.rs * crates/palyra-daemon/src/application/run\_stream/tool\_flow\.rs * crates/palyra-daemon/src/application/tool\_registry.rs * crates/palyra-daemon/src/application/tool\_registry/catalog.rs * crates/palyra-daemon/src/application/tool\_registry/hashing.rs * crates/palyra-daemon/src/application/tool\_registry/normalization.rs * crates/palyra-daemon/src/application/tool\_registry/schema.rs * crates/palyra-daemon/src/application/tool\_registry/types.rs * crates/palyra-daemon/src/application/tool\_runtime/mod.rs * crates/palyra-daemon/src/gateway.rs * crates/palyra-daemon/src/tool\_posture.rs * crates/palyra-daemon/src/tool\_protocol.rs * crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs * crates/palyra-daemon/tests/gateway\_grpc.rs
The Tool Runtime and Execution Subsystems manage the lifecycle of tool calls proposed by agents. This includes catalog validation, security policy enforcement via the Cedar engine, operator approval gating, and final execution across a variety of specialized backends. The system is designed with a "deny-by-default" posture, ensuring that every tool invocation is attested and recorded for auditability. ## Tool Registry and Dispatch Pipeline The `tool_registry` serves as the central authority for available tools, mapping them to their required capabilities and sensitive-tool classifications [crates/palyra-common/src/tool\_catalog.rs#1-6](http://crates/palyra-common/src/tool_catalog.rs#1-6). When an agent proposes a tool call, it enters a multi-stage dispatch pipeline: 1. **Validation & Normalization**: The proposal is validated against the `ModelVisibleToolCatalogSnapshot` and arguments are normalized [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#46-54](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#46-54). 2. **Security Evaluation**: The system evaluates the call against the Cedar policy engine, checking for required capabilities like `ProcessExec` or `Network` [crates/palyra-daemon/src/tool\_protocol.rs#4-11](http://crates/palyra-daemon/src/tool_protocol.rs#4-11). 3. **Approval Gating**: If the tool is marked as sensitive or the policy requires it, an interactive approval request is sent to the operator [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#3-10](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#3-10). 4. **Runtime Dispatch**: Once approved, the call is routed to the appropriate executor (e.g., Sandbox, Browser, or Wasm) [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#64-71](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#64-71). ### Tool Execution Flow Diagram This diagram maps the logical flow of a tool proposal to the code entities responsible for each stage. ```mermaid theme={null} graph TD subgraph "Natural Language Space (Agent Intent)" A["Agent Proposes ToolCall"] end subgraph "Code Entity Space (palyra-daemon)" B["tool_flow::prepare_run_stream_tool_proposal_event"] C["tool_registry::validate_tool_call_against_catalog_snapshot"] D["tool_protocol::decide_tool_call (Cedar Policy)"] E["approvals::build_pending_tool_approval"] F["gateway::execute_tool_with_runtime_dispatch"] end A --> B B --> C C --> D D -- "Requires Approval" --> E E -- "Approved" --> F D -- "Always Allow" --> F ``` Sources: [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#1-11](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#1-11), [crates/palyra-daemon/src/tool\_protocol.rs#1-15](http://crates/palyra-daemon/src/tool_protocol.rs#1-15), [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#40-54](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#40-54) ## Security Posture and Attestation Palyra implements a tamper-evident audit trail for all tool executions. Every outcome—whether a success, a policy denial, or a timeout—is bundled with a `ToolAttestation` [crates/palyra-daemon/src/tool\_protocol.rs#89-97](http://crates/palyra-daemon/src/tool_protocol.rs#89-97). This attestation includes a SHA-256 hash that binds the proposal ID, input, output, and the specific executor metadata together [crates/palyra-daemon/src/tool\_protocol.rs#83-88](http://crates/palyra-daemon/src/tool_protocol.rs#83-88). The system also supports "Tool Posture" overrides, allowing operators to set tools to `AlwaysAllow`, `AskEachTime`, or `Disabled` at various scopes (Global, Workspace, Agent, or Session) [crates/palyra-daemon/src/tool\_posture.rs#91-98](http://crates/palyra-daemon/src/tool_posture.rs#91-98). ### Security and Posture Entities ```mermaid theme={null} graph LR subgraph "Security Context" TRC["ToolRequestContext"] TD["ToolDecision"] end subgraph "Posture Management" TPR["ToolPostureRegistry"] TPS["ToolPostureState"] end subgraph "Audit & Verification" TA["ToolAttestation"] TEO["ToolExecutionOutcome"] end TRC --> TD TPS --> TD TD --> TEO TEO --> TA ``` Sources: [crates/palyra-daemon/src/tool\_protocol.rs#73-107](http://crates/palyra-daemon/src/tool_protocol.rs#73-107), [crates/palyra-daemon/src/tool\_posture.rs#1-11](http://crates/palyra-daemon/src/tool_posture.rs#1-11) ## Tool Executors Palyra utilizes several specialized executors to provide a secure and functional environment for agents. ### [Sandbox Process Runner](/tool_runtime_and_execution_subsystems/sandbox_process_runner) Executes arbitrary shell commands and binaries. It supports multiple isolation tiers, including direct execution with `rlimits` (Tier B) and containerized/sandboxed execution via Docker or Bubblewrap (Tier C). For details, see [Sandbox Process Runner](/tool_runtime_and_execution_subsystems/sandbox_process_runner). ### [Filesystem Tools: Workspace and OS File Access](/tool_runtime_and_execution_subsystems/filesystem_tools_workspace_and_os_file_access) Provides structured access to the filesystem. The `palyra.fs` tool family includes scoped workspace operations like directory listing, file reading, and atomic patching using the Palyra Patch Document format. For details, see [Filesystem Tools: Workspace and OS File Access](/tool_runtime_and_execution_subsystems/filesystem_tools_workspace_and_os_file_access). ### [Browser Automation (palyra-browserd)](/tool_runtime_and_execution_subsystems/browser_automation_palyra-browserd) Manages a separate `palyra-browserd` service for Chromium-based web automation. It handles session management, SSRF protection, and provides tools for navigation, screenshots, and DOM interaction. For details, see [Browser Automation (palyra-browserd)](/tool_runtime_and_execution_subsystems/browser_automation_palyra-browserd). ### [Skills and Wasm Plugin System](/tool_runtime_and_execution_subsystems/skills_and_wasm_plugin_system) A plugin architecture using WebAssembly (`wasmtime`). It allows for extensible "Skills" that run in a highly constrained environment with strictly defined fuel and memory limits. For details, see [Skills and Wasm Plugin System](/tool_runtime_and_execution_subsystems/skills_and_wasm_plugin_system). ### [Additional Tool Executors](/tool_runtime_and_execution_subsystems/additional_tool_executors) Covers utility tools such as `palyra.http.fetch` (with egress proxying), memory management tools, and system routine controls. For details, see [Additional Tool Executors](/tool_runtime_and_execution_subsystems/additional_tool_executors). ## Tool Protocol Constants The system enforces strict quotas and budgets on tool inputs and execution latency to prevent resource exhaustion. | Constant | Value | Description | | :------------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TOOL_EXECUTION_LATENCY_BUDGET_MS` | 200ms | Budget for tool dispatch overhead [crates/palyra-daemon/src/gateway.rs#132-132](http://crates/palyra-daemon/src/gateway.rs#132-132) | | `MAX_PROCESS_RUNNER_TOOL_INPUT_BYTES` | 128 KB | Maximum size for process execution arguments [crates/palyra-daemon/src/tool\_protocol.rs#177-177](http://crates/palyra-daemon/src/tool_protocol.rs#177-177) | | `MAX_HTTP_FETCH_TOOL_INPUT_BYTES` | 64 KB | Maximum size for HTTP request parameters [crates/palyra-daemon/src/tool\_protocol.rs#176-176](http://crates/palyra-daemon/src/tool_protocol.rs#176-176) | | `TOOL_MAX_SLEEP_MS` | 30,000ms | Maximum duration for the `palyra.sleep` tool [crates/palyra-daemon/src/tool\_protocol.rs#160-160](http://crates/palyra-daemon/src/tool_protocol.rs#160-160) | Sources: [crates/palyra-daemon/src/gateway.rs#128-145](http://crates/palyra-daemon/src/gateway.rs#128-145), [crates/palyra-daemon/src/tool\_protocol.rs#158-185](http://crates/palyra-daemon/src/tool_protocol.rs#158-185) ## Child Pages * [Sandbox Process Runner](/tool_runtime_and_execution_subsystems/sandbox_process_runner) * [Filesystem Tools: Workspace and OS File Access](/tool_runtime_and_execution_subsystems/filesystem_tools_workspace_and_os_file_access) * [Browser Automation (palyra-browserd)](/tool_runtime_and_execution_subsystems/browser_automation_palyra-browserd) * [Skills and Wasm Plugin System](/tool_runtime_and_execution_subsystems/skills_and_wasm_plugin_system) * [Additional Tool Executors](/tool_runtime_and_execution_subsystems/additional_tool_executors)