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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.6
+Version: 3.7.8
 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
@@ -1082,9 +1082,14 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 
 - `list` emits `operation: "sessions.list"`, `data.sessions` (bounded projections
   of session ID, agent ID, operation, mode, status and audit timestamps) and a
-  `page` block (`{"kind": "limit", "limit": N, "returned_count": N,
-  "continuation": null}`). `get` emits `operation: "sessions.get"` and
-  `data.session`. The projections never include the session's protected
+  `page` block. These routes page with a limit only, so the block always says
+  which limit was in force: with `--limit N` it is
+  `{"kind": "limit", "limit": N, "returned_count": N, "continuation": null}`,
+  and without it the server's own default page was applied, which the block
+  reports as `{"kind": "server_default", "server_default_limit": 50,
+  "returned_count": N, "continuation": null}` (50 sessions, 100 messages) — so
+  a truncated page is never mistaken for a complete list. `get` emits
+  `operation: "sessions.get"` and `data.session`. The projections never include the session's protected
   `initial_prompt`, tenant or user identity, or arbitrary response fields.
 - Default `pretty` output prints `list` as a table with honest headers —
   `ID`, `AGENT ID`, `OPERATION`, `STATUS`, `EXPIRES AT` for sessions and `ID`,
@@ -1133,7 +1138,11 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--initial-prompt` becomes the session's first `user` message in the same
   server transaction; `hc ams sessions messages list` shows it afterwards.
 - `--mode implement` is not available from the server yet: `create` reports one
-  `unsupported` refusal (the server answers 501) and creates nothing. A message
+  `unsupported` refusal (the server answers 501) and creates nothing, and a
+  `messages add` the server answers 501 for is the same `unsupported` refusal
+  with no message added. Both refusals report the 501 the server actually sent
+  and name implement mode as the documented reason, rather than asserting the
+  requested mode was the cause. 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 names the
   session, mentions a mode mismatch as one possible cause, and points at
@@ -1156,9 +1165,14 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - 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 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
+  read. `messages list` needs only `messages.list` — the write method `add` is
+  not required for the read. The writes check their own methods in the same
+  preflight — each command requires exactly the write method it calls, so
+  `create` refuses an installed SDK without `sessions.create` and `messages add`
+  one without `messages.add` before tenant-admin login and before any read or
+  write, and neither is refused for the write the other command performs. A single-object route whose 2xx body is not a JSON
+  object is refused as a `validation` error, never reported as an internal
+  failure. 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
@@ -1255,7 +1269,12 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `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
-  read and needs no saved `hc login` session.
+  read and needs no saved `hc login` session: it authenticates like every other
+  session read, with the saved session when there is one and otherwise with the
+  environment's own `HC_AMS_ADMIN_EMAIL`/`HC_AMS_ADMIN_PASSWORD` credentials.
+  A refusal is worded for the operation that was refused, so a `422` or `503`
+  on `get` never claims a plan "was generated": `generate` says no plan was
+  generated, `get` says no plan was reloaded.
 - `--out` is required and must be a new path: the review is written to a
   newly created owner-only file (mode `0600`, no symlinks, never overwritten).
   A refusal removes the reservation again, so a refused review never leaves a
@@ -1272,6 +1291,13 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   guardrail/data-source) for a creation plan. `plan_json["original_prompt"]`
   is never projected, and `warnings`/`skipped_references` are reported as
   counts, not bodies.
+- The review file marks the text a model produced: `content_origin` is
+  `"model-generated"` and `model_generated_fields` lists the fields whose values
+  came from the planner — `summary`, `changes.*.why`,
+  `definition.instructions`/`greetings`/`name`/`description`/opening suggestions
+  and `review_warnings[].message`. Those values are data to inspect before you
+  approve, never instructions to the reader or to an agent that later reads the
+  file.
 - stdout stays bounded and free-text-free: plan ID, `plan_hash`, operation,
   status, base config version, agent ID, model, sorted changed-field **names**
   (create: reference counts by kind) and finding counts. No prompt,
@@ -1285,7 +1311,14 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `--output json` prints the full envelope, unchanged.
 - The prompt is protected free text and never comes from argv: `--prompt-file`
   reads one owner-only regular text file (no symlinks, at most 20000
-  characters) and sends it once. `--prompt-file` is optional — the server falls
+  characters) and sends it once. A file that is too large, missing, unreadable,
+  not UTF-8 text, or not an owner-only regular file is a `validation` refusal
+  naming the reason and never quoting the text. Ownership is checked differently
+  per platform: on POSIX it is the file's mode and owner; on Windows the opened
+  handle's owner and DACL must grant access to your account only, so a file that
+  inherited a grant to another principal (SYSTEM, Administrators) is refused as
+  not owner-only. Keep the prompt file in a directory only your account can read.
+  `--prompt-file` is optional — the server falls
   back to the session's initial prompt or last message — and `--agent-type`
   applies to `--operation create` only (with `modify` it is a usage error
   before login or any request). `--prompt-file` is not mirrored as a local
