How to Make a Coding Agent Read Before It Edits

A coding agent can be told to inspect a repository before changing it. That instruction helps, but it does not remove its edit tools. A workflow can make the order explicit: keep diagnosis read-only, allow edits during implementation, run checks during validation, and return to read-only access for review. Statewright expresses those phases as states with their own tools and transitions. Whether a tool call is blocked before execution depends on the connected host and integration.

This pattern is useful for a bug fix, a small feature, or a refactor where you want to see what the agent learned before it starts changing files. It also gives the agent a clear path when a test fails: go back to implementation, make a focused repair, then validate again.

Give each phase one job

Start with the decision you want to control. For a bug fix, the first decision is whether the agent understands the failure well enough to edit. The second is whether the changed code passed the checks you chose. The last is whether the result is ready for a human to accept.

Phase	What the agent can do	What should be recorded before leaving
Diagnose	Read and search relevant code	The observed failure and a proposed fix
Implement	Read and make the bounded change	Files changed and why
Validate	Read and run the named checks	Commands, results, and remaining failures
Review	Inspect the diff and evidence	Findings, limitations, and a handoff

The Statewright engineering starter follows a more detailed version of this path. Its diagnose and baseline phases do not expose source editing; implementation enables a focused change; validation and review follow. It does not automatically commit or deploy. You can use the starter before designing a custom workflow.

Put tool access in the workflow definition

For a custom workflow, define states and the events that move between them. In each state, list the capabilities that belong there with allowed_tools. A read-only phase might allow Read, Grep, and Glob; an implementation phase can add Edit and Write. A testing phase can allow Bash with an allowed_commands list for the checks you intend to run. The complete code-review example shows a definition with tool limits, transitions, a guard, and an approval gate. Start from that complete example rather than copying an isolated field into a new file.

Two defaults matter. If you omit allowed_tools from a state, Statewright applies no tool restriction in that state. If you merely write “do not edit” in a state's instructions, the instruction guides the model, but the tool list is what an enforcing integration uses to reject a disallowed edit. The schema reference documents both behaviors and the command restrictions available for shell phases.

Keep the test command list narrow enough that its output means something. “Run the tests” leaves the agent to choose which tests count. Naming the command and recording its result makes the validation step reviewable. A transition guard can check a reported value such as test_result, but that value comes from transition data. Look at the actual command output when the decision matters.

Try the boundary in a disposable project

Before applying a new workflow to a production repository, exercise it on a small local change. Install and connect a supported integration, then select the starter or a workflow you have reviewed. Ask the agent to explain a failing test while it is in the read-only phase. Check the state it reports and the tools it can use.

Next, ask it to make a tiny edit before advancing. In an integration that intercepts that edit path, the edit should be rejected. Advance through the declared event, make the small change in the implementation phase, run the named check in validation, and inspect the diff in review. This is a boundary test, not a benchmark of the model's coding quality. The Quick Start explains the starter's states and what to inspect in its handoff.

If a legitimate tool call is blocked, adjust the relevant phase or use the workflow's declared transition. Do not solve a phase mismatch by leaving every tool available throughout the run; that removes the boundary you were trying to test.

Know which controls your host enforces

A workflow definition is portable, but enforcement is not identical across clients. A managed integration can reject an unlisted tool on the paths it intercepts. A remote MCP connection alone does not control every native tool in a host, and Statewright does not replace the host's own permissions. Read the guide for the client you use, then test the exact tool path you care about. The Statewright docs describe this boundary on the overview and in the individual integration guides.

The review phase is a separate step in the process; it is not necessarily a separate reviewer. Validation evidence in the starter is still the agent's report. For an important change, compare that report with the diff and the command results yourself. Try the engineering starter on a disposable bug fix, then adjust one phase at a time based on what its handoff shows.