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

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#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.

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#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.

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#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.

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), 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, returning structured metadata with sandbox_boundary_required and the specific requiredExpansion.
• User Prompt: The SandboxBoundaryPrompt component in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}