healthcloud-cli 3.7.2__tar.gz → 3.7.5__tar.gz

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.2
+Version: 3.7.5
 Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
 Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
 Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
@@ -576,11 +576,23 @@ raw JSON line. `--output json` prints the full envelope above, byte-identical to
 before. An unknown outcome still prints its one-line `error:` plus the
 reconciliation on stderr.
 
-Pre-checks refuse with exit 1 and **no write**: a missing `--confirm` (exit 2
-usage error, before login), an agent outside the explicit tenant, an already
-in-effect state, an unsupported `archived`/`draft` target (named as having no
-supported reversible transition here), or a `config_version` that no longer
-matches `--expected-config-version`. That version check is a local best-effort
+Without `--confirm` the command is a **preview**: it re-reads the agent exactly
+once (the same one bounded `GET`), runs the same local pre-checks, prints
+`preview: --confirm was not passed, so nothing has been sent.` and then the
+resolved change to stderr — the target (`agent_id`, `name`, `type`,
+`config_version`), `status` and `active` before -> after, and
+`one PUT /agents/{agent_id} with body keys: status, active` — and exits 2 having
+sent nothing. With `--confirm` the write path is unchanged: it re-reads before
+the single `PUT`, so a preview is never an approval token. The preview text is
+suppressed under `--output json`/`raw` (the same rule the confirmed path's
+review follows) so those modes keep stderr machine-parsable.
+
+Pre-checks refuse with exit 1 and **no write**: an agent outside the explicit
+tenant, an already in-effect state, an unsupported `archived`/`draft` target
+(named as having no supported reversible transition here), or a
+`config_version` that no longer matches `--expected-config-version` — all of
+these are also enforced by the preview, which still sends nothing. A missing
+`--confirm` exits 2. That version check is a local best-effort
 guard only: the route has no `If-Match` and the server never compares the
 version, so it cannot prove atomicity and a request could still race between
 the read and the PUT.
@@ -657,15 +669,23 @@ the server checks tenant scope only for the department, team, skill, policy and
 guardrail references. This command does not imply otherwise, and it does not
 re-implement the server's reference checks.
 
-Pre-checks refuse with exit 1 and **no write**: a missing `--confirm` (exit 2
-usage error, before login and before any request), no assignment option at all
+Without `--confirm` the command is a **preview**: it reads the agent exactly once
+(the same one bounded `GET`), computes the same reviewed diff and runs the same
+local pre-checks, prints `preview: --confirm was not passed, so nothing has been
+sent.` followed by the reviewed diff, and exits 2 having sent no `PUT`. With
+`--confirm` the write path is unchanged: it re-reads before the single `PUT`, so
+a preview is never an approval token. The preview text is suppressed under
+`--output json`/`raw`, like the confirmed path's review.
+
+Pre-checks refuse with exit 1 and **no write**: no assignment option at all
 (exit 2), setting and clearing the same family together (exit 2), an agent
 outside the explicit tenant, a request where every reference already equals the
 read state ("already in effect"), or a `config_version` that no longer matches
-`--expected-config-version`. That version check is a local best-effort guard
-only: the route has no `If-Match` and the server never compares the version, so
-it cannot prove atomicity and a request could still race between the read and
-the PUT. Operation-specific approval here is the CLI's own `--confirm` plus the
+`--expected-config-version` — all of these are also enforced by the preview,
+which still sends nothing. A missing `--confirm` exits 2. That version check is
+a local best-effort guard only: the route has no `If-Match` and the server never
+compares the version, so it cannot prove atomicity and a request could still
+race between the read and the PUT. Operation-specific approval here is the CLI's own `--confirm` plus the
 reviewed diff, deliberately separate from the tuning/plan-apply approval path;
 the server enforces tenant isolation, reference existence and the audit log, and
 it has **no** assignment approval or consent entity.
@@ -733,10 +753,17 @@ disclosure: `agent_id`, `deleted: true`, `target`, `disclosure`, `evidence`
 reviewed target and disclosure above are still printed to stderr in `pretty`
 mode only; `--output json`/`raw` keep stderr machine-parsable.
 
