> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Steer a coding agent

> Replay runner events to steer a coding agent, interrupt a turn, answer approvals, or restart work.

Before you steer a coding agent, identify its current turn and save the last event sequence you processed. This lets you reconnect without losing your place in the event stream.

## Replay events

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead events ID --follow
bead events ID --after 42
bead status ID
```

Save the last event sequence you processed and use it as `--after` when reconnecting. Runner events are separate from [lifecycle webhooks](https://docs.bead.run/platform/events.md).

## Steer or interrupt

Replace `TURN_UUID` with the current turn ID from runner state. Retain a new UUID for each distinct control request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead steer ID 'Focus on the smallest failing test first' --turn TURN_UUID \
  --request-id 296fae42-f1d3-41f6-a58b-213a32d2e41b
bead interrupt ID --turn TURN_UUID \
  --request-id 92dfd048-a72c-4a64-b6c6-c878d306f27a
```

The API uses `requestId` and `expectedTurnId`; steering also includes `text`. Supplying the expected turn prevents a delayed control request from targeting later work. Reuse the same control request UUID only when retrying that request.

## Answer an approval

Use the server request ID from the approval event:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead approval ID --turn TURN_UUID --server-id REQUEST_ID --decision accept
```

Decisions are `accept`, `decline`, and `cancel`. The server request ID can be a string or JSON value, matching the event.

Prompts default to `approvalPolicy: "untrusted"`. The prompt flag `--approve-tools` selects `"never"`, which skips approval prompts for that turn. Choose the policy deliberately before starting work.

## Restart the runner

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead restart ID
```

Inspect status and events afterwards before dispatching another prompt. A restart does not prove an uncertain external action did not happen.

The MCP equivalents are `bead:runner_steer`, `bead:runner_interrupt`, `bead:runner_approval`, and `bead:runner_restart`. For interactive human help, use [desktop takeover](https://docs.bead.run/agents/watch-takeover.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.