[DOCS] Add Wait tool documentation

[inference-gateway-maintainer]

The Wait tool has been added to the CLI (PR inference-gateway/cli#792). This is a user-facing feature that adds a new tool the LLM can call to block until a condition is met instead of using sleep-and-poll loops that cost a full LLM round-trip per iteration.

Overview

The Wait tool blocks inside a single tool execution until a condition is met (shells exit, file event, or check command succeeds), then returns once with the outcome. Waiting costs zero chat completions.

Tool Definition

• Name: Wait
• Approval: No (passive utility tool - no side effects)
• Enabled by default: Yes (gated by tools.wait.enabled)
• Config:
  • tools.wait.max_timeout_seconds - Maximum timeout ceiling (default: 600)
  • tools.wait.command_poll_interval_ms - Poll interval for command condition (default: 2000)

Conditions

1. Shells (condition=shells)

Block until the given background shell ID(s) exit. When shell_ids is omitted, waits for all currently running background shells.

Parameters:

• shell_ids (optional, array of strings) - Specific shell IDs to wait for. Omit to wait for all pending background shells.

Returns: Exit codes and tail output (last 4096 bytes) for each shell.

Use cases:

• Wait for a long-running build or test to finish
• Wait for multiple parallel background tasks to complete
• Coordinate sequential steps that depend on background work

2. File (condition=file)

Block until a file path is created, modified, or removed (uses fsnotify for efficient inotify/FSEvents-based watching).

Parameters:

• path (required, string) - File path to watch.
• event (optional, string, enum: create, modify, remove, any) - File event to wait for. Default: any.

Behavior:

• For create: checks if the file already exists first (returns immediately if so)
• Watches the parent directory for the target filename
• Uses OS-native file system notifications (no polling)

Use cases:

• Wait for a download to complete
• Wait for a log file to be created
• Wait for a lock file to be removed
• Wait for a build artifact to appear

3. Command (condition=command)

Re-run a check command server-side at a fixed interval until it exits 0. The check command goes through the same bash allow-list as the Bash tool.

Parameters:

• command (required, string) - Check command to re-run until it exits 0.
• pending_exit_codes (optional, array of numbers) - Non-zero exit codes that mean "still pending, keep polling". Any other non-zero exit ends the wait immediately with reason check_failed.

Behavior:

• First run happens immediately (no initial delay)
• Subsequent runs at command_poll_interval_ms interval (default 2s)
• Each run has a 30-second per-execution timeout
• Not available on Windows (requires bash)

Exit code classification:

• Exit 0: condition_met - success
• Exit in pending_exit_codes: keep polling
• Exit non-zero (not in pending): check_failed - ends immediately
• No pending_exit_codes specified: keep polling on any non-zero exit

Use cases:

• Wait for a service to become healthy: curl -sf localhost:8080/health
• Wait for CI to complete: gh pr checks with pending_exit_codes=[8]
• Wait for a file to contain specific content: grep -q 'ready' /var/log/app.log
• Wait for a port to open: nc -z localhost 3000

Common Parameters

• timeout_seconds (required, number) - Maximum time to wait in seconds. Bounded by the config ceiling (tools.wait.max_timeout_seconds, default 600).

Return Value

Returns a structured result with:

• condition - The condition type
• reason - Outcome: condition_met, timeout, cancelled, check_failed, no_shells, error, not_allowed
• elapsed_seconds - Time spent waiting
• Condition-specific details (exit codes, last output, shell states) - included even on failure so the model can see why the wait ended

Cancellation

Pressing Esc in chat or session cancel interrupts the wait immediately (reason: cancelled).

Configuration

# .infer/config.yaml
tools:
  wait:
    enabled: true                          # Enable/disable the Wait tool
    max_timeout_seconds: 600               # Maximum allowed timeout (ceiling)
    command_poll_interval_ms: 2000         # Poll interval for command condition (ms)

Examples

Wait for background build to finish

Wait(condition=shells, shell_ids=["build-1"], timeout_seconds=300)

Wait for a file to be created

Wait(condition=file, path="/tmp/result.json", event="create", timeout_seconds=60)

Wait for service health

Wait(condition=command, command="curl -sf http://localhost:8080/health", timeout_seconds=120)

Wait for CI checks with pending exit codes

Wait(condition=command, command="gh pr checks 792 --repo inference-gateway/cli", pending_exit_codes=[8], timeout_seconds=600)

Wait for all background shells

Wait(condition=shells, timeout_seconds=300)

Affected docs pages

• tools-reference.md - Add Wait tool entry with full parameter documentation, conditions, and usage examples
• Any page listing available tools or describing the tool execution model

[edenreich]

@infer Can you work on this?

[inference-gateway-maintainer]

Model: ollama_cloud/deepseek-v4-flash · View Job

Todos

• Check for existing work on this issue (branches, PRs)
• Create working branch and add issue to project board
• Read tools-reference.md and understand current structure
• Add Wait tool documentation to cli.md
• Run validation checks (lint, format, build)
• Commit and push changes
• Create draft PR
• Set project status to QA

Pull Request

#371

✅ Infer Result: Success

Everything is in order - clean tree, no ahead commits, draft PR #371 is open on fix/issue-369 targeting main. No further action needed.

Model: ollama_cloud/deepseek-v4-flash · Exit Code: 0 · Duration: 8m 5s

Tokens: 7,064,657 in · 11,713 out · 7,076,370 total (46 requests)

Tool calls: 53 total · 91% success rate

⚠️ 5 failed tool call(s)

• Read: NOT_FOUND: /home/runner/work/docs/docs/tools-reference.md
• Bash: exit status 127: $ prettier --check .
  /usr/bin/bash: line 1: prettier: command not found
  error: script "format:check" exited with code 127
• Bash: exit status 1: $ markdownlint "**/*.md" --ignore node_modules --ignore .vitepress
  cli.md:821 error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Wait for a long-running buil..."]
  cli.md:833 error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Wait for a download to compl..."]
  cli.md:851 error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Wait for a service to become..."]
  error: script "lint:md" exited with code 1
• Bash: exit status 1: $ markdownlint "**/*.md" --ignore node_modules --ignore .vitepress
  cli.md:834 error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Wait for a download to compl..."]
  cli.md:852 error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Wait for a service to become..."]
  error: script "lint:md" exited with code 1
• Bash: exit status 1: $ prettier --check .
  Checking formatting...
  [�[33mwarn�[39m] cli.md
  [�[33mwarn�[39m] Code style issues found in the above file. Run Prettier with --write to fix.
  error: script "format:check" exited with code 1

Triggered by edenreich · Infer Action

[inference-gateway-releaser]

🎉 This issue has been resolved in version 0.9.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