feat(healthcare): coherent patient, drug-interaction check, contraindication gate

Deepen the clinical realism of the healthcare example while keeping the
FDA/NHS/MOH jurisdiction variants untouched.

- Replace the thin canned EHR data with one coherent patient: ICD-10-coded
  diagnoses, medications with dosing, documented allergies and labs. The
  clinical_decision_support differential now matches the record.
- Add ehr.drug_interaction_check, which screens a proposed treatment against
  the patient's current medications and allergies. The agent passes its result
  into the write call.
- Add a medication-contraindication forbid: a severe interaction or allergy
  contraindication blocks the treatment-plan write, alongside the existing
  EU AI Act Art. 14 high-risk human-oversight rule.
- Three scenarios (standard / high-risk / contraindication), each with a
  signed TRACE record regenerated from a real run.
- New clinical_engine module + unit tests and a CI job.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: imran-siddique

.github/workflows/ci.yml

@@ -71,6 +71,22 @@ jobs:
         if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
         run: python validate_artifacts.py
 
+  healthcare:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: healthcare
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Run clinical engine tests
+        run: python -m unittest discover -s tests -v
+
   embodied-action-receipts:
     runs-on: ubuntu-latest
     defaults:

README.md

@@ -13,7 +13,7 @@ End-to-end integration examples showing cMCP, Agent Manifest, and TRACE working
 |---|---|---|---|
 | `embodied-action-receipts/` | Fixture-style offline verification for embodied action receipts: accepted chain, missing receipt, signature mismatch and valid controller rejection | Software-only fixtures | TRACE action-receipt evidence boundary |
 | `financial-services/` | Corporate credit risk agent: six-step assessment with CDD, exposure and IFRS 9 guardrails on the write | SEV-SNP / TDX | EU AI Act Art. 9/12, CRR Art. 395, EBA/GL/2020/06, EU AML, DORA Art. 9 |
-| `healthcare/` | Clinical decision agent: EU AI Act Art. 14 HITL deny on high-risk treatment plans | SEV-SNP / TDX | EU AI Act Art. 14, HIPAA |
+| `healthcare/` | Clinical agent on a coherent ICD-10 patient: drug-interaction check feeds EU AI Act Art. 14 HITL and contraindication denies | SEV-SNP / TDX | EU AI Act Art. 14, HIPAA |
 | `industrial-embodied-ai/` | Material-movement agent with cMCP authorization, an independent safety-controller boundary and offline-verifiable closed-session evidence | TEE / software-only development mode | OT security and industrial robot safety references |
 | `multi-tenant-saas/` | HR SaaS with an EU tenant (enforcing GDPR residency/Art. 9) and a US tenant (advisory) on one catalog | TDX | GDPR Art. 6/9/44, customer DPA |
 | `startup-tpm/` | 15-minute quickstart on any cloud VM with Trusted Launch | TPM 2.0 | Development / staging |

healthcare/README.md

@@ -1,6 +1,8 @@
 # healthcare: Clinical Decision Support Agent Demo
 
-End-to-end demo of a hospital AI agent processing patient records through a cMCP Runtime with Cedar policy enforcement and signed TRACE Trust Records for healthcare regulatory compliance (EU AI Act Art. 14, HIPAA).
+End-to-end demo of a hospital AI agent running a clinical assessment through a cMCP Runtime with Cedar policy enforcement and signed TRACE Trust Records for healthcare regulatory compliance (EU AI Act Art. 14, HIPAA).
+
+The worked patient is a fictional 54-year-old with type 2 diabetes and hypertension. Diagnoses carry ICD-10 codes, medications carry dosing, and the agent runs a drug-interaction check whose result feeds the human-oversight guardrails, so a deny reflects the real safety outcome of the plan.
 
 ---
 
@@ -9,14 +11,17 @@ End-to-end demo of a hospital AI agent processing patient records through a cMCP
 **1. EU AI Act Article 14 - human oversight for high-risk AI**
 The Cedar policy blocks any treatment plan write where `patient_risk_category == "high"`. The deny response carries the policy's `@annotation` metadata as structured advice (`regulation: eu-ai-act-art-14`, `reviewer_role: attending-physician`), and the audit chain records the deny as machine-readable Art. 14 evidence.
 
