Interaction Timeout

Interaction Timeout

A user interaction request — approval prompt, auth response, password — that the user never answers. This flow shows the timeout path in both interactive and headless sessions.

---

Setup

• Interactive session: bundled TUI is attached; user is at a keyboard.
• A tool in ask mode requires per-call approval. The Interaction Protocol delivers an Approval request to the interactor.
• The user walks away. No input arrives.

A headless variant is covered below.

---

Sequence (interactive)

sequenceDiagram
    autonumber
    participant LLM as provider
    participant Core as message loop
    participant Mode as mode gate
    participant Inter as interactor (TUI)
    participant User

    LLM-->>Core: ToolInvocationProposed
    Core->>Mode: mode=ask — needs approval
    Mode->>Inter: Interaction.Approval<br/>request_id R, timeoutMs T
    Inter->>User: render prompt
    Note over User: no response...
    Inter-->>Core: timeout elapsed
    Core->>Core: audit InteractionTimedOut
    Core->>Mode: timeout → deny-by-default
    Mode-->>LLM: "follow-up turn<br/>tool-result: ToolCallDenied<br/>{ decider: modeGate, reason: timeout }"
    LLM-->>Core: LLM may repropose or stop

Loading

---

Timeout values

Kind of request	Default timeout	Rationale
Approval (tool call)	120s	User attention may drift; do not hang a session indefinitely.
Auth.Password	120s	Same. Password flows include visible instructions.
Auth.DeviceCode	Provider-declared; typically 300-600s per device-code RFC.	Device-code flows have their own timing.
Confirm (destructive action)	60s	Shorter — destructive flows are fresh-attention moments.

These are defaults. A request may declare a shorter or longer timeoutMs within the declared ceiling. Requests must declare a finite timeout; a request with no timeout is a validation error — see Interaction Protocol § Timeouts.

---

Deny-by-default

On timeout, the mode gate treats the interaction as a deny. This is the safe default:

• Approval request timeout → tool call denied.
• Destructive-confirm timeout → destructive action blocked.
• Auth.Password timeout → provider auth fails; session does not gain the credential.

"Approve on timeout" is not configurable in v1. The risk of a silent approval is higher than the annoyance of a re-prompt.

---

Headless sessions

A headless session has no interactor by contract. An interaction request that arrives in a headless session is handled per Headless and Interactor:

flowchart LR
    Req[interaction request] -->|headless session| Mode{non-interactive<br/>default available?}
    Mode -->|yes| Default[use the declared default]
    Mode -->|no| Fail[session fails<br/>exit code 4]

Loading

A request that declares a non-interactive default (e.g., "deny by default", "use this env var") follows it. A request that has no default fails the session with exit code 4. This happens immediately — there is no timeout to elapse.

---

Retry from the LLM side

After a timeout-deny, the LLM's next turn sees a typed tool-result:

Field	Value
status	denied.
decider	modeGate.
reason	timeout.

The LLM may repropose. Reproposing the same call runs the same approval flow; the user still absent still times out. A well-behaved LLM either stops proposing or explains the situation to the user.

---

Audit

Event	When
InteractionRequested	Request delivered to interactor.
InteractionAnswered	User responded.
InteractionTimedOut	Timeout elapsed without a response.
ToolCallDenied (reason: timeout)	Downstream of an approval timeout.

Timeouts are visible in the trail; a silent "user never responded" is not.

---

Related pages

• Interaction Protocol
• Security Modes
• Headless and Interactor
• Approval and Auth
• Audit Trail
• Platform Integration § Exit codes