Execution Engine

The execution engine bridges Gateway requests to the Orchestrator and agent harness. It owns run admission, per-session exclusivity, global and per-agent limits, event emission, persistence, cancellation, deadlines, steering, and per-request tool-service construction. Sandboxed command execution is one tool path inside this engine, not the engine itself.

Run Lifecycle and Admission

A RunRequest carries the run and session ids, input, timeout, metadata, attachments, optional workspace and sandbox overrides, iteration cap, and model override. The engine tracks Running, Completed, Cancelled, and Failed states and emits ordered stream events.

Concurrency is enforced at two levels:

• SessionRunRegistry permits only one active run per session.
• ConcurrencyLimiter applies [execution] max_runs_global and max_runs_per_agent for the lifetime of each run. These limits are hot-reloadable.

Messages that arrive while a session is busy follow an explicit channel policy: steer injects at the next turn boundary, interrupt cancels and restarts through the wait lane, and queue waits without disturbing the current run. The shared per-session wait lane is FIFO and bounded.

Resource-Aware Tool Concurrency

When [tool_service] parallel_tool_concurrency is at least 2 and a model emits multiple calls, the Act phase asks the tool service for a ConcurrencyClaim for each call's concrete arguments.

pub enum ConcurrencyClaim {
    Shared,
    Exclusive { scope: ExclusiveScope },
}

pub enum ExclusiveScope {
    Global,
    Paths(BTreeSet<String>),
    Nodes(BTreeSet<String>),
    Sessions(BTreeSet<String>),
}

Claims describe the resources a call may affect:

• Shared is for read-only or side-effect-free calls. Shared calls can run together.
• Global is the conservative fallback for unknown or unbounded mutation and conflicts with every call.
• Paths names normalized filesystem paths. Equal or ancestor/descendant paths conflict; disjoint path trees can run together.
• Nodes names remote cluster nodes. Calls to distinct nodes can run together; the same node conflicts.
• Sessions names delegated local sessions. Distinct sibling sessions can run together, but a session claim conflicts with paths, nodes, global mutation, and shared reads because the delegated run's local footprint is unknown.

An empty or unresolvable resource set degrades to Global rather than guessing.

Ordered Bucketing

The scheduler does not make one parallel-or-serial decision for the whole batch. partition_parallel_groups walks calls in model order and creates contiguous groups whose members are pairwise non-conflicting. Groups execute sequentially; calls inside a group execute concurrently up to the configured cap.

For example, several reads followed by bash become one parallel read group followed by one serial global group. Same-file writes split into separate groups, while writes to disjoint files can remain together. This preserves the relative order of conflicting calls without serializing unrelated work.

Claims are computed from the arguments used for admission and carried into dispatch. Unknown tools receive a global claim. Duplicate calls stay on the serial deduplication path.

Resource Declarations

The default tool declaration is fail-closed: is_concurrent_safe = false maps to Global; an explicitly concurrent-safe tool maps to Shared. Tools with bounded effects override concurrency_claim(input):

• file_write and file_edit claim their target path.
• apply_patch claims every file parsed from the patch envelope.
• Mutating file_ops actions claim source and destination paths; read actions are shared.
• node_invoke claims its resolved node.
• session_send claims its resolved target session.
• Input-dependent tools may declare shared for read modes and global for mutating modes.

MCP tools use their read-only/idempotent annotations for shared admission; unannotated tools remain global. A resource declaration affects scheduling only. It does not grant permission or bypass approval.

Approval and Sandbox Boundaries

Every execution still passes through the scoped tool service. The action-aware approval gate keys grants on the concrete action, while execution tiers control automatic approval:

[sandbox.command_policy] remains a hard floor that no tier can weaken. Unattended runs fail closed for confirmation-gated tools. Platform sandboxing, command policy, workspace scope, timeout, cancellation, and output limits are enforced after scheduling and approval decisions.

Code Locations

• src/gateway/execution_engine/ — run lifecycle, admission, steering, cancellation, and tool-service wiring
• src/harness/agent/act.rs — ordered claim collection and group dispatch
• src/tools/concurrency.rs — claim types, conflict rules, path normalization, and partitioning
• src/tools/runtime.rs — per-tool concurrency_claim declaration
• src/tools/adapters/registry_adapter.rs — argument-aware claims for built-in tools
• src/tools/scoped/ — approval and policy choke point
• src/sandbox/ — command policy and platform sandboxing

See Also

• Approval — human approval surfaces
• Builtin Tools — available execution tools
• Teams — team and task-level concurrency