Ten minutes was not a timeout policy

2026-08-15

An agent asked ConnectOnion to let a shell command run for two hours. Ten minutes later, the command stopped. Worse, the tool reported the stop as an ordinary string result, so the agent believed the command had completed.

Both behaviours came from a small convenience that had outgrown its original context. The shell tools accepted a timeout argument but silently replaced every value above 600 seconds with 600. When subprocess raised its timeout exception, the tools caught it and returned text beginning with Error:. Humans could read that text as a failure; the tool executor could not. From its perspective the Python function returned normally, so the trace status was success.

Nested agents changed the scale

Ten minutes may sound generous for a command typed at a terminal. It is not generous for an agent that launches another agent. The child may inspect a repository, edit several files, run a test suite, and wait for a remote build. That work can legitimately exceed the old ceiling, and the parent already has the context needed to choose an appropriate bound.

The fix makes the public argument truthful: the default remains 120 seconds, but an explicit caller-supplied timeout now reaches subprocess.run unchanged. There is no hidden second policy inside the tool.

Failure needs structure

The shell tools also no longer consume TimeoutExpired. A direct Python caller can catch that exception normally. When the same function runs as an Agent tool, ConnectOnion's existing executor catches it at the orchestration boundary and records a tool result with status: error and error_type: TimeoutExpired. The model still receives a useful error message, while the trace, events, and clients can reliably tell that the command did not finish.

Tests cover both halves of the contract. A 7,200-second timeout must be passed through unchanged for bash, Shell.run, and Shell.run_in_dir; a simulated timeout must raise from the direct API and become an error in an Agent trace. No test needs to wait two hours to prove it.

The broader lesson is that limits are part of an API even when they are hidden. If a caller is allowed to request a value, silently substituting another value creates false confidence. And once a failure crosses a tool boundary, it must remain a failure—not merely look like one in a string.