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

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, 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. 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. 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. 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:

// 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:

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, sandbox-boundary-declaration.ts, sandbox-boundary-path.ts, and 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 (backend selection), sandbox-boundary-declaration.ts (schema validation), sandbox-boundary-path.ts (path normalization and conflict detection), and sandbox-boundary-tool.ts (request tool implementation). The orchestration logic resides in tool-runtime.ts, while shared types are defined in packages/core/src/sandbox-boundary.ts.

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