# How Maka's Sandbox-Boundary-Tool Enforcement Secures Critical Operations

> Discover how Maka's sandbox-boundary-tool enforces security for critical operations. Learn how it isolates tool execution and manages permission requests for secure filesystem and network access.

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

---

**Maka isolates tool execution inside a session sandbox and requires explicit permission requests via the `request_sandbox_boundary` tool whenever a critical operation exceeds current filesystem or network boundaries.**

Apache Maka's security model ensures that potentially dangerous operations—such as writing files or opening network sockets—cannot execute silently. Instead, Maka's sandbox-boundary-tool enforcement mechanism intercepts these requests and forces the model to negotiate for expanded permissions through a structured, user-controlled approval flow. This article examines the runtime architecture, execution flow, and implementation details based on the source code in `apache/maka`.

## The Four-Layer Enforcement Architecture

The enforcement system consists of four coordinated components that validate, normalize, and authorize sandbox boundary expansions. Each component is implemented in a specific module within the runtime package.

### Sandbox Manager

The **Sandbox Manager** determines whether a session requires sandboxing and selects the appropriate platform-specific backend. In [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts), the `SandboxManager.shouldSandbox` method evaluates the current permission profile to decide if isolation is necessary, while `SandboxManager.selectInitial` chooses between macOS-Seatbelt, Linux, or Windows implementations. This layer establishes the initial authority boundary before any tool executes.

### Sandbox-Boundary Declaration

Before a tool can request expanded permissions, it must declare its requirements using the **Sandbox-Boundary Declaration** system defined in [`packages/runtime/src/sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-declaration.ts). This layer uses Zod schemas—specifically `sandboxBoundaryExpansionSchema`—to validate the shape of boundary requests. The module also provides `preprocessBashBoundaryDeclaration` and `selectedBashBoundaryExpansion` functions to strip declarations when the tool only needs the current boundary, optimizing performance for compliant operations.

### Sandbox-Boundary Path

Path normalization and conflict detection occur in [`packages/runtime/src/sandbox-boundary-path.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-path.ts). The `normalizeSandboxBoundaryExpansion` function converts requested paths to absolute form, while `preflightDeclaredSandboxBoundary` checks these paths against the active sandbox profile. If a request conflicts with an explicit deny rule, this layer raises a `SandboxCommandError` with reason `requires_bypass`. For unresolved paths, it throws `sandbox_boundary_required`, triggering the request flow.

### Tool Runtime