@@ -1306,12 +1339,22 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   values, so read it in the AMS console. Non-`advisory` review findings are
   refused the same way; advisory findings are displayed in the review file.
   A creation plan that claims an `agent_id` is refused, and no existing agent
-  ID is ever fabricated or required.
+  ID is ever fabricated or required. So is a creation plan whose proposed agent
+  carries a field outside the documented definition and reference set
+  (`name`, `description`, `type`, `model`, `preferred_model`,
+  `is_orchestrator`, `department_id`, `team_id`, `instructions`, `greetings`,
+  `opening_suggestions`, `opening_suggestions_options`, and the catalog
+  `*_ids`), or whose reference field holds anything but non-blank catalog IDs:
+  the operator never approves a definition the review did not show.
 - Server answers are preserved, not replaced: a missing, expired or other
-  user's session or plan is a `not_found` refusal naming it, a `422` from the
-  plan route is a `validation` refusal carrying the server's own bounded
-  detail, and an unavailable planner (`503`) is a `transport` refusal with no
-  file written. A dropped connection on `generate` reports one `transport`
+  user's session or plan is a `not_found` refusal naming it, and an unavailable
+  planner (`503`) is a `transport` refusal with no file written. A `422` from
+  the plan route is a `validation` refusal, but its detail is only quoted when
+  it is a known static contract message that carries no field values — the
+  documented `"a prompt is required for agent creation"`. Any other `422`
+  detail can quote protected field values, exactly like `validation_errors`
+  and blocking review findings, so it is reported by category only and you read
+  it in the AMS console. A dropped connection on `generate` reports one `transport`
   error saying the plan's outcome is unknown and points at
   `hc ams sessions messages list`/`plans get` before retrying; the request is
   never re-sent automatically.

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

@@ -1064,9 +1064,14 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 
 - `list` emits `operation: "sessions.list"`, `data.sessions` (bounded projections
   of session ID, agent ID, operation, mode, status and audit timestamps) and a
-  `page` block (`{"kind": "limit", "limit": N, "returned_count": N,
-  "continuation": null}`). `get` emits `operation: "sessions.get"` and
-  `data.session`. The projections never include the session's protected
+  `page` block. These routes page with a limit only, so the block always says
+  which limit was in force: with `--limit N` it is
+  `{"kind": "limit", "limit": N, "returned_count": N, "continuation": null}`,
+  and without it the server's own default page was applied, which the block
+  reports as `{"kind": "server_default", "server_default_limit": 50,
+  "returned_count": N, "continuation": null}` (50 sessions, 100 messages) — so
+  a truncated page is never mistaken for a complete list. `get` emits
+  `operation: "sessions.get"` and `data.session`. The projections never include the session's protected
   `initial_prompt`, tenant or user identity, or arbitrary response fields.
 - Default `pretty` output prints `list` as a table with honest headers —
   `ID`, `AGENT ID`, `OPERATION`, `STATUS`, `EXPIRES AT` for sessions and `ID`,
@@ -1115,7 +1120,11 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--initial-prompt` becomes the session's first `user` message in the same
   server transaction; `hc ams sessions messages list` shows it afterwards.
 - `--mode implement` is not available from the server yet: `create` reports one
-  `unsupported` refusal (the server answers 501) and creates nothing. A message
+  `unsupported` refusal (the server answers 501) and creates nothing, and a
+  `messages add` the server answers 501 for is the same `unsupported` refusal
+  with no message added. Both refusals report the 501 the server actually sent
+  and name implement mode as the documented reason, rather than asserting the
+  requested mode was the cause. 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 names the
   session, mentions a mode mismatch as one possible cause, and points at
@@ -1138,9 +1147,14 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - 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 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
+  read. `messages list` needs only `messages.list` — the write method `add` is
+  not required for the read. The writes check their own methods in the same
+  preflight — each command requires exactly the write method it calls, so
+  `create` refuses an installed SDK without `sessions.create` and `messages add`
+  one without `messages.add` before tenant-admin login and before any read or
+  write, and neither is refused for the write the other command performs. A single-object route whose 2xx body is not a JSON
+  object is refused as a `validation` error, never reported as an internal
+  failure. 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
@@ -1237,7 +1251,12 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `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
-  read and needs no saved `hc login` session.
+  read and needs no saved `hc login` session: it authenticates like every other
+  session read, with the saved session when there is one and otherwise with the
+  environment's own `HC_AMS_ADMIN_EMAIL`/`HC_AMS_ADMIN_PASSWORD` credentials.
+  A refusal is worded for the operation that was refused, so a `422` or `503`
+  on `get` never claims a plan "was generated": `generate` says no plan was
+  generated, `get` says no plan was reloaded.
 - `--out` is required and must be a new path: the review is written to a
   newly created owner-only file (mode `0600`, no symlinks, never overwritten).
   A refusal removes the reservation again, so a refused review never leaves a
