The part of agent harness scaffolding that earns its keep when a tool stalls

Three timeout tiers, one classifier

The harness picks a wall-clock budget per tool call. There are three tiers and the rule for which tier applies is six lines long. The values come from real production: 10 seconds is the longest an internal lookup ever legitimately takes; 2 minutes is the upper bound on a Playwright navigation against a slow site; 5 minutes is the longest a model-issued Bash command should run before something is wrong.

The classifier is a single function that tests one boolean and one string prefix. It runs once at the moment the timer is created. The values can be globally overridden by setting the environment variableFAZM_TOOL_TIMEOUT_SECONDSbefore the bridge starts; the Settings page surfaces this as Tool Timeout.

What happens when the timer fires

The hard problem is that the harness cannot kill the work. The MCP subprocess holds the actual tool implementation. Maybe Playwright is stuck on a page that never fired DOMContentLoaded. Maybe the macOS accessibility tree is locked because the system showed a security prompt. The harness does not own those failures. It owns one thing: the chat UI is frozen because the tool call is still pending, and the model is waiting for a result it will never receive.

The recovery is a four-step synthesis. The harness pretends a tool result arrived. It removes the tool from the pending-tools list so the loop's bookkeeping matches reality. It emits atool_activityevent with status completed so the spinner stops. It emits atool_result_displaywhose body is a literal text result the model can read on its next turn ("Tool X timed out after Ns"), and which embeds the deep linkfazm://settings/tool-timeoutsso the user can click straight into the override. And it logs the string "Tool completed" with a TIMEOUT body to stderr, because the Swift host process counts running tools by tailing those log lines and decrementing on every "Tool completed". Without the log line, the Swift counter never reaches zero, and the host's own bookkeeping drifts.

The four steps are deliberate. The first three serve the chat. The fourth serves the host. None of them is the "right" thing in the sense that the work actually completed. They are the right thing in the sense that everyone above the harness can now make a decision.

The synthesized event, drawn out

From the model's perspective the message flow looks identical to a tool that took a long time and then returned a short text body. From the user's perspective the chat thread shows one greyed-out tool call and a paragraph of explanation. From the host's perspective the running-tools counter goes from one to zero. All three are reading the same four messages.

The MCP tool is still running on the right side of that diagram. The harness does not draw the line that kills it. That line never gets drawn. The subprocess is allowed to finish whenever the OS lets it finish; if its eventual reply does arrive, the harness sees a tool_call_update for a toolCallId no longer inactiveToolTimers, and silently ignores it.

The literal code

The above prose corresponds to onesetTimeoutcallback. It is reproduced below verbatim, with comments added for readability. Variable names match the source.

The function this lives in is calledstartToolTimer. Its only job is to register the callback and stash a reference inactiveToolTimersso a real completion can cancel it before it fires. There is a companionclearAllToolTimersthat is called when the bridge unloads, and that is everything the watchdog is. Two functions, one Map, one setTimeout.

What a naive harness does, and why we don't

Most reference implementations of an agent loop you find online have no per-tool wall clock at all. They look like this: build the tool list, send the prompt, await the model's tool calls, await each tool, feed the results back, repeat. That is a fine teaching shape and a terrible production shape, because the third await is unbounded. One bad tool freezes the loop forever.

The naive shape is what most "build your own agent" tutorials end on. The watchdog shape is what survives the first week of running a harness against real users on real machines with real Wi-Fi.

The diagnostic dump on user interrupt

The watchdog handles wall-clock-style hangs. The other failure mode is the user pressing stop because the agent is doing the wrong thing, not because anything is technically wrong. The harness handles those too, but the visible artifact is different: a single log line per stuck tool, dumped at the moment the interrupt arrives.

The data structure is a second Map calledinFlightTools, keyed by toolCallId, with one entry per tool the bridge has seen start but not finish. Each entry holds the tool's title, kind, sessionId, sessionKey, startedAt timestamp, last status, and a JSON-stringified copy of the input the model passed in. When the user hits stop, the functionlogStuckToolsOnInterruptwalks the map and writes one line per still-running tool.

Concretely, the line looks like this: Tool STUCK on user interrupt (key=onboarding): Bash (id=t_42, kind=execute, session=onboarding, elapsed=18.4s, lastStatus=in_progress) [command=npm install --legacy-peer-deps, description=install deps]. ThesummarizeToolInputhelper truncates Bash commands to 300 characters and Edit old_strings to 80, so the log stays grep-friendly without leaking entire file contents into the user's machine logs.

The reason this exists is that "user pressed stop while a tool was mid-flight" is the most common single source of frustrating bug reports against an agent. Without the diagnostic line, the support conversation is "the agent froze when I pressed stop." With the diagnostic line, it is "the agent was 18.4 seconds into a Bash command that ran npm install --legacy-peer-deps when you stopped it," which is a different conversation.

Why these specific values

10 seconds for internal lookups is generous. ToolSearch and the other internal handlers are local, in-process, with no network dependency. If they take more than a few seconds, something in the harness is wrong, not slow. 10 seconds is a sanity check, not a budget.

120 seconds for MCP tools is the tightest interesting number. It covers the long tail of legitimate browser navigations, the heavier macOS accessibility traversals on cold app launches, and the occasional Google Workspace API call against a slow OAuth flow. Anything past two minutes is almost always a hang, not slow work. The two-minute mark is also short enough that the user has not yet given up on the agent.

300 seconds (5 minutes) for everything else is mostly there to keep Bash commands from becoming infinite. Anything legitimately longer than 5 minutes is something the user explicitly asked for (a long build, a deep research script, a video render) and they should either setFAZM_TOOL_TIMEOUT_SECONDSglobally or break the work into smaller steps. Five minutes is the wall the model has to learn to live within.

All three are user-overridable through the same env var and the same settings panel. There is no per-tool override; the design choice there was that a per-tool table grows complexity faster than it adds value, and a single global override covers every observed case.

What this means for anyone scaffolding their own

The list is short. If you are building a harness from scratch, the failure-recovery layer is the part you will be tempted to skip first and regret first. Three things are worth taking from this file as a starting template, regardless of which agent SDK and which transport you are on:

1. Have a tier system, not one global timeout. The shape that holds up is something close to internal vs MCP vs everything-else. The exact numbers can be tuned. The tiering is what makes the system feel responsive instead of either trigger-happy or sluggish.
2. Synthesize a completion, do not try to kill the worker. You usually cannot. Pretending the tool returned a short text body keeps the loop alive and lets the model decide what to do, which is almost always smarter than what the harness would have decided.
3. Embed a deep link into the failure message. The user is staring at the chat. The setting they need to change is two clicks away. A literal URL the chat UI can render as a button is the cheapest way to bridge the gap between "I see the error" and "I changed the timeout."

None of this is novel research. It is an inventory of the small decisions that, in aggregate, are the difference between an agent harness people complain about and one they keep open during the workday. The whole watchdog and diagnostic layer in Fazm's bridge is somewhere around 200 lines. That is a small piece of the file that does the largest amount of work in keeping the product usable.