# STEWARD Agent Team and Deterministic Routing

## Implementation contract for Hermes

**Product:** STEWARD — Hospital & Clinic Administrator Mission Control  
**Lane:** `hospital_clinic_administration`  
**Namespace:** `hcadmin_steward.*`  
**Home:** My STEWARD  
**Default agent state:** `PERM-P0 Disabled`

Implement the STEWARD agent layer as a visible, permissioned assistance system. It must never operate as an invisible executive, autonomous command center, or substitute for an accountable administrator and the organization's official systems.

The local application must remain fully useful when no AI backend is connected. Mission, project, task, evidence, note, review, export, import, backup, and continuous-improvement functions must work without AI. Agent controls may activate only after a real Hermes or approved OpenAI-compatible backend passes health and capability checks. Never substitute canned text, delayed sample responses, simulated tool activity, or fabricated citations for a missing backend.

## 1. Canonical agent registry

Create exactly these ten suggested agents. Installation registers their definitions but grants no execution permission.

| ID | Agent | Narrow objective | Install state | Proposed maximum if separately approved |
|---|---|---|---|---|
| `AGT-01` | Source & Requirement Verifier | Verify publisher, exact title, version, status, applicability, conflicts, review date, and expiry for approved sources. | `PERM-P0 Disabled` | `PERM-P2 Private Approved Read-Only` |
| `AGT-02` | Executive Brief & Scenario Drafter | Draft option-neutral decision briefs, assumption ledgers, sensitivity questions, and pre-mortems from approved inputs. | `PERM-P0 Disabled` | `PERM-P2 Private Approved Read-Only` |
| `AGT-03` | Portfolio & Dependency Mapper | Normalize approved initiative records and expose dependencies, capacity conflicts, missing owners, benefits, and stop rules. | `PERM-P0 Disabled` | `PERM-P2 Private Approved Read-Only` |
| `AGT-04` | Access & Flow Aggregate Analyst | Analyze approved aggregates with measure definitions, small-cell rules, uncertainty, balancing measures, and no patient rows. | `PERM-P0 Disabled` | `PERM-P3 Institution-Approved Read or Sandbox` |
| `AGT-05` | Financial Scenario Analyst | Calculate traceable, non-transactional scenarios from finance-approved inputs and explicit assumptions. | `PERM-P0 Disabled` | `PERM-P3 Institution-Approved Read or Sandbox` |
| `AGT-06` | Workforce Evidence Analyst | Analyze approved workforce aggregates without employee profiling, individual scoring, assignment, or adequacy conclusions. | `PERM-P0 Disabled` | `PERM-P3 Institution-Approved Read or Sandbox` |
| `AGT-07` | Quality, Policy & Control Crosswalk Assistant | Map current requirements to approved policies, owners, controls, and evidence while leaving applicability and sufficiency to qualified humans. | `PERM-P0 Disabled` | `PERM-P3 Institution-Approved Read or Sandbox` |
| `AGT-08` | Change, Accessibility & Communications Assistant | Draft accessible internal change materials, learning aids, and feedback plans without sending or publishing. | `PERM-P0 Disabled` | `PERM-P2 Private Approved Read-Only` |
| `AGT-09` | Resilience Exercise Facilitator | Facilitate clearly synthetic continuity and downtime exercises and prepare after-action drafts from approved plans. | `PERM-P0 Disabled` | `PERM-P2 Private Approved Read-Only` |
| `AGT-10` | Independent Agent Auditor & Kill Sentinel | Evaluate frozen agent versions, surface violations, and prepare kill, rollback, purge, and retirement evidence. | `PERM-P0 Disabled` | `PERM-P2 Separate-Control-Plane Read-Only` |

The proposed maximum is a hard ceiling, not an active grant or a recommendation to grant it. A run may be approved at a lower level. No role, title, prompt, dashboard control, or agent may raise the ceiling. `AGT-10` must run through a separate control path, cannot approve itself or another agent, cannot change permissions, and cannot be the sole evidence for release.

## 2. Permission model

