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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/PKG-INFO +94 -35
  2. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/README.md +93 -34
  3. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/agents/commands.py +5 -4
  4. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/agents/operations.py +284 -38
  5. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/context.py +96 -0
  6. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/errors.py +5 -4
  7. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/guardrails/commands.py +5 -2
  8. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/guardrails/operations.py +115 -6
  9. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/pretty.py +26 -13
  10. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/results.py +15 -0
  11. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/pyproject.toml +1 -1
  12. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/.gitignore +0 -0
  13. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/hatch_build.py +0 -0
  14. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/__init__.py +0 -0
  15. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/admins/__init__.py +0 -0
  16. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/admins/commands.py +0 -0
  17. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/admins/group.py +0 -0
  18. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/admins/operations.py +0 -0
  19. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/__init__.py +0 -0
  20. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/agents/__init__.py +0 -0
  21. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/agents/group.py +0 -0
  22. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/agents/projections.py +0 -0
  23. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/auth.py +0 -0
  24. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/commands.py +0 -0
  25. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/compatibility.py +0 -0
  26. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/data_sources/__init__.py +0 -0
  27. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/data_sources/commands.py +0 -0
  28. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/data_sources/group.py +0 -0
  29. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/data_sources/operations.py +0 -0
  30. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/data_sources/projections.py +0 -0
  31. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/departments/__init__.py +0 -0
  32. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/departments/commands.py +0 -0
  33. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/departments/group.py +0 -0
  34. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/departments/operations.py +0 -0
  35. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/departments/projections.py +0 -0
  36. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/domain_errors.py +0 -0
  37. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/group.py +0 -0
  38. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/guardrails/__init__.py +0 -0
  39. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/guardrails/group.py +0 -0
  40. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/guardrails/projections.py +0 -0
  41. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/organization/__init__.py +0 -0
  42. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/organization/commands.py +0 -0
  43. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/organization/group.py +0 -0
  44. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/organization/operations.py +0 -0
  45. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/organization/projections.py +0 -0
  46. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/output.py +0 -0
  47. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/policies/__init__.py +0 -0
  48. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/policies/commands.py +0 -0
  49. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/policies/group.py +0 -0
  50. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/policies/operations.py +0 -0
  51. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/policies/projections.py +0 -0
  52. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/registry.py +0 -0
  53. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/session.py +0 -0
  54. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/sessions/__init__.py +0 -0
  55. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/sessions/commands.py +0 -0
  56. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/sessions/group.py +0 -0
  57. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/sessions/operations.py +0 -0
  58. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/sessions/projections.py +0 -0
  59. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/skills/__init__.py +0 -0
  60. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/skills/commands.py +0 -0
  61. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/skills/group.py +0 -0
  62. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/skills/operations.py +0 -0
  63. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/skills/projections.py +0 -0
  64. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/target.py +0 -0
  65. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/teams/__init__.py +0 -0
  66. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/teams/commands.py +0 -0
  67. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/teams/group.py +0 -0
  68. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/teams/operations.py +0 -0
  69. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/teams/projections.py +0 -0
  70. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/tools/__init__.py +0 -0
  71. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/tools/commands.py +0 -0
  72. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/tools/group.py +0 -0
  73. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/tools/operations.py +0 -0
  74. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/tools/projections.py +0 -0
  75. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/tuning.py +0 -0
  76. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/ui.py +0 -0
  77. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/ams/windows_files.py +0 -0
  78. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/cli.py +0 -0
  79. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/context.py +0 -0
  80. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/contracts/__init__.py +0 -0
  81. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/contracts/mcp-tools.manifest.json +0 -0
  82. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/main.py +0 -0
  83. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/manifest.py +0 -0
  84. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/output.py +0 -0
  85. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/params.py +0 -0
  86. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/tenants/__init__.py +0 -0
  87. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/tenants/commands.py +0 -0
  88. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/tenants/group.py +0 -0
  89. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/tenants/operations.py +0 -0
  90. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/healthcloud_cli/util.py +0 -0
  91. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/scripts/__init__.py +0 -0
  92. {healthcloud_cli-3.7.8 → healthcloud_cli-3.7.10}/scripts/bundle_manifest.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: healthcloud-cli
