# What Is the Approval Flow for Tools That Cross Maka's Sandbox Boundary?

> Learn Maka's approval flow for tools crossing sandbox boundaries. Understand how Maka prompts for explicit consent to expand permissions or fails the turn.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-28

---

**When a tool attempts to access resources outside its session sandbox, Apache Maka pauses execution and triggers a structured approval flow that surfaces a `SandboxBoundaryPrompt` to the user, requiring explicit consent via the `request_sandbox_boundary` tool before expanding sandbox permissions or failing the turn.**

The approval flow for tools that cross Maka's sandbox boundary is a critical security mechanism in the Apache Maka runtime. When local tools attempt to access filesystem paths, network endpoints, or system capabilities beyond their current session scope, the system enforces a "fail-closed" policy that requires explicit user consent before widening permissions. This architecture ensures that AI-driven tool executions remain securely contained unless the user explicitly authorizes broader access through a formal escalation protocol.

## Detecting Boundary Violations in the Runtime

When a tool execution violates sandbox constraints, the runtime detects the violation and generates a structured failure signal. In [[`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts#L42-L48), the `sandboxBoundaryFailureSignal` function (lines 42-48) processes tool outputs to identify specific error reasons indicating a boundary breach:

- **`sandbox_boundary_required`** — The tool needs expanded filesystem or network access.
- **`requires_bypass`** — The operation requires sandbox bypass privileges.

The function returns a metadata object containing the `reason` and an optional `requiredExpansion` field that describes the exact paths or capabilities needed. This structured failure interrupts the current turn and prevents further tool execution until the boundary issue is resolved.

```typescript
function sandboxBoundaryFailureSignal(metadata) {
  if (metadata?.reason !== 'sandbox_boundary_required' && metadata?.reason !== 'requires_bypass')
    return undefined;
  return {
    reason: metadata.reason,
    ...(metadata.requiredExpansion ? { requiredExpansion: metadata.requiredExpansion } : {}),
  };
}

```

## The User Approval Interface

Once the runtime identifies a boundary violation, control passes to the UI layer. The `SandboxBoundaryPrompt` component in [[`packages/ui/src/sandbox-boundary-prompt.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/sandbox-boundary-prompt.tsx)](https://github.com/apache/maka/blob/main/packages/ui/src/sandbox-boundary-prompt.tsx#L30-L40) (lines 30-40) renders an interactive dialog that presents the user with the specific justification for the expansion request and the exact resources being requested.

This component receives the expansion requirements via the `request` prop and handles user decisions through the `onRespond` callback, which accepts either `allow` or `deny` as valid responses.

```typescript
function SandboxBoundaryPrompt({ request, onRespond }) {
  // request.expansion contains the required paths/network
  // onRespond({ requestId, decision: 'allow' | 'deny' })
}

```

## Expanding the Sandbox After Approval

If the user approves the request, the model invokes the built-in `request_sandbox_boundary` tool. This tool, defined in [[`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts#L38-L78) (lines 38-78), serves as the official mechanism for widening the session sandbox.

### The Allow Path

When the user clicks **Allow**, the model calls `request_sandbox_boundary` with a structured expansion parameter containing the required capabilities and a human-readable justification. The tool implementation validates that `context.requestSandboxBoundary` exists, then invokes the host's sandbox manager to permanently expand the session boundaries. After successful expansion, the runtime automatically retries the original tool execution with the new permissions in effect.

```typescript
export const REQUEST_SANDBOX_BOUNDARY_TOOL_NAME = 'request_sandbox_boundary';
export function buildRequestSandboxBoundaryTool() {
  return {
    name: REQUEST_SANDBOX_BOUNDARY_TOOL_NAME,
    description:
      'Request the smallest session sandbox boundary expansion needed to retry a local tool that returned sandbox_boundary_required.',
    parameters: z.object({
      expansion: sandboxBoundaryExpansionSchema,
      justification: z.string().min(1),
    }),
    impl: ({ expansion, justification }, context) => {
      if (!context.requestSandboxBoundary) throw new Error(SANDBOX_BOUNDARY_UNAVAILABLE);
      return context.requestSandboxBoundary(expansion, justification);
    },
  };
}

```

### The Deny Path and Finalization

If the user denies the request, the runtime records the `sandbox_boundary_required` failure for the current turn and enforces a strict "fail-closed" policy. According to the sandbox contract implemented in [[`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts), no further boundary expansion attempts are permitted within the same turn. The system emits a `SANDBOX_BOUNDARY_FINALIZATION_PROMPT` to inform the model that the operation is blocked, guiding it toward alternative approaches that respect the current sandbox constraints.

## Summary

- **Violation Detection:** The tool runtime detects out-of-boundary access via `sandboxBoundaryFailureSignal` in [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts), returning structured metadata with `sandbox_boundary_required` and the specific `requiredExpansion`.
- **User Prompt:** The `SandboxBoundaryPrompt` component in [`sandbox-boundary-prompt.tsx`](https://github.com/apache/maka/blob/main/sandbox-boundary-prompt.tsx) displays the exact resources requested and captures the user's allow or deny decision.
- **Expansion Protocol:** The `request_sandbox_boundary` tool in [`sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-tool.ts) formalizes the expansion request, requiring a valid justification before the sandbox manager widens session permissions.
- **Security Enforcement:** Denied requests trigger turn finalization with no retry capability, ensuring that unauthorized access attempts fail securely without automatic bypasses.

## Frequently Asked Questions

### What triggers the sandbox boundary approval flow in Apache Maka?

The approval flow activates when a local tool attempts to access filesystem paths, network endpoints, or system capabilities outside the current session's defined sandbox limits. The runtime checks tool outputs for the `sandbox_boundary_required` or `requires_bypass` reasons and immediately pauses execution to request user authorization.

### How does the `request_sandbox_boundary` tool work?

The `request_sandbox_boundary` tool is a built-in runtime utility that accepts an `expansion` parameter describing the required capabilities and a `justification` string explaining why the access is needed. When invoked, it calls `context.requestSandboxBoundary` to communicate with the host's sandbox manager, which permanently expands the session boundaries before allowing the original tool to retry.

### What happens if a user denies a sandbox boundary request?

If the user denies the request, the runtime marks the current turn with a `sandbox_boundary_required` failure and emits a `SANDBOX_BOUNDARY_FINALIZATION_PROMPT`. Per the sandbox manager's fail-closed policy, no further boundary expansion attempts are permitted for that turn, forcing the model to either request alternative tools or complete the task within existing constraints.

### Can tools automatically retry after a sandbox expansion?

Yes, but only after explicit user approval. Once the `request_sandbox_boundary` tool successfully expands the sandbox, the runtime automatically retries the original tool execution that triggered the boundary violation. This retry occurs transparently without requiring additional model turns, provided the expansion satisfied the original resource requirements.