-**2. HIPAA PHI protection at the tool boundary**
-All three tools are classified `compliance_domain: hipaa_phi` in the attested catalog. A Cedar rule forbids PHI tools when no attestation evidence is present, enforcing "PHI only flows through attested runtimes" at the policy layer.
+**2. A medication-safety guardrail that fires on the assessment result**
+The agent runs `ehr.drug_interaction_check` against the patient's current medications and documented allergies, then passes `has_severe_contraindication` into the write call. A Cedar rule blocks the write when a severe contraindication is present, so the guardrail acts on the actual interaction result rather than on a static flag.
+
+**3. HIPAA PHI protection at the tool boundary**
+All four tools are classified `compliance_domain: hipaa_phi` in the attested catalog. A Cedar rule forbids PHI tools when no attestation evidence is present, enforcing "PHI only flows through attested runtimes" at the policy layer.
 
-**3. Cryptographic proof of the tool call sequence**
+**4. Cryptographic proof of the tool call sequence**
 Every call is recorded in a hash-chained audit log persisted to SQLite. Closing the session seals the chain into a signed `RuntimeClaim` (the TRACE Trust Record): which tools ran, in what order, what was denied - verifiable without trusting the agent process.
 
-**4. Two demo paths**
-Run without flags for the happy path (all three calls allowed). Run with `--trigger-hitl` to see the Art. 14 block fire with the advice payload.
+**5. Three demo scenarios**
+`--scenario standard` (all four calls allowed), `--scenario high-risk` (Art. 14 block on a high-risk patient), `--scenario contraindication` (a proposed drug that the patient is allergic to blocks the write).
 
 ---
 
@@ -44,6 +49,7 @@ Run without flags for the happy path (all three calls allowed). Run with `--trig
   |   server/mock_mcp_server.py                                       |
   |   ehr.patient_record_lookup                                       |
   |   ehr.clinical_decision_support                                   |
+  |   ehr.drug_interaction_check                                      |
   |   ehr.treatment_plan_writer                                       |
   +------------------------------------------------------------------+
 ```
@@ -72,43 +78,45 @@ cd healthcare
 CMCP_DEV_MODE=1 cmcp start --config cmcp-config.yaml
 ```
 
-**Terminal 3 - happy path:**
+**Terminal 3 - the three scenarios:**
 
 ```bash
 cd examples
-python healthcare/agent/clinical_decision_agent.py
-```
+# A. standard: performing plan, no interaction -> all four steps allow
+python healthcare/agent/clinical_decision_agent.py --scenario standard
 
-Expected output:
+# B. high-risk patient -> Art. 14 human-oversight block on the write
+python healthcare/agent/clinical_decision_agent.py --scenario high-risk
 
+# C. a proposed drug the patient is allergic to -> contraindication block
+python healthcare/agent/clinical_decision_agent.py --scenario contraindication
 ```
-Patient: P-2024-008471  |  Risk category: standard
-
-[1/3] Calling ehr.patient_record_lookup ...
-      -> decision: allow
-[2/3] Calling ehr.clinical_decision_support ...
-      -> decision: allow
-[3/3] Calling ehr.treatment_plan_writer ...
-      -> decision: allow
 
-Closing session <id> and fetching the signed TRACE Trust Record ...
+Standard scenario:
 
-=== TRACE Trust Record (signed RuntimeClaim) ===
-{ "cmcp_version": "1.0", "trace": {...}, "gateway": {...}, "signature": "..." }
 ```
-
-**HITL path:**
-
-```bash
-python healthcare/agent/clinical_decision_agent.py --trigger-hitl
+Scenario: standard  |  Patient: P-2024-008471  |  Risk category: standard
+
+[1/4] ehr.patient_record_lookup ...
+      -> decision: allow  active dx: E11.9, I10, E78.5
+[2/4] ehr.clinical_decision_support ...
+      -> decision: allow  Type 2 diabetes mellitus, suboptimal glycaemic control
+[3/4] ehr.drug_interaction_check ...
+      -> decision: allow  highest_severity=none
+[4/4] ehr.treatment_plan_writer ...
+      -> decision: allow
 ```
 
+Contraindication scenario (the patient has a documented sulfonamide allergy, so proposing co-trimoxazole trips a severe contraindication):
+
 ```
