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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.2
+Version: 3.7.3
 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.
 

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.3}/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.
 

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.3}/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)

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.3}/healthcloud_cli/ams/agents/operations.py

@@ -136,6 +136,14 @@ def _lifecycle_target(target: TenantTarget, agent_id: str) -> dict:
     return _target(target, agent_id)
 
 
+def _lifecycle_write_pair(transition: str) -> tuple[str, bool]:
+    """The fixed status/active pair for one transition, or a local refusal."""
+
+    if transition not in LIFECYCLE_TRANSITIONS:
+        raise AgentWriteRefused("validation", "Unsupported lifecycle transition; nothing was sent.")
+    return LIFECYCLE_TRANSITIONS[transition]
+
+
 def _state(agent) -> dict:
     return {
         "status_field": agent.status,
@@ -325,9 +333,7 @@ def set_lifecycle(
     from healthcloud.errors import HealthCloudHTTPError, HealthCloudNetworkError
 
     agent_id = _agent_id(agent_id)
-    if transition not in LIFECYCLE_TRANSITIONS:
-        raise AgentWriteRefused("validation", "Unsupported lifecycle transition; nothing was sent.")
-    status, active = LIFECYCLE_TRANSITIONS[transition]
+    status, active = _lifecycle_write_pair(transition)
     operation = f"agents.{transition}"
     with dependencies.authenticated_sdk_factory(target) as sdk:
         before = _verified_agent(sdk, target, agent_id)
@@ -478,6 +484,16 @@ def _assignment_diff(before, changes: dict) -> dict:
     return changed
 
 
+def _echo_preview_notice() -> None:
+    """Say plainly that the review below is a preview and nothing has been sent."""
+
+    import click
+
+    if not _review_enabled():
+        return
+    click.echo("preview: --confirm was not passed, so nothing has been sent.", err=True)
+
+
 def _review_enabled() -> bool:
     """A reviewed write rendering is human: json/raw keep stderr machine-parsable."""
 
@@ -509,6 +525,39 @@ def _echo_assignment_review(agent_id: str, before, changed: dict) -> None:
     click.echo(f"one PUT /agents/{agent_id} with body keys: {', '.join(changed)}", err=True)
 
 
+def _echo_lifecycle_review(agent, agent_id: str, transition: str, status: str, active: bool) -> None:
+    """Print the exact lifecycle change the confirmed run would send."""
+
+    import click
+
+    if not _review_enabled():
+        return
+    target = _delete_target(agent, agent_id)
+    click.echo(
+        f"{transition} agent '{agent_id}' would change (name {target['name']!r}, type {target['type']!r}, "
+        f"config_version {target['config_version']}):",
+        err=True,
+    )
+    click.echo(f"  status: {getattr(agent, 'status', None)!r} -> {status!r}", err=True)
+    click.echo(f"  active: {getattr(agent, 'active', None)!r} -> {active!r}", err=True)
+    click.echo(f"one PUT /agents/{agent_id} with body keys: status, active", err=True)
+
+
+def _assignment_plan(sdk, target: TenantTarget, agent_id: str, changes: dict, expected_config_version: int):
+    """One verified read, the reviewed diff, and the local version guard."""
+
+    before = _verified_agent(sdk, target, agent_id)
+    changed = _assignment_diff(before, changes)
+    if not changed:
+        raise AgentWriteRefused(
+            "validation",
+            f"No assignment option changes agent '{agent_id}'; every requested reference already equals "
+            "the read state and no write was sent.",
+        )
+    _assignment_precheck(before, agent_id, expected_config_version, changed)
+    return before, changed
+
+
 def _assignment_precheck(before, agent_id: str, expected_config_version: int, changed: dict) -> None:
     if before.config_version != expected_config_version:
         raise AgentWriteRefused(
@@ -642,15 +691,7 @@ def set_assignments(
     except ValueError as error:
         raise AgentWriteRefused("validation", f"{error}; nothing was sent.") from None
     with dependencies.authenticated_sdk_factory(target) as sdk:
-        before = _verified_agent(sdk, target, agent_id)
-        changed = _assignment_diff(before, changes)
-        if not changed:
-            raise AgentWriteRefused(
-                "validation",
-                f"No assignment option changes agent '{agent_id}'; every requested reference already equals "
-                "the read state and no write was sent.",
-            )
-        _assignment_precheck(before, agent_id, expected_config_version, changed)
+        before, changed = _assignment_plan(sdk, target, agent_id, changes, expected_config_version)
         _echo_assignment_review(agent_id, before, changed)
         body = {field: entry["after"] for field, entry in changed.items()}
         try:
@@ -775,6 +816,22 @@ _DELETE_RUNTIME_UNVERIFIED = (
 )
 
 
+def _delete_review_target(sdk, target: TenantTarget, agent_id: str):
+    """The one bounded read a delete reviews: a 404 is its own refusal."""
+
+    from healthcloud.errors import HealthCloudHTTPError
+
+    try:
+        return _verified_agent(sdk, target, agent_id)
+    except HealthCloudHTTPError as error:
+        if getattr(error, "status_code", 0) == 404:
+            raise AgentWriteRefused(
+                "not_found",
+                f"Agent '{agent_id}' was not found in this tenant; nothing was sent.",
+            ) from None
+        raise
+
+
 def _delete_target(agent, agent_id: str) -> dict:
     """The exact record the operator is approving: ids and bounded fields only."""
 
@@ -788,8 +845,12 @@ def _delete_target(agent, agent_id: str) -> dict:
     }
 
 
-def _echo_delete_review(agent, agent_id: str) -> None:
-    """Print the destructive target and the disclosure before the single DELETE."""
+def _echo_delete_review(agent, agent_id: str, *, preview: bool = False) -> None:
+    """Print the destructive target and the disclosure before the single DELETE.
+
+    ``preview`` is the unconfirmed half: it prints the same target and the same
+    disclosure, worded as what the confirmed run would do.
+    """
 
     import click
 
@@ -797,7 +858,8 @@ def _echo_delete_review(agent, agent_id: str) -> None:
         return
     target = _delete_target(agent, agent_id)
     click.echo(
-        f"deleting agent '{agent_id}' (name {target['name']!r}, type {target['type']!r}, "
+        f"{'would delete' if preview else 'deleting'} agent '{agent_id}' "
+        f"(name {target['name']!r}, type {target['type']!r}, "
         f"status {target['status']!r}, active {target['active']}, "
         f"config_version {target['config_version']}):",
         err=True,
@@ -929,15 +991,7 @@ def delete_agent(dependencies: AmsDependencies, target: TenantTarget, agent_id:
 
     agent_id = _agent_id(agent_id)
     with dependencies.authenticated_sdk_factory(target) as sdk:
-        try:
-            before = _verified_agent(sdk, target, agent_id)
-        except HealthCloudHTTPError as error:
-            if getattr(error, "status_code", 0) == 404:
-                raise AgentWriteRefused(
-                    "not_found",
-                    f"Agent '{agent_id}' was not found in this tenant; nothing was sent.",
-                ) from None
-            raise
+        before = _delete_review_target(sdk, target, agent_id)
         _echo_delete_review(before, agent_id)
         try:
             sdk.ams_admin.delete_agent(agent_id)
@@ -1046,3 +1100,74 @@ def delete_agent(dependencies: AmsDependencies, target: TenantTarget, agent_id:
                 "before doing anything else."
             ),
         )
+
+
+# --- previews: read the target and print the change, send nothing -----------
+#
+# A write is reviewed before it is sent, and `--confirm` acknowledges that
+# review. Without `--confirm` the command therefore reads the same target and
+# prints the same reviewed change, then refuses with exit 2. A preview is a
+# read, so it performs exactly one GET and never a write, a preflight write or a
+# second read: the confirmed run re-reads before its single write, so a preview
+# is never an approval token and never a TOCTOU shortcut.
+
+
+def preview_lifecycle(
+    dependencies: AmsDependencies,
+    target: TenantTarget,
+    agent_id: str,
+    *,
+    transition: Literal["activate", "deactivate"],
+    expected_config_version: int,
+) -> None:
+    """Print the exact lifecycle change without sending it.
+
+    Same one bounded ``GET``, same local pre-checks and same projected target as
+    ``set_lifecycle``; the only differences are that nothing is written and the
+    reviewed change goes to stderr.
+    """
+
+    agent_id = _agent_id(agent_id)
+    status, active = _lifecycle_write_pair(transition)
+    with dependencies.authenticated_sdk_factory(target) as sdk:
+        before = _verified_agent(sdk, target, agent_id)
+        _lifecycle_precheck(before, agent_id, status, active, expected_config_version)
+        _echo_preview_notice()
+        _echo_lifecycle_review(before, agent_id, transition, status, active)
+
+
+def preview_assignments(
+    dependencies: AmsDependencies,
+    target: TenantTarget,
+    agent_id: str,
+    changes: dict,
+    *,
+    expected_config_version: int,
+) -> None:
+    """Print the reviewed assignment diff without sending it.
+
+    Same bounded body validation, one ``GET``, the same diff and local version
+    guard as ``set_assignments``; no PUT is sent.
+    """
+
+    from healthcloud.clients.ams_admin import prepare_assignment_update
+
+    agent_id = _agent_id(agent_id)
+    try:
+        changes = prepare_assignment_update(**changes)
+    except ValueError as error:
+        raise AgentWriteRefused("validation", f"{error}; nothing was sent.") from None
+    with dependencies.authenticated_sdk_factory(target) as sdk:
+        before, changed = _assignment_plan(sdk, target, agent_id, changes, expected_config_version)
+        _echo_preview_notice()
+        _echo_assignment_review(agent_id, before, changed)
+
+
+def preview_delete(dependencies: AmsDependencies, target: TenantTarget, agent_id: str) -> None:
+    """Print the delete target and its disclosure without sending the DELETE."""
+
+    agent_id = _agent_id(agent_id)
+    with dependencies.authenticated_sdk_factory(target) as sdk:
+        before = _delete_review_target(sdk, target, agent_id)
+        _echo_preview_notice()
+        _echo_delete_review(before, agent_id, preview=True)

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.3}/healthcloud_cli/ams/errors.py

@@ -135,6 +135,25 @@ def emit_compact_json(value: dict, *, err: bool = False) -> None:
     click.echo(json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True), err=err)
 
 
+def run_preview(operation: str, target: dict, callback: Callable[[], Any]) -> None:
+    """Run the read half of an unconfirmed write, printing no success envelope.
+
+    A preview is a read: a failure (not logged in, wrong tenant, 404, transport,
+    SDK missing) renders the same bounded error envelope as any other read and
+    exits nonzero, so nothing escapes as a traceback. On success the caller has
+    already printed the reviewed target to stderr, so this renders nothing: the
+    adapter then refuses with exit 2 and a message saying nothing was sent.
+    """
+
+    mode = output_mode()
+    try:
+        callback()
+    except KeyboardInterrupt as error:
+        _bounded_failure(operation, target, error, mode, read_only=True)
+    except Exception as error:
+        _bounded_failure(operation, target, error, mode, read_only=True)
+
+
 def _render_success(envelope: dict, mode: str) -> None:
     if mode != "json":
         click.echo(success_text(envelope))
@@ -169,6 +188,32 @@ def _error_message(operation: str, category: str, target: dict, error: Exception
     return _message(operation, category, target)
 
 
+def _bounded_failure(operation: str, target: dict, error: BaseException, mode: str, *, read_only: bool) -> None:
+    """Classify ``error``, render the error envelope, and exit bounded."""
+
+    # ``error`` may be a KeyboardInterrupt (BaseException): classification
+    # maps it to transport/130 and the bounded envelope, never a traceback.
+
+    category, exit_code = _classification(operation, error)
+    # An unknown mutation outcome carries its own reconciliation envelope:
+    # the write may have committed, so it renders as ``unknown`` (never a
+    # plain failure and never success) and still exits nonzero.
+    envelope = getattr(error, "envelope", None)
+    _render_failure(
+        envelope
+        if isinstance(envelope, dict)
+        else failed(
+            operation,
+            target,
+            category,
+            _error_message(operation, category, target, error),
+            read_only=read_only,
+        ),
+        mode,
+    )
+    raise SystemExit(exit_code) from None
+
+
 def run_domain(operation: str, target: dict, callback: Callable[[], Any], *, read_only: bool = True) -> None:
     """Run one AMS operation and render its envelope in the active output mode.
 
@@ -180,29 +225,7 @@ def run_domain(operation: str, target: dict, callback: Callable[[], Any], *, rea
     mode = output_mode()
 
     def _fail(error: BaseException) -> None:
-        """Classify ``error``, render the error envelope, and exit bounded."""
-
-        # ``error`` may be a KeyboardInterrupt (BaseException): classification
-        # maps it to transport/130 and the bounded envelope, never a traceback.
-
-        category, exit_code = _classification(operation, error)
-        # An unknown mutation outcome carries its own reconciliation envelope:
-        # the write may have committed, so it renders as ``unknown`` (never a
-        # plain failure and never success) and still exits nonzero.
-        envelope = getattr(error, "envelope", None)
-        _render_failure(
-            envelope
-            if isinstance(envelope, dict)
-            else failed(
-                operation,
-                target,
-                category,
-                _error_message(operation, category, target, error),
-                read_only=read_only,
-            ),
-            mode,
-        )
-        raise SystemExit(exit_code) from None
+        _bounded_failure(operation, target, error, mode, read_only=read_only)
 
     try:
         envelope = callback()

{healthcloud_cli-3.7.2 → healthcloud_cli-3.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "healthcloud-cli"
-version = "3.7.2"
+version = "3.7.3"
 description = "Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest."
 readme = "README.md"
 requires-python = ">=3.14"