Read reasoning blocks, tool cards, and diffs

Why learn to inspect these blocks?

Remember the extra elements around the AI's answer when you started your first conversation in Chapter 7? The collapsible gray block, white card, and red-and-green correction-like display are not decoration or bugs. They distinguish Pi Agent from a conventional chat page: they expose available reasoning information and the record of what the agent did.

Reading them lets you:

• Inspect available reasoning information when an answer takes a wrong turn.
• When the AI says it read configuration.yaml, open the tool card to confirm which file it read and what the tool returned.
• Review a diff line by line before accepting or retaining a configuration change—your final human checkpoint before allowing the agent to alter your home setup.

These records improve visibility, but they do not make an action safe automatically. A tool can run before you read its card, depending on the active guardrails. The goal is to recognize each block immediately and know whether to expand it while understanding the permissions your Session has.

Three special blocks at a glance

Start with this overview. The remaining sections add detail to this mental model:

Reasoning blocks explained

Reasoning blocks are the easiest of the three to miss because they are commonly collapsed.

What they look like

A gray block may be labeled “Thinking” or its localized equivalent and include a disclosure control such as ▶ or +. It commonly appears above the final answer. Expanding it reveals whatever reasoning text or summary the provider and route make available.

When they appear

Only a supported reasoning model and route can produce one. Chapter 12 explains the trade-offs. This quick reference helps identify what a route may expose:

Do not infer capabilities from a family name alone. Models such as GLM-4-Flash, GPT-4o, Claude Haiku 3.5, and Kimi K2-Instruct are non-reasoning examples in the source material; on OpenRouter, check the exact current model page and route.

What an expanded block contains

It may show provider-exposed reasoning about the answer—for example, identifying a 10:00 p.m. lighting trigger, choosing light.turn_off, and considering presence conditions. It may be a long passage, a short summary, or only metadata; do not assume it is the model's private chain of thought.

When to read it

• The final answer is strange or conflicts with your constraints.
• You want to inspect the stated analysis framework, such as how a lighting request was divided into trigger, condition, and action.
• You want to see whether an important condition appears in the available reasoning summary.

When to skip it

• The task is low risk and the final answer is easy to verify.
• You asked a simple lookup question.
• You will not use the result.

Why a reasoning model may show no block

Check three possibilities:

1. The Chapter 6 reasoning option is not enabled—where a model entry exposes a reasoning checkbox, it controls whether pi-web renders reasoning as a separate block.
2. The provider's thinkingFormat is wrong—this is a provider-level field. Use openai only for an applicable direct OpenAI-compatible route, zai for GLM, deepseek for DeepSeek, or qwen for a compatible Qwen route; a direct Anthropic route normally leaves it blank. The wrong parser may fail to separate reasoning_content. For OpenRouter, follow the exact model route's current documentation.
3. You selected a non-reasoning model under the provider—for example, a catalog may include both reasoning and non-reasoning variants, while a Groq Kimi K2 listing may be Instruct rather than Thinking. Confirm the exact model ID.

Tool call cards explained

A tool card is the most important of the three because it records something the agent actually attempted or did.

What they look like

A white card labeled “Tool: xxx” or “Calling xxx” includes a summary of the input parameters and output result. Expand it for complete details. Depending on the version, a card can show “Running…,” success, or failure.

When they appear

They appear when the agent needs to act rather than only generate prose—for example, reading a file, running a shell command, or querying an enabled service. Available tools depend on the active agent and installed Skills; Chapter 16 explains how Skills add capabilities. A model's own knowledge is not a live web search.

Common tool names: Seven pi coding agent built-ins

The core Pi Agent package, @earendil-works/pi-coding-agent, includes these seven lowercase tools:

What an expanded card contains

It contains the actual arguments—such as the read path or the bash command—and the returned file content, command output, or grep matches. This is stronger evidence of an attempted action than the model's narrative.

When to read it

• When the AI says it read a file, expand the corresponding read card and verify the path and result.
• For write / edit, always expand the card. Confirm the path; for edit, also verify that old_string really comes from the original file.
• For a bash card, inspect the command for dangerous patterns such as rm -rf, chmod 777, or curl | sh.
• If the conclusion differs from what you expected, inspect the raw tool output.

Inline diffs: Your file-change checkpoint

An inline diff requires close review because it records a proposed or executed file change. It is a review aid, not proof that the change is safe or waiting for approval.

What it looks like

Deleted lines appear in red with -; added lines appear in green with +. Unchanged white lines provide context, much like a GitHub pull-request diff.

When it appears

It can appear when the agent proposes or performs an edit to a known file. For example, after reading configuration.yaml, it can show the MQTT integration lines that differ. A standalone code sample has no baseline and may not produce a diff.