The **Tool Runtime** orchestrates the actual negotiation process in [`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts). It implements `buildRequestSandboxBoundaryTool` to inject the permission request tool into the model's available functions, `recordSandboxBoundaryFailure` to track denials, and `forceSandboxBoundaryFinalization` to cap negotiation rounds. This layer also enforces loop-gate logic to prevent infinite retry cycles when boundary requests fail repeatedly.

## The Execution Flow for Critical Operations

When a tool attempts a critical operation, the runtime executes a seven-phase enforcement flow that ensures no privileged action proceeds without explicit authorization.

### 1. Admission and Schema Validation

Upon invocation, `ToolRuntime.executeTool` first validates admission rules (exclusive-step constraints) and checks arguments against the tool's Zod schema. Tools that require boundary expansion specify this via `boundary_intent: 'expand'` in their `permissionArgs` configuration.

### 2. Boundary Assessment

The runtime calls `preflightDeclaredSandboxBoundary` to normalize the requested expansion via `normalizeSandboxBoundaryExpansion`. The system then compares the request against the `executionBoundary.profile`:

- **Noop**: If the permission is already granted, execution proceeds immediately.
- **Conflict**: If the request violates an explicit deny rule, the runtime throws `SandboxCommandError` with reason `requires_bypass`.
- **Expansion Required**: For new permissions, the runtime throws `SandboxCommandError` with reason `sandbox_boundary_required`.

### 3. The Request Tool Mechanism

When expansion is required, the runtime injects the `request_sandbox_boundary` tool into the model's tool set. The implementation in `buildRequestSandboxBoundaryTool` forwards requests to `context.requestSandboxBoundary`. If the surface cannot handle interactive requests (such as non-interactive UIs), the tool throws `SANDBOX_BOUNDARY_UNAVAILABLE`.

### 4. User Decision and Retry Logic

The request surfaces to the user or host UI. A **deny** response triggers `SANDBOX_BOUNDARY_DENIED_FOR_TURN`, preventing further boundary requests during the same turn. An **allow** response expands the session's sandbox profile, and the runtime automatically retries the original tool with the new authority.

### 5. Failure Caps and Loop-Gate Protection

To prevent deadlocks, the runtime tracks invalid and unresolved rounds via `sandboxBoundaryInvalidRounds` and `sandboxBoundaryUnresolvedRounds`. After three failures (`SANDBOX_BOUNDARY_FAILURE_ROUND_LIMIT`), `forceSandboxBoundaryFinalization` emits a deterministic final status (`SANDBOX_BOUNDARY_FINALIZATION_PROMPT`) and terminates negotiation. Additionally, identical failing calls trigger a loop-gate after `LOOP_GATE_IDENTICAL_THRESHOLD` (three consecutive identical failures) to stop infinite retry loops.

## Implementing Sandbox Boundary Requests in Practice

Developers declare boundary requirements through tool configuration or direct API calls. Below are practical implementations showing both approaches.

### Declaring Requirements in Tool Definitions

Tools specify their boundary needs through the `permissionArgs` function, which returns a `boundary_intent` and `required_boundary` configuration:

```typescript
// packages/runtime/src/tools/write-file.ts (example implementation)
export const writeFileTool: MakaTool<{ path: string; content: string }, void> = {
  name: 'write_file',
  description: 'Write text to a file, requires write permission on the target path.',
  parameters: z.object({
    path: z.string(),
    content: z.string(),
  }).strict(),
  // Declare sandbox expansion requirements
  permissionArgs: (args, ctx) => ({
    boundary_intent: 'expand',
    required_boundary: {
      filesystem: {
        entries: [{ path: args.path, access: 'write', scope: 'exact' }],
      },
    },
  }),
  impl: async ({ path, content }, ctx) => {
    await ctx.fs.writeFile(path, content);
  },
};

```

### Direct Runtime Requests

Tool implementations can also request boundary expansions dynamically using the context API:

```typescript
async function runSensitiveOp(ctx: MakaToolContext) {
  // Request expanded permissions directly
  const result = await ctx.requestSandboxBoundary?.(
    {
      filesystem: {
        entries: [{ path: '/tmp/data', access: 'write', scope: 'subtree' }],
      },
    },
    'Need write access to temporary data directory for processing',
  );
  
  // Result contains the approved sandbox profile or throws on denial
  console.log('Sandbox expanded:', result);
}

```

When `writeFileTool` executes without sufficient permissions, the runtime automatically invokes the built-in `request_sandbox_boundary` tool. The model must then request user justification, and upon approval, the original operation retries with the expanded authority.

## Summary

- **Four-layer architecture**: Sandbox Manager, Declaration, Path validation, and Tool Runtime coordinate to enforce boundaries.
- **Explicit permission model**: Critical operations require `boundary_intent: 'expand'` declarations and user-approved `request_sandbox_boundary` calls.
- **Automatic retry mechanism**: Upon approval, the runtime retries failed operations with the expanded sandbox profile.
- **Circuit breaker protection**: The system caps negotiations at `SANDBOX_BOUNDARY_FAILURE_ROUND_LIMIT` (three rounds) and throttles identical failures via loop-gate logic.
- **Source locations**: Core logic resides in [`sandbox-manager.ts`](https://github.com/apache/maka/blob/main/sandbox-manager.ts), [`sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-declaration.ts), [`sandbox-boundary-path.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-path.ts), and [`sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-tool.ts) within `packages/runtime/src/`.

## Frequently Asked Questions

### What happens when a tool requests a sandbox boundary expansion that conflicts with existing rules?

If the requested expansion conflicts with an explicit deny rule in the active profile, `preflightDeclaredSandboxBoundary` raises a `SandboxCommandError` with reason `requires_bypass`. This error indicates that the operation cannot proceed through standard boundary expansion and requires manual bypass authorization from the user or host system.

### How does Maka prevent infinite loops during boundary negotiations?

Maka implements a loop-gate mechanism that tracks consecutive identical failures. After `LOOP_GATE_IDENTICAL_THRESHOLD` (three) identical failures, the runtime throttles further attempts. Additionally, after `SANDBOX_BOUNDARY_FAILURE_ROUND_LIMIT` (three) total rounds of unresolved or invalid boundary requests, `forceSandboxBoundaryFinalization` terminates the negotiation with a deterministic final status, preventing infinite retry cycles.

### Can non-interactive surfaces use the sandbox boundary tool?

No. If the execution surface cannot carry an interactive sandbox request—such as automated or non-interactive UIs—the `request_sandbox_boundary` tool throws `SANDBOX_BOUNDARY_UNAVAILABLE`. This ensures that critical permission expansions always require interactive user consent and cannot be silently approved in headless environments.

### Which source files implement the core sandbox boundary enforcement?

The enforcement layer spans four primary files in `packages/runtime/src/`: [`sandbox-manager.ts`](https://github.com/apache/maka/blob/main/sandbox-manager.ts) (backend selection), [`sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-declaration.ts) (schema validation), [`sandbox-boundary-path.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-path.ts) (path normalization and conflict detection), and [`sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary-tool.ts) (request tool implementation). The orchestration logic resides in [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts), while shared types are defined in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts).