Tool Execution Lifecycle
The execution of a tool follows a strict sequence of validation, authorization, and attestation. This flow is managed primarily withinprocess_run_stream_tool_proposal_event crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-101.
1. Proposal and Security Evaluation
When an agent proposes a tool call, the system first evaluates the security context usingevaluate_tool_proposal_security crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134. This checks if the tool is allowlisted and if it requires explicit user approval.
2. Authorization (Cedar Policy)
The daemon uses thepalyra-policy crate to evaluate the request against Cedar policies. The core function evaluate_with_context crates/palyra-policy/src/lib.rs#217-218 constructs a Cedar request containing:
- Principal: The identity invoking the tool crates/palyra-policy/src/lib.rs#12.
- Action: Typically
tool.executeorskill.executecrates/palyra-policy/src/lib.rs#120-134. - Resource: The specific tool or skill ID crates/palyra-policy/src/lib.rs#14.
- Context: A rich set of attributes including
is_sensitive_action,capabilities, andis_allowlisted_toolcrates/palyra-policy/src/lib.rs#18-26.
3. Approval Workflow
If a tool is marked as sensitive (e.g.,process_exec or network), the policy engine may require an ApprovalDecision crates/palyra-daemon/src/application/approvals/mod.rs#32-64.
- Cached Approvals: The system checks for existing approvals for the same
subject_id(e.g.,tool:name|skill:id) usingresolve_cached_tool_approval_for_proposalcrates/palyra-daemon/src/application/approvals/mod.rs#67-98. - Pending Approvals: If no valid approval exists, a
PendingToolApprovalis created and broadcast to the operator via gRPC or the Web Console crates/palyra-daemon/src/application/approvals/mod.rs#100-135.
4. Execution and Attestation
Once authorized, the tool is dispatched to the appropriate runtime (Sandbox Process Runner or WASM Plugin). Upon completion, aToolAttestation is generated crates/palyra-daemon/src/tool_protocol.rs#73-80. This record includes the execution_sha256 hash, the executor used, and the sandbox_enforcement level applied crates/palyra-daemon/src/tool_protocol.rs#75-80.
Tool Flow and Code Entity Mapping
The following diagram bridges the natural language concepts of “Request” and “Approval” to the specific Rust entities that handle them. Diagram: Tool Authorization and Execution Flow Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-101, crates/palyra-daemon/src/application/approvals/mod.rs#100-135, crates/palyra-daemon/src/tool_protocol.rs#73-80, crates/palyra-policy/src/lib.rs#217-218Tool Capabilities and Metadata
Tools are categorized by their capabilities, which dictate the level of sandboxing and the policy constraints applied.| Capability | Policy Name | Description |
|---|---|---|
ProcessExec | process_exec | Execution of OS binaries/scripts. |
Network | network | Outbound network access. |
SecretsRead | secrets_read | Access to the Palyra Vault. |
FilesystemWrite | filesystem_write | Modifying files within the workspace. |
ToolCallConfig and Budgeting
TheToolCallConfig crates/palyra-daemon/src/tool_protocol.rs#19-26 defines the runtime limits for a specific agent run:
max_calls_per_run: Prevents infinite loops or resource exhaustion crates/palyra-daemon/src/tool_protocol.rs#22.execution_timeout_ms: Hard limit on tool execution duration crates/palyra-daemon/src/tool_protocol.rs#23.process_runner: Policy for OS-level sandboxing (Tier B/C) crates/palyra-daemon/src/tool_protocol.rs#24.wasm_runtime: Policy for WASM-based plugins crates/palyra-daemon/src/tool_protocol.rs#25.
Cedar Policy Implementation
Palyra uses a baseline Cedar policy set defined inDEFAULT_POLICY_SRC crates/palyra-policy/src/lib.rs#99-187.
Default Policy Rules
- Deny Sensitive: Forbids any action marked as sensitive if
allow_sensitive_toolsis false in the context crates/palyra-policy/src/lib.rs#100-105. - Allow Read-Only: Permits safe actions like
tool.listordaemon.statuswithout extra checks crates/palyra-policy/src/lib.rs#107-118. - Allowlisted Execution: Permits
tool.executeonly if the tool is in the allowlist and the principal/channel are authorized crates/palyra-policy/src/lib.rs#120-127.
Policy Context Construction
ThePolicyRequestContext crates/palyra-policy/src/lib.rs#18-26 is populated before every evaluation. It includes dynamic flags such as is_allowlisted_tool and is_sensitive_action, which are derived from the ToolCallConfig and the requested tool’s ToolMetadata crates/palyra-daemon/src/tool_protocol.rs#66-70.
Diagram: Policy Evaluation Data Flow
Sources: crates/palyra-policy/src/lib.rs#18-38, crates/palyra-daemon/src/tool_protocol.rs#19-26, crates/palyra-daemon/src/tool_protocol.rs#66-70
Sandboxing and Enforcement Modes
When a tool requiresProcessExec, the run_constrained_process function crates/palyra-daemon/src/sandbox_runner.rs#147-151 applies the configured SandboxProcessRunnerPolicy crates/palyra-daemon/src/sandbox_runner.rs#81-93.
Egress Enforcement
The system supports three modes for network isolation:- None: No network restrictions.
- Preflight: Validates requested hosts against an allowlist before execution but does not enforce at the OS level crates/palyra-daemon/src/sandbox_runner.rs#49.
- Strict: Uses Tier C backends (e.g.,
LinuxBubblewrap) to provide kernel-level network isolation crates/palyra-daemon/src/sandbox_runner.rs#50.
Tier C Backends
Tier C backends provide the highest level of isolation by leveraging platform-specific features:- Linux:
bwrap(Bubblewrap) for namespaces andunshare-netcrates/palyra-sandbox/src/lib.rs#109-178. - macOS:
sandbox-execcrates/palyra-sandbox/src/lib.rs#10. - Windows:
JobObjectfor resource limits crates/palyra-sandbox/src/lib.rs#11.