# Extension host

Understand how customer extension code participates in the model loop without running in the trusted worker.

Hosted extensions execute in a dedicated host inside the sandbox. The trusted worker communicates with that host through an authenticated, bounded channel.

```mermaid
flowchart LR
  Worker[Trusted worker] -->|Authenticated bounded channel| Host[Sandbox extension host]
  Host --> Extension[Customer extension]
  Extension --> Workspace[Run workspace]
  Worker --> Provider[Model provider]
  Extension -. no process access .-> Worker
```

## Two phases

| Phase              | Purpose                                | Available behavior                             |
| ------------------ | -------------------------------------- | ---------------------------------------------- |
| Manifest discovery | Compile declarations before deployment | `registerTool()`, `on()`                       |
| Hosted execution   | Run declared behavior in the sandbox   | Tools, hooks, `setModel()`, `setActiveTools()` |

Discovery imports the module but does not execute tool bodies or lifecycle handlers. Extension initialization must therefore be deterministic and free of network calls.

## Runtime projection

The worker sends only event-specific, JSON-safe data required by the hook or tool. The shared handler context currently contains bounded external integration metadata. Worker process memory and platform credentials are never passed through the contract.

## Failure boundary

Tools and hooks have explicit timeouts. Invalid results, timeouts, and thrown errors fail the active extension operation and produce sanitized lifecycle evidence.

## Source authority

The compiled deployment manifest declares entrypoints, tools, and hook subscriptions. The sandbox loads the immutable extension resources from the pinned deployment; mutable workspace files do not redefine that authority.

Use the [extension reference](/docs/reference/extensions/pi-object) for the exact public contract.