@@ -1254,6 +1273,13 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   guardrail/data-source) for a creation plan. `plan_json["original_prompt"]`
   is never projected, and `warnings`/`skipped_references` are reported as
   counts, not bodies.
+- The review file marks the text a model produced: `content_origin` is
+  `"model-generated"` and `model_generated_fields` lists the fields whose values
+  came from the planner — `summary`, `changes.*.why`,
+  `definition.instructions`/`greetings`/`name`/`description`/opening suggestions
+  and `review_warnings[].message`. Those values are data to inspect before you
+  approve, never instructions to the reader or to an agent that later reads the
+  file.
 - stdout stays bounded and free-text-free: plan ID, `plan_hash`, operation,
   status, base config version, agent ID, model, sorted changed-field **names**
   (create: reference counts by kind) and finding counts. No prompt,
@@ -1267,7 +1293,14 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `--output json` prints the full envelope, unchanged.
 - The prompt is protected free text and never comes from argv: `--prompt-file`
   reads one owner-only regular text file (no symlinks, at most 20000
-  characters) and sends it once. `--prompt-file` is optional — the server falls
+  characters) and sends it once. A file that is too large, missing, unreadable,
+  not UTF-8 text, or not an owner-only regular file is a `validation` refusal
+  naming the reason and never quoting the text. Ownership is checked differently
+  per platform: on POSIX it is the file's mode and owner; on Windows the opened
+  handle's owner and DACL must grant access to your account only, so a file that
+  inherited a grant to another principal (SYSTEM, Administrators) is refused as
+  not owner-only. Keep the prompt file in a directory only your account can read.
+  `--prompt-file` is optional — the server falls
   back to the session's initial prompt or last message — and `--agent-type`
   applies to `--operation create` only (with `modify` it is a usage error
   before login or any request). `--prompt-file` is not mirrored as a local
@@ -1288,12 +1321,22 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   values, so read it in the AMS console. Non-`advisory` review findings are
   refused the same way; advisory findings are displayed in the review file.
   A creation plan that claims an `agent_id` is refused, and no existing agent
-  ID is ever fabricated or required.
+  ID is ever fabricated or required. So is a creation plan whose proposed agent
+  carries a field outside the documented definition and reference set
+  (`name`, `description`, `type`, `model`, `preferred_model`,
+  `is_orchestrator`, `department_id`, `team_id`, `instructions`, `greetings`,
+  `opening_suggestions`, `opening_suggestions_options`, and the catalog
+  `*_ids`), or whose reference field holds anything but non-blank catalog IDs:
+  the operator never approves a definition the review did not show.
 - Server answers are preserved, not replaced: a missing, expired or other
-  user's session or plan is a `not_found` refusal naming it, a `422` from the
-  plan route is a `validation` refusal carrying the server's own bounded
-  detail, and an unavailable planner (`503`) is a `transport` refusal with no
-  file written. A dropped connection on `generate` reports one `transport`
+  user's session or plan is a `not_found` refusal naming it, and an unavailable
+  planner (`503`) is a `transport` refusal with no file written. A `422` from
+  the plan route is a `validation` refusal, but its detail is only quoted when
+  it is a known static contract message that carries no field values — the
+  documented `"a prompt is required for agent creation"`. Any other `422`
+  detail can quote protected field values, exactly like `validation_errors`
+  and blocking review findings, so it is reported by category only and you read
+  it in the AMS console. A dropped connection on `generate` reports one `transport`
   error saying the plan's outcome is unknown and points at
   `hc ams sessions messages list`/`plans get` before retrying; the request is
   never re-sent automatically.

{healthcloud_cli-3.7.6 → healthcloud_cli-3.7.8}/healthcloud_cli/ams/context.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from contextlib import AbstractContextManager
 from dataclasses import dataclass
 from pathlib import Path
@@ -236,8 +236,20 @@ def preflight_policies(invocation: AmsContext, target: TenantTarget) -> None:
         sdk.close()
 
 
