The investigation loop

The shape of a run

START -> fetch_failure -> investigate <-> tools -> diagnose -> END
            (no model)      (model)     (bounded)   (typed)

The workspace shows this as four phases. The first two both come from fetch_failure and are separated in the interface because they fail for different reasons and it is useful to know which one you are stuck in.

Why the first two phases have no model in them

Everything fetch_failure does is unconditional. There is no version of this problem where you do not want the failing step's log, and no judgement involved in fetching it. Putting a model in front of that decision would add latency, add cost, and add a way for the run to fail before it started. The agentic part begins where the certainty ends — which, in practice, is the question “is the log enough, or do I need to read the source?”

The tool budget

An investigation may make six tool calls. The bound is enforced twice, in two different ways, because they fail differently:

• A counter in graph state, checked before the model runs. When the budget is spent, the final call is made with no tools bound at all, so the model physically cannot request another one. Enforcing the limit in code rather than asking for it in the prompt is the difference between a cap and a wish.
• A graph recursion limit behind it, which catches a routing bug turning into an unbounded spend even if the counter logic is wrong.

Six is deliberately tight. The failure mode it prevents is not cost, it is drift: an agent with twenty calls available will keep looking, and each additional file it reads makes it more likely to build a story around something incidental. Most correct diagnoses in practice use zero, one or two.

How a run ends

An investigation leaves the loop in one of four ways:

1. The agent stops asking. It produces a message with no tool calls, which routes straight to diagnose. This is the normal path.
2. The budget runs out. The agent is told it has used all six calls and asked to conclude from what it has. The diagnosis still gets produced; its confidence is usually lower, and it should be.
3. An error. Anything from an expired log to a rate-limited provider. The stream emits one sentence you can act on, and the phase where it happened is marked failed in the trace. Partial progress is kept.
4. You stop it. The request is aborted. Nothing is saved to the server and the trace shows how far it got.

Why diagnosis is a separate call

Asking one model call both to reason freely and to emit strict JSON degrades both: the reasoning gets terse because it is thinking about schema, and the JSON gets malformed because it is thinking about the problem. Splitting them means the loop can think in prose and the final step is a pure, schema-validated transform over everything the loop produced.

This is why the diagnosis appears all at once rather than assembling itself line by line while you watch. The streaming text in the trace is the investigation; the result is written afterwards.

Reopening a run

Each investigation is checkpointed under a thread id. That id lets you reopen the complete record later, including the exact log window and diff summary the agent worked from. The record contains no key: the credential lives in the run configuration under a name the checkpointer refuses to persist, so there is nothing to filter out when the record is read back — which is the only kind of secret handling that survives a refactor.

To watch the loop with your own eyes rather than read about it, replay a recorded investigation.