codex-async-wait-rules AGENTS.md

Async waits (long-running work)

Scope note: this section overrides the general preference for short waits. It applies only to tools that (a) return as soon as the underlying work finishes and (b) can be cut short by user input. Under those two conditions a long yield has no downside — finishing early is the normal case, not the exception.

1. Status-check write_stdin calls (empty payload) Floor: 180000 ms. Use 300000 ms unless you specifically need to read partial output as it streams.

2. functions.wait Floor: 180000 ms. Same reasoning as above.

3. functions.exec wrapping any of the above The outer cell's yield must exceed the largest inner wait by 30000 ms or more. Getting this wrong makes the inner floors pointless — the wrapper times out first and the whole nesting yields early anyway.

4. Backing off Two polls in a row with nothing new means the task is slow, not stuck. Move to 300000 ms and stay there until output actually appears.

5. After an early return An early return is not a cue to poll again. Re-enter the wait only if what came back demands a decision. "Still working" is not a reason to surface anything to the model.

6. Out of scope Interactive write_stdin calls — anything carrying real input — keep their normal short timeouts. Latency matters there.