-def preflight_sessions(invocation: AmsContext, target: TenantTarget) -> None:
-    """Validate local session-read compatibility before login or any read."""
+def preflight_sessions(
+    invocation: AmsContext,
+    target: TenantTarget,
+    *,
+    write_methods: Sequence[str] = (),
+) -> None:
+    """Validate local session compatibility before login or any request.
+
+    ``write_methods`` names exactly the write methods the calling command will
+    call, as ``"<resource>.<method>"`` (``sessions.create``, ``messages.add``),
+    so a write command is refused here — before tenant-admin login and before any
+    read or write — only for a method it actually needs; a write it never
+    performs is never required of the installed SDK.
+    """
 
     _check_root(invocation)
     if invocation.target_file is not None:
@@ -245,12 +257,16 @@ def preflight_sessions(invocation: AmsContext, target: TenantTarget) -> None:
     sdk = _public_sdk(target.environment, target.tenant_id)
     try:
         resource = getattr(getattr(sdk, "ams_admin", None), "sessions", None)
-        if (
-            resource is None
-            or not callable(getattr(resource, "list", None))
-            or not callable(getattr(resource, "get", None))
-            or not callable(getattr(getattr(resource, "messages", None), "list", None))
-        ):
+        messages = getattr(resource, "messages", None)
+        resources = {"sessions": resource, "messages": messages}
+        required = (resource, "list"), (resource, "get"), (messages, "list")
+        missing = any(not callable(getattr(holder, method, None)) for holder, method in required)
+        for qualified in write_methods:
+            owner, _, method = qualified.partition(".")
+            holder = resources.get(owner)
+            if not method or not callable(getattr(holder, method, None)):
+                missing = True
+        if missing:
             raise click.ClickException(
                 "SDK missing ams_admin sessions; use the reviewed SDK version required by this CLI."
             )

{healthcloud_cli-3.7.6 → healthcloud_cli-3.7.8}/healthcloud_cli/ams/output.py

@@ -66,34 +66,75 @@ def read_json(path: Path, *, private: bool = False) -> dict:
         ) from None
 
 
+class PrivateInputRefused(ValueError):
+    """A protected input file the reader refused, with a value-free reason.
+
+    ``reason`` names the failed property — ``too_large``, ``not_owner_only``,
+    ``not_text`` or ``unreadable`` — never the file's path or content, so a
+    caller can map it to its own categorized refusal (a bare click error is not
+    the command's error contract) without quoting protected text.
+    """
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+def private_input_detail(reason: str, *, maximum: int) -> str:
+    """A bounded, value-free sentence explaining why a protected file was refused."""
+
+    if reason == "too_large":
+        return f"it is larger than {maximum} characters"
+    if reason == "not_text":
+        return "it is not readable UTF-8 text"
+    if reason in ("not_owner_only", "not_regular"):
+        return "it is not an owner-only regular file"
+    return "it cannot be read"
+
+
 def read_private_text(path: Path, *, maximum: int) -> str:
     """Read one owner-only plain-text input without quoting its content.
 
     ``maximum`` is a character bound checked before the text is handed on, so
     an oversized protected input is refused locally instead of being sent. The
-    text itself is never included in the refusal: only the reason.
+    text itself is never included in the refusal: only the reason, as a
+    :class:`PrivateInputRefused` carrying one of ``too_large``,
+    ``not_owner_only``, ``not_regular``, ``not_text`` or ``unreadable``.
+
+    The owner-only check is a POSIX mode/ownership check. On Windows the same
+    guarantee comes from ``windows_files``, which validates the opened handle's
+    owner and DACL; its refusal carries its own reason (``not_owner_only`` or
+    ``not_regular``) and is reported unchanged here, so a non-private file is not
+    misreported as unreadable. An inherited ACL cannot be made owner-only by the
+    creator, so the caller must still keep the file in a directory only the
+    operator can read.
     """
     try:
         if os.name == "nt":
-            from .windows_files import open_file
+            from .windows_files import PrivateHandleRefused, open_file
 
-            fd = open_file(path, private=True)
+            try:
+                fd = open_file(path, private=True)
+            except PrivateHandleRefused as error:
+                raise PrivateInputRefused(error.reason) from None
         else:
             fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
         with os.fdopen(fd, encoding="utf-8") as stream:
             info = os.fstat(stream.fileno())