3
- Version: 3.7.8
3
+ Version: 3.7.10
4
4
  Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
5
5
  Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
6
6
  Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
@@ -529,14 +529,15 @@ and a missing `--agent-id` fails with one envelope on stderr and exit 1:
529
529
  ```
530
530
 
531
531
  Agent lifecycle changes are two first-class, send-once write commands. They
532
- require a saved `hc login` session (env-var credentials are not accepted for
533
- writes) and an explicit `--expected-config-version`, `--confirm` acknowledgement:
532
+ require a saved `hc login` session (the command refuses before any request when
533
+ none is saved; env-var credentials are not accepted here) and the `--confirm`
534
+ acknowledgement. `--expected-config-version` is optional:
534
535
 
535
536
  ```bash
536
537
  uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
537
- --agent-id AGENT_ID --expected-config-version N --confirm
538
+ --agent-id AGENT_ID [--expected-config-version N] --confirm
538
539
  uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
539
- --agent-id AGENT_ID --expected-config-version N --confirm
540
+ --agent-id AGENT_ID [--expected-config-version N] --confirm
540
541
  ```
541
542
 
542
543
  Each command issues exactly one `GET /agents/{agent_id}`, local pre-checks,
@@ -566,9 +567,21 @@ explicitly that
566
567
  fields — a disabled agent can still be selected by those paths — and that
567
568
  in-flight runs, WSS sessions and schedules are untouched by this route.
568
569
 
570
+ `data.config_version_check` says which concurrent-edit check actually ran:
571
+ `matched` (the read `config_version` equals `--expected-config-version`),
572
+ `not_run` (the flag was omitted, so **no** version check ran and the reviewed
573
+ target plus `--confirm` are the approval), never a silent success. It is carried
574
+ on the confirmed, refused **and** unknown envelopes alike, so an outcome where
575
+ the write may already have committed still says which check ran. A deployment
576
+ whose agent payload omits or nulls `config_version` cannot honour the flag: the
577
+ command refuses that flag with a way forward (`Re-run without
578
+ --expected-config-version`) instead of refusing every lifecycle command forever
579
+ and instead of interpolating a Python `None` repr.
580
+
569
581
  Default `pretty` output prints those facts as labelled lines — `transition`,
570
- `requested`, `evidence` (`saved`, `side_effects`, `runtime`), `eligibility`,
571
- `mutation_replayed: false` — and closes with a `verification:` block, so a
582
+ `requested`, `config_version_check`, `evidence` (`saved`, `side_effects`,
583
+ `runtime`), `eligibility`, `mutation_replayed: false` — and closes with a
584
+ `verification:` block, so a
572
585
  deactivate reads `transition: deactivate`, then
573
586
  `evidence: / saved: / status: confirmed`, then `verification: / saved_state:
