feat: add --wait for Instance and Tool lifecycle transitions

[jo-hnny]

Problem

Instance and tool lifecycle operations are asynchronous. Today, callers must build their own polling loops to wait for resources to leave transitional states, including handling polling intervals, timeouts, cancellation, final output, and terminal failures.

A generic condition language would add substantial CLI and schema complexity. The required use case is narrower: wait for an Instance or Tool lifecycle transition to settle.

Requested capability

Add a resource-aware --wait flag for Instance and Tool lifecycle commands.

Examples:

agr instance create --tool-id tool-xxxx --wait
agr instance resume ins-xxxx --wait
agr tool create --tool-name example --tool-type code-interpreter --wait

agr instance get ins-xxxx --wait
agr tool get tool-xxxx --wait

This is a modeled waiter, similar to AgentCore CLI's job --wait: it waits for a known resource to move from a transitional state into a terminal state. It does not accept arbitrary jq/JMESPath conditions.

Command scope

Support --wait on lifecycle mutations that resolve to one Instance or Tool:

• Instance: create, update, pause, resume, delete
• Tool: create, update, fork, delete

Also support --wait on:

• instance get <instance-id>
• tool get <tool-id>

Do not support --wait on list: terminal semantics for multiple resources would be ambiguous.

Behavior

Lifecycle mutations

1. Execute the mutation exactly once.
2. Resolve the affected resource ID from the request or response.
3. Poll the corresponding read API until the resource reaches a terminal state.
4. Return the normal final resource result.

The mutation must never be replayed while polling.

Get commands

• If the resource is transitional, poll until it becomes terminal.
• If the resource is already terminal, return immediately.
• get --wait observes an existing transition; it does not wait for a future transition that has not become visible yet.
• NotFound remains an error for get --wait.

Delete commands

• Instance deletion waits for the Instance's terminal stopped state.
• Tool deletion treats NotFound as successful completion after the delete request has been accepted.

State model

Maintain explicit state classifications per resource.

Current known states:

Resource	Transitional	Terminal
Instance	STARTING, STOPPING, and other confirmed service transitional states	RUNNING, PAUSED, STOPPED, STOP_FAILED, FAILED
Tool	CREATING, DELETING	ACTIVE, FAILED

Unknown states must not be assumed terminal. Continue polling until a known terminal state or timeout, and include the last observed status in timeout diagnostics.

A successful terminal state returns normally. Failure terminal states such as FAILED and STOP_FAILED end the wait and return a structured non-zero CLI failure.

Polling policy

MVP exposes only --wait:

• Poll interval: 5 seconds
• Overall wait timeout: 10 minutes
• Respect context cancellation and process signals

Do not add a generic --timeout flag for the waiter because instance create --timeout already controls Instance lifetime. Waiter timing can be made configurable later with unambiguous flag names if a real need emerges.

Output and discoverability

• Preserve the command's normal final output format.
• Keep stdout machine-readable; progress belongs on stderr.
• Timeout, cancellation, terminal failure, and polling failure must produce deterministic structured errors and exit codes.
• Timeout diagnostics should include the resource ID, attempts, elapsed time, and last observed status.
• Expose --wait support through command help and agr schema.

Prior art

• AgentCore CLI's run ... --wait and shared job terminal waiter:
  https://github.com/aws/agentcore-cli/blob/main/src/cli/operations/jobs/shared/wait.ts
• AWS SDK modeled waiters

Acceptance criteria

• Instance and Tool lifecycle mutations execute once and, with --wait, return only after the affected resource reaches a terminal state.
• instance get <id> --wait and tool get <id> --wait wait for an already visible transitional state and return immediately for a terminal state.
• list commands do not expose --wait.
• The implementation uses shared polling mechanics with resource-specific state classification.
• Default polling is bounded by a 10-minute timeout and supports cancellation.
• Failure terminal states, timeout, NotFound, and polling errors have deterministic structured output and exit codes.
• Text, JSON, jq-filtered JSON, help, schema metadata, unit tests, and lifecycle tests cover the wait behavior.