---
title: "Write one isolated executor"
lesson_id: "03"
---

# Write one isolated executor

- **Lesson ID:** 03
- **Goal:** Introduce one executor actor that tools must call for file, network, or long work.
- **Human lesson:** [03-isolated-executor.html](03-isolated-executor.html)

## Prerequisites

Lesson 02.

## Inputs, outputs, and artifacts

- **Inputs:** ToolRequest and allow-lists.
- **Outputs:** A single run method that can refuse work.
- **Artifacts:** ToolExecutor and optional macOS XPC sketches.

## Agent build steps

1. Ban direct FileManager use in tools.
2. Show allow-list and timeout in the executor.
3. Mention XPC only as the macOS helper behind the same executor.
4. Link [Talk to tools with MCP](../on-device-mcp-server-client/), [Stop prompt attacks and leaks](../on-device-guardrails/), and [Make several agents agree first](../on-device-multi-agent-consensus/).

## Constraints

iOS 27 or later, or macOS 27 or later, and Xcode 27. Plain spoken English. No metaphor, quizzes, Mermaid, or em dashes. Be honest: Foundation Models tools run in the app process by default. Extra isolation is XPC or an app extension, and iOS options are narrower than macOS.

## Key concepts

- The executor actor is the only type that touches files, network, or long work.
- A request carries name, file ids, optional url, and a work closure.
- Errors include unknown tool, file not allowed, network denied, and timeout.
- Timeout by racing sleep in a task group, then cancel.

## Takeaways

- Tools call the executor, never `FileManager` or `URLSession` directly.
- One executor gives one enforcement point.
- If a tool can open a file without the executor, the box is optional.

## Acceptance checks

- Tools call the executor, not FileManager.
- Sibling links, progressive .flow diagrams, and the Agent brief link are present.
- [ ] Proceed to [lesson brief](04-resource-limits.llms.md).