# How to Use the Read and Write Tools in Apache Maka: A Complete Guide to Safe File Operations

> Learn to use Apache Maka's Read and Write tools for safe, sandboxed file operations. This guide covers Zod schema validation and I/O delegation for secure execution.

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

---

**The `Read` and `Write` tools in Apache Maka are sandboxed filesystem utilities defined in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) that validate inputs with Zod schemas and delegate all I/O to a permission-bound executor running in an isolated worker process.**

Apache Maka provides built-in file manipulation tools that let language models safely interact with the filesystem. This guide explains how to use the **Read** and **Write** tools programmatically from your JavaScript/TypeScript code or through the command line interface, with technical details drawn directly from the [apache/maka](https://github.com/apache/maka) source.

## How Apache Maka Builds the Read and Write Tools

When a session starts, Maka's runtime assembles its built-in tool set through `buildBuiltinTools()` in [[`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts#L94-L103). This factory function creates an array of `MakaTool` objects, each containing:

- **name** — the tool identifier ("Read" or "Write")
- **activityKind** — classification for telemetry and UI
- **inputSchema** — Zod schema for runtime validation
- **impl** — the async function that executes the operation

Both tools share a **sandboxed filesystem executor** initialized at lines 95-100. This executor enforces session-specific permission profiles and runs file operations in a dedicated worker process, isolating I/O from the model's execution context.

## Using the Read Tool in Maka

The **Read** tool retrieves file contents with support for pagination and runtime resource references.

### Read Tool Schema and Validation

The input schema (lines 24-58) accepts two mutually exclusive shapes:

| Variant | Fields | Use Case |
|---------|--------|----------|
| Path-based | `path` (string), `offset?` (number), `limit?` (number) | Read local files with optional line range |
| Ref-based | `ref` (string) | Access runtime resources or attachments |

Zod validation ensures only one variant is provided. The `readDescription` constant (lines 55-57) defines the tool's documentation for model consumption.

### Read Tool Implementation Logic

The implementation (lines 61-108) branches based on input type:

1. **`ref` present** — routes to `classifyRuntimeResourceRef()` (lines 147-166) which distinguishes normal paths from `maka:runtime` references and unsupported refs. Runtime resources or attachments are read through the appropriate handler (lines 61-80).

2. **Path-based** — validates the path isn't a reserved "runtime" ref, then delegates to `createBoundaryFilesystemExecutor` (lines 82-98).

The executor returns either:
- Plain text: `{ content: string }`
- Image snapshot: `{ snapshot: Reference }` (lines 99-108)

Errors are normalized through `internalFilesystemReadFailure()` (lines 40-58) for consistent model-friendly reporting.

### Read Tool Code Example: Programmatic Usage

```typescript
import { buildBuiltinTools } from '@maka/runtime';
import { createLocalWorkspaceExecutor } from '@maka/runtime';

const tools = buildBuiltinTools({ executor: createLocalWorkspaceExecutor() });
const readTool = tools.find(t => t.name === 'Read')!;

// Read first 20 lines of README.md
const result = await readTool.impl({
  path: 'README.md',
  offset: 0,
  limit: 20,
}, {
  cwd: process.cwd(),
  sessionId: 'demo-session',
  turnId: 'turn-1',
  abortSignal: new AbortController().signal,
});

console.log(result.content);

```

### Read Tool CLI Usage

```bash
maka run "Read" '{"path":"apps/desktop/README.md","offset":0,"limit":5}'

```

## Using the Write Tool in Maka

The **Write** tool creates or overwrites files with automatic diff reporting.

### Write Tool Schema

The schema (lines 26-30) is straightforward:

```typescript
{
  path: z.string(),
  content: z.string()
}

```

### Write Tool Implementation

The implementation (lines 31-44) forwards a `write` operation to the sandboxed executor:

- If the executor returns a diff → reports `{ kind: 'file_diff', ... }`
- Otherwise → reports `{ kind: 'file_write', path, size }`

Failures are wrapped by `internalFilesystemWriteFailure()` (lines 50-57) with structured error information for model retry logic.

### Write Tool Code Example: Programmatic Usage

```typescript
const writeTool = tools.find(t => t.name === 'Write')!;

await writeTool.impl({
  path: 'tmp/example.txt',
  content: 'Hello, Maka!'
}, {
  cwd: process.cwd(),
  sessionId: 'demo-session',
  turnId: 'turn-2',
  abortSignal: new AbortController().signal,
});

```

### Write Tool CLI Usage

```bash
maka run "Write" '{"path":"tmp/example.txt","content":"Hello, Maka!"}'

```

## Read and Write Tool Security Architecture

Both tools rely on [[`packages/runtime/src/filesystem-executor.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/filesystem-executor.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/filesystem-executor.ts), which implements **createBoundaryFilesystemExecutor**. This component:

- Validates all paths against the session's **permission profile**
- Runs file operations in a **dedicated worker process**
- Prevents path traversal and unauthorized access
- Returns structured results through `fileWriteToolResultToModelOutput` in [[`packages/runtime/src/file-tool-model-output.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/file-tool-model-output.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/file-tool-model-output.ts)

The `classifyRuntimeResourceRef()` helper (lines 147-166) provides defense-in-depth by explicitly categorizing reference types before any I/O occurs.

## Common Error Handling in Maka File Tools

| Error Function | Location | Trigger Condition |
|----------------|----------|-----------------|
| `internalFilesystemReadFailure()` | builtin-tools.ts:40-58 | Sandbox worker read error, invalid ref |
| `internalFilesystemWriteFailure()` | builtin-tools.ts:50-57 | Sandbox worker write error, permission denied |
| Zod validation errors | Built into schema | Missing required fields, type mismatches |

All errors include machine-parseable codes that the language model can use for automatic retry or user notification.

## Summary

- **`buildBuiltinTools()`** creates Read and Write tool instances with Zod-validated schemas and sandboxed implementations
- **Read tool** supports both file paths (with offset/limit) and runtime resource references via `ref`
- **Write tool** creates files and reports either `file_write` or `file_diff` results depending on executor output
- Both tools delegate to **createBoundaryFilesystemExecutor** for permission-enforced, worker-isolated I/O
- Error handling produces structured, model-friendly outputs through dedicated failure functions
- Access the CLI with `maka run "<ToolName>" '<JSON-input>'` for quick testing

## Frequently Asked Questions

### What permissions does the Maka Read tool require?

The Read tool inherits permissions from the **session's permission profile** passed to `createBoundaryFilesystemExecutor`. The executor validates every path against this profile before any filesystem access occurs. If the path falls outside allowed directories, `internalFilesystemReadFailure()` returns a permission error without attempting I/O.

### Can the Maka Write tool modify binary files?

The Write tool schema accepts `content` as a **string**, so it is designed for text file creation and modification. Binary data handling would require encoding (e.g., base64) outside the tool or using a different runtime utility. The tool's `file_diff` response format in [[`file-tool-model-output.ts`](https://github.com/apache/maka/blob/main/file-tool-model-output.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/file-tool-model-output.ts) is optimized for textual diffs.

### How do I test Read and Write tool behavior in Apache Maka?

The Maka repository includes comprehensive test suites: [[`runtime-event-read-model.test.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.test.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/runtime-event-read-model.test.ts) validates Read tool behavior and error paths, while [[`builtin-tools.test.ts`](https://github.com/apache/maka/blob/main/builtin-tools.test.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/builtin-tools.test.ts) covers Write tool operations. These tests mock the filesystem executor to verify schema validation, error handling, and result formatting without actual disk I/O.