574
587
  confirmed`, `side_effects: unverified`, `runtime: unverified`; it is never one
@@ -592,24 +605,45 @@ tenant, an already in-effect state, an unsupported `archived`/`draft` target
592
605
  (named as having no supported reversible transition here), or a
593
606
  `config_version` that no longer matches `--expected-config-version` — all of
594
607
  these are also enforced by the preview, which still sends nothing. A missing
595
- `--confirm` exits 2. That version check is a local best-effort
608
+ `--confirm` exits 2. An `active` value the server emits as `1`/`0`/`"true"`/
609
+ `"false"` is interpreted as a flag (an already in-effect state is still
610
+ recognised and a correct write is still confirmed); any other value is
611
+ unconfirmed, never a false success. That version check is a local best-effort
596
612
  guard only: the route has no `If-Match` and the server never compares the
597
613
  version, so it cannot prove atomicity and a request could still race between
598
614
  the read and the PUT.
599
615
 
600
- A transport error or `5xx` from the PUT is reported as `outcome: "unknown"`
601
- with `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
616
+ A transport error, a `5xx`/`408` from the PUT, or an interrupt (`Ctrl-C`) during
617
+ the PUT or the readback is reported as `outcome: "unknown"` with
618
+ `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
602
619
  `reconciliation: {"status": "not_read", …}` block; the CLI sends no retry and
603
620
  does not re-read automatically — run `hc ams agents get` before doing anything
604
621
  else. A failed readback after an accepted PUT is reported the same way (unknown,
605
622
  not success). A `2xx` PUT answer whose body cannot be read as an agent object is
606
- also `outcome: "unknown"` (sent once, saved state unverified), never an internal
607
- error and never a success.
623
+ also `outcome: "unknown"` (attempted once; the request may not have been sent
624
+ and its saved state is unverified), never an internal error and never a
625
+ success.
626
+
627
+ A non-`5xx` rejection of the PUT (`409`, `422`, `400`, `403`, …) is worded as a
628
+ **write** that the server refused, never as a read: `outcome: "failed"`,
629
+ `verification.saved_state: "failed"`, `mutation_replayed: false`, the pre-write
630
+ state under `data.evidence.saved.before`, and a `reconciliation` saying the CLI
631
+ did not re-read. A `2xx` body that is not an agent object at all (for example a
632
+ plain-text body) is a bounded `validation` refusal with the same
633
+ `verification: not_applicable` as any read, never an `AttributeError` and never a
634
+ traceback.
635
+
636
+ The saved-session requirement above is enforced at the command boundary: the
637
+ shared AMS authentication path still has the `HC_AMS_ADMIN_EMAIL`/
638
+ `HC_AMS_ADMIN_PASSWORD` tenant-admin fallback that every AMS command group uses,
639
+ so the guarantee is "these commands refuse without a saved session", not "no AMS
640
+ write anywhere can reach the server on env-var credentials".
608
641
 
609
642
  Capability and organization assignments are one first-class, send-once write
610
- command. It requires a saved `hc login` session (env-var credentials are not
611
- accepted for writes), an explicit `--expected-config-version`, and the
612
- `--confirm` acknowledgement of the target and the printed reviewed diff:
643
+ command. It requires a saved `hc login` session (the command refuses before any
644
+ request when none is saved; env-var credentials are not accepted here), an
645
+ explicit `--expected-config-version`, and the `--confirm` acknowledgement of the
646
+ target and the printed reviewed diff:
613
647
 
614
648
  ```bash
615
649
  uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
@@ -706,8 +740,9 @@ carries a reference field is refused by field name by
706
740
  capabilities.
707
741
 
708
742
  Deleting an agent is one first-class, send-once destructive command. It requires
709
- a saved `hc login` session (env-var credentials are not accepted for writes) and
710
- the `--confirm` acknowledgement of the target and disclosure block it prints:
743
+ a saved `hc login` session (the command refuses before any request when none is
744
+ saved; env-var credentials are not accepted here) and the `--confirm`
745
+ acknowledgement of the target and disclosure block it prints:
711
746
 
