Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/technical/CLINIC_AGENT_ACTION_POLICY.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

Clinic Agent Action Policy

Action Policy is the guardrail layer between tool planning (PL-003 goal/task routing) and tool execution (handler invocation). It answers more than permission checks:

• Is the user allowed to run this action class?
• Is the tool read-only or write?
• Does it require staff confirmation?
• Is it idempotent?
• Is there duplication risk on real customer/clinic data?

Execution logic keys off action class, not ad-hoc tool name string matching.

Pipeline position

User message
  → Intent classification (product)
  → Goal / task planning (PL-003)
  → Tool routing (PL-003)
  → Action Policy authorize()   ← this layer
  → Tool handler execution
  → Response composition + UI blocks

Tool classification

Tool	Action class	Mutation	Idempotent	Duplication risk
list_today_appointments	Read	read_only	yes	low
search_leads	Read	read_only	yes	low
get_admin_navigation	Navigate	read_only	yes	none
get_operational_snapshot	Sensitive	read_only	yes	medium
generate_daily_report	Sensitive	read_only	yes	medium
propose_booking_for_lead	Write	write	no	high

Action classes

• Read — relatively safe lookups (list_today_appointments, search_leads)
• Navigate — admin links and page routing (get_admin_navigation)
• Write — creates or queues mutations (propose_booking_for_lead)
• Sensitive — financial/export-grade operational data (get_operational_snapshot, generate_daily_report)

Policy decisions

ClinicToolActionPolicyEvaluator returns one of:

Status	Meaning
allowed	Handler may execute
blocked	Do not execute (permissions, unknown tool, duplicate write)
requires_confirmation	Reserved for explicit staff confirmation before execution

Blocked and confirmation-required results are returned to the LLM/runtime as structured JSON so the agent can explain the guardrail instead of failing silently.

Implementation map

Component	Role
ClinicToolActionPolicyRegistry	Canonical tool catalog + classification
ClinicToolActionPolicyEvaluator	Policy rules
ClinicToolActionPolicyGuard	Turn-scoped facade
ClinicToolActionDedupStore	Short-window dedup for non-idempotent tools
PolicyAwareProductToolHandlerBridge	Enforces policy at PL-003 handler boundary
AiToolExecutionOrchestrator	Enforces policy on local execution path
ClinicAgentOrchestrator	Binds policy context for each agent turn

Extending tools

When adding a clinic agent tool:

1. Register handler + schema in ClinicDomainToolRegistration
2. Add a policy definition in ClinicToolActionPolicyRegistry
3. Choose action class and duplication risk explicitly
4. Add unit coverage in ClinicToolActionPolicyTest

Never rely on tool name checks scattered across orchestrators — extend the registry instead.