docs: align guard spec with lifecycle states

docs/specification.md

@@ -309,6 +309,11 @@ The following standards are integrated into the architecture:
 <span style="color: cyan; font-weight: 600;">agents</span> resource type list [<span style="color: #66cc66;">&lt;REGEX&gt;</span>]
 <span style="color: cyan; font-weight: 600;">agents</span> resource type show <span style="color: #66cc66;">&lt;NAME&gt;</span>
 
+<span style="color: cyan; font-weight: 600;">agents</span> provider add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;">&lt;FILE&gt;</span> [<span style="color: cyan;">--update</span>]
+<span style="color: cyan; font-weight: 600;">agents</span> provider remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;">&lt;NAME&gt;</span>
+<span style="color: cyan; font-weight: 600;">agents</span> provider list [<span style="color: cyan;">--all</span>] [<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span> <span style="color: #66cc66;">&lt;NS&gt;</span>]
+<span style="color: cyan; font-weight: 600;">agents</span> provider show <span style="color: #66cc66;">&lt;NAME&gt;</span>
+
 <span style="color: cyan; font-weight: 600;">agents</span> resource add [(<span style="color: magenta;"><span style="color: cyan;">--description</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;">&lt;DESC&gt;</span>] [<span style="color: cyan;">--update</span>] <span style="color: #66cc66;">&lt;TYPE&gt;</span> <span style="color: #66cc66;">&lt;NAME&gt;</span> [type-specific-flags...]
 <span style="color: cyan; font-weight: 600;">agents</span> resource remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;">&lt;NAME&gt;</span>
 <span style="color: cyan; font-weight: 600;">agents</span> resource list [<span style="color: cyan;">--all</span>] [(<span style="color: magenta;"><span style="color: cyan;">--type</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;">&lt;TYPE&gt;</span>]
@@ -10562,6 +10567,72 @@ Show detailed information about a resource type, including its full schema.
       - "Resource type details loaded"
     ```
 
+#### agents provider
+
+**Purpose**
+Manage LLM provider registrations. Providers encapsulate LLM SDK integrations and are referenced by actors via the `provider/model` notation. Commands in this group operate on provider definitions stored in YAML configuration files or discovered via entry points.
+
+##### agents provider add
+
+<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> provider add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;">&lt;FILE&gt;</span> [<span style="color: cyan;">--update</span>]</code></pre></div>
+
+**Purpose**
+Register or update a provider definition. The provider becomes available immediately for actor references (e.g., `local/my-provider/my-model`).
+
+**Arguments**
+
+- `--config/-c FILE`: Path to the provider YAML file (required). The file must declare the provider's `name`, implementation module/class, and any required environment variables.
+- `--update`: If the provider already exists, replace the registration in place. Without this flag, attempting to register an existing provider fails.
+
+**Examples**
+
+=== "Rich"
+
+    <div class="highlight"><pre><code>
+    <span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> provider add <span style="color: cyan;">--config</span> providers/my-custom-provider.yaml
+
+    ╭─ Provider Registered ─────────────────────────────╮
+    │ <span style="color: cyan; font-weight: 600;">Name:</span> local/my-llm-provider                    │
+    │ <span style="color: #5599ff; font-weight: 600;">Module:</span> my_package.providers.my_llm         │
+    │ <span style="color: #5599ff; font-weight: 600;">Class:</span> MyLLMProvider                        │
+    │ <span style="color: #66cc66; font-weight: 600;">Models:</span> my-model-v1, my-model-v2            │
+    ╰────────────────────────────────────────────────────╯
+
+    <span style="color: #66cc66; font-weight: 600;">✓ OK</span> Provider local/my-llm-provider registered
+    </code></pre></div>
+
+=== "Plain"
+
+    ```
+    $ agents provider add --config providers/my-custom-provider.yaml
+
+    Provider Registered
+      Name: local/my-llm-provider
+      Module: my_package.providers.my_llm
+      Class: MyLLMProvider
+      Models: my-model-v1, my-model-v2
+
+    [OK] Provider local/my-llm-provider registered
+    ```
+
+##### agents provider list
+
+<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> provider list [<span style="color: cyan;">--all</span>] [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;">&lt;NS&gt;</span>]</code></pre></div>
+
+List registered providers. By default only user-defined providers are shown; pass `--all` to include built-ins. `--namespace` filters by namespace prefix.
+
+##### agents provider show
+
+<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> provider show <span style="color: #66cc66;">&lt;NAME&gt;</span></code></pre></div>
+
+Display the full provider definition, including environment requirements and supported models.
+
+##### agents provider remove
+
+<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> provider remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;">&lt;NAME&gt;</span></code></pre></div>
+
+Remove a provider registration. Built-in providers cannot be removed.
+
 #### agents resource
 
 !!! info "Purpose"
@@ -18561,6 +18632,8 @@ A plan's ==phase== indicates "what step of the lifecycle it is in." Separately,
     | :---- | :-------: | :---------- |
     | `queued` | No | Waiting for compute/worker |
     | `processing` | No | Currently running |
+    | `awaiting_approval` | No | Paused pending human approval due to guard budget caps or automation profile thresholds |
+    | `blocked` | No | Guard violation or safety constraint prevented progress; requires user intervention or correction |
     | `errored` | Yes | Failed; includes error metadata |
     | `complete` | Yes | Finished successfully |
     | `cancelled` | Yes | User/system cancelled; safe terminal |
@@ -18571,11 +18644,15 @@ A plan's ==phase== indicates "what step of the lifecycle it is in." Separately,
     | :---- | :-------: | :---------- |
     | `queued` | No | Waiting for compute/worker |
     | `processing` | No | Currently running — diff review, conflict resolution, validation |
+    | `awaiting_merge_resolution` | No | Merge conflicts detected; waiting for user to resolve sandbox conflicts |
     | `errored` | Yes | Failed; includes error metadata |
     | `applied` | Yes | ==Changes successfully committed== to real resources |
     | `constrained` | Yes | Cannot complete within current strategy's constraints; may trigger reversion to Strategize |
     | `cancelled` | Yes | User/system cancelled; safe terminal |
 
+!!! note "Guard-driven states"
+    Plans enter `awaiting_approval` when budget-related guards pause execution and resume once the user approves additional budget. Plans enter `blocked` when a denylist or retry guard prevents a tool invocation; the user must cancel, correct, or adjust the automation profile before the plan can continue. During Apply, merge conflicts transition the plan to `awaiting_merge_resolution`; completing conflict resolution and re-running `agents plan apply` returns the plan to `processing`.
+
 #### Plan Identity and Traceability
 
 Every plan should have:
@@ -28823,10 +28900,12 @@ A `SafetyProfile` may also be attached directly to an `Action` (via the `safety_
 | `require_human_approval` | boolean | `false` | Require human approval before each action step | When `true`, every action step pauses for explicit human approval before execution. |
 | `allowed_skill_categories` | list[string] | `[]` (all) | Skill categories permitted for execution | When non-empty, only skills in the listed categories may be used. Empty list means all categories are allowed. |
 | `max_cost_per_plan` | float \| null | `null` | Maximum cost in USD per plan execution | When set, the plan is paused or terminated if the cost limit is reached. `null` means no limit. Must be <= `max_total_cost` when both are set. |
+| `max_tokens_per_plan` | int \| null | `null` | Maximum total LLM tokens per plan execution | When set, the plan pauses in `awaiting_approval` once the cumulative token usage would exceed the limit. |
+| `max_wall_clock_seconds` | int \| null | `null` | Maximum wall-clock time allowed for the plan | When set, exceeding the limit pauses the plan in `awaiting_approval` until the user approves extending the budget. |
 | `max_total_cost` | float \| null | `null` | Maximum total cost in USD across all plans | When set, execution is paused or terminated if the aggregate cost limit is reached. `null` means no limit. |
-| `max_retries_per_step` | integer | `3` | Maximum retry attempts per action step | Limits the number of retries for a single step before escalating to the user. Range: 0–100. |
+| `max_retries_per_step` | integer | `3` | Maximum retry attempts per tool invocation | Limits retries for a single tool before escalating to the user. Range: 0–100. |
 
-**Relationship to Automation Guards**: The `SafetyProfile.max_total_cost` field sets a **plan-level** budget cap (broad scope), while `AutomationGuard.max_total_cost` sets a **per-invocation** budget cap (narrow scope). These operate at different granularities and both may be active simultaneously — the tighter constraint takes precedence at any given point.
+**Relationship to Automation Guards**: The `SafetyProfile` budget fields (`max_cost_per_plan`, `max_tokens_per_plan`, `max_wall_clock_seconds`) set **plan-level** caps. The `AutomationGuard` sub-model can further constrain individual tool invocations (per-invocation cost caps, tool allowlists/denylists, retry limits). Both layers may be active simultaneously — the tightest constraint in effect takes precedence at any moment.
 
 #### Automation Guard Sub-Model
 
@@ -29283,8 +29362,8 @@ Guards are evaluated in strict priority order. The first guard that triggers cau
    - `max_tokens_per_plan` (tokens): Total tokens consumed would exceed the cap → same pause behavior.
    - `max_wall_clock_seconds` (seconds): Elapsed time since plan start would exceed the cap → plan paused.
 3. **Tool call limits** — Checked per-actor per-invocation:
-   - `max_tool_calls_per_actor`: Total tool calls by this actor in this plan would exceed the limit → actor invocation rejected.
-   - `max_retries_per_tool`: Retry count for this specific tool in this plan would exceed the limit → tool invocation rejected, plan enters `blocked` state.
+   - `max_tool_calls_per_step`: Total tool calls by this actor in this plan would exceed the limit → actor invocation rejected.
+   - `max_retries_per_step`: Retry count for this specific tool in this plan would exceed the limit → tool invocation rejected, plan enters `blocked` state.
 
 #### GuardEnforcer Component
 
@@ -29383,6 +29462,17 @@ class PlanEvent:
 The `A2aEventQueue` provides the publish/subscribe interface:
 
 ```python
+from dataclasses import dataclass
+from collections.abc import AsyncIterator
+
+@dataclass
+class SubscriptionHandle:
+    """Active subscription returned by `subscribe`."""
+
+    id: str
+    iterator: AsyncIterator[PlanEvent]
+
+
 class A2aEventQueue:
     """In-process async event queue for plan lifecycle events."""
 
@@ -29394,19 +29484,21 @@ class A2aEventQueue:
         self,
         event_types: list[str] | None = None,  # None = subscribe to all
         plan_id: str | None = None,             # None = all plans
-    ) -> AsyncIterator[PlanEvent]:
+    ) -> SubscriptionHandle:
         """
-        Subscribe to events. Returns an async iterator that yields events
-        matching the filter criteria. Caller must consume events promptly
-        to avoid backpressure.
+        Subscribe to events. Returns a SubscriptionHandle containing the
+        subscription ID and an async iterator that yields matching events.
+        Callers must consume events promptly to avoid backpressure.
         """
         ...
 
-    async def unsubscribe(self, subscription_id: str) -> None:
-        """Cancel a subscription."""
+    async def unsubscribe(self, subscription: SubscriptionHandle | str) -> None:
+        """Cancel a subscription by handle or subscription ID."""
         ...
 ```
 
+`SubscriptionHandle` allows callers to manage long-lived subscriptions safely. The handle's `iterator` yields events, while the `id` is used when calling `unsubscribe()` or when storing subscriptions for later cancellation.
+
 #### Local vs. Server Mode
 
 | Mode | Implementation | Persistence |
@@ -47240,7 +47332,7 @@ provider:
     - MY_LLM_BASE_URL
 ```
 
-Register with: `agents actor add --config providers/my-custom-provider.yaml`
+Register with: `agents provider add --config providers/my-custom-provider.yaml`
 
 ##### Actor YAML with Custom Provider