-Refusals claim nothing and send nothing extra: a missing `--confirm` is an exit
-2 usage error before login or any request; an agent outside the explicit tenant,
-the tenant identity mismatch and a delete target that no longer exists are
-refused before the `DELETE`; a `409` is a `conflict` refusal naming the referring
+Without `--confirm` the command is a **preview**: it reads the agent exactly once
+(the same one bounded `GET`), prints `preview: --confirm was not passed, so
+nothing has been sent.` plus the resolved destructive target and the whole
+disclosure block to stderr, and exits 2 having sent no `DELETE`. With `--confirm`
+the sequence above is unchanged: it re-reads before the single `DELETE`, so a
+preview is never an approval token. The preview text is suppressed under
+`--output json`/`raw`, like the confirmed path's review.
+
+Refusals claim nothing and send nothing extra: an agent outside the explicit
+tenant, the tenant identity mismatch and a delete target that no longer exists
+are refused before the `DELETE` (the preview reports the same `not_found`); a `409` is a `conflict` refusal naming the referring
 schedules; a `404` from the `DELETE` is `not_found`; and a `405` is the server's
 refusal (`unsupported`). None of them is retried.
 
@@ -770,25 +797,39 @@ and the result envelope carries the server's authoritative readback of the
 department (same bounded projection as reads):
 
 ```bash
-uv run --frozen hc ams departments create --environment dev --tenant-id TENANT_ID   --name "Clinical Operations" --created-by-user-id ADMIN_USER_ID   [--description TEXT] [--parent-department-id PARENT_ID] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
+uv run --frozen hc ams departments create --environment dev --tenant-id TENANT_ID   --name "Clinical Operations"   [--description TEXT] [--parent-department-id PARENT_ID] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
 uv run --frozen hc ams departments update --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID [--name NAME] [--description TEXT]   [--parent-department-id PARENT_ID] [--key KEY] [--required-eval-suite-ids SUITE_ID ...]
 uv run --frozen hc ams departments set-active --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID
 uv run --frozen hc ams departments deactivate --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID
-uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID
+uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID [--confirm]
 ```
 
 - `create` succeeds with `operation: "departments.create"` and
-  `data.department` = the server's 201 readback. `--name` and
-  `--created-by-user-id` are required by the server contract (the tenant is
-  taken from the saved session's authenticated admin, never from a flag).
+  `data.department` = the server's 201 readback. `--name` is required. There is
+  no creator flag: before the write the CLI reads the saved session's own
+  identity (`GET /admins/me`) and sends it as the server contract's
+  `created_by_user_id`, so a create can never be attributed to another admin
+  and the tenant is taken from that same authenticated admin. A failed identity
+  read is a bounded failure and the write is never sent — it is not reported as
+  an unknown outcome.
 - `update` sends only the options you pass (an empty `--description ""`
   clears it); it refuses with exit 1 (`validation`) when no field option is
   given. `set-active` and `deactivate` mark the department active/inactive.
-- `delete` succeeds with `data: {"deleted": true}` (the server answers 204
-  with no body) and is irreversible.
+- `delete --confirm` succeeds with `data: {"deleted": true}` (the server
+  answers 204 with no body) and is irreversible: the CLI keeps no restore.
+  Without `--confirm` the command is a **preview**: it reads the department
+  exactly once (one bounded `GET`), prints `preview: --confirm was not passed,
+  so nothing has been sent.` plus the resolved target and the disclosure block
+  to stderr, and exits 2 having sent no `DELETE`. With `--confirm` the confirmed
+  run makes the same single `GET` before its single `DELETE`, and the result
+  envelope is the same, so a preview is never an approval token. The preview
+  text is suppressed under `--output json`/`raw`, which keep stderr
+  machine-parsable (the exit-2 refusal message itself is plain text on stderr;
+  see #890).
 - A 404 for the requested department is a `not_found` refusal naming the ID
   (on `create`, a 404 names the referenced department — typically the missing
-  `--parent-department-id`); a target/tenant or identity mismatch is a
+  `--parent-department-id`; on `delete`, the reviewed read refuses identically
+  and nothing is sent); a target/tenant or identity mismatch is a
   `validation` refusal; both exit 1
   without changes. The one exception is a tenant mismatch on the `create`
   readback: the department has already been created server-side, so the CLI
@@ -822,7 +863,7 @@ projection as reads). Teams have no active/inactive lifecycle, so there are no
 
 ```bash
 uv run --frozen hc ams teams create --environment dev --tenant-id TENANT_ID   --name "Escalation Team" --department-id DEPARTMENT_ID   --created-by-user-id ADMIN_USER_ID [--description TEXT] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
-uv run --frozen hc ams teams update --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID [--name NAME] [--description TEXT] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
+uv run --frozen hc ams teams update --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID [--name NAME] [--description TEXT] [--key KEY]   [--required-eval-suite-ids SUITE_ID ... | --clear-required-eval-suite-ids]
 uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID
 ```
 