Keep installation state, proposed maximum, approved permission, and current run state as separate fields.

| Level | Meaning | Enforcement rule |
|---|---|---|
| `PERM-P0 Disabled` | Registered but unable to execute | Default for all ten agents; no inference, retrieval, tool use, background work, or model call |
| `PERM-P1 Private Nonsensitive or Synthetic Draft` | Public, owner-created nonsensitive, or unmistakably synthetic input; draft only | No connectors, external actions, official-system access, PHI, personnel records, or confidential institutional data |
| `PERM-P2 Private Approved Read-Only` | One exact owner-controlled or approved read-only source; draft only | No write, send, publish, schedule, connector mutation, or consequential release |
| `PERM-P3 Institution-Approved Read or Sandbox` | One approved partition, purpose, dataset, owner, sandbox, and retention rule | Separate institutional authorization, human review, and reconciliation are mandatory |
| `PERM-P4 One-Run Staged Administrative Write` | One approved, nonbinding draft to one named non-authoritative destination | Per-run confirmation and named-human release; none of the ten agents has P4 as its proposed maximum in this release |
| `PERM-P5 Prohibited` | High-impact, production, self-expanding, hidden, or otherwise prohibited action | Cannot be enabled by configuration, policy exception, prompt, title, or administrator request |

The effective permission for a run is always the most restrictive result of:

1. the agent's proposed maximum;
2. the current human-approved permission;
3. the user's verified active hat and delegated authority;
4. the current EDENA classification and edition policy;
5. the allowed data class and partition;
6. the backend's verified capabilities;
7. the destination's approval and action policy; and
8. any organizational or local deny rule.

Unknown or conflicting values reduce permission; they never expand it.

## 3. Agent lifecycle and run state

Implement the following state machine:

`Disabled → Preview → One-Run Approved → Running → Human Review → Completed or Revised → Disabled`

`Preview` displays the frozen definition, proposed route, charter, controls, and tests. It performs no model inference, retrieval, or tool call while the agent remains `PERM-P0 Disabled`.

Also support `Paused`, `Blocked`, `Killed`, `Failed`, and `Retired` terminal or recovery states. Invalid state jumps must fail closed and create a nonsensitive denial receipt.

Every agent requires an ORBIT charter containing:

- one narrow objective and named human owner;
- beneficiary, affected people, and non-goals;
- active hat and authority source with expiry;
- EDENA tier and explanation;
- allowed and prohibited data classes;
- approved sources, tools, and destinations;
- actual permission and proposed maximum;
- model/provider and frozen agent version;
- time, token, and cost limits;
- required normal, failure, missing-source, bias, privacy, security, prompt-injection, permission, cost, and recovery tests;
- human checkpoints and final release owner;
- stop conditions, manual fallback, incident route, expiry, kill, rollback, purge, and retirement method.

No agent may approve, score as sole judge, modify, delegate to, reactivate, or retire itself.

## 4. Deterministic routing pipeline

Routing must be explainable, reproducible, and testable. Do not route by model intuition alone. Implement this sequence in application code before any model call:

1. **Establish context.** Read the selected role dashboard, active hat, entity/site/service, mission, current ADPIE stage, intended artifact, requested action, data class, edition, and EDENA tier.
2. **Run the preliminary CHART gate.** A `Block` or `Emergency Stop & Official Route` prevents agent routing. A `Question` routes to the human clarification queue, not to an agent.
3. **Normalize the task intent.** Map it to one primary route key from the table below. Do not infer a consequential intent from ambiguous text.
4. **Calculate route and run eligibility separately.** The canonical table may identify a suggested agent while it is still P0; show that route as `Suggested — setup or approval required`. Mark it ineligible to run if it is disabled, unapproved for the data/partition, above its permission ceiling, incompatible with the EDENA tier, missing a healthy backend, expired, untested, or outside the active hat's authority. Never perform a model call merely to calculate routing.
5. **Apply the explicit override, if present.** An override may select only an agent compatible with the normalized task and must include the user's reason. A P0 agent may be selected for definition preview but cannot run. The override changes the suggested primary selection; it never changes risk, data, authority, tools, eligibility, or permission.
6. **Apply deterministic tie-breaking.** Prefer the most specific matching route. If two routes remain equally specific, require the user to choose; do not use a hidden score.
7. **Show a Routing Card.** Display the selected agent, route key, reason, alternatives considered, rejected candidates and reasons, actual permission, maximum permission, allowed inputs/tools/destination, EDENA result, approvals, cost/time cap, and stop control.
8. **Require confirmation.** A route is not a run. Obtain the required one-run confirmation before execution.
9. **Execute once and return to review.** Stream real output and visible tool events. On finish, failure, cancellation, or timeout, revoke the run grant and return the agent to Disabled unless a separately approved persistent session policy says otherwise.

