# How the Apache Maka Tool Runtime Handles Tool Execution and Sandboxing

> Discover how Apache Maka's Tool Runtime executes tools securely. Learn about its deterministic pipeline, event emission, and robust sandboxing for isolated operations.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-08

---

**The Apache Maka Tool Runtime (`ToolRuntime` class) executes tools through a deterministic pipeline that validates arguments, emits structured events, and isolates untrusted operations via sandbox boundary requests and denial flags.**

The **Tool Runtime** is the core execution engine inside the `apache/maka` repository that mediates every tool invocation during a Maka session. It enforces strict sandboxing rules, prevents infinite retry loops, and ensures the host system remains protected from unsafe tool behavior while maintaining a deterministic execution log.

## ToolRuntime Initialization and Sandbox State

The `ToolRuntime` class is constructed from a `ToolRuntimeInput` bundle defined in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts). During initialization, the runtime validates that a `readExecutionBoundary` function is present and verifies that hosted session IDs align with the current turn.

```typescript
// packages/runtime/src/tool-runtime.ts#L6-L18
const toolRuntime = new ToolRuntime({
  sessionId: 'sess-123',
  turnId: 'turn-5',
  readExecutionBoundary: async () => {/* fetch from host */},
  createSandboxBoundaryRequest: async (req) => {/* send to host */},
  settleSandboxBoundaryRequest: async (settlement) => {/* send to host */},
});

```

The runtime immediately seeds a **sandbox denial flag** (`sandboxBoundaryDenied`) from `input.inheritedSandboxBoundaryDenied`. When this flag is true, the runtime short-circuits any further sandbox boundary requests for the entire turn, returning a `SANDBOX_BOUNDARY_DENIED_FOR_TURN` error without forwarding the request to the host.

## The Tool Execution Pipeline

Tool execution flows through `ToolRuntime.settleToolCall()`, which delegates to the private `executeTool()` method. This pipeline performs several deterministic steps before invoking the actual tool implementation:

1. **Argument snapshotting** – Captures raw arguments via `snapshotToolArgs` to prevent mutation during execution.
2. **Pre-flight validation** – Checks for direct-only nesting violations, tool-availability gating, schema validation, and sandbox availability for the `request_sandbox_boundary` tool.
3. **Permission projection** – Derives optional permission arguments for permission prompts.
4. **Event emission** – Queues a `tool_start` event and optional diagnostic traces via `eventSink`.
5. **Implementation call** – Invokes `tool.impl` with the validated context.
6. **Result handling** – Applies result projection, enforces size limits, and converts errors.

The implementation in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) (lines 95-140) guarantees exactly one `tool_start` event per call and handles abort signals gracefully.

## Sandbox Boundary Request Handling

When a tool requires expanded privileges (typically via the `request_sandbox_boundary` tool), the runtime invokes `context.requestSandboxBoundary()`. This registers a pending request in the `sandboxBoundaryRequests` registry—an `AwaitRegistry` instance that tracks the asynchronous conversation with the host.

```typescript
// Sandbox request lifecycle
sandboxBoundaryRequests.register(requestId, promise);
// Host responds via:
await toolRuntime.respondToSandboxBoundaryResponse({
  requestId: 'req-7',
  decision: 'allow', // or 'deny'
});

```

The `respondToSandboxBoundaryResponse()` method (lines 37-44) resolves the pending registry entry and persists the settlement via `input.settleSandboxBoundaryRequest`. If the request belongs to a hosted interaction, the runtime throws a runtime invariant error to preserve host-side continuity.

To prevent infinite negotiation loops, the runtime enforces a `SANDBOX_BOUNDARY_FAILURE_ROUND_LIMIT`. Once reached, or if `sandboxBoundaryDenied` is set, `forceSandboxBoundaryFinalization()` stops further sandbox expansion attempts for that turn.

## Safety Mechanisms and Loop-Gate Protection

The Tool Runtime implements a **loop-gate** mechanism to block infinite retries on identical failing calls. It maintains two pieces of state:

- `lastFailedToolCallSignature` – A hash of the last failed call's identity.
- `failedToolCallStreak` – A counter tracking consecutive identical failures.

If the same signature fails `LOOP_GATE_IDENTICAL_THRESHOLD` (3) times consecutively, the runtime blocks the call before the tool implementation executes again. This logic resides in `recordLoopGateOutcome` (lines 112-124) and protects against resource exhaustion from misbehaving agents.

## Turn Lifecycle and Cleanup

When a turn completes—whether successfully or aborted—the host invokes `ToolRuntime.endTurn()`. This method performs critical cleanup:

- **Pending request settlement** – Automatically denies any embedded sandbox requests that remain unanswered by calling `settleSandboxBoundaryRequest` with a denial.
- **Registry closure** – Closes the `AwaitRegistry` instances for sandbox boundaries, user questions, and forms, rejecting any pending promises.
- **State reset** – Clears internal counters, admission limits for sub-agents, and the loop-gate state (`lastFailedToolCallSignature`, `failedToolCallStreak`).
- **Inflight synchronization** – Waits for `activeToolSettlements` to complete before returning, ensuring no dangling async operations survive the turn boundary.

The implementation spans lines 22-35 in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts).

## Summary

- The **ToolRuntime** class in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) orchestrates all tool execution within Apache Maka, providing deterministic event emission and result projection.
- **Sandboxing** is enforced through an explicit request/response flow using `sandboxBoundaryRequests` (an `AwaitRegistry`) and the `sandboxBoundaryDenied` flag, with hard limits on retry rounds.
- **Loop-gate protection** blocks tool calls that fail identically three times in a row, preventing infinite retry storms.
- **Turn finalization** via `endTurn()` guarantees cleanup of pending promises, registry closure, and reset of safety counters.

## Frequently Asked Questions

### What happens when a sandbox boundary request is denied?

When a host denies a sandbox request through `respondToSandboxBoundaryResponse()`, the runtime sets the `sandboxBoundaryDenied` flag to true. Subsequent sandbox requests in the same turn immediately return a `SANDBOX_BOUNDARY_DENIED_FOR_TURN` error without contacting the host, effectively freezing the sandbox state for the remainder of the turn.

### How does the loop-gate prevent infinite tool call retries?

The runtime tracks the signature of the last failed tool call and increments a `failedToolCallStreak` counter when identical failures repeat. Once the streak reaches three (`LOOP_GATE_IDENTICAL_THRESHOLD`), the runtime blocks the call before execution, breaking potential infinite loops from deterministic failures.

### What is the difference between `settleToolCall()` and `executeTool()`?

`settleToolCall()` is the public entry point that receives a `ResolvedMakaToolCall` and manages the high-level settlement promise, while `executeTool()` is the private implementation containing the actual execution logic: pre-flight checks, event queuing, tool implementation invocation, and result handling.

### Which source files define the sandbox boundary schema and contracts?

The Zod schema for sandbox boundary expansions lives in [`packages/runtime/src/sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-declaration.ts), the tool definition is in [`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts), and the core type contracts (`CreateSandboxBoundaryRequest`, `SandboxBoundarySettlement`) are defined in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts).