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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.3
+Version: 3.7.6
 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
@@ -797,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
@@ -849,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
 ```
 
@@ -861,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
@@ -928,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
@@ -1020,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
@@ -1081,8 +1099,12 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   the envelope carries the server's authoritative readback:
   `operation: "sessions.create"` with `data.session`, and
   `operation: "sessions.messages.add"` with `data.message` (message ID, role,
-  mode, plan ID, model, timestamps) plus `data.idempotency_key` when a key was
-  supplied. Protected free text — `--initial-prompt` and `--content` — is sent to
+  mode, plan ID, model, timestamps) plus `data.idempotency_key` — the key the
+  server read back, when the returned message carries one. When the readback
+  does not echo a key, the field is omitted: the envelope never asserts a
+  key→message association the server did not confirm. An `--idempotency-key`
+  longer than 128 characters (or an empty one) is refused locally with a
+  `validation` error naming the flag, before anything is sent. Protected free text — `--initial-prompt` and `--content` — is sent to
   the server but never appears in the envelope, a refusal, a diagnostic or a log.
 - The protected free text can also arrive from an owner-only file, which keeps it
   out of the command line entirely (argv, the process table under
@@ -1113,16 +1135,18 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--mode implement` is not available from the server yet: `create` reports one
   `unsupported` refusal (the server answers 501) and creates nothing. A message
   whose `--mode` differs from its session's mode is refused by the server with
-  409 and reported as one write-worded `conflict` refusal that says a message's
-  mode must match its session's mode and points at `hc ams sessions get`; no
-  message is added, and the read-era conflict wording is never used.
+  409 and reported as one write-worded `conflict` refusal that names the
+  session, mentions a mode mismatch as one possible cause, and points at
+  `hc ams sessions get`; no message is added, and the read-era conflict wording
+  is never used.
 - A missing, expired or other user's session is a `not_found` refusal naming the
   session on `get`, `messages list` and `messages add`; on `create`, a 404 names
   the requested `--agent-id`.
 - Messages with an `--idempotency-key` are replay-safe: the server answers 201
   with the existing message instead of inserting a second one, and the command
   reports that message (its original ID) — a replay is never reported as a new
-  write, and the command itself never re-sends a write.
+  write, and the command itself never re-sends a write. The envelope echoes the
+  server's read-back key, never a key the server did not confirm.
 - If the transport times out or the connection drops mid-write, the write's
   outcome is unknown: the CLI reports one `transport` error whose message says so
   and points at `hc ams sessions list`/`hc ams sessions messages list` before
@@ -1131,8 +1155,10 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   landed write is never reported as stopped.
 - Reads refuse target files, root credentials or base URLs, raw output, blank or
   dot-segment session IDs, out-of-range limits, and installed SDKs without the
-  session list/get and message list/add methods before tenant-admin login or any
-  read. The existing `hc ams plan|show|apply|restore` tuning commands and their
+  session list/get and message list methods before tenant-admin login or any
+  read; `messages list` needs only `messages.list` — the write method `add` is
+  not required for the read, and `messages add` still refuses `unsupported`
+  without it. The existing `hc ams plan|show|apply|restore` tuning commands and their
   signatures are unchanged.
 - These session and message commands do not attach files, apply or roll back
   configuration, or send session history to a model. Plan review is its own
@@ -1223,6 +1249,9 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   message write, no `PUT` and no apply. The server runs the planner once. It
   requires a saved `hc login` session and reports
   `operation: "sessions.plans.generate"` with `data.plan` and `data.out`.
+  An `--idempotency-key` longer than 128 characters (or an empty one) is
+  refused locally with a `validation` error naming the flag, before anything
+  is sent.
   `get` sends exactly one `GET /vibecoder/plans/PLAN_ID` and reports
   `operation: "sessions.plans.get"`; a reload is immutable, so it returns the
   same `plan_hash` and diff however the session changed afterwards. `get` is a

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/README.md

@@ -779,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
@@ -831,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
 ```
 
@@ -843,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
@@ -910,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
@@ -1002,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
@@ -1063,8 +1081,12 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   the envelope carries the server's authoritative readback:
   `operation: "sessions.create"` with `data.session`, and
   `operation: "sessions.messages.add"` with `data.message` (message ID, role,
-  mode, plan ID, model, timestamps) plus `data.idempotency_key` when a key was
-  supplied. Protected free text — `--initial-prompt` and `--content` — is sent to
+  mode, plan ID, model, timestamps) plus `data.idempotency_key` — the key the
+  server read back, when the returned message carries one. When the readback
+  does not echo a key, the field is omitted: the envelope never asserts a
+  key→message association the server did not confirm. An `--idempotency-key`
+  longer than 128 characters (or an empty one) is refused locally with a
+  `validation` error naming the flag, before anything is sent. Protected free text — `--initial-prompt` and `--content` — is sent to
   the server but never appears in the envelope, a refusal, a diagnostic or a log.
 - The protected free text can also arrive from an owner-only file, which keeps it
   out of the command line entirely (argv, the process table under
@@ -1095,16 +1117,18 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--mode implement` is not available from the server yet: `create` reports one
   `unsupported` refusal (the server answers 501) and creates nothing. A message
   whose `--mode` differs from its session's mode is refused by the server with
-  409 and reported as one write-worded `conflict` refusal that says a message's
-  mode must match its session's mode and points at `hc ams sessions get`; no
-  message is added, and the read-era conflict wording is never used.
+  409 and reported as one write-worded `conflict` refusal that names the
+  session, mentions a mode mismatch as one possible cause, and points at
+  `hc ams sessions get`; no message is added, and the read-era conflict wording
+  is never used.
 - A missing, expired or other user's session is a `not_found` refusal naming the
   session on `get`, `messages list` and `messages add`; on `create`, a 404 names
   the requested `--agent-id`.
 - Messages with an `--idempotency-key` are replay-safe: the server answers 201
   with the existing message instead of inserting a second one, and the command
   reports that message (its original ID) — a replay is never reported as a new
-  write, and the command itself never re-sends a write.
+  write, and the command itself never re-sends a write. The envelope echoes the
+  server's read-back key, never a key the server did not confirm.
 - If the transport times out or the connection drops mid-write, the write's
   outcome is unknown: the CLI reports one `transport` error whose message says so
   and points at `hc ams sessions list`/`hc ams sessions messages list` before
@@ -1113,8 +1137,10 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   landed write is never reported as stopped.
 - Reads refuse target files, root credentials or base URLs, raw output, blank or
   dot-segment session IDs, out-of-range limits, and installed SDKs without the
-  session list/get and message list/add methods before tenant-admin login or any
-  read. The existing `hc ams plan|show|apply|restore` tuning commands and their
+  session list/get and message list methods before tenant-admin login or any
+  read; `messages list` needs only `messages.list` — the write method `add` is
+  not required for the read, and `messages add` still refuses `unsupported`
+  without it. The existing `hc ams plan|show|apply|restore` tuning commands and their
   signatures are unchanged.
 - These session and message commands do not attach files, apply or roll back
   configuration, or send session history to a model. Plan review is its own
@@ -1205,6 +1231,9 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   message write, no `PUT` and no apply. The server runs the planner once. It
   requires a saved `hc login` session and reports
   `operation: "sessions.plans.generate"` with `data.plan` and `data.out`.
+  An `--idempotency-key` longer than 128 characters (or an empty one) is
+  refused locally with a `validation` error naming the flag, before anything
+  is sent.
   `get` sends exactly one `GET /vibecoder/plans/PLAN_ID` and reports
   `operation: "sessions.plans.get"`; a reload is immutable, so it returns the
   same `plan_hash` and diff however the session changed afterwards. `get` is a

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/auth.py

@@ -121,6 +121,31 @@ def _saved_session_token(target: AmsTarget | TenantTarget) -> str:
         return session.access_token
 
 
+def session_admin_id(target: AmsTarget | TenantTarget) -> str:
+    """The saved ``hc login`` session's own tenant-admin id (``GET /admins/me``).
+
+    The server resolves the identity from the verified access token, so nothing
+    here is caller-supplied. This is a read of the saved session only: there is
+    no environment-variable credential fallback and no password path, so a write
+    that needs the creator identity can never borrow another admin's id.
+    """
+
+    token = _saved_session_token(target)
+    with _tenant_admin_sdk(target.environment, target.tenant_id) as admin:
+        admin.set_access_token(token)
+        try:
+            profile = admin.admin.get_current_tenant_admin()
+        finally:
+            admin.clear_access_token()
+    admin_id = getattr(profile, "admin_id", None)
+    if not isinstance(admin_id, str) or not admin_id.strip():
+        raise click.ClickException("Saved AMS session identity unavailable; run hc login.")
+    profile_tenant_id = getattr(profile, "tenant_id", None)
+    if profile_tenant_id is not None and profile_tenant_id != target.tenant_id:
+        raise click.ClickException("Saved AMS session identity does not match the AMS target; run hc login.")
+    return admin_id
+
+
 def selected_agent(sdk, target: AmsTarget):
     agent = sdk.ams_admin.get_agent(target.agent_id)
     if agent is None or agent.id != target.agent_id or agent.tenant_id != target.tenant_id:

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/departments/commands.py

@@ -4,8 +4,9 @@ from __future__ import annotations
 
 import click
 
+from ..auth import session_admin_id
 from ..context import AmsDependencies, pass_ams, preflight_departments
-from ..errors import run_domain
+from ..errors import run_domain, run_preview
 from ..session import resolve_tenant_target
 from .operations import (
     activate_department,
@@ -14,10 +15,12 @@ from .operations import (
     delete_department,
     get_department,
     list_departments,
+    preview_delete,
     update_department,
 )
 
 LOGIN_HINT = "Not logged in; run `hc login` before writing department changes."
+DELETE_LOGIN_HINT = "Not logged in; run `hc login` before deleting a department."
 
 
 def _environment(function):
@@ -71,23 +74,45 @@ def create_get_command(dependencies: AmsDependencies) -> click.Command:
     return command
 
 
-def _require_login() -> None:
+def _require_login(hint: str = LOGIN_HINT) -> None:
     """Department writes need a saved `hc login` session, not env-var credentials."""
 
     from ..session import load_session
 
     if load_session() is None:
-        raise click.ClickException(LOGIN_HINT)
+        raise click.ClickException(hint)
+
+
+def _preview_then_refuse(invocation, target_data: dict, preview, refusal: str) -> None:
+    """Read the target once, print the reviewed delete, 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 makes
+    the same read before its single DELETE, so a preview is never an approval
+    token.
+    """
+
+    def read() -> None:
+        _require_login(DELETE_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_departments(invocation, target)
+        preview(target)
+
+    run_preview("departments.delete", target_data, read)
+    raise click.UsageError(refusal)
 
 
 def create_create_command(dependencies: AmsDependencies) -> click.Command:
-    @click.command("create", help="Create one department (send-once write; requires `hc login`).")
+    @click.command(
+        "create",
+        help="Create one department (send-once write; requires `hc login`). The creator is the saved "
+        "session's own admin, resolved from the verified token.",
+    )
     @_environment
     @_tenant
     @click.option("--name", required=True, help="Department name.")
-    @click.option(
-        "--created-by-user-id", required=True, help="Calling admin's user ID (required by the server contract)."
-    )
     @click.option("--description", default=None, help="Optional department description.")
     @click.option("--parent-department-id", default=None, help="Optional parent department ID.")
     @click.option("--key", default=None, help="Optional department key.")
@@ -102,7 +127,6 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
         environment: str | None,
         tenant_id: str | None,
         name: str,
-        created_by_user_id: str,
         description: str | None,
         parent_department_id: str | None,
         key: str | None,
@@ -115,6 +139,10 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
             target = resolve_tenant_target(environment, tenant_id)
             target_data.update(environment=target.environment, tenant_id=target.tenant_id)
             preflight_departments(invocation, target)
+            # Attribution is a read of the saved session's own identity (GET /admins/me):
+            # the server derives it from the verified token, so it is resolved before
+            # the write and never supplied by the caller.
+            created_by_user_id = session_admin_id(target)
             return create_department(
                 dependencies,
                 target,
@@ -239,20 +267,39 @@ def create_deactivate_command(dependencies: AmsDependencies) -> click.Command:
 
 
 def create_delete_command(dependencies: AmsDependencies) -> click.Command:
-    @click.command("delete", help="Delete one department (send-once, irreversible; requires `hc login`).")
+    help_text = (
+        "Delete one department (irreversible; send-once; requires `hc login` and --confirm). The CLI keeps "
+        "no restore and cannot undo the delete."
+    )
+
+    @click.command("delete", help=help_text)
     @_environment
     @_tenant
     @click.option("--department-id", required=True)
+    @click.option(
+        "--confirm",
+        is_flag=True,
+        default=False,
+        help="Required acknowledgement of the printed target and disclosure block; without it the command "
+        "reads the department, prints both and sends nothing.",
+    )
     @pass_ams
-    def command(invocation, environment: str | None, tenant_id: str | None, department_id: str) -> None:
+    def command(invocation, environment: str | None, tenant_id: str | None, department_id: str, confirm: bool) -> None:
         target_data = {
             "environment": environment,
             "tenant_id": tenant_id,
             "department_id": department_id,
         }
+        if not confirm:
+            _preview_then_refuse(
+                invocation,
+                target_data,
+                lambda target: preview_delete(dependencies, target, department_id),
+                "--confirm is required; no delete was sent. Re-run with --confirm to send it.",
+            )
 
         def execute():
-            _require_login()
+            _require_login(DELETE_LOGIN_HINT)
             target = resolve_tenant_target(environment, tenant_id)
             target_data.update(environment=target.environment, tenant_id=target.tenant_id)
             preflight_departments(invocation, target)

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/departments/operations.py

@@ -270,12 +270,119 @@ def deactivate_department(dependencies: AmsDependencies, target: TenantTarget, d
     return _lifecycle(dependencies, target, department_id, "deactivate")
 
 
+DELETE_DISCLOSURE = {
+    "irreversible": "the server deletes the department; the CLI has no restore and no retention window.",
+    "no_retry": "exactly one DELETE is sent, and an uncertain outcome is never replayed.",
+}
+
+
+def _review_enabled() -> bool:
+    """A reviewed write rendering is human: json/raw keep stderr machine-parsable."""
+
+    import click
+
+    from ...context import CliConfig
+
+    ctx = click.get_current_context(silent=True)
+    config = ctx.find_object(CliConfig) if ctx is not None else None
+    return getattr(config, "output", None) not in ("json", "raw")
+
+
+def _echo_preview_notice() -> None:
+    """Say plainly that what follows 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 _delete_target(department, department_id: str) -> dict:
+    """The exact record the operator is approving: ids and bounded fields only."""
+
+    return {
+        "department_id": department_id,
+        "name": getattr(department, "name", None),
+        "key": getattr(department, "key", None),
+        "active": getattr(department, "active", None),
+        "parent_department_id": getattr(department, "parent_department_id", None),
+    }
+
+
+def _echo_delete_review(department, department_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
+
+    if not _review_enabled():
+        return
+    target = _delete_target(department, department_id)
+    click.echo(
+        f"{'would delete' if preview else 'deleting'} department '{department_id}' "
+        f"(name {target['name']!r}, key {target['key']!r}, active {target['active']}, "
+        f"parent_department_id {target['parent_department_id']!r}):",
+        err=True,
+    )
+    for key, fact in DELETE_DISCLOSURE.items():
+        click.echo(f"  {key}: {fact}", err=True)
+    click.echo(f"one DELETE /departments/{department_id}", err=True)
+
+
+def _delete_review_target(sdk, target: TenantTarget, department_id: str):
+    """The one bounded read a delete reviews: a 404 is its own refusal.
+
+    Used by both the unconfirmed preview and the confirmed run, so the target the
+    operator reviewed and the target that is deleted cannot drift.
+    """
+
+    from healthcloud.errors import HealthCloudHTTPError
+
+    try:
+        department = _resource(sdk, ("get",)).get(department_id)
+    except HealthCloudHTTPError as error:
+        if getattr(error, "status_code", 0) == 404:
+            raise DepartmentWriteRefused(
+                "not_found",
+                f"Department '{department_id}' was not found in this tenant; nothing was sent.",
+            ) from None
+        raise
+    if (
+        department is None
+        or getattr(department, "id", None) != department_id
+        or getattr(department, "tenant_id", None) != target.tenant_id
+    ):
+        raise DepartmentWriteRefused("validation", "Department/tenant identity mismatch; stopped.")
+    return department
+
+
+def preview_delete(dependencies: AmsDependencies, target: TenantTarget, department_id: str) -> None:
+    """Print the delete target and its disclosure without sending the DELETE."""
+
+    department_id = _department_id(department_id)
+    with dependencies.authenticated_sdk_factory(target) as sdk:
+        before = _delete_review_target(sdk, target, department_id)
+    _echo_preview_notice()
+    _echo_delete_review(before, department_id, preview=True)
+
+
 def delete_department(dependencies: AmsDependencies, target: TenantTarget, department_id: str) -> dict:
-    """Delete one department (204, no body); no retry on unknown outcome."""
+    """Delete one department (204, no body); no retry on unknown outcome.
+
+    Sequence: exactly one ``GET /departments/{id}`` (the reviewed target, the same
+    read the unconfirmed preview makes) and exactly one ``DELETE``. There is never
+    a retry, a replay, a second delete or a restore claim.
+    """
     from healthcloud.errors import HealthCloudHTTPError, HealthCloudNetworkError
 
     department_id = _department_id(department_id)
     with dependencies.authenticated_sdk_factory(target) as sdk:
+        before = _delete_review_target(sdk, target, department_id)
+        _echo_delete_review(before, department_id)
         resource = _resource(sdk, ("delete",))
         try:
             resource.delete(department_id)

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/policies/commands.py

@@ -188,6 +188,8 @@ def create_update_command(dependencies: AmsDependencies) -> click.Command:
     ) -> None:
         if content is not None and content_file is not None:
             raise click.UsageError("Pass --content or --content-file, not both; nothing was sent.")
+        if guardrail_ids and clear_guardrail_ids:
+            raise click.UsageError("--guardrail-ids and --clear-guardrail-ids cannot be combined; nothing was sent.")
         target_data = {
             "environment": environment,
             "tenant_id": tenant_id,

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/sessions/operations.py

@@ -87,6 +87,28 @@ def _session_id(value: str) -> str:
     return value
 
 
+IDEMPOTENCY_KEY_MAX_CHARS = 128
+
+
+def _idempotency_key(value, refuse):
+    """Mirror the SDK's 128-character bound locally (the help text advertises it).
+
+    Refused before login or any request, so the bound holds regardless of the
+    installed SDK version. A non-empty string within the bound passes through
+    unchanged; the caller keeps its own refusal class (message write vs plan
+    review).
+    """
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value or len(value) > IDEMPOTENCY_KEY_MAX_CHARS:
+        raise refuse(
+            "validation",
+            f"--idempotency-key must be a non-empty string of at most {IDEMPOTENCY_KEY_MAX_CHARS} "
+            "characters; nothing was sent.",
+        )
+    return value
+
+
 def _limit(value: int | None, maximum: int, name: str) -> int | None:
     if value is None:
         return None
@@ -572,7 +594,9 @@ def get_session(dependencies: AmsDependencies, target: TenantTarget, session_id:
     with dependencies.authenticated_sdk_factory(target) as sdk:
         session = _sessions(sdk).get(session_id)
     if session is None:
-        raise SessionReadRefused("validation", "Session/tenant identity mismatch; stopped.")
+        # A 200 with a JSON null body is the server saying "no such session
+        # here" — not an identity mismatch.
+        raise SessionReadRefused("not_found", f"Session '{session_id}' was not found in this tenant.")
     _identity(session, target, session_id)
     return succeeded(
         "sessions.get", _target(target, session_id), {"session": session_projection(session)}, read_only=True
@@ -622,9 +646,9 @@ def _message_conflict(error: BaseException, session_id: str) -> SessionWriteRefu
         return None
     return SessionWriteRefused(
         "conflict",
-        f"The message was refused for session '{session_id}': the server reported a conflict. A "
-        "message's mode must match its session's mode; read the session with `hc ams sessions get` "
-        "before retrying. No message was added.",
+        f"The message was refused for session '{session_id}': the server reported a conflict — for "
+        "example, a message's mode not matching its session's mode. Read the session with "
+        "`hc ams sessions get` before retrying. No message was added.",
     )
 
 
@@ -709,7 +733,7 @@ def list_messages(
     limit = _limit(limit, MESSAGE_LIMIT_MAX, "--limit")
     with dependencies.authenticated_sdk_factory(target) as sdk:
         try:
-            messages = _messages(sdk).list(session_id, **({} if limit is None else {"limit": limit}))
+            messages = _messages(sdk, ("list",)).list(session_id, **({} if limit is None else {"limit": limit}))
         except HealthCloudHTTPError as error:
             if getattr(error, "status_code", None) == 404:
                 raise SessionReadRefused(
@@ -944,6 +968,7 @@ def generate_plan(
     session_id = _session_id(session_id)
     operation = _plan_operation(operation)
     prompt = None if prompt_file is None else _prompt_file(prompt_file)
+    idempotency_key = _idempotency_key(idempotency_key, PlanReviewRefused)
     with private_output(out) as write, dependencies.authenticated_sdk_factory(target) as sdk:
         resource = _plans(sdk, ("generate",), write=True)
         try:
@@ -1038,6 +1063,7 @@ def add_message(
         refuse=SessionWriteRefused,
         required=True,
     )
+    idempotency_key = _idempotency_key(idempotency_key, SessionWriteRefused)
     with dependencies.authenticated_sdk_factory(target) as sdk:
         resource = _messages(sdk, ("add",), write=True)
         try:
@@ -1067,8 +1093,13 @@ def add_message(
             "anything else.",
         )
     data: dict = {"message": message_projection(message)}
-    if idempotency_key is not None:
-        data["idempotency_key"] = idempotency_key
+    # Echo the server's readback key when the message carries one, so the
+    # envelope never asserts a key→message association the server did not
+    # confirm. When the readback omits the key entirely the field is omitted
+    # too — the caller can see the key they passed in their own command line.
+    readback_key = getattr(message, "idempotency_key", None)
+    if readback_key is not None:
+        data["idempotency_key"] = readback_key
     return succeeded("sessions.messages.add", _target(target, session_id), data, read_only=False)
 
 

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/skills/commands.py

@@ -141,6 +141,8 @@ def create_update_command(dependencies: AmsDependencies) -> click.Command:
         tool_ids: tuple[str, ...],
         clear_tool_ids: bool,
     ) -> None:
+        if tool_ids and clear_tool_ids:
+            raise click.UsageError("--tool-ids and --clear-tool-ids cannot be combined; nothing was sent.")
         target_data = {
             "environment": environment,
             "tenant_id": tenant_id,

{healthcloud_cli-3.7.3 → healthcloud_cli-3.7.6}/healthcloud_cli/ams/teams/commands.py

@@ -149,6 +149,10 @@ def create_update_command(dependencies: AmsDependencies) -> click.Command:
         required_eval_suite_ids: tuple[str, ...],
         clear_required_eval_suite_ids: bool,
     ) -> None:
+        if required_eval_suite_ids and clear_required_eval_suite_ids:
+            raise click.UsageError(
+                "--required-eval-suite-ids and --clear-required-eval-suite-ids cannot be combined; nothing was sent."
+            )
         target_data = {
             "environment": environment,
             "tenant_id": tenant_id,

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

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