### Canonical primary route table

| Route key | Task or intended artifact | Primary agent |
|---|---|---|
| `source_requirement` | Source freshness, publisher/version/status, claim verification, applicability questions | `AGT-01` |
| `executive_decision` | Options brief, decision packet, assumption ledger, scenario comparison, pre-mortem | `AGT-02` |
| `portfolio_dependency` | Initiative portfolio, dependency map, owner/capacity conflict, benefit gate | `AGT-03` |
| `access_flow_aggregate` | Aggregate access, demand, capacity, queue, flow, bottleneck, balancing measures | `AGT-04` |
| `financial_scenario` | Budget, forecast, variance, sensitivity, resource scenario | `AGT-05` |
| `workforce_aggregate` | Aggregate workload, capacity, skill-mix, vacancy, turnover, culture evidence | `AGT-06` |
| `quality_policy_control` | Quality, safety, accreditation-readiness, policy, control, evidence crosswalk | `AGT-07` |
| `change_communication` | Change impact, accessibility, learning, adoption, internal communication draft | `AGT-08` |
| `resilience_exercise` | Synthetic emergency, continuity, downtime, recovery, after-action exercise | `AGT-09` |
| `agent_assurance` | Agent evaluation, control test, incident review, kill, rollback, purge, retirement evidence | `AGT-10` |

If the intended artifact spans several domains, choose the agent responsible for the artifact's principal decision question. Other agents may be proposed as sequential supporting reviewers, never silently invoked as a fan-out. When no route matches, set `route=human_unassigned`, preserve the mission locally, and ask the user to select a workflow or continue without AI.

### Deterministic examples

- “Check whether this CMS requirement is current” routes to `AGT-01`, not `AGT-07`, because source validity precedes crosswalk work.
- “Map the verified requirement to our approved policy and evidence” routes to `AGT-07`; it may require an earlier or separately approved `AGT-01` verification receipt.
- “Compare three staffing-model scenarios using approved aggregate data” routes to `AGT-06`, not `AGT-02`; the final executive option brief may later route to `AGT-02`.
- “Draft a plain-language rollout message from an already approved plan” routes to `AGT-08`. Sending remains prohibited.
- “Evaluate whether another agent respected its charter” routes to `AGT-10`. The evaluated agent cannot be selected as its own auditor.

## 5. User-selectable override

Provide an Agent selector on every AI-enabled mission and artifact surface. It must show:

- `Auto — deterministic route`;
- each currently eligible agent;
- disabled or ineligible agents as visible but unavailable, with a plain-language reason; and
- `Continue without AI`.

An override requires a short reason and produces a `routing_override` receipt with the automatic route, selected route, user ID, active hat, timestamp, EDENA tier, permission, and decision. Selecting a disabled agent may open only its preview and enablement checklist. The system must reject any preview-to-run transition that would bypass a CHART result, EDENA requirement, data boundary, proposed maximum, separation-of-duties rule, missing approval, or unhealthy backend.

## 6. Multi-agent work

Do not activate a multi-agent chain as a user's first agent run. Multi-agent orchestration is allowed only when:

- each agent has passed its individual test suite at the requested permission;
- each step has a narrow objective, bounded input/output contract, and named human owner;
- a visible graph defines the order, handoffs, stop rules, budgets, and data allowed at each edge;
- the user approves the complete graph and each consequential checkpoint;
- intermediate artifacts remain labeled as drafts and retain provenance;
- no agent can add another agent, tool, connector, destination, or permission;
- `AGT-10` is independent of the run and cannot be the orchestrator; and
- cancellation, kill, rollback, and orphan cleanup are tested for the complete graph.

Prefer sequential human-reviewed handoffs over autonomous fan-out. The human is the orchestration owner.

## 7. Runtime transparency

The Agent Console must display in real time:

- connection and capability health;
- selected profile and model without exposing secrets;
- selected agent and routing reason;
- current objective, EDENA tier, permission, budget, and expiry;
- approved sources and data class;
- tool request, approval status, start, result, and failure events;
- streaming response state;
- pending human approval requests;
- Stop, Cancel, Pause All, and Kill controls; and
- the final receipt and return-to-Disabled status.

Do not expose chain-of-thought. Show concise decision summaries, source provenance, tool facts, assumptions, uncertainty, and enforcement reasons.

## 8. Receipts and audit events

Use append-only, tamper-evident run receipts. Each receipt must include:

- receipt, mission, artifact, role-dashboard, agent, and session IDs;
- frozen agent/config/model/backend versions;
- automatic route, override, and routing reason;
- active hat, authority source, and expiry;
- edition, EDENA tier/reason, CHART result, and ORBIT charter ID;
- actual permission and proposed maximum;
- allowed data classes, source references, tool IDs, and destination;
- input and output hashes, not sensitive content in the audit index;
- start/end timestamps, cost/time/token totals, and termination reason;
- human approvals, review decision, and acknowledgment;
- before/after state hashes;
- rollback, purge, correction, and official-reconciliation references; and
- `no_background_work_remaining` verification.

The receipt records what the software did. It does not establish organizational authority, regulatory compliance, clinical validity, accreditation, or approval.

## 9. Failure, stop, and recovery

- **Stop/Cancel:** interrupt the current stream and tool sequence, revoke the one-run grant, preserve a minimal failure receipt, and leave the local artifact editable.
- **Pause All:** prevent every new model call, tool call, scheduled action, connector use, and agent transition while retaining non-AI local work.
- **Kill:** terminate the selected agent or graph, cancel work, revoke temporary credentials and tool grants, purge ephemeral state, check for orphan tasks, and report verified status.
- **Rollback:** restore a verified local configuration or artifact version. Never claim that software rollback reversed an external real-world action.
- **Purge:** remove temporary prompts, retrieved chunks, caches, embeddings, staged files, and ephemeral agent state according to the approved retention policy.
- **Retire:** disable the agent version, revoke permissions and connectors, archive required nonsensitive evidence, purge disallowed state, and block revival without a new charter and test cycle.

On timeout, disconnect, capability drift, model change, permission mismatch, or policy error, fail closed. Never retry a consequential tool call silently.

## 10. Required verification

Automated and manual tests must prove at minimum:

1. all ten agents install as `PERM-P0 Disabled` with the exact proposed maxima above;
2. every canonical route selects the expected agent from the same input;
3. ambiguous and unmatched work routes to human clarification or no-AI mode;
4. overrides cannot bypass authority, EDENA, partition, permission, backend, or separation-of-duties controls;
5. no agent can self-approve, self-modify, self-delegate, or raise permission;
6. `AGT-10` runs through a separate control path and cannot approve release;
7. offline mode performs no model or tool calls and shows no simulated output;
8. real configured responses stream end to end with visible source/tool events;
9. Stop, Pause All, Kill, rollback, purge, expiry, and retirement leave no background or orphan work;
10. sensitive content is absent from routing indexes, logs, analytics, badges, and receipt summaries;
11. every completed or failed run returns the temporary permission to its prior safe state; and
12. screen-reader and keyboard users can inspect, approve, stop, and review every routing and agent state.

Activation is blocked if a required enforcement path is missing, unsupported, or only represented by decorative UI.