-[3/3] Calling ehr.treatment_plan_writer ...
+[3/4] ehr.drug_interaction_check ...
+      -> decision: allow  highest_severity=severe
+[4/4] ehr.treatment_plan_writer ...
       -> decision: deny (POLICY_DENY)
          advice from policy:
-           id: hitl-high-risk
-           reason: human-review-required
+           id: medication-contraindication
+           reason: severe-contraindication-detected
            regulation: eu-ai-act-art-14
            reviewer_role: attending-physician
 
@@ -133,7 +141,7 @@ permit (
 };
 ```
 
-On top of the workflow-scoped permits sit two forbid rules. Annotations on a `forbid` are returned to the caller as structured advice when that rule causes a deny:
+On top of the workflow-scoped permits sit three forbid rules (high-risk human oversight, severe medication contraindication, and the HIPAA attestation gate). Annotations on a `forbid` are returned to the caller as structured advice when that rule causes a deny:
 
 ```cedar
 @id("hitl-high-risk")
@@ -150,17 +158,34 @@ forbid (
 };
 ```
 
+The second forbid blocks the write when the drug-interaction check returned a severe contraindication:
+
+```cedar
+@id("medication-contraindication")
+@reason("severe-contraindication-detected")
+@regulation("eu-ai-act-art-14")
+@reviewer_role("attending-physician")
+forbid (
+  principal,
+  action == Action::"Ehr.treatmentPlanWriter",
+  resource
+) when {
+  context.arguments has has_severe_contraindication &&
+  context.arguments.has_severe_contraindication == true
+};
+```
+
 Action names follow the cMCP convention: `ehr.treatment_plan_writer` becomes `Action::"Ehr.treatmentPlanWriter"` (PascalCase per underscore segment). Tool arguments are available under `context.arguments`.
 
 ---
 
 ## The TRACE Trust Record
 
-See `trace-output/example-trust-record.json` - captured from a real run of this demo. Key fields:
+`trace-output/` holds one signed record per scenario (`standard-trust-record.json`, `high-risk-trust-record.json`, `contraindication-trust-record.json`), captured from real runs. Verify one with `cmcp verify trace-output/high-risk-trust-record.json` (schema, signature and audit chain pass; hardware attestation fails in software-only dev mode). Key fields:
 
 | Field | Meaning |
 |---|---|
-| `trace.policy.bundle_hash` / `version` | Exactly which Cedar bundle was enforced (`clinical-hipaa-v2.1`) |
+| `trace.policy.bundle_hash` / `version` | Exactly which Cedar bundle was enforced (`clinical-safety-v3.0`) |
 | `trace.data_class` | Highest sensitivity touched in the session (`confidential`) |
 | `trace.tool_transcript.hash` | Hash of the audit chain tip covering all calls |
 | `trace.cnf.jwk` | The runtime's Ed25519 signing key (verifies `signature`) |
@@ -196,6 +221,16 @@ curl "http://localhost:8443/audit/export?session_id=<id>" | python3 -m json.tool
 
 ---
 
+## The tests
+
+`tests/test_clinical_engine.py` checks that diagnoses carry ICD-10 codes, that the differential matches the record, that an appropriate second-line agent is safe, and that a sulfonamide allergy and a drug-drug interaction are both detected.
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+---
+
 ## Regulatory Variants
 
 This demo uses EU AI Act Art. 14 and HIPAA as its primary policy example. Additional

healthcare/agent/clinical_decision_agent.py

@@ -2,34 +2,60 @@
 """
 Clinical decision support agent demo for hospital AI compliance.
 
-Calls three EHR tools through the cMCP Runtime using JSON-RPC 2.0 over HTTP,
-then closes the session to obtain the signed TRACE Trust Record.
+Runs a four-step workflow through the cMCP Runtime using JSON-RPC 2.0 over HTTP,
+then closes the session to obtain the signed TRACE Trust Record. The agent runs
+a drug-interaction check and passes its result into the write call, so the
+guardrails act on the real safety outcome.
+
+Scenarios:
+
+    --scenario standard          Add empagliflozin (second-line), standard risk.
+                                 Interaction check clean. All four steps allow.
+    --scenario high-risk         Same plan, patient_risk_category=high. The write
+                                 is blocked for human oversight (EU AI Act Art. 14).
+    --scenario contraindication  Propose co-trimoxazole for an incidental UTI.
+                                 The patient has a documented sulfonamide allergy,
+                                 so the interaction check flags a severe
+                                 contraindication and the write is blocked.
 
 Usage:
-    python clinical_decision_agent.py [--gateway http://localhost:8443] [--trigger-hitl]
-
-Without --trigger-hitl: patient_risk_category=standard, all tool calls allowed.
-With    --trigger-hitl: patient_risk_category=high, the treatment plan write is
-                         denied with EU AI Act Art. 14 advice from the Cedar policy.
+    python clinical_decision_agent.py [--gateway http://localhost:8443]
+                                      [--scenario standard|high-risk|contraindication]
 """
 
 import argparse
 import json
 import sys
 import httpx
 
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
 DEFAULT_GATEWAY = "http://localhost:8443"
 WORKFLOW_ID = "clinical-decision-support"
-
 PATIENT_ID = "P-2024-008471"
 SYMPTOMS = ["fatigue", "polyuria", "polydipsia", "blurred vision"]
-LAB_VALUES = {"fasting_glucose_mmol": 9.2, "hba1c_percent": 8.1, "bmi": 31.4}
-DIAGNOSIS = "Type 2 Diabetes Mellitus with Hypertension"
-TREATMENT = "Metformin 500mg twice daily; lisinopril 10mg once daily; HbA1c recheck in 3 months"
 
-
-def call_tool(client: httpx.Client, gateway: str, tool_name: str, arguments: dict, req_id: int) -> dict:
-    """POST a tools/call. Returns {"ok": bool, "result"/"error", "session_id"}."""
+SCENARIOS = {
+    "standard": {
+        "risk": "standard",
+        "proposed": ["empagliflozin"],
+        "treatment": "Continue metformin 500mg BID; add empagliflozin 10mg once daily; HbA1c recheck in 3 months",
+    },
+    "high-risk": {
+        "risk": "high",
+        "proposed": ["empagliflozin"],
+        "treatment": "Continue metformin 500mg BID; add empagliflozin 10mg once daily; HbA1c recheck in 3 months",
+    },
+    "contraindication": {
+        "risk": "standard",
+        "proposed": ["co-trimoxazole"],
+        "treatment": "Add co-trimoxazole 960mg BID for 3 days (incidental urinary tract infection)",
+    },
+}
+
+
+def call_tool(client, gateway, tool_name, arguments, req_id):
     payload = {
         "jsonrpc": "2.0",
         "id": req_id,
@@ -43,20 +69,17 @@ def call_tool(client: httpx.Client, gateway: str, tool_name: str, arguments: dic
     resp = client.post(f"{gateway}/mcp", json=payload, timeout=30)
     body = resp.json()
     if "error" in body:
-        return {"ok": False, "error": body["error"], "session_id": None}
+        return {"ok": False, "error": body["error"], "payload": None, "session_id": None}
     result = body["result"]
-    return {
-        "ok": True,
-        "result": result,
-        "session_id": result.get("_cmcp", {}).get("session_id"),
-    }
+    payload_text = result.get("content", [{}])[0].get("text", "{}")
+    return {"ok": True, "payload": json.loads(payload_text),
+            "session_id": result.get("_cmcp", {}).get("session_id")}
 
 
-def print_outcome(outcome: dict) -> None:
+def print_outcome(step, tool, outcome, note=""):
+    print(f"[{step}] {tool} ...")
     if outcome["ok"]:
-        meta = outcome["result"].get("_cmcp", {})
-        decision = "advisory_deny" if meta.get("would_have_denied") else "allow"
-        print(f"      -> decision: {decision}")
+        print(f"      -> decision: allow{('  ' + note) if note else ''}")
     else:
         data = outcome["error"].get("data", {})
         print(f"      -> decision: deny ({data.get('error_code', 'unknown')})")
@@ -67,48 +90,58 @@ def print_outcome(outcome: dict) -> None:
                 print(f"           {key}: {value}")
 
 
-def close_session(client: httpx.Client, gateway: str, session_id: str) -> dict:
+def close_session(client, gateway, session_id):
     resp = client.post(f"{gateway}/sessions/{session_id}/close", timeout=10)
     resp.raise_for_status()
     return resp.json()
 
 
-def run(gateway: str, trigger_hitl: bool) -> None:
-    risk_category = "high" if trigger_hitl else "standard"
+def run(gateway, scenario):
+    sc = SCENARIOS[scenario]
     print(f"Connecting to cMCP Runtime at {gateway}")
-    print(f"Patient: {PATIENT_ID}  |  Risk category: {risk_category}")
-    if trigger_hitl:
-        print("Mode: --trigger-hitl - the treatment plan write will require HITL approval")
+    print(f"Scenario: {scenario}  |  Patient: {PATIENT_ID}  |  Risk category: {sc['risk']}")
     print()
 
     session_id = None
     with httpx.Client(headers={"Content-Type": "application/json"}) as client:
-        print("[1/3] Calling ehr.patient_record_lookup ...")
         o1 = call_tool(client, gateway, "ehr.patient_record_lookup",
                        {"patient_id": PATIENT_ID, "record_type": "full"}, 1)
-        print_outcome(o1)
+        note = ""
+        if o1["ok"]:
+            dx = ", ".join(d["icd10"] for d in o1["payload"].get("active_diagnoses", []))
+            note = f"active dx: {dx}"
+        print_outcome("1/4", "ehr.patient_record_lookup", o1, note)
         session_id = o1.get("session_id") or session_id
 
-        print("[2/3] Calling ehr.clinical_decision_support ...")
         o2 = call_tool(client, gateway, "ehr.clinical_decision_support",
-                       {"patient_id": PATIENT_ID, "presenting_symptoms": SYMPTOMS,
-                        "lab_values": LAB_VALUES}, 2)
-        print_outcome(o2)
+                       {"patient_id": PATIENT_ID, "presenting_symptoms": SYMPTOMS}, 2)
+        note = ""
+        if o2["ok"] and o2["payload"].get("differential"):
+            note = o2["payload"]["differential"][0]["condition"]
+        print_outcome("2/4", "ehr.clinical_decision_support", o2, note)
         session_id = o2.get("session_id") or session_id
 
-        print("[3/3] Calling ehr.treatment_plan_writer ...")
-        o3 = call_tool(client, gateway, "ehr.treatment_plan_writer",
-                       {"patient_id": PATIENT_ID, "diagnosis": DIAGNOSIS,
-                        "treatment": TREATMENT,
-                        "patient_risk_category": risk_category}, 3)
-        print_outcome(o3)
+        o3 = call_tool(client, gateway, "ehr.drug_interaction_check",
+                       {"patient_id": PATIENT_ID, "proposed_medications": sc["proposed"]}, 3)
+        has_contra = bool(o3["payload"].get("has_severe_contraindication")) if o3["ok"] else False
+        print_outcome("3/4", "ehr.drug_interaction_check", o3,
+                      f"highest_severity={o3['payload'].get('highest_severity')}" if o3["ok"] else "")
         session_id = o3.get("session_id") or session_id
 
-        if not o3["ok"]:
+        o4 = call_tool(client, gateway, "ehr.treatment_plan_writer", {
+            "patient_id": PATIENT_ID,
+            "diagnosis": "Type 2 diabetes mellitus with hypertension",
+            "treatment": sc["treatment"],
+            "patient_risk_category": sc["risk"],
+            "has_severe_contraindication": has_contra,
+        }, 4)
+        print_outcome("4/4", "ehr.treatment_plan_writer", o4)
+        session_id = o4.get("session_id") or session_id
+
+        if not o4["ok"]:
             print()
             print("  The treatment plan was NOT written to the EHR.")
             print("  An attending physician must review and approve before the plan takes effect.")
-            print("  The audit chain records this deny for EU AI Act Art. 14 evidence.")
 
         print()
         if session_id is None:
@@ -130,7 +163,7 @@ def run(gateway: str, trigger_hitl: bool) -> None:
     parser = argparse.ArgumentParser(description="Clinical decision support agent demo")
     parser.add_argument("--gateway", default=DEFAULT_GATEWAY,
                         help=f"cMCP Runtime base URL (default: {DEFAULT_GATEWAY})")
-    parser.add_argument("--trigger-hitl", action="store_true",
-                        help="Set patient_risk_category=high to trigger the EU AI Act Art. 14 HITL deny")
+    parser.add_argument("--scenario", default="standard", choices=sorted(SCENARIOS),
+                        help="which clinical scenario to run (default: standard)")
     args = parser.parse_args()
-    run(args.gateway, args.trigger_hitl)
+    run(args.gateway, args.scenario)