What you can inspect

Review the complete patch, not only the first visible lines. Controls such as “Show details,” “Apply,” “Copy,” or “Compare HEAD” depend on the pi-web version, active guardrails, and repository state.

When to read it

Every time.Also inspect the associated tool card to determine whether the edit already ran.

Three ways to handle a diff

1. Option A: Manually copy a reviewed final version

   This is the most conservative option. If your pi-web version offers Copy (the i18n.copy label), it may also offer Show details / Hide details for the complete patch and Compare HEAD for a Git comparison. Compare the result with the original configuration.yaml, preserve YAML indentation, and apply only the reviewed portion.

2. Option B: Ask the agent to use edit or write

   The agent may call edit for an exact local replacement or write to replace a complete file. Prefer edit when an exact local change is appropriate, but remember that you must watch the tool card: verify the path, the full content, and whether the action already ran. Use this only within approved guardrails.

3. Option C: Reject it and request a different approach

   If the direction is wrong or a line must remain, state exactly what to preserve and what to change. The agent can generate a new diff, which you must review again from the beginning.

Worked example: A lighting automation

Suppose you ask a suitable current model to add a 10:00 p.m. living-room lighting automation. The Session has file tools and the home-assistant-best-practices Skill, which provides Home Assistant guidance but no new tool. It encourages the agent to use edit rather than write over the complete automations.yaml. The response may follow this sequence:

If you read only “Done,” you miss the path, entity ID, exact YAML, and whether the tool succeeded. The diff and tool result let you catch mistakes before relying on the automation.

How these blocks affect context and cost

All three can affect token usage, although billing details vary by provider and route:

Use these three practical controls alongside Chapter 12:

1. Use reasoning only when the task benefits from it.For simple lookups and low-risk tasks, choose a current lower-cost non-reasoning model from your provider or OpenRouter catalog.
2. Before asking the agent to read a file, decide whether it needs the whole file.If only one range matters, request that range instead of loading thousands of irrelevant lines from automations.yaml into context.
3. Start a new Session when the conversation becomes too long.Old reasoning blocks and tool output can be carried into later context. Watch the contextUsage indicator if your version displays % used / contextWindow tokens. The documented baseline has no universal warning thresholds, so follow your exact route's limit rather than treating 60% as a guaranteed cutoff or waiting for a provider rejection.

Hide reasoning without confusing display and billing

Some people find reasoning blocks distracting. The documented pi-web 0.8.4 baseline does not provide a guaranteed global UI switch that directly hides every reasoning block; it commonly collapses them by default. Interface controls vary by version, and hiding a block does not prove that the provider stopped reasoning or billing. Two practical choices are:

• Return to Chapter 6 and change the model entry's reasoning setting only if the exact route supports it—the display and API behavior are route-specific. On OpenRouter, verify the selected model's documented reasoning settings and whether it returns reasoning_content.
• Select a non-reasoning model—choose a current non-reasoning model ID from your provider or OpenRouter catalog. This avoids assuming that a hidden display also avoids reasoning usage.

A useful compromise is to keep one Session for deliberate analysis and another for quick, low-risk questions. Choose current OpenRouter model IDs for each role instead of relying on region-specific defaults.

Common block problems

1. A reasoning block will not expand

   Wait for generation to finish. If it still will not expand, reload the page and try a private window without extensions. Press F12 and inspect the browser Console for a real JavaScript error.

2. A tool card reports an error

   Expand the card and read the output field named isError. Common causes include an incorrect /config/automations.yaml path, a bash command with a nonzero exit, or an edit old_string that did not match. Verify whether a partial action occurred before asking the agent to retry.

3. A copied diff breaks YAML indentation

   Compare whitespace against the original because tabs and spaces can look alike. Ask for a complete reviewed file only when whole-file replacement is appropriate; do not use write / edit merely to avoid understanding the diff.

4. A selected reasoning model shows no block

   Check the provider's thinkingFormat. A later direct GLM route may require zai as described in Chapter 6; for OpenRouter, verify the exact model's current reasoning support and route configuration. Open a new Session after changing provider settings.

5. A tool remains on “Running…”

   Inspect the exact tool. A long bash command such as find / or ffmpeg, or a very large read, may take time. The baseline pi coding agent has no built-in web_fetch tool, though a Skill can add one. Use Cancel if available; otherwise follow the installed version's recovery guidance and check the resulting isError state.

6. No diff appears; the agent shows only code

   A diff needs an original file or baseline. If you did not provide the actual automations.yaml, ask the agent to read and compare the reviewed file before editing.

Blocks FAQ