712
747
  ```bash
713
748
  uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \
@@ -775,7 +810,10 @@ The same unknown outcome applies when the delete was accepted but the
775
810
  confirmation read could not be read. A confirmation read that still returns the
776
811
  agent (`200`) — or a `2xx` body that cannot be read as an agent — is
777
812
  `outcome: "failed"` with `data.deleted: false` and
778
- `verification.saved_state: "failed"`, never success.
813
+ `verification.saved_state: "failed"`, never success. A confirmation read that
814
+ answers 401/403 (or any other non-404, non-2xx status) observed nothing about
815
+ the row, so `data.evidence.deleted.confirmation` is `unobserved` — the same
816
+ three-way state as the guardrail delete — and never `still_present`.
779
817
 
780
818
  Read-only department listing and inspection use the same explicit tenant-admin
781
819
  targeting. They emit one versioned JSON result on stdout; failures emit one
@@ -1487,17 +1525,19 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1487
1525
 
1488
1526
  - `create` succeeds with `operation: "guardrails.create"` and
1489
1527
  `data.guardrail` = the server's 201 readback. `--name` and
1490
- `--created-by-user-id` are required by the server contract; the tenant is
1491
- taken from the saved session's authenticated admin, never from a flag.
1492
- `--rules-file` names a regular JSON file holding the rules object with string
1493
- keys. Rules never ride argv (so they stay out of the process list) and are
1494
- never echoed: an unreadable, symlinked, duplicate-keyed or non-object file is
1495
- refused with one fixed message that does not quote its content. Rules are
1496
- write-only — they are sent but never appear in any command output, error
1497
- message or readback.
1528
+ `--created-by-user-id` are required by the server contract. The tenant comes
1529
+ from the saved session's authenticated admin; `--tenant-id` is accepted only
1530
+ as an explicit target that must match that session (a mismatch is refused
1531
+ before any request). `--rules-file` names an owner-only (0600) regular JSON
1532
+ file holding the rules object with string keys. Rules never ride argv (so they
1533
+ stay out of the process list) and are never echoed: an unreadable, symlinked,
1534
+ non-owner-only, duplicate-keyed or non-object file is refused with one fixed
1535
+ message that does not quote its content. Rules are write-only — they are sent
1536
+ but never appear in any command output, error message or readback.
1498
1537
  - `update` sends only the options you pass (an empty `--description ""` clears
1499
1538
  it; a `--rules-file` holding `{}` sends an empty rule set); it refuses with exit 1
1500
- (`validation`) when no field option is given.
1539
+ (`validation`) when no field option is given. `create` treats an empty
1540
+ `--description ""` the same way: it is omitted rather than refused.
1501
1541
  - `delete` is a reviewed one-shot destructor and requires `--confirm`; without
1502
1542
  it the command exits 2 before login and sends nothing. With it the CLI makes
1503
1543
  exactly one `GET` for the guardrail, one `GET /agents` and one `GET /policies`
@@ -1509,9 +1549,15 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1509
1549
  confirmed` for a 404, `data.deleted: false` with `saved_state: failed` when
1510
1550
  the guardrail is still served, and `outcome: unknown` with
1511
1551
  `data.mutation_replayed: false` and a `not_read` reconciliation when the
1512
- answer is 5xx or the transport fails. It never replays, retries or re-reads on
1513
- its own, and it never claims a restore: `hc ams restore` replays tuning fields
1514
- onto an existing agent and can never restore a deleted guardrail.
1552
+ answer is 5xx or the transport fails. A confirmation read that answers
1553
+ 401/403 (or any other non-404, non-2xx status) observed nothing about the row,
1554
+ so `data.evidence.deleted.confirmation` is `unobserved`, never
1555
+ `still_present`. A 2xx answer to the `DELETE` itself (a proxy or misbehaving
1556
+ server returning a body) is treated as sent, not as input validation: the one
1557
+ confirmation `GET` still decides the outcome. It never replays, retries or
1558
+ re-reads on its own, and it never claims a restore: `hc ams restore` replays
1559
+ tuning fields onto an existing agent and can never restore a deleted
1560
+ guardrail.
1515
1561
  - The server guards one reference only: an agent whose `guardrail_ids` contain
1516
1562
  the guardrail answers 409 and nothing is deleted (the CLI reports one
1517
1563
  `conflict` refusal). A policy whose `guardrail_ids` still name it is NOT
@@ -1519,7 +1565,9 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1519
1565
  that policy fails; the disclosure says so, and the printed affected references
1520
1566
  name every policy that still points at the guardrail. When the agent or policy
1521
1567
  catalog cannot be read, the delete is refused (`nothing was changed`) rather
1522
- than executed without its disclosure.
1568
+ than executed without its disclosure; the refusal category is the honest one
1569
+ (`authentication`, `authorization`, `unsupported` for a missing catalog route,
1570
+ `internal` for a server error, `transport` for a network failure).
1523
1571
  - Any other 409 on `create` or `update` is one write-worded `conflict` refusal
1524
1572
  that says the server refused the write and to review the guardrail's current
1525
1573
  server state before retrying; no changes were made.
@@ -1527,10 +1575,21 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1527
1575
  the ID; a target/tenant mismatch on a write readback is a `validation` refusal
1528
1576
  that reports the landed write truthfully: it names the guardrail and the
