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

# Chat modes

> How Fleet Pi's Agent, Plan, and Harness chat modes change the tool allowlist passed to the Pi runtime, including read-only Plan mode and per-mode tool tables.

Fleet Pi exposes the same chat surface in three distinct modes. The mode is sent on every `/api/chat` request as `mode: "agent" | "plan" | "harness"` and decides which tool allowlist the Pi runtime receives.

The full list of available tools and per-mode allowlists lives in [`apps/web/src/lib/pi/plan-mode.ts`](https://github.com/Qredence/fleet-pi/blob/main/apps/web/src/lib/pi/plan-mode.ts).

## Agent mode

Agent mode is the default and the broadest. It enables full repo-scoped editing and the Pi-managed extension tools.

**Allowed tools**

| Tool                                                  | Purpose                                                  |
| ----------------------------------------------------- | -------------------------------------------------------- |
| `read`                                                | Read a file from the repo                                |
| `write`                                               | Create or overwrite a file                               |
| `edit`                                                | String-replace inside a file                             |
| `bash`                                                | Execute shell commands inside the project root           |
| `workspace_write`                                     | Durable `agent-workspace/` updates with rationale fields |
| `resource_install`                                    | Install Pi skills, prompts, extensions, themes, packages |
| `questionnaire`                                       | Ask the user a structured follow-up question             |
| `web_fetch`                                           | Fetch a URL with safety-checked allowlist                |
| `project_inventory`, `workspace_index`                | Project-resource introspection                           |
| `autocontext_*`                                       | Pi autocontext judge, improve, queue, snapshot tools     |
| `init_experiment`, `run_experiment`, `log_experiment` | Pi autoresearch tools                                    |
| `subagent`                                            | Delegate work to a subagent                              |

## Plan mode

Plan mode is **read-only**. The agent inspects the repo, asks focused follow-up questions, and produces numbered execution plans. Structured plan cards keep `execute`, `stay`, and `refine` actions visible after page refresh or session resume — backed by persisted custom session entries so legacy text parsing remains a fallback.

**Allowed tools**

`read`, `bash` (inspection only — mutating shell activity is blocked with an explicit reason), `grep`, `find`, `ls`, `questionnaire`, `project_inventory`, `workspace_index`, and the read-only `autocontext_status` family.

**Behavior contract**

* Tool allowlist is inspection-only.
* Blocked shell commands return an explicit reason instead of silently mutating the repo.
* Plan state is emitted on the stream as `plan` events that include `{ executing, completed, total, todos, message, state }`.
* Plan cards survive refresh because Plan mode persists structured entries to the Pi session file.

See `evaluatePlanCommand` and `applyPlanModeSelection` in [`apps/web/src/lib/pi/plan-mode.ts`](https://github.com/Qredence/fleet-pi/blob/main/apps/web/src/lib/pi/plan-mode.ts) for the exact enforcement logic.

## Harness mode

Harness mode is for **workspace-architecture work**. It swaps general repo-mutation tools (`write`, `edit`) for the workspace-aware `workspace_write` and `resource_install` tools so durable changes always go through the [adaptive workspace contract](/fleet-pi/adaptive-workspace).

**Allowed tools**

`read`, `bash`, `grep`, `find`, `ls`, `workspace_write`, `resource_install`, `questionnaire`, `web_fetch`, plus the project-resource and autocontext-status families.

**When to use it**

* Adding or changing canonical files under `agent-workspace/memory/`, `plans/`, `skills/`, `evals/`, or `artifacts/`.
* Installing Pi skills, prompts, extensions, themes, or packages.
* Authoring workspace policies or evaluation material that must include rationale.

`workspace_write` requires a rationale for protected or rationale-required areas. `resource_install` is the only supported way to add chat-installed Pi resources under `agent-workspace/pi/*`.

## Streaming behavior

Two streaming behaviors decide how prompts queued mid-stream are handled:

* `streamingBehavior: "steer"` — enqueue the message as a steering prompt for the active assistant turn.
* `streamingBehavior: "followUp"` — enqueue the message to run after the current turn finishes.

Steering and follow-up queues are surfaced on the stream as `queue` events.

## Related

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/fleet-pi/api-reference">
    The chat endpoints and the full stream event taxonomy.
  </Card>

  <Card title="Adaptive workspace" icon="file-contract" href="/fleet-pi/adaptive-workspace">
    Where `workspace_write` is allowed to write, and why.
  </Card>

  <Card title="Generative UI" icon="shapes" href="/fleet-pi/generative-ui">
    Inline OpenUI components the agent can stream into chat in Agent and Plan modes.
  </Card>
</CardGroup>