@mastra/core/dist/docs/references/reference-harness-harness-class.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# Harness class

**Added in:** `@mastra/core@1.5.0`

> **Warning:** The `Harness` class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.
>
> [Mastra Code](https://code.mastra.ai/) is the flagship implementation of the `Harness` class, showcasing how it can be used to build a powerful terminal-based coding agent with multi-model support, persistent conversations, and built-in tools.

The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.

## Usage example

```typescript
import { Harness } from '@mastra/core/harness'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const harness = new Harness({
  id: 'my-coding-agent',
  storage: new LibSQLStore({ url: 'file:./data.db' }),
  stateSchema: z.object({
    currentModelId: z.string().optional(),
  }),
  modes: [
    { id: 'plan', name: 'Plan', default: true, agent: planAgent },
    { id: 'build', name: 'Build', agent: buildAgent },
  ],
})

harness.subscribe(event => {
  if (event.type === 'message_update') {
    renderMessage(event.message)
  }
})

await harness.init()
await harness.selectOrCreateThread()
await harness.sendMessage({ content: 'Hello!' })
```

## Constructor parameters

**id** (`string`): Unique identifier for this harness instance.

**resourceId** (`string`): Resource ID for grouping threads (e.g., project identifier). Threads are scoped to this resource ID. Defaults to \`id\`.

**storage** (`MastraCompositeStore`): Storage backend for persistence (threads, messages, state).

**stateSchema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the shape of harness state. Used for validation and extracting defaults.

**initialState** (`Partial<z.infer<TState>>`): Initial state values. Must conform to the schema if provided.

**memory** (`MastraMemory`): Memory configuration shared across all modes. Propagated to mode agents that don't have their own memory.

**modes** (`HarnessMode[]`): Available agent modes. At least one mode is required. Each mode defines an agent and optional defaults.

**modes.id** (`string`): Unique identifier for this mode (e.g., \`"plan"\`, \`"build"\`).

**modes.name** (`string`): Human-readable name for display.

**modes.default** (`boolean`): Whether this is the default mode when the harness starts.

**modes.defaultModelId** (`string`): Default model ID for this mode (e.g., \`"anthropic/claude-sonnet-4-20250514"\`). Used when no per-mode model has been explicitly selected.

**modes.color** (`string`): Hex color for the mode indicator (e.g., \`"#7c3aed"\`).

**modes.agent** (`Agent | ((state) => Agent)`): The agent for this mode. It can be a static Agent instance or a function that receives harness state and returns an Agent.

**tools** (`ToolsInput | ((ctx) => ToolsInput)`): Tools available to all agents across all modes. It can be a static tools object or a dynamic function that receives the request context.

**workspace** (`Workspace | WorkspaceConfig | ((ctx) => Workspace)`): Workspace configuration. Accepts a pre-constructed Workspace, a WorkspaceConfig for the harness to construct internally, or a dynamic factory function.

**subagents** (`HarnessSubagent[]`): Subagent definitions. When provided, the harness creates a built-in \`subagent\` tool that parent agents can call to spawn focused subagents.

**subagents.id** (`string`): Unique identifier for this subagent type (e.g., \`"explore"\`, \`"execute"\`).

**subagents.name** (`string`): Human-readable name shown in tool output.

**subagents.description** (`string`): Description of what this subagent does. Used in the auto-generated tool description.

**subagents.instructions** (`string`): System prompt for this subagent.

**subagents.tools** (`ToolsInput`): Tools this subagent has direct access to.

**subagents.allowedHarnessTools** (`string[]`): Tool IDs from the harness's shared \`tools\` config. Merged with \`tools\` above to let subagents use a subset of harness tools.

**subagents.allowedWorkspaceTools** (`string[]`): Workspace tool names the subagent is allowed to use. Uses the exposed names (after any renames via workspace tool config). When set, workspace tools not in this list are hidden from the model. Non-workspace tools are never affected. When omitted, all workspace tools are visible.

**subagents.defaultModelId** (`string`): Default model ID for this subagent type.

**subagents.maxSteps** (`number`): Optional maximum number of steps for the spawned subagent. Defaults to \`50\` when omitted.

**subagents.stopWhen** (`LoopOptions['stopWhen']`): Optional stop condition for the spawned subagent.

**subagents.forked** (`boolean`): When \`true\`, calls to this subagent default to forked mode: the subagent runs on a clone of the parent thread, reusing the parent agent’s instructions, tools, and model so the prompt-cache prefix stays intact. Requires \`memory\` to be configured. The subagent definition’s own \`instructions\`, \`tools\`, \`allowedHarnessTools\`, \`allowedWorkspaceTools\`, \`defaultModelId\`, \`maxSteps\`, and \`stopWhen\` are ignored in forked mode. Callers can still override per-invocation via \`forked: false\` in the \`subagent\` tool input. See the \[Forked subagents]\(#forked-subagents) section below for full semantics.

**resolveModel** (`(modelId: string) => MastraLanguageModel`): Converts a model ID string (e.g., \`"anthropic/claude-sonnet-4"\`) to a language model instance. Used by subagents and observational memory model resolution.

**omConfig** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).

**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.

**heartbeatHandlers** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.

**idGenerator** (`() => string`): Custom ID generator for Harness-managed IDs such as threads and mode-run identifiers. (Default: `timestamp + random string`)

**modelAuthChecker** (`ModelAuthChecker`): Custom auth checker for model providers. Return \`true\`/\`false\` to override the default environment variable check, or \`undefined\` to fall back to defaults.

**modelUseCountProvider** (`ModelUseCountProvider`): Provides per-model use counts for sorting and display in \`listAvailableModels()\`.

**toolCategoryResolver** (`(toolName: string) => ToolCategory | null`): Maps tool names to permission categories (\`'read'\`, \`'edit'\`, \`'execute'\`, \`'mcp'\`, \`'other'\`). Used by the permission system to resolve category-level policies.

**threadLock** (`{ acquire, release }`): Thread locking callbacks to prevent concurrent access from multiple processes. \`acquire\` should throw if the lock is held.

## Properties

**id** (`string`): Harness identifier, set at construction.

## Methods

### Lifecycle

#### `init()`

Initialize the harness. Loads storage, initializes the workspace, propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the harness.

```typescript
await harness.init()
```

#### `selectOrCreateThread()`

Select the most recent thread for the current resource, or create one if none exist. Loads thread metadata and acquires a thread lock.

```typescript
const thread = await harness.selectOrCreateThread()
```

#### `destroy()`

Stop all heartbeat handlers and clean up resources.

```typescript
await harness.destroy()
```

### State

#### `getState()`

Return a read-only snapshot of the current harness state.

```typescript
const state = harness.getState()
```

#### `getDisplayState()`

Return the current `HarnessDisplayState` snapshot for UI rendering.

```typescript
const displayState = harness.getDisplayState()
```

#### `restoreDisplayTasks(tasks)`

Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.

If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.

```typescript
await harness.setState({ tasks: replayedTasks })
harness.restoreDisplayTasks(replayedTasks)
```

#### `setState(updates)`

Update the harness state. Validates against `stateSchema` if provided, and emits a `state_changed` event with the new state and changed keys.

```typescript
await harness.setState({ currentModelId: 'anthropic/claude-sonnet-4-6' })
```

### Modes

#### `listModes()`

Return all configured `HarnessMode` instances.

```typescript
const modes = harness.listModes()
```

#### `getCurrentModeId()`

Return the ID of the currently active mode.

```typescript
const modeId = harness.getCurrentModeId()
```

#### `getCurrentMode()`

Return the `HarnessMode` object for the current mode.

```typescript
const mode = harness.getCurrentMode()
```

#### `switchMode({ modeId })`

Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events.

```typescript
await harness.switchMode({ modeId: 'build' })
```

### Models

#### `getCurrentModelId()`

Return the ID of the currently selected model from state.

```typescript
const modelId = harness.getCurrentModelId()
```

#### `getModelName()`

Return a short display name from the current model ID. For example, `"claude-sonnet-4"` from `"anthropic/claude-sonnet-4"`.

```typescript
const name = harness.getModelName()
```

#### `getFullModelId()`

Return the complete model ID string.

```typescript
const fullId = harness.getFullModelId()
```

#### `hasModelSelected()`

Check if a model ID is currently selected.

```typescript
if (harness.hasModelSelected()) {
  // Ready to send messages
}
```

#### `switchModel({ modelId, scope?, modeId? })`

Switch the active model. When `scope` is `'thread'`, the model ID is persisted to thread metadata so it's restored when switching back. Emits a `model_changed` event.

```typescript
// Set for current session only
await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-6' })

// Persist to the current thread
await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-6', scope: 'thread' })
```

#### `getCurrentModelAuthStatus()`

Check if the current model's provider has authentication configured. Uses `modelAuthChecker` if provided, falling back to environment variable checks from the provider registry.

```typescript
const status = await harness.getCurrentModelAuthStatus()
// { hasAuth: true, apiKeyEnvVar: 'ANTHROPIC_API_KEY' }
```

#### `listAvailableModels()`

Retrieve all available models from the provider registry, including their authentication status and use counts.

```typescript
const models = await harness.listAvailableModels()
// [{ id, provider, modelName, hasApiKey, apiKeyEnvVar, useCount }]
```

### Threads

#### `getCurrentThreadId()`

Return the ID of the currently active thread.

```typescript
const threadId = harness.getCurrentThreadId()
```

#### `createThread({ title? })`

Create a new thread. Initializes thread metadata, saves it to storage, acquires a thread lock, and emits a `thread_created` event.

```typescript
const thread = await harness.createThread({ title: 'New conversation' })
```

#### `switchThread({ threadId })`

Switch to a different thread. Aborts any in-progress operations, acquires a lock on the new thread, releases the lock on the previous thread, loads the thread's metadata, and emits a `thread_changed` event.

```typescript
await harness.switchThread({ threadId: 'thread-abc123' })
```

#### `listThreads(options?)`

List threads from storage. By default, only threads for the current resource are returned, and transient [forked subagent](#forked-subagents) threads are hidden so they don’t appear in user-facing thread pickers / startup flows.

```typescript
// List threads for current resource (forks hidden)
const threads = await harness.listThreads()

// List all threads across resources (forks still hidden)
const allThreads = await harness.listThreads({ allResources: true })

// Include forked subagent fork threads (debug / admin tooling only)
const everything = await harness.listThreads({ includeForkedSubagents: true })
```

Fork threads are tagged with `metadata.forkedSubagent === true` (and `metadata.parentThreadId`) by the harness. Set `includeForkedSubagents: true` to opt back into seeing them — e.g. for a debug panel.

#### `renameThread({ title })`

Update the title of the current thread.

```typescript
await harness.renameThread({ title: 'Updated title' })
```

#### `cloneThread({ sourceThreadId?, title?, resourceId? })`

Clone an existing thread and switch to the clone. Copies all messages, acquires a lock on the new thread, releases the lock on the previous thread, and emits a `thread_created` event. If `sourceThreadId` is omitted, the current thread is cloned. When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, OM records are cloned with remapped message IDs.

```typescript
// Clone the current thread
const cloned = await harness.cloneThread()

// Clone a specific thread with a custom title
const cloned = await harness.cloneThread({
  sourceThreadId: 'thread-abc123',
  title: 'Alternative approach',
})
```

See [`Memory.cloneThread()`](https://mastra.ai/reference/memory/cloneThread) for details on what gets cloned.

#### `getResourceId()`

Return the current resource ID.

```typescript
const resourceId = harness.getResourceId()
```

#### `setResourceId({ resourceId })`

Set the resource ID and clear the current thread.

```typescript
harness.setResourceId({ resourceId: 'project-xyz' })
```

#### `getSession()`

Return current session information including thread ID, mode ID, and the list of threads.

```typescript
const session = await harness.getSession()
// { currentThreadId, currentModeId, threads }
```

### Messages

#### `sendMessage({ content, files?, requestContext? })`

Send a message to the current agent. Creates a thread if none exists, builds a `RequestContext` and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically. If you provide `requestContext`, the harness forwards it to tools and subagents during the run.

```typescript
await harness.sendMessage({ content: 'Explain the authentication flow' })
```

#### `listMessages(options?)`

Retrieve messages for the current thread.

```typescript
const messages = await harness.listMessages()

// Limit to the last 50 messages
const recent = await harness.listMessages({ limit: 50 })
```

#### `listMessagesForThread({ threadId, limit? })`

Retrieve messages for a specific thread.

```typescript
const messages = await harness.listMessagesForThread({ threadId: 'thread-abc123' })
```

#### `getFirstUserMessageForThread({ threadId })`

Retrieve the first user message for a given thread.

```typescript
const firstMsg = await harness.getFirstUserMessageForThread({ threadId: 'thread-abc123' })
```

### Memory

The `memory` property exposes thread management operations. These are also available as top-level methods on the harness.

#### `memory.createThread({ title? })`

Create a new thread. Same as `harness.createThread()`.

#### `memory.switchThread({ threadId })`

Switch to a different thread. Same as `harness.switchThread()`.

#### `memory.listThreads(options?)`

List threads from storage. Same as `harness.listThreads()`.

#### `memory.renameThread({ title })`

Update the title of the current thread. Same as `harness.renameThread()`.

#### `memory.deleteThread({ threadId })`

Delete a thread and all its messages from storage. If the deleted thread is the currently active thread, the thread lock is released and the harness clears its active thread. Emits a `thread_deleted` event.

```typescript
await harness.memory.deleteThread({ threadId: 'thread-abc123' })
```

### Flow control

#### `abort()`

Abort any in-progress generation.

```typescript
harness.abort()
```

#### `steer({ content, requestContext? })`

Steer the agent mid-stream by injecting an instruction into the current generation.

```typescript
harness.steer({ content: 'Focus on security implications' })
```

#### `followUp({ content, requestContext? })`

Queue a follow-up message to be sent after the current generation completes. If no operation is running, sends the message immediately.

```typescript
harness.followUp({ content: 'Now apply those changes' })
```

### Tool approvals

#### `respondToToolApproval({ decision, requestContext? })`

Respond to a pending tool approval request. Called when a `tool_approval_required` event is received.

```typescript
harness.respondToToolApproval({ decision: 'approve' })
harness.respondToToolApproval({ decision: 'decline' })
```

### Questions and plans

#### `respondToQuestion({ questionId, answer })`

Respond to a pending question from the `ask_user` built-in tool.

```typescript
harness.respondToQuestion({ questionId: 'q-123', answer: 'Yes, proceed with the refactor' })
```

For multi-select questions, pass the selected option labels as a string array.

```typescript
harness.respondToQuestion({ questionId: 'q-123', answer: ['Add tests', 'Update docs'] })
```

#### `respondToPlanApproval({ planId, response })`

Respond to a pending plan approval from the `submit_plan` built-in tool. The `response` object contains `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.

```typescript
harness.respondToPlanApproval({ planId: 'plan-123', response: { action: 'approved' } })
harness.respondToPlanApproval({
  planId: 'plan-123',
  response: { action: 'rejected', feedback: 'Needs more detail' },
})
```

### Permissions

#### `grantSessionCategory({ category })`

Grant a tool category for the current session. Tools in this category are auto-approved without prompting.

```typescript
harness.grantSessionCategory({ category: 'edit' })
```

#### `grantSessionTool({ toolName })`

Grant a specific tool for the current session.

```typescript
harness.grantSessionTool({ toolName: 'mastra_workspace_execute_command' })
```

#### `getSessionGrants()`

Return currently granted session categories and tools.

```typescript
const grants = harness.getSessionGrants()
// { categories: Set<string>, tools: Set<string> }
```

#### `setPermissionForCategory({ category, policy })`

Set the permission policy for a tool category.

```typescript
harness.setPermissionForCategory({ category: 'execute', policy: 'ask' })
```

#### `setPermissionForTool({ toolName, policy })`

Set the permission policy for a specific tool. Per-tool policies take precedence over category policies.

```typescript
harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' })
```

#### `getPermissionRules()`

Return the current permission rules.

```typescript
const rules = harness.getPermissionRules()
// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }
```

#### `getToolCategory({ toolName })`

Resolve a tool's category using the configured `toolCategoryResolver`.

```typescript
const category = harness.getToolCategory({ toolName: 'mastra_workspace_write_file' })
// 'edit'
```

### Workspace

#### `getWorkspace()`

Return the current workspace instance, or `undefined` if no workspace is configured or it hasn't been resolved yet.

```typescript
const workspace = harness.getWorkspace()
```

#### `resolveWorkspace({ requestContext? })`

Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.

```typescript
const workspace = await harness.resolveWorkspace()
```

#### `hasWorkspace()`

Return whether a workspace is configured (static, config-based, or dynamic).

```typescript
if (harness.hasWorkspace()) {
  const workspace = await harness.resolveWorkspace()
}
```

#### `isWorkspaceReady()`

Return whether the workspace is ready to use. For dynamic workspaces (factory function), always returns `true`. For static workspaces, returns `true` after `init()` succeeds.

```typescript
if (harness.isWorkspaceReady()) {
  const workspace = harness.getWorkspace()
}
```

#### `destroyWorkspace()`

Destroy the workspace and release resources. Only applies to static workspaces — dynamic workspaces aren't destroyed.

```typescript
await harness.destroyWorkspace()
```

### Observational Memory

#### `loadOMProgress()`

Load observational memory records for the current thread and emit an `om_status` event with reconstructed progress.

```typescript
await harness.loadOMProgress()
```

#### `getObservationalMemoryRecord()`

Return the full `ObservationalMemoryRecord` for the current thread and resource, or `null` if no thread is selected or no record exists.

```typescript
const record = await harness.getObservationalMemoryRecord()

if (record) {
  console.log(record.activeObservations)
  console.log(record.generationCount)
  console.log(record.observationTokenCount)
}
```

#### `getObserverModelId()`

Return the observer model ID from state or the default from `omConfig`.

```typescript
const modelId = harness.getObserverModelId()
```

#### `getReflectorModelId()`

Return the reflector model ID from state or the default from `omConfig`.

```typescript
const modelId = harness.getReflectorModelId()
```

#### `switchObserverModel({ modelId })`

Switch the observer model. Persists the setting to thread metadata and emits an `om_model_changed` event.

```typescript
await harness.switchObserverModel({ modelId: 'anthropic/claude-haiku-3.5' })
```

#### `switchReflectorModel({ modelId })`

Switch the reflector model. Persists the setting to thread metadata and emits an `om_model_changed` event.

```typescript
await harness.switchReflectorModel({ modelId: 'anthropic/claude-haiku-3.5' })
```

#### `getObservationThreshold()`

Return the observation threshold in tokens from state or the default from `omConfig`.

```typescript
const threshold = harness.getObservationThreshold()
```

#### `getReflectionThreshold()`

Return the reflection threshold in tokens from state or the default from `omConfig`.

```typescript
const threshold = harness.getReflectionThreshold()
```

### Subagents

#### `getSubagentModelId({ agentType? })`

Retrieve the subagent model ID. Prioritizes per-type settings over the global setting.

```typescript
const modelId = harness.getSubagentModelId({ agentType: 'explore' })
```

#### `setSubagentModelId({ modelId, agentType? })`

Set the subagent model ID. Pass an `agentType` to set a per-type override, or omit it to set the global default. Persists to thread settings and emits a `subagent_model_changed` event.

```typescript
// Set global subagent model
await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-6' })

// Set per-type model
await harness.setSubagentModelId({ modelId: 'anthropic/claude-haiku-3.5', agentType: 'explore' })
```

### Forked subagents

By default, a subagent runs with a fresh context — it doesn't see the parent conversation. **Forked subagents** opt into a different model: the subagent runs on a clone of the parent thread and reuses the parent agent's full configuration. This is useful when the subagent needs the full context of the conversation so far (e.g., recalling earlier user-supplied facts), and when prompt-cache hit rates matter.

#### Enabling forked mode

Set `forked: true` either on the `HarnessSubagent` definition (per-type default) or on each `subagent` tool call (per-invocation override):

```typescript
// Per-type default — every call to this subagent forks unless overridden.
const subagents: HarnessSubagent[] = [
  {
    id: 'collaborator',
    name: 'Collaborator',
    description: 'Continues the conversation in a fork to try a different angle.',
    instructions: '...',
    forked: true,
  },
]
```

The model can also pass `forked: true` (or `forked: false`) per-invocation in the `subagent` tool input; the per-invocation value wins.

#### Semantics and constraints

- **Memory required.** Forked mode calls `memory.cloneThread` to create the fork, so the harness must have `memory` configured and an active parent thread. Calls without those return a structured error rather than throwing.
- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedHarnessTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode — this is what preserves the prompt-cache prefix.
- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured harness tools, _including the `subagent` tool itself_) so the LLM request prefix — system prompt + tool list + tool schemas + tool descriptions — stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
- **Fork threads are tagged.** Each fork thread is created with `metadata.forkedSubagent === true` and `metadata.parentThreadId === <parent>`. By default, [`listThreads`](#listthreadsoptions) hides these so they don't show up in user-facing thread pickers / startup flows. Pass `includeForkedSubagents: true` to see them in admin / debug tooling.
- **Save-queue flushed before clone.** The agent stream batches message saves through a debounced `SaveQueueManager`, so the parent's latest user / assistant turn may not be on disk yet when the subagent tool call fires. The fork tool flushes pending saves first via the `flushMessages` callback on `AgentToolExecutionContext` before cloning, so the fork actually carries the latest turn. Flush failures are non-fatal — the clone still runs.
- **Parent thread untouched.** All subagent activity (messages, OM writes) lands on the fork. The parent thread is never appended to during a forked subagent run.

#### When to prefer non-forked mode

Forked mode trades isolation for context inheritance. If the subagent should run with a strictly smaller toolset, a different system prompt, or a cheaper model, use the default (non-forked) mode and pass any required context explicitly in the `task` description.

### Events

#### `subscribeDisplayState(listener, options?)`

Register a listener for coalesced display state snapshots. Use this method for UI, Server-Sent Events (SSE), terminal UI (TUI), and bridge rendering paths that only need the latest `HarnessDisplayState`. Use [`subscribe`](#subscribelistener) when you need the raw event log.

```typescript
const unsubscribe = harness.subscribeDisplayState(displayState => {
  render(displayState)
})

// Optional tuning:
harness.subscribeDisplayState(render, {
  windowMs: 250,
  maxWaitMs: 500,
})

// Later:
unsubscribe()
```

Returns: `() => void`

`subscribeDisplayState()` does not call the listener immediately. Call [`getDisplayState`](#getdisplaystate) first if the UI needs an initial render before the next harness event.

#### `subscribe(listener)`

Register an event listener. Returns an unsubscribe function.

Use this method for audit logs, debugging, analytics, deterministic replay, or consumers that need every raw event. For display rendering, prefer [`subscribeDisplayState`](#subscribedisplaystatelistener-options) so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the latest display state snapshot.

```typescript
const unsubscribe = harness.subscribe(event => {
  switch (event.type) {
    case 'message_update':
      renderMessage(event.message)
      break
    case 'tool_approval_required':
      showApprovalPrompt(event.toolName)
      break
    case 'error':
      console.error(event.error)
      break
  }
})

// Later:
unsubscribe()
```

## Events

The harness emits events through registered listeners. The following table lists the available event types:

| Event type                 | Description                                                                                         |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| `mode_changed`             | The active mode changed.                                                                            |
| `model_changed`            | The active model changed.                                                                           |
| `thread_changed`           | The active thread changed.                                                                          |
| `thread_created`           | A new thread was created.                                                                           |
| `thread_deleted`           | A thread was deleted.                                                                               |
| `state_changed`            | Harness state was updated.                                                                          |
| `agent_start`              | The agent started processing.                                                                       |
| `agent_end`                | The agent finished processing.                                                                      |
| `message_start`            | A new message started streaming.                                                                    |
| `message_update`           | A message was updated with new content.                                                             |
| `message_end`              | A message finished streaming.                                                                       |
| `tool_start`               | A tool call started.                                                                                |
| `tool_approval_required`   | A tool call requires user approval.                                                                 |
| `tool_update`              | A tool call was updated with progress.                                                              |
| `tool_end`                 | A tool call finished.                                                                               |
| `tool_input_start`         | Tool input started streaming.                                                                       |
| `tool_input_delta`         | Tool input received a streaming delta.                                                              |
| `tool_input_end`           | Tool input finished streaming.                                                                      |
| `usage_update`             | Token usage was updated.                                                                            |
| `error`                    | An error occurred.                                                                                  |
| `info`                     | An informational message was emitted.                                                               |
| `follow_up_queued`         | A follow-up message was queued.                                                                     |
| `workspace_status_changed` | The workspace status changed.                                                                       |
| `workspace_ready`          | The workspace finished initializing.                                                                |
| `workspace_error`          | The workspace encountered an error.                                                                 |
| `om_status`                | Observational Memory status update.                                                                 |
| `om_observation_start`     | An observation started.                                                                             |
| `om_observation_end`       | An observation completed.                                                                           |
| `om_reflection_start`      | A reflection started.                                                                               |
| `om_reflection_end`        | A reflection completed.                                                                             |
| `ask_question`             | The agent asked a question via the `ask_user` tool. Includes optional choices and a selection mode. |
| `plan_approval_required`   | The agent submitted a plan for approval via the `submit_plan` tool.                                 |
| `plan_approved`            | A plan was approved.                                                                                |
| `subagent_start`           | A subagent started processing.                                                                      |
| `subagent_text_delta`      | A subagent emitted a text delta.                                                                    |
| `subagent_tool_start`      | A subagent started a tool call.                                                                     |
| `subagent_tool_end`        | A subagent finished a tool call.                                                                    |
| `subagent_end`             | A subagent finished processing.                                                                     |
| `subagent_model_changed`   | A subagent's model changed.                                                                         |
| `task_updated`             | A task list was updated.                                                                            |

## Built-in tools

The harness provides built-in tools to agents in every mode:

| Tool            | Description                                                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ask_user`      | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
| `submit_plan`   | Submit a plan for user review and approval.                                                                                                                                                          |
| `task_write`    | Create or replace a structured task list for tracking progress. Assigns task IDs when omitted and returns the structured task list snapshot.                                                         |
| `task_update`   | Update one tracked task by ID and return the structured task list snapshot.                                                                                                                          |
| `task_complete` | Mark one tracked task completed by ID and return the structured task list snapshot.                                                                                                                  |
| `task_check`    | Check the completion status of the current task list and return `tasks`, `summary`, `incompleteTasks`, and `isError` fields.                                                                         |
| `subagent`      | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |

### `ask_user` selections

The `ask_user` tool accepts `options` for choice prompts. Set `selectionMode` to `single_select` to let the user pick one option, or `multi_select` to let the user pick multiple options. When `options` are provided and `selectionMode` is omitted, the prompt defaults to `single_select`. Omit `options` for free-text questions.

The following example demonstrates a multi-select response handler. The UI reads `event.selectionMode`, lets the user choose multiple options, then returns a string array with `respondToQuestion()`.

```typescript
harness.subscribe(event => {
  if (event.type === 'ask_question' && event.selectionMode === 'multi_select') {
    harness.respondToQuestion({
      questionId: event.questionId,
      answer: ['Add tests', 'Update docs'],
    })
  }
})
```