@@ -834,7 +875,8 @@ uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --
   clears it; `--clear-required-eval-suite-ids` sends an empty list to clear
   the required evaluation suites; `--key` accepts a nonblank key, it cannot be
   blanked); it refuses with exit 1 (`validation`) when no field option is
-  given.
+  given. `--required-eval-suite-ids` and `--clear-required-eval-suite-ids` are
+  alternatives: passing both is a usage error (exit 2) and nothing is sent.
 - `delete` succeeds with `data: {"deleted": true}` (the server answers 204
   with no body) and is irreversible. When AI agents still reference the team,
   the server refuses with 409 and the CLI reports one `conflict` refusal that
@@ -901,7 +943,8 @@ uv run --frozen hc ams skills delete --environment dev --tenant-id TENANT_ID --s
 - `update` sends only the options you pass (an empty `--description ""`
   clears it; `--clear-tool-ids` sends an explicit empty list to clear the
   skill's tool bindings); it refuses with exit 1 (`validation`) when no field
-  option is given.
+  option is given. `--tool-ids` and `--clear-tool-ids` are alternatives:
+  passing both is a usage error (exit 2) and nothing is sent.
 - `delete` succeeds with `data: {"deleted": true}` (the server answers 204
   with no body) and is irreversible. When AI agents still reference the skill
   (via their `skill_ids`), the server refuses with 409 and the CLI reports one
@@ -993,7 +1036,9 @@ uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID -
 - `update` sends only the options you pass (an empty `--description ""` or
   `--content ""` clears it; `--clear-guardrail-ids` sends an explicit empty
   list to clear the policy's guardrail bindings); it refuses with exit 1
-  (`validation`) when no field option is given.
+  (`validation`) when no field option is given. `--guardrail-ids` and
+  `--clear-guardrail-ids` are alternatives: passing both is a usage error
+  (exit 2) and nothing is sent.
 - `activate`/`deactivate` PUT `active: true|false` and succeed only when the
   readback confirms the requested flag.
 - `delete` succeeds with `data: {"deleted": true}` (the server answers 204

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.5}/README.md

@@ -558,11 +558,23 @@ raw JSON line. `--output json` prints the full envelope above, byte-identical to
 before. An unknown outcome still prints its one-line `error:` plus the
 reconciliation on stderr.
 
-Pre-checks refuse with exit 1 and **no write**: a missing `--confirm` (exit 2
-usage error, before login), an agent outside the explicit tenant, an already
-in-effect state, an unsupported `archived`/`draft` target (named as having no
-supported reversible transition here), or a `config_version` that no longer
-matches `--expected-config-version`. That version check is a local best-effort
+Without `--confirm` the command is a **preview**: it re-reads the agent exactly
+once (the same one bounded `GET`), runs the same local pre-checks, prints
+`preview: --confirm was not passed, so nothing has been sent.` and then the
+resolved change to stderr — the target (`agent_id`, `name`, `type`,
+`config_version`), `status` and `active` before -> after, and
+`one PUT /agents/{agent_id} with body keys: status, active` — and exits 2 having
+sent nothing. With `--confirm` the write path is unchanged: it re-reads before
+the single `PUT`, so a preview is never an approval token. The preview text is
+suppressed under `--output json`/`raw` (the same rule the confirmed path's
+review follows) so those modes keep stderr machine-parsable.
+
+Pre-checks refuse with exit 1 and **no write**: an agent outside the explicit
+tenant, an already in-effect state, an unsupported `archived`/`draft` target
+(named as having no supported reversible transition here), or a
+`config_version` that no longer matches `--expected-config-version` — all of
+these are also enforced by the preview, which still sends nothing. A missing
+`--confirm` exits 2. That version check is a local best-effort
 guard only: the route has no `If-Match` and the server never compares the
 version, so it cannot prove atomicity and a request could still race between
 the read and the PUT.
@@ -639,15 +651,23 @@ the server checks tenant scope only for the department, team, skill, policy and
 guardrail references. This command does not imply otherwise, and it does not
 re-implement the server's reference checks.
 
-Pre-checks refuse with exit 1 and **no write**: a missing `--confirm` (exit 2
-usage error, before login and before any request), no assignment option at all
+Without `--confirm` the command is a **preview**: it reads the agent exactly once
+(the same one bounded `GET`), computes the same reviewed diff and runs the same
+local pre-checks, prints `preview: --confirm was not passed, so nothing has been
+sent.` followed by the reviewed diff, and exits 2 having sent no `PUT`. With
+`--confirm` the write path is unchanged: it re-reads before the single `PUT`, so
+a preview is never an approval token. The preview text is suppressed under
+`--output json`/`raw`, like the confirmed path's review.
+
+Pre-checks refuse with exit 1 and **no write**: no assignment option at all
 (exit 2), setting and clearing the same family together (exit 2), an agent
 outside the explicit tenant, a request where every reference already equals the
 read state ("already in effect"), or a `config_version` that no longer matches
-`--expected-config-version`. That version check is a local best-effort guard
-only: the route has no `If-Match` and the server never compares the version, so
-it cannot prove atomicity and a request could still race between the read and
-the PUT. Operation-specific approval here is the CLI's own `--confirm` plus the
+`--expected-config-version` — all of these are also enforced by the preview,
+which still sends nothing. A missing `--confirm` exits 2. That version check is
+a local best-effort guard only: the route has no `If-Match` and the server never
+compares the version, so it cannot prove atomicity and a request could still
+race between the read and the PUT. Operation-specific approval here is the CLI's own `--confirm` plus the
 reviewed diff, deliberately separate from the tuning/plan-apply approval path;
 the server enforces tenant isolation, reference existence and the audit log, and
 it has **no** assignment approval or consent entity.
@@ -715,10 +735,17 @@ disclosure: `agent_id`, `deleted: true`, `target`, `disclosure`, `evidence`
 reviewed target and disclosure above are still printed to stderr in `pretty`
 mode only; `--output json`/`raw` keep stderr machine-parsable.
 
-Refusals claim nothing and send nothing extra: a missing `--confirm` is an exit
-2 usage error before login or any request; an agent outside the explicit tenant,
-the tenant identity mismatch and a delete target that no longer exists are
-refused before the `DELETE`; a `409` is a `conflict` refusal naming the referring
+Without `--confirm` the command is a **preview**: it reads the agent exactly once
+(the same one bounded `GET`), prints `preview: --confirm was not passed, so
+nothing has been sent.` plus the resolved destructive target and the whole
+disclosure block to stderr, and exits 2 having sent no `DELETE`. With `--confirm`
+the sequence above is unchanged: it re-reads before the single `DELETE`, so a
+preview is never an approval token. The preview text is suppressed under
+`--output json`/`raw`, like the confirmed path's review.
+
+Refusals claim nothing and send nothing extra: an agent outside the explicit
+tenant, the tenant identity mismatch and a delete target that no longer exists
+are refused before the `DELETE` (the preview reports the same `not_found`); a `409` is a `conflict` refusal naming the referring
 schedules; a `404` from the `DELETE` is `not_found`; and a `405` is the server's
 refusal (`unsupported`). None of them is retried.
 
@@ -752,25 +779,39 @@ and the result envelope carries the server's authoritative readback of the
 department (same bounded projection as reads):
 
 ```bash
-uv run --frozen hc ams departments create --environment dev --tenant-id TENANT_ID   --name "Clinical Operations" --created-by-user-id ADMIN_USER_ID   [--description TEXT] [--parent-department-id PARENT_ID] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
+uv run --frozen hc ams departments create --environment dev --tenant-id TENANT_ID   --name "Clinical Operations"   [--description TEXT] [--parent-department-id PARENT_ID] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
 uv run --frozen hc ams departments update --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID [--name NAME] [--description TEXT]   [--parent-department-id PARENT_ID] [--key KEY] [--required-eval-suite-ids SUITE_ID ...]
 uv run --frozen hc ams departments set-active --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID
 uv run --frozen hc ams departments deactivate --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID
-uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID
+uv run --frozen hc ams departments delete --environment dev --tenant-id TENANT_ID   --department-id DEPARTMENT_ID [--confirm]
 ```
 
 - `create` succeeds with `operation: "departments.create"` and
-  `data.department` = the server's 201 readback. `--name` and
-  `--created-by-user-id` are required by the server contract (the tenant is
-  taken from the saved session's authenticated admin, never from a flag).
+  `data.department` = the server's 201 readback. `--name` is required. There is
+  no creator flag: before the write the CLI reads the saved session's own
+  identity (`GET /admins/me`) and sends it as the server contract's
+  `created_by_user_id`, so a create can never be attributed to another admin
+  and the tenant is taken from that same authenticated admin. A failed identity
+  read is a bounded failure and the write is never sent — it is not reported as
+  an unknown outcome.
 - `update` sends only the options you pass (an empty `--description ""`
   clears it); it refuses with exit 1 (`validation`) when no field option is
   given. `set-active` and `deactivate` mark the department active/inactive.
-- `delete` succeeds with `data: {"deleted": true}` (the server answers 204
-  with no body) and is irreversible.
+- `delete --confirm` succeeds with `data: {"deleted": true}` (the server
+  answers 204 with no body) and is irreversible: the CLI keeps no restore.
+  Without `--confirm` the command is a **preview**: it reads the department
+  exactly once (one bounded `GET`), prints `preview: --confirm was not passed,
+  so nothing has been sent.` plus the resolved target and the disclosure block
+  to stderr, and exits 2 having sent no `DELETE`. With `--confirm` the confirmed
+  run makes the same single `GET` before its single `DELETE`, and the result
+  envelope is the same, so a preview is never an approval token. The preview
+  text is suppressed under `--output json`/`raw`, which keep stderr
+  machine-parsable (the exit-2 refusal message itself is plain text on stderr;
+  see #890).
 - A 404 for the requested department is a `not_found` refusal naming the ID
   (on `create`, a 404 names the referenced department — typically the missing
-  `--parent-department-id`); a target/tenant or identity mismatch is a
+  `--parent-department-id`; on `delete`, the reviewed read refuses identically
+  and nothing is sent); a target/tenant or identity mismatch is a
   `validation` refusal; both exit 1
   without changes. The one exception is a tenant mismatch on the `create`
   readback: the department has already been created server-side, so the CLI
@@ -804,7 +845,7 @@ projection as reads). Teams have no active/inactive lifecycle, so there are no
 
 ```bash
 uv run --frozen hc ams teams create --environment dev --tenant-id TENANT_ID   --name "Escalation Team" --department-id DEPARTMENT_ID   --created-by-user-id ADMIN_USER_ID [--description TEXT] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
-uv run --frozen hc ams teams update --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID [--name NAME] [--description TEXT] [--key KEY]   [--required-eval-suite-ids SUITE_ID ...]
+uv run --frozen hc ams teams update --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID [--name NAME] [--description TEXT] [--key KEY]   [--required-eval-suite-ids SUITE_ID ... | --clear-required-eval-suite-ids]
 uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --team-id TEAM_ID
 ```
 
@@ -816,7 +857,8 @@ uv run --frozen hc ams teams delete --environment dev --tenant-id TENANT_ID   --
   clears it; `--clear-required-eval-suite-ids` sends an empty list to clear
   the required evaluation suites; `--key` accepts a nonblank key, it cannot be
   blanked); it refuses with exit 1 (`validation`) when no field option is
-  given.
+  given. `--required-eval-suite-ids` and `--clear-required-eval-suite-ids` are
+  alternatives: passing both is a usage error (exit 2) and nothing is sent.
 - `delete` succeeds with `data: {"deleted": true}` (the server answers 204
   with no body) and is irreversible. When AI agents still reference the team,
   the server refuses with 409 and the CLI reports one `conflict` refusal that
@@ -883,7 +925,8 @@ uv run --frozen hc ams skills delete --environment dev --tenant-id TENANT_ID --s
 - `update` sends only the options you pass (an empty `--description ""`
   clears it; `--clear-tool-ids` sends an explicit empty list to clear the
   skill's tool bindings); it refuses with exit 1 (`validation`) when no field
-  option is given.
+  option is given. `--tool-ids` and `--clear-tool-ids` are alternatives:
+  passing both is a usage error (exit 2) and nothing is sent.
 - `delete` succeeds with `data: {"deleted": true}` (the server answers 204
   with no body) and is irreversible. When AI agents still reference the skill
   (via their `skill_ids`), the server refuses with 409 and the CLI reports one
@@ -975,7 +1018,9 @@ uv run --frozen hc ams policies delete --environment dev --tenant-id TENANT_ID -
 - `update` sends only the options you pass (an empty `--description ""` or
   `--content ""` clears it; `--clear-guardrail-ids` sends an explicit empty
   list to clear the policy's guardrail bindings); it refuses with exit 1
-  (`validation`) when no field option is given.
+  (`validation`) when no field option is given. `--guardrail-ids` and
+  `--clear-guardrail-ids` are alternatives: passing both is a usage error
+  (exit 2) and nothing is sent.
 - `activate`/`deactivate` PUT `active: true|false` and succeed only when the
   readback confirms the requested flag.
 - `delete` succeeds with `data: {"deleted": true}` (the server answers 204

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.5}/healthcloud_cli/ams/agents/commands.py

@@ -7,7 +7,7 @@ from pathlib import Path
 import click
 
 from ..context import AmsDependencies, pass_ams, preflight_agents
-from ..errors import run_domain
+from ..errors import run_domain, run_preview
 from ..session import resolve_tenant_target
 from .operations import (
     ASSIGNMENT_FAMILIES,
@@ -16,6 +16,9 @@ from .operations import (
     export_agent,
     get_agent,
     list_agents,
+    preview_assignments,
+    preview_delete,
+    preview_lifecycle,
     set_assignments,
     set_lifecycle,
 )
@@ -37,6 +40,34 @@ def _agent(function):
     return click.option("--agent-id", required=True)(function)
 
 
+def _preview_then_refuse(
+    invocation,
+    operation: str,
+    target_data: dict,
+    preview,
+    refusal: str,
+    *,
+    login_hint: str,
+) -> None:
+    """Read the target once, print the reviewed change, then refuse with exit 2.
+
+    Nothing is written before the refusal, and the preview is still a read: a
+    failed read (not logged in, wrong tenant, 404, transport) keeps the bounded
+    error envelope instead of escaping as a traceback. The confirmed run
+    re-reads before its single write, so a preview is never an approval token.
+    """
+
+    def read() -> None:
+        _require_login(login_hint)
+        target = resolve_tenant_target(target_data["environment"], target_data["tenant_id"])
+        target_data.update(environment=target.environment, tenant_id=target.tenant_id)
+        preflight_agents(invocation, target, methods=("get_agent",))
+        preview(target)
+
+    run_preview(operation, target_data, read)
+    raise click.UsageError(refusal)
+
+
 def _require_login(hint: str = LOGIN_HINT) -> None:
     """Agent writes need a saved `hc login` session, not env-var credentials."""
 
@@ -71,7 +102,8 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
         "--confirm",
         is_flag=True,
         default=False,
-        help="Required acknowledgement of the exact target and state; without it nothing is sent.",
+        help="Required acknowledgement of the exact target and state; without it the command reads the "
+        "target, prints the change and sends nothing.",
     )
     @pass_ams
     def command(
@@ -82,14 +114,27 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
         expected_config_version: int,
         confirm: bool,
     ) -> None:
-        if not confirm:
-            raise click.UsageError("--confirm is required; no lifecycle write was sent.")
         target_data = {
             "environment": environment,
             "tenant_id": tenant_id,
             "agent_id": agent_id,
             "expected_config_version": expected_config_version,
         }
+        if not confirm:
+            _preview_then_refuse(
+                invocation,
+                f"agents.{transition}",
+                target_data,
+                lambda target: preview_lifecycle(
+                    dependencies,
+                    target,
+                    agent_id,
+                    transition=transition,
+                    expected_config_version=expected_config_version,
+                ),
+                "--confirm is required; no lifecycle write was sent. Re-run with --confirm to send it.",
+                login_hint=LOGIN_HINT,
+            )
 
         def execute():
             _require_login()
@@ -123,13 +168,21 @@ def create_delete_command(dependencies: AmsDependencies) -> click.Command:
         "--confirm",
         is_flag=True,
         default=False,
-        help="Required acknowledgement of the printed target and disclosure block; without it nothing is sent.",
+        help="Required acknowledgement of the printed target and disclosure block; without it the command "
+        "prints both and sends nothing.",
     )
     @pass_ams
     def command(invocation, environment: str | None, tenant_id: str | None, agent_id: str, confirm: bool) -> None:
-        if not confirm:
-            raise click.UsageError("--confirm is required; no delete was sent.")
         target_data = {"environment": environment, "tenant_id": tenant_id, "agent_id": agent_id}
+        if not confirm:
+            _preview_then_refuse(
+                invocation,
+                "agents.delete",
+                target_data,
+                lambda target: preview_delete(dependencies, target, agent_id),
+                "--confirm is required; no delete was sent. Re-run with --confirm to send it.",
+                login_hint=DELETE_LOGIN_HINT,
+            )
 
         def execute():
             _require_login(DELETE_LOGIN_HINT)
@@ -221,7 +274,10 @@ CONFIG_VERSION_HELP = (
     "The config_version read before the write. A local best-effort guard only: the route has no "
     "If-Match, so it never proves atomicity."
 )
-CONFIRM_HELP = "Required acknowledgement of the target and the printed reviewed diff; without it nothing is sent."
+CONFIRM_HELP = (
+    "Required acknowledgement of the target and the printed reviewed diff; without it the command prints "
+    "the diff and sends nothing."
+)
 
 
 def _assignment_changes(values: dict, cleared: dict) -> dict:
@@ -320,8 +376,6 @@ def create_assignments_set_command(dependencies: AmsDependencies) -> click.Comma
         clear_data_source_ids: bool,
         confirm: bool,
     ) -> None:
-        if not confirm:
-            raise click.UsageError("--confirm is required; no assignment write was sent.")
         changes = _assignment_changes(
             {
                 "department_id": department_id,
@@ -351,6 +405,21 @@ def create_assignments_set_command(dependencies: AmsDependencies) -> click.Comma
             "expected_config_version": expected_config_version,
             "changed_fields": sorted(changes),
         }
+        if not confirm:
+            _preview_then_refuse(
+                invocation,
+                "agents.assignments.set",
+                target_data,
+                lambda target: preview_assignments(
+                    dependencies,
+                    target,
+                    agent_id,
+                    changes,
+                    expected_config_version=expected_config_version,
+                ),
+                "--confirm is required; no assignment write was sent. Re-run with --confirm to send it.",
+                login_hint=ASSIGNMENT_LOGIN_HINT,
+            )
 
         def execute():
             _require_login(ASSIGNMENT_LOGIN_HINT)