[FEATURE]: Sleep tool for agents to wait without holding a shell process #20486

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

Agents that need to wait between polling operations (e.g., waiting for a build to finish, rate-limiting API calls, pausing before retry) currently have no lightweight option. The only workaround is bash({ command: "sleep 5" }), which:

• Holds a full shell process for the duration
• Counts against the DangerFullAccess permission level — requiring full approval even for a trivial wait
• Conflates "I want to wait" with "I want to execute shell commands", confusing permission models
• Is blocked outright in explore and plan sub-agent scopes (see [FEATURE]: Sub-agent tool-set isolation by role (Explore / Plan / Verification scopes) #20483)

claw-code implements a dedicated Sleep tool that uses a native async timer, requiring no shell process and only ReadOnly permission.

Proposed solution

// packages/opencode/src/tool/sleep.ts

export const SleepTool = Tool.define({
  name: "Sleep",
  description: "Wait for a specified duration without holding a shell process. Use this for polling delays, rate limiting, or waiting between retries.",
  parameters: z.object({
    duration_ms: z.number().int().min(0).max(300_000) // max 5 minutes
  }),
  execute: async ({ duration_ms }) => {
    await new Promise(resolve => setTimeout(resolve, duration_ms))
    return {
      duration_ms,
      message: `Waited ${duration_ms}ms`
    }
  }
})

Why this matters

• Enables clean polling patterns without shell overhead: Sleep(2000) then bash({ command: "check-status" })
• Required permission is ReadOnly — eliminates the need for DangerFullAccess just to wait
• Available in restricted sub-agent scopes (explore, plan, verify) where bash is not allowed
• Cleaner intent signaling: the agent explicitly says "I am waiting" vs. "I am running a shell command"

Acceptance criteria

• Sleep tool requires ReadOnly permission only
• Maximum duration_ms is capped (suggested: 300,000ms / 5 minutes) to prevent agents from indefinitely stalling
• Tool is available in all sub-agent scopes including explore and plan
• The wait is non-blocking at the runtime level (does not hold a thread or process)
• Tool result returns actual elapsed time for agent observability

Related / cross-reference

• claw-code reference: https://github.com/instructkr/claw-code/tree/main/rust (Sleep tool)
• Sub-agent tool-set isolation (scope context): [FEATURE]: Sub-agent tool-set isolation by role (Explore / Plan / Verification scopes) #20483
• Background task result batching: [FEATURE]: Silent result collection for background tasks to avoid consuming LLM turns #20460
• Learnings from claude-code source: Lessons from claude-code-main? #20475