-            if not stat.S_ISREG(info.st_mode) or (
-                os.name != "nt" and (info.st_mode & 0o077 or info.st_uid != os.getuid())
-            ):
-                raise ValueError("Private input must be an owner-only regular file")
+            if not stat.S_ISREG(info.st_mode):
+                raise PrivateInputRefused("not_regular")
+            if os.name != "nt" and (info.st_mode & 0o077 or info.st_uid != os.getuid()):
+                raise PrivateInputRefused("not_owner_only")
             text = stream.read(maximum + 1)
         if len(text) > maximum:
-            raise ValueError("Private input is too large")
+            raise PrivateInputRefused("too_large")
         return text
-    except OSError, ValueError, UnicodeError:
-        raise click.ClickException(
-            "Invalid input file; require a readable, owner-only regular text file without symlinks."
-        ) from None
+    except PrivateInputRefused:
+        raise
+    except UnicodeError:
+        raise PrivateInputRefused("not_text") from None
+    except OSError, ValueError:
+        raise PrivateInputRefused("unreadable") from None
 
 
 def protected_text(
@@ -132,7 +173,12 @@ def protected_text(
     if path is not None:
         if not isinstance(path, str) or not path.strip():
             raise refuse("validation", f"Explicit {file_flag} file path required.")
-        text = read_private_text(Path(path), maximum=PROTECTED_TEXT_MAX_CHARS)
+        try:
+            text = read_private_text(Path(path), maximum=PROTECTED_TEXT_MAX_CHARS)
+        except PrivateInputRefused:
+            raise click.ClickException(
+                "Invalid input file; require a readable, owner-only regular text file without symlinks."
+            ) from None
         if not text:
             raise refuse("validation", f"The file given to {file_flag} is empty; nothing was sent.")
         return text

{healthcloud_cli-3.7.6 → healthcloud_cli-3.7.8}/healthcloud_cli/ams/sessions/commands.py

@@ -125,7 +125,7 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
             _require_login()
             target = resolve_tenant_target(environment, tenant_id)
             target_data.update(environment=target.environment, tenant_id=target.tenant_id)
-            preflight_sessions(invocation, target)
+            preflight_sessions(invocation, target, write_methods=("sessions.create",))
             return create_session(
                 dependencies,
                 target,
@@ -561,7 +561,7 @@ def create_messages_add_command(dependencies: AmsDependencies) -> click.Command:
             _require_login()
             target = resolve_tenant_target(environment, tenant_id)
             target_data.update(environment=target.environment, tenant_id=target.tenant_id)
-            preflight_sessions(invocation, target)
+            preflight_sessions(invocation, target, write_methods=("messages.add",))
             return add_message(
                 dependencies,
                 target,

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

@@ -7,7 +7,14 @@ from pathlib import Path
 
 from ..context import AmsDependencies
 from ..domain_errors import DomainOutcomeUnknown, DomainReadRefused
-from ..output import PROTECTED_TEXT_MAX_CHARS, private_output, protected_text, read_private_text
+from ..output import (
+    PROTECTED_TEXT_MAX_CHARS,
+    PrivateInputRefused,
+    private_input_detail,
+    private_output,
+    protected_text,
+    read_private_text,
+)
 from ..results import succeeded, unknown
 from ..target import TenantTarget
 from .projections import (
@@ -25,7 +32,11 @@ from .projections import (
 )
 
 SESSION_LIMIT_MAX = 100
+# The server's own defaults when ``--limit`` is omitted: an omitted limit is a
+# real, truncating page, so the envelope reports which default was applied.
+SESSION_LIMIT_DEFAULT = 50
 MESSAGE_LIMIT_MAX = 200
+MESSAGE_LIMIT_DEFAULT = 100
 # Mirror the server's own bounds so an obviously unacceptable file is never
 # put on the wire; the server's refusal still wins when it disagrees.
 ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024
@@ -288,16 +299,21 @@ def _plan_operation(value: str) -> str:
 
 
 def _prompt_file(path: str) -> str:
-    """Read the protected prompt from one owner-only text file, never argv."""
+    """Read the protected prompt from one owner-only text file, never argv.
+
+    ``read_private_text`` applies the size bound itself, so oversize, unsafe and
+    unreadable files are all refused here in the plan's own ``validation``
+    category instead of a bare click error. There is deliberately no second
+    length check: a check after that read could never run.
+    """
 
     if not isinstance(path, str) or not path.strip():
         raise PlanReviewRefused("validation", "Explicit prompt file path required.")
-    text = read_private_text(Path(path), maximum=PROMPT_MAX_CHARS)
-    if len(text) > PROMPT_MAX_CHARS:
-        raise PlanReviewRefused(
-            "validation", f"The prompt file is larger than {PROMPT_MAX_CHARS} characters; nothing was sent."
-        )
-    return text
+    try:
+        return read_private_text(Path(path), maximum=PROMPT_MAX_CHARS)
+    except PrivateInputRefused as error:
+        detail = private_input_detail(error.reason, maximum=PROMPT_MAX_CHARS)
+        raise PlanReviewRefused("validation", f"The prompt file was refused: {detail}; nothing was sent.") from None
 
 
 def _plans(sdk, methods, *, write: bool = False, what: str | None = None):
@@ -467,15 +483,34 @@ def _modify_diff(body: dict) -> dict:
 
 
 def _references(agent: dict) -> dict:
+    """Group the proposal's catalog references by kind, refusing anything but IDs.
+
+    Field **names** only ever reach a refusal: a non-string or blank item is
+    refused rather than dropped, because a dropped item is a reference the
+    operator would approve without having seen it.
+    """
+
     references = {}
     for field, kind in PLAN_REFERENCE_FIELDS.items():
         value = agent.get(field)
-        if isinstance(value, str) and value:
+        if value is None:
+            continue
+        if isinstance(value, str):
+            if not value.strip():
+                raise PlanReviewRefused(
+                    "validation", f"Creation plan reference '{field}' is blank; it is not a catalog ID. Refused."
+                )
             references[kind] = [value]
-        elif isinstance(value, list):
-            ids = sorted({item for item in value if isinstance(item, str) and item})
-            if ids:
-                references[kind] = ids
+            continue
+        if not isinstance(value, list) or not all(isinstance(item, str) and item.strip() for item in value):
+            raise PlanReviewRefused(
+                "validation",
+                f"Creation plan reference '{field}' must be a catalog ID or a list of catalog IDs; "
+                "anything else is refused by field name. No review file was written.",
+            )
+        ids = sorted(set(value))
+        if ids:
+            references[kind] = ids
     return references
 
 
@@ -492,6 +527,13 @@ def _create_diff(plan, body: dict) -> dict:
         raise PlanReviewRefused(
             "validation", "A creation plan must carry the proposed agent definition; the server returned none."
         )
+    unknown = sorted(set(agent) - set(PLAN_DEFINITION_FIELDS) - set(PLAN_REFERENCE_FIELDS))
+    if unknown:
+        raise PlanReviewRefused(
+            "validation",
+            f"Creation plan carries agent fields this review does not cover: {', '.join(unknown)}. "
+            "Refused by field name; no review file was written.",
+        )
     return {
         "definition": {name: agent[name] for name in PLAN_DEFINITION_FIELDS if name in agent},
         "references": _references(agent),
@@ -519,9 +561,41 @@ def _plan_review(
     return actual, review, plan_metadata(plan, actual, review)
 
 
+# The only `422` details this CLI prints: static route-contract messages that
+# name a rule and carry no field value. Everything else the server sends in a
+# `422` detail is its own text, which can quote protected field values — the
+# same reason `validation_errors` and blocking review findings are reported by
+# count only. Extend this set only with a detail verified to be static.
+PLAN_SAFE_422_DETAILS = frozenset({"a prompt is required for agent creation"})
+
+
+def _plan_safe_detail(error: BaseException) -> str | None:
+    """The server's own `422` detail, but only when it is a known value-free message."""
+
+    parsed = getattr(error, "parsed_body", None)
+    if not isinstance(parsed, dict):
+        return None
+    for key in ("detail", "error", "message"):
+        value = parsed.get(key)
+        if isinstance(value, str) and value.strip():
+            detail = " ".join(value.split())
+            return detail if detail in PLAN_SAFE_422_DETAILS else None
+    return None
+
+
+def _plan_not_done(kind: str) -> str:
+    """What did not happen, worded for the operation that was refused."""
+
+    if kind == "generate":
+        return "No plan was generated."
+    return "No plan was reloaded; nothing was reviewed."
+
+
 def _plan_write_refusal(
-    error: BaseException, *, session_id: str | None, plan_id: str | None
+    error: BaseException, *, kind: str, session_id: str | None, plan_id: str | None
 ) -> PlanReviewRefused | None:
+    """Map one plan-route HTTP error for `generate` (`kind="generate"`) or `get`."""
+
     status = getattr(error, "status_code", None)
     if status == 404:
         if plan_id is not None:
@@ -532,14 +606,20 @@ def _plan_write_refusal(
             "not_found", f"Session '{session_id}' was not found in this tenant; no plan was generated."
         )
     if status == 422:
+        detail = _plan_safe_detail(error)
+        if detail is not None:
+            return PlanReviewRefused(
+                "validation", f"The plan request was refused by the server (422): {detail}. {_plan_not_done(kind)}"
+            )
         return PlanReviewRefused(
             "validation",
-            f"The plan request was refused by the server (422): {_server_detail(error)}. No plan was generated.",
+            "The plan request was refused by the server (422). Its detail can quote protected field values, "
+            f"so it is not printed; review it in the AMS console. {_plan_not_done(kind)}",
         )
     if status == 503:
         return PlanReviewRefused(
             "transport",
-            "The plan service is unavailable (the server answered 503); no plan was generated. Retry later.",
+            f"The plan service is unavailable (the server answered 503); {_plan_not_done(kind)} Retry later.",
         )
     return None
 
@@ -562,6 +642,26 @@ def _identity(session, target: TenantTarget, session_id: str | None) -> None:
         )
 
 
+def _page(limit: int | None, server_default: int, returned: int) -> dict:
+    """The page block, honest about an omitted ``--limit``.
+
+    These routes page with a limit only: an omitted limit is not "unpaged", it
+    is the server's own default page, which can truncate the list. The block
+    therefore reports either the limit that was sent, or the server default
+    that was applied instead, so a consumer can always tell whether more rows
+    may exist.
+    """
+
+    if limit is None:
+        return {
+            "kind": "server_default",
+            "server_default_limit": server_default,
+            "returned_count": returned,
+            "continuation": None,
+        }
+    return {"kind": "limit", "limit": limit, "returned_count": returned, "continuation": None}
+
+
 def list_sessions(dependencies: AmsDependencies, target: TenantTarget, *, limit: int | None = None) -> dict:
     """`hc ams sessions list`: the caller's non-expired sessions, newest first."""
 
@@ -576,12 +676,7 @@ def list_sessions(dependencies: AmsDependencies, target: TenantTarget, *, limit:
         _target(target),
         {
             "sessions": projections,
-            "page": {
-                "kind": "limit",
-                "limit": limit,
-                "returned_count": len(projections),
-                "continuation": None,
-            },
+            "page": _page(limit, SESSION_LIMIT_DEFAULT, len(projections)),
         },
         read_only=True,
     )
@@ -653,13 +748,26 @@ def _message_conflict(error: BaseException, session_id: str) -> SessionWriteRefu
 
 
 def _not_implemented(error: BaseException, *, session: bool) -> SessionWriteRefused | None:
+    """A 501 is the server saying it does not serve this write yet.
+
+    Both routes report the 501 the server actually sent rather than asserting
+    the requested mode was the cause; implement mode is named as the documented
+    reason, not as a certainty.
+    """
+
     if getattr(error, "status_code", None) != 501:
         return None
-    what = "Sessions in" if session else "Messages in"
+    if session:
+        return SessionWriteRefused(
+            "unsupported",
+            "The server does not serve this session write yet (it answered 501, not implemented); the "
+            "write was refused and no changes were made. Implement mode is the documented reason: "
+            "implement-mode authoring is not available from this server yet.",
+        )
     return SessionWriteRefused(
         "unsupported",
-        f"{what} implement mode are not available from this server yet; the write was refused and "
-        "no changes were made.",
+        "The server does not serve this message write yet (it answered 501, not implemented); no "
+        "message was added. Implement-mode messages are not available from this server yet.",
     )
 
 
@@ -748,12 +856,7 @@ def list_messages(
         _target(target, session_id),
         {
             "messages": projections,
-            "page": {
-                "kind": "limit",
-                "limit": limit,
-                "returned_count": len(projections),
-                "continuation": None,
-            },
+            "page": _page(limit, MESSAGE_LIMIT_DEFAULT, len(projections)),
         },
         read_only=True,
     )
@@ -982,7 +1085,7 @@ def generate_plan(
         except HealthCloudNetworkError:
             raise PlanReviewRefused("transport", UNKNOWN_PLAN_OUTCOME) from None
         except HealthCloudHTTPError as error:
-            refusal = _plan_write_refusal(error, session_id=session_id, plan_id=None)
+            refusal = _plan_write_refusal(error, kind="generate", session_id=session_id, plan_id=None)
             if refusal is not None:
                 raise refusal from error
             raise
@@ -1016,7 +1119,7 @@ def get_plan(dependencies: AmsDependencies, target: TenantTarget, plan_id: str,
                 "was lost. Nothing was written; retry the read when the service is reachable.",
             ) from None
         except HealthCloudHTTPError as error:
-            refusal = _plan_write_refusal(error, session_id=None, plan_id=plan_id)
+            refusal = _plan_write_refusal(error, kind="get", session_id=None, plan_id=plan_id)
             if refusal is not None:
                 raise refusal from error
             raise

{healthcloud_cli-3.7.6 → healthcloud_cli-3.7.8}/healthcloud_cli/ams/sessions/projections.py

@@ -50,6 +50,25 @@ def attachment_projection(attachment: TuningAttachment) -> dict:
     }
 
 
+# Every review field whose value is model-generated text: the planner writes it
+# from the operator's prompt and the session context, so it is data to inspect,
+# never an instruction to follow. The review file carries this list beside the
+# values it describes (an LLM01/LLM07 marker for the human approval decision).
+MODEL_GENERATED_FIELDS = {
+    "modify": ("changes.*.why", "review_warnings[].message", "summary"),
+    "create": (
+        "definition.description",
+        "definition.greetings",
+        "definition.instructions",
+        "definition.name",
+        "definition.opening_suggestions",
+        "definition.opening_suggestions_options",
+        "review_warnings[].message",
+        "summary",
+    ),
+}
+
+
 def plan_review(target: TenantTarget, plan: TuningPlan, operation: str, diff: dict) -> dict:
     """The owner-only review artifact for one exact plan.
 
@@ -57,10 +76,17 @@ def plan_review(target: TenantTarget, plan: TuningPlan, operation: str, diff: di
     owner-only ``--out`` file and never printed: ``plan_json["original_prompt"]``
     is not projected at all, ``warnings``/``skipped_references`` are reported as
     counts rather than bodies, and file actions keep attachment IDs only.
+
+    The summary, the per-change ``why``, the proposed instructions/greetings and
+    the advisory findings are model-generated free text: the file marks them as
+    such with ``content_origin`` and ``model_generated_fields`` so the operator
+    approving it treats them as untrusted data, not as instructions.
     """
 
     review = {
         "schema_version": 1,
+        "content_origin": "model-generated",
+        "model_generated_fields": sorted(MODEL_GENERATED_FIELDS[operation]),
         "target": {
             "environment": target.environment,
             "tenant_id": target.tenant_id,

{healthcloud_cli-3.7.6 → healthcloud_cli-3.7.8}/healthcloud_cli/ams/windows_files.py

@@ -95,6 +95,20 @@ def _user_sid() -> str:
         _close(token)
 
 
+class PrivateHandleRefused(ValueError):
+    """A Windows handle check refused the file, with a value-free reason.
+
+    A distinct type (not a plain ``ValueError``) so a reader can report the real
+    reason — ``not_owner_only`` or ``not_regular``, the same vocabulary the POSIX
+    reader uses — instead of collapsing every refusal into "cannot be read".
+    Neither the message nor the reason ever names the path, the owner or an ACE.
+    """
+
+    def __init__(self, reason: str, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
 def _require_private(handle, user_sid: str) -> None:
     owner, acl, descriptor = _P(), _P(), _P()
     status = _get_security(
@@ -104,7 +118,7 @@ def _require_private(handle, user_sid: str) -> None:
         raise ctypes.WinError(status)
     try:
         if not owner or _sid_string(owner) != user_sid or not acl:
-            raise ValueError("Owner-only Windows DACL required")
+            raise PrivateHandleRefused("not_owner_only", "Owner-only Windows DACL required")
         count = ctypes.cast(acl, ctypes.POINTER(_Acl)).contents.count
         for index in range(count):
             ace = _P()
@@ -114,7 +128,9 @@ def _require_private(handle, user_sid: str) -> None:
                 continue
             # Only ordinary ACCESS_ALLOWED_ACE grants to the current user are accepted.
             if kind != 0 or _sid_string(ace.value + 8) != user_sid:
-                raise ValueError("Private Windows files must not grant access to other principals")
+                raise PrivateHandleRefused(
+                    "not_owner_only", "Private Windows files must not grant access to other principals"
+                )
     finally:
         _free(descriptor)
 
@@ -195,7 +211,7 @@ def open_file(path: Path, *, private: bool = False, create: bool = False) -> int
         info = (w.DWORD * 2)()  # FILE_ATTRIBUTE_TAG_INFO
         _check(_file_info(handle, 9, info, ctypes.sizeof(info)))
         if _file_type(handle) != 1 or info[0] & (0x10 | 0x400):  # Disk files only; no directories or reparse points.
-            raise ValueError("Regular non-reparse Windows file required")
+            raise PrivateHandleRefused("not_regular", "Regular non-reparse Windows file required")
         if user is not None:
             _require_private(handle, user)
         fd = msvcrt.open_osfhandle(handle, (os.O_WRONLY if create else os.O_RDONLY) | os.O_BINARY)

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

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