1529
1577
  tenant that actually received it and points to `hc ams guardrails get`.
1530
- - If the transport times out or the connection drops mid-write, the write's
1531
- outcome is unknown: the CLI reports one `transport` error whose message says
1532
- the outcome is unknown and to check `hc ams guardrails get` before retrying.
1533
- It never re-sends the write on its own.
1578
+ - If the transport times out, the connection drops mid-write, the server
1579
+ answers 5xx/408, or a 2xx write body cannot be read as a guardrail, the
1580
+ write's outcome is unknown: the CLI reports `outcome: unknown` with
1581
+ `data.mutation_replayed: false` and a `not_read` reconciliation, and its
1582
+ message says the write may have landed and to check `hc ams guardrails get`
1583
+ before retrying. It never re-sends the write on its own. That unknown envelope
1584
+ carries the shared `transport` error category for **both** a 5xx/408 answer and
1585
+ a network failure (the disclosure reads above use `internal` for a server error
1586
+ and `transport` for a network failure; the send-once write helper is shared
1587
+ across every catalog domain, so it reports one category for either).
1588
+ - A drifted installed SDK is refused before the tenant-admin login: the
1589
+ preflight checks that `create`, `update`, `delete`, `list` and `get` accept the
1590
+ exact call this CLI makes, so a renamed keyword is reported as `unsupported`
1591
+ with "Nothing was sent" instead of being mistaken for a landed write with an
1592
+ unreadable answer.
1534
1593
 
1535
1594
  Read-only tool catalog listing and inspection are complete and unpaged. The
1536
1595
  bounded projection includes only IDs, names, read-only and confirmation flags,
@@ -511,14 +511,15 @@ and a missing `--agent-id` fails with one envelope on stderr and exit 1:
511
511
  ```
512
512
 
513
513
  Agent lifecycle changes are two first-class, send-once write commands. They
514
- require a saved `hc login` session (env-var credentials are not accepted for
515
- writes) and an explicit `--expected-config-version`, `--confirm` acknowledgement:
514
+ require a saved `hc login` session (the command refuses before any request when
515
+ none is saved; env-var credentials are not accepted here) and the `--confirm`
516
+ acknowledgement. `--expected-config-version` is optional:
516
517
 
517
518
  ```bash
518
519
  uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
519
- --agent-id AGENT_ID --expected-config-version N --confirm
520
+ --agent-id AGENT_ID [--expected-config-version N] --confirm
520
521
  uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
521
- --agent-id AGENT_ID --expected-config-version N --confirm
522
+ --agent-id AGENT_ID [--expected-config-version N] --confirm
522
523
  ```
523
524
 
524
525
  Each command issues exactly one `GET /agents/{agent_id}`, local pre-checks,
@@ -548,9 +549,21 @@ explicitly that
548
549
  fields — a disabled agent can still be selected by those paths — and that
549
550
  in-flight runs, WSS sessions and schedules are untouched by this route.
550
551
 
552
+ `data.config_version_check` says which concurrent-edit check actually ran:
553
+ `matched` (the read `config_version` equals `--expected-config-version`),
554
+ `not_run` (the flag was omitted, so **no** version check ran and the reviewed
555
+ target plus `--confirm` are the approval), never a silent success. It is carried
556
+ on the confirmed, refused **and** unknown envelopes alike, so an outcome where
557
+ the write may already have committed still says which check ran. A deployment
558
+ whose agent payload omits or nulls `config_version` cannot honour the flag: the
559
+ command refuses that flag with a way forward (`Re-run without
560
+ --expected-config-version`) instead of refusing every lifecycle command forever
561
+ and instead of interpolating a Python `None` repr.
562
+
551
563
  Default `pretty` output prints those facts as labelled lines — `transition`,
552
- `requested`, `evidence` (`saved`, `side_effects`, `runtime`), `eligibility`,
553
- `mutation_replayed: false` — and closes with a `verification:` block, so a
564
+ `requested`, `config_version_check`, `evidence` (`saved`, `side_effects`,
565
+ `runtime`), `eligibility`, `mutation_replayed: false` — and closes with a
566
+ `verification:` block, so a
554
567
  deactivate reads `transition: deactivate`, then
555
568
  `evidence: / saved: / status: confirmed`, then `verification: / saved_state:
