Tool Timeout Tiers
Centralized timeout configuration for all agent tools. Added as assistant/tooltimeouts.go; overhauled July 23, 2026.
Purpose
Every tool an agent can invoke has a maximum execution time. Without per-tool tuning, tools either time out prematurely (causing phantom failures) or hang forever (blocking sessions). This system provides tiered defaults plus explicit per-tool overrides.
Architecture
Tier System
| Tier | Default Duration | Use Case |
|---|---|---|
Fast |
5 seconds | Simple lookups, boolean checks |
Normal |
45 seconds | Typical tool execution |
Slow |
120 seconds | Heavy operations (Proxmox, CSF, Jira) |
Extended |
300 seconds | Full audits, long-running analysis |
Resolution Logic (GetTimeoutForTool)
- Exact match — tool name found directly in
DefaultToolTimeoutsmap - Wildcard prefix — entries ending in
*match tool name prefixes (e.g.,proxmox_*matchesproxmox_list_containers) - Tier fallback — unmatched tools fall through to the tier-based default
Notable Per-Tool Overrides
| Tool | Timeout | Rationale |
|---|---|---|
shell_execution |
90s | Was 10s — too tight for apt/build/download workloads |
remote_ssh_execution |
360s | Dial-retry chain: 6 attempts × 15s dial + backoff sleeps (~320s worst case) |
call_agent |
25 min | Must exceed internal dynamic delegation timeout (20m at depth 1) |
execute_playbook |
15 min | Full playbook sessions |
plan |
10 min | Plan generation for complex tasks |
distill_memory |
5 min | Memory distillation passes |
memory_reflection |
5 min | Memory reflection passes |
file_exists |
3s | Pure filesystem check |
finish_task |
5s | Task completion signal |
Historical Bug (July 23, 2026)
The old remote_ssh entry was a dead map key — GetTimeoutForTool does exact-key or *-suffix prefix matching, and bare "remote_ssh" never matched the actual tool name "remote_ssh_execution". This meant remote_ssh_execution fell through to the generic 45s Normal tier, which was far below the dial-retry chain's ~320s worst case. Fixed by adding explicit "remote_ssh_execution": 360s entry and removing the dead key.
Key Files
| File | Purpose |
|---|---|
assistant/tooltimeouts.go |
Tier definitions, per-tool overrides, GetTimeoutForTool() |
Cross-References
- Features/assistant/tool-execution.md — Tool execution pipeline
- Features/assistant/circuit-breaker-and-resilience.md — Related resilience patterns