556
569
  confirmed`, `side_effects: unverified`, `runtime: unverified`; it is never one
@@ -574,24 +587,45 @@ tenant, an already in-effect state, an unsupported `archived`/`draft` target
574
587
  (named as having no supported reversible transition here), or a
575
588
  `config_version` that no longer matches `--expected-config-version` — all of
576
589
  these are also enforced by the preview, which still sends nothing. A missing
577
- `--confirm` exits 2. That version check is a local best-effort
590
+ `--confirm` exits 2. An `active` value the server emits as `1`/`0`/`"true"`/
591
+ `"false"` is interpreted as a flag (an already in-effect state is still
592
+ recognised and a correct write is still confirmed); any other value is
593
+ unconfirmed, never a false success. That version check is a local best-effort
578
594
  guard only: the route has no `If-Match` and the server never compares the
579
595
  version, so it cannot prove atomicity and a request could still race between
580
596
  the read and the PUT.
581
597
 
582
- A transport error or `5xx` from the PUT is reported as `outcome: "unknown"`
583
- with `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
598
+ A transport error, a `5xx`/`408` from the PUT, or an interrupt (`Ctrl-C`) during
599
+ the PUT or the readback is reported as `outcome: "unknown"` with
600
+ `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
584
601
  `reconciliation: {"status": "not_read", …}` block; the CLI sends no retry and
585
602
  does not re-read automatically — run `hc ams agents get` before doing anything
586
603
  else. A failed readback after an accepted PUT is reported the same way (unknown,
587
604
  not success). A `2xx` PUT answer whose body cannot be read as an agent object is
588
- also `outcome: "unknown"` (sent once, saved state unverified), never an internal
589
- error and never a success.
605
+ also `outcome: "unknown"` (attempted once; the request may not have been sent
606
+ and its saved state is unverified), never an internal error and never a
607
+ success.
608
+
609
+ A non-`5xx` rejection of the PUT (`409`, `422`, `400`, `403`, …) is worded as a
610
+ **write** that the server refused, never as a read: `outcome: "failed"`,
611
+ `verification.saved_state: "failed"`, `mutation_replayed: false`, the pre-write
612
+ state under `data.evidence.saved.before`, and a `reconciliation` saying the CLI
613
+ did not re-read. A `2xx` body that is not an agent object at all (for example a
614
+ plain-text body) is a bounded `validation` refusal with the same
615
+ `verification: not_applicable` as any read, never an `AttributeError` and never a
616
+ traceback.
617
+
618
+ The saved-session requirement above is enforced at the command boundary: the
619
+ shared AMS authentication path still has the `HC_AMS_ADMIN_EMAIL`/
620
+ `HC_AMS_ADMIN_PASSWORD` tenant-admin fallback that every AMS command group uses,
621
+ so the guarantee is "these commands refuse without a saved session", not "no AMS
622
+ write anywhere can reach the server on env-var credentials".
590
623
 
591
624
  Capability and organization assignments are one first-class, send-once write
592
- command. It requires a saved `hc login` session (env-var credentials are not
593
- accepted for writes), an explicit `--expected-config-version`, and the
594
- `--confirm` acknowledgement of the target and the printed reviewed diff:
625
+ command. It requires a saved `hc login` session (the command refuses before any
626
+ request when none is saved; env-var credentials are not accepted here), an
627
+ explicit `--expected-config-version`, and the `--confirm` acknowledgement of the
628
+ target and the printed reviewed diff:
595
629
 
596
630
  ```bash
597
631
  uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
@@ -688,8 +722,9 @@ carries a reference field is refused by field name by
688
722
  capabilities.
689
723
 
690
724
  Deleting an agent is one first-class, send-once destructive command. It requires
691
- a saved `hc login` session (env-var credentials are not accepted for writes) and
692
- the `--confirm` acknowledgement of the target and disclosure block it prints:
725
+ a saved `hc login` session (the command refuses before any request when none is
726
+ saved; env-var credentials are not accepted here) and the `--confirm`
727
+ acknowledgement of the target and disclosure block it prints:
693
728
 
694
729
  ```bash
695
730
  uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \
@@ -757,7 +792,10 @@ The same unknown outcome applies when the delete was accepted but the
757
792
  confirmation read could not be read. A confirmation read that still returns the
758
793
  agent (`200`) — or a `2xx` body that cannot be read as an agent — is
759
794
  `outcome: "failed"` with `data.deleted: false` and
760
- `verification.saved_state: "failed"`, never success.
795
+ `verification.saved_state: "failed"`, never success. A confirmation read that
796
+ answers 401/403 (or any other non-404, non-2xx status) observed nothing about
797
+ the row, so `data.evidence.deleted.confirmation` is `unobserved` — the same
798
+ three-way state as the guardrail delete — and never `still_present`.
761
799
 
762
800
  Read-only department listing and inspection use the same explicit tenant-admin
763
801
  targeting. They emit one versioned JSON result on stdout; failures emit one
@@ -1469,17 +1507,19 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1469
1507
 
1470
1508
  - `create` succeeds with `operation: "guardrails.create"` and
1471
1509
  `data.guardrail` = the server's 201 readback. `--name` and
1472
- `--created-by-user-id` are required by the server contract; the tenant is
1473
- taken from the saved session's authenticated admin, never from a flag.
1474
- `--rules-file` names a regular JSON file holding the rules object with string
1475
- keys. Rules never ride argv (so they stay out of the process list) and are
1476
- never echoed: an unreadable, symlinked, duplicate-keyed or non-object file is
1477
- refused with one fixed message that does not quote its content. Rules are
1478
- write-only — they are sent but never appear in any command output, error
1479
- message or readback.
1510
+ `--created-by-user-id` are required by the server contract. The tenant comes
1511
+ from the saved session's authenticated admin; `--tenant-id` is accepted only
1512
+ as an explicit target that must match that session (a mismatch is refused
1513
+ before any request). `--rules-file` names an owner-only (0600) regular JSON
1514
+ file holding the rules object with string keys. Rules never ride argv (so they
1515
+ stay out of the process list) and are never echoed: an unreadable, symlinked,
1516
+ non-owner-only, duplicate-keyed or non-object file is refused with one fixed
1517
+ message that does not quote its content. Rules are write-only — they are sent
1518
+ but never appear in any command output, error message or readback.
1480
1519
  - `update` sends only the options you pass (an empty `--description ""` clears
1481
1520
  it; a `--rules-file` holding `{}` sends an empty rule set); it refuses with exit 1
1482
- (`validation`) when no field option is given.
1521
+ (`validation`) when no field option is given. `create` treats an empty
1522
+ `--description ""` the same way: it is omitted rather than refused.
1483
1523
  - `delete` is a reviewed one-shot destructor and requires `--confirm`; without
1484
1524
  it the command exits 2 before login and sends nothing. With it the CLI makes
1485
1525
  exactly one `GET` for the guardrail, one `GET /agents` and one `GET /policies`
@@ -1491,9 +1531,15 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1491
1531
  confirmed` for a 404, `data.deleted: false` with `saved_state: failed` when
1492
1532
  the guardrail is still served, and `outcome: unknown` with
1493
1533
  `data.mutation_replayed: false` and a `not_read` reconciliation when the
1494
- answer is 5xx or the transport fails. It never replays, retries or re-reads on
1495
- its own, and it never claims a restore: `hc ams restore` replays tuning fields
1496
- onto an existing agent and can never restore a deleted guardrail.
1534
+ answer is 5xx or the transport fails. A confirmation read that answers
1535
+ 401/403 (or any other non-404, non-2xx status) observed nothing about the row,
1536
+ so `data.evidence.deleted.confirmation` is `unobserved`, never
1537
+ `still_present`. A 2xx answer to the `DELETE` itself (a proxy or misbehaving
1538
+ server returning a body) is treated as sent, not as input validation: the one
1539
+ confirmation `GET` still decides the outcome. It never replays, retries or
1540
+ re-reads on its own, and it never claims a restore: `hc ams restore` replays
1541
+ tuning fields onto an existing agent and can never restore a deleted
1542
+ guardrail.
1497
1543
  - The server guards one reference only: an agent whose `guardrail_ids` contain
1498
1544
  the guardrail answers 409 and nothing is deleted (the CLI reports one
1499
1545
  `conflict` refusal). A policy whose `guardrail_ids` still name it is NOT
@@ -1501,7 +1547,9 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1501
1547
  that policy fails; the disclosure says so, and the printed affected references
1502
1548
  name every policy that still points at the guardrail. When the agent or policy
1503
1549
  catalog cannot be read, the delete is refused (`nothing was changed`) rather
1504
- than executed without its disclosure.
1550
+ than executed without its disclosure; the refusal category is the honest one
1551
+ (`authentication`, `authorization`, `unsupported` for a missing catalog route,
1552
+ `internal` for a server error, `transport` for a network failure).
1505
1553
  - Any other 409 on `create` or `update` is one write-worded `conflict` refusal
1506
1554
  that says the server refused the write and to review the guardrail's current
1507
1555
  server state before retrying; no changes were made.
@@ -1509,10 +1557,21 @@ uv run --frozen hc ams guardrails delete --environment dev --tenant-id TENANT_ID
1509
1557
  the ID; a target/tenant mismatch on a write readback is a `validation` refusal
1510
1558
  that reports the landed write truthfully: it names the guardrail and the
1511
1559
  tenant that actually received it and points to `hc ams guardrails get`.
1512
- - If the transport times out or the connection drops mid-write, the write's
1513
- outcome is unknown: the CLI reports one `transport` error whose message says
1514
- the outcome is unknown and to check `hc ams guardrails get` before retrying.
1515
- It never re-sends the write on its own.
1560
+ - If the transport times out, the connection drops mid-write, the server
1561
+ answers 5xx/408, or a 2xx write body cannot be read as a guardrail, the
1562
+ write's outcome is unknown: the CLI reports `outcome: unknown` with
1563
+ `data.mutation_replayed: false` and a `not_read` reconciliation, and its
1564
+ message says the write may have landed and to check `hc ams guardrails get`
1565
+ before retrying. It never re-sends the write on its own. That unknown envelope
1566
+ carries the shared `transport` error category for **both** a 5xx/408 answer and
1567
+ a network failure (the disclosure reads above use `internal` for a server error
1568
+ and `transport` for a network failure; the send-once write helper is shared
1569
+ across every catalog domain, so it reports one category for either).
1570
+ - A drifted installed SDK is refused before the tenant-admin login: the
1571
+ preflight checks that `create`, `update`, `delete`, `list` and `get` accept the
1572
+ exact call this CLI makes, so a renamed keyword is reported as `unsupported`
1573
+ with "Nothing was sent" instead of being mistaken for a landed write with an
1574
+ unreadable answer.
1516
1575
 
1517
1576
  Read-only tool catalog listing and inspection are complete and unpaged. The
1518
1577
  bounded projection includes only IDs, names, read-only and confirmation flags,
@@ -93,10 +93,11 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
93
93
  @_agent
94
94
  @click.option(
95
95
  "--expected-config-version",
96
- required=True,
97
96
  type=int,
98
- help="The config_version read before the write. A local best-effort guard only: the route has no "
99
- "If-Match, so it never proves atomicity.",
97
+ default=None,
98
+ help="Optional: the config_version read before the write. A local best-effort guard only, because "
99
+ "the route has no If-Match. Omitting it runs no version check and says so in the envelope; a "
100
+ "deployment that reports no config_version refuses the flag rather than the whole command.",
100
101
  )
101
102
  @click.option(
102
103
  "--confirm",
@@ -111,7 +112,7 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
111
112
  environment: str | None,
112
113
  tenant_id: str | None,
113
114
  agent_id: str,
114
- expected_config_version: int,
115
+ expected_config_version: int | None,
115
116
  confirm: bool,
116
117
  ) -> None:
117
118
  target_data = {