Role Transition Validation Prompt Template

This prompt is a programmatic gate for your orchestrator, not a conversational suggestion. Its sole job is to produce a machine-readable decision—approve, deny, or request_preconditions—before any role transition executes. You need this when your system has defined roles with explicit permission boundaries and you must prevent unauthorized escalation, scope violation, or context contamination during handoffs. The ideal user is a safety engineer or orchestrator builder who already has role manifests, permission scopes, and transition policies in place. If you are still sketching out what your agents can do, this prompt is premature; it enforces rules, it does not invent them.

Do not use this prompt for simple, stateless routing where no permission boundary exists. If every agent can access every tool and data source, a validation gate adds latency without reducing risk. Similarly, avoid this prompt for purely user-initiated transitions that carry no automated enforcement—if a user clicks a button to switch modes and the system has no policy to check, you are adding a decision point with nothing to decide. This prompt is most valuable in compound AI systems where a sub-agent's capabilities exceed the current role's scope, where tool access is gated, or where regulatory or compliance constraints require auditable proof that a transition was evaluated before it occurred.

Before wiring this prompt into your orchestrator, ensure you have three artifacts ready: a role manifest declaring each role's capabilities and constraints, a permission scope mapping roles to allowed tools and data, and a transition policy defining which source roles can hand off to which target roles under what conditions. The prompt will reference these by ID, not by description. If your policies live only in prose documents, invest the time to structure them into machine-readable objects first. Once deployed, pair this prompt with an audit log that records every decision, the policy version evaluated, and the reason for denial. In regulated environments, a human reviewer should be able to replay a transition request and reach the same conclusion.

This prompt template acts as a policy enforcement gate before any role handoff executes in a multi-agent system. It receives the current agent state, the proposed target role, and the governing policy constraints, then produces a structured validation decision. The output is designed to be consumed by an orchestrator's control flow—not by an end user—so the schema is strict and machine-readable. Use this template when the cost of an unauthorized escalation, scope violation, or context contamination is higher than the latency of an extra validation call.

textCopy
You are a Role Transition Validator. Your only job is to decide whether a proposed role handoff is permitted given the current state, the target role's declared capabilities, and the active policy constraints. You do not execute the handoff. You do not modify state. You output only a structured decision.

## Current State
- Active Role: [CURRENT_ROLE]
- Active Permissions: [CURRENT_PERMISSIONS]
- Pending Work: [PENDING_WORK_SUMMARY]
- Session Constraints: [SESSION_CONSTRAINTS]
- Recent Tool Calls: [RECENT_TOOL_CALLS]

## Proposed Transition
- Target Role: [TARGET_ROLE]
- Target Permissions: [TARGET_PERMISSIONS]
- Reason for Handoff: [HANDOFF_REASON]
- Requesting Agent: [REQUESTING_AGENT_ID]

## Policy Rules (in priority order)
[POLICY_RULES]

## Validation Checks
For each check below, determine PASS or FAIL with a brief reason. A single FAIL in a BLOCKING check means the transition is denied.

1. **Permission Escalation Check (BLOCKING):** Does the target role request permissions that exceed the current role's scope without explicit policy allowance?
2. **Scope Boundary Check (BLOCKING):** Does the handoff reason fall within the target role's declared capability boundary?
3. **Precondition Check (BLOCKING):** Are all required preconditions for this handoff satisfied? Check for missing approvals, incomplete work, or unresolved decisions that must be completed first.
4. **Context Contamination Risk (WARNING):** Does the pending work or recent tool output contain data that the target role should not receive?
5. **Policy Conflict Check (BLOCKING):** Does any active session constraint or policy rule explicitly forbid this transition?
6. **Idempotency Check (WARNING):** Has this exact handoff already been attempted and failed? If so, flag for escalation.

## Output Schema
Return ONLY valid JSON matching this schema:
{
  "transition_permitted": boolean,
  "blocking_failures": [
    {
      "check_name": string,
      "reason": string,
      "recommended_action": string
    }
  ],
  "warnings": [
    {
      "check_name": string,
      "detail": string
    }
  ],
  "required_preconditions": [string],
  "escalation_required": boolean,
  "escalation_target": string | null,
  "decision_evidence": string
}

## Constraints
- If transition_permitted is false, blocking_failures must contain at least one entry.
- Never invent permissions or capabilities not present in the input.
- If the policy rules are ambiguous, fail closed and recommend human review.
- Do not output anything except the JSON object.

Adapt this template by replacing the policy rules block with your organization's actual role-based access control policies, capability manifests, and handoff preconditions. For high-risk domains such as healthcare, finance, or safety-critical systems, add a Human Approval Check as an additional BLOCKING check that requires an explicit approval token before any transition executes. Wire the output into your orchestrator so that a transition_permitted: false response aborts the handoff and triggers the escalation path defined in escalation_target. Log every validation decision—including warnings—for audit and debugging, because silent denials make multi-agent failures nearly impossible to diagnose.

The Role Transition Validation prompt is not a standalone decision-maker; it is a policy gate that must sit between the orchestrator's intent to hand off work and the actual execution of that handoff. In a production compound AI system, this prompt should be called synchronously before any context serialization, agent dispatch, or user notification occurs. The orchestrator passes the current session state, the proposed target role, the reason for transition, and the active policy constraints into the prompt. The output is a structured validation decision—permit, deny, or escalate—that the orchestrator must enforce programmatically. Do not rely on the model's refusal alone; the application layer must hard-block denied transitions and log every decision for auditability.

Wire this prompt into your agent framework as a pre-handoff hook. The orchestrator should construct the prompt payload with: [CURRENT_ROLE] and its declared capabilities, [TARGET_ROLE] and its permission boundary, [TRANSITION_REASON] from the orchestrator's planning step, [SESSION_STATE_SUMMARY] containing active constraints and pending approvals, and [POLICY_DOCUMENT] defining escalation rules and scope boundaries. The model returns a JSON object with fields decision (permit|deny|escalate), reason, violations (array of specific policy breaches), and required_approvals (list of human sign-offs needed). Your harness must validate this JSON against a schema before acting on it. If the output fails schema validation, retry once with a stricter format instruction; if it fails again, default to deny and escalate to a human operator. For high-risk domains such as healthcare or finance, always require human approval when decision is escalate or when violations is non-empty.

Model choice matters here. Use a model with strong instruction-following and low hallucination rates on structured classification tasks—GPT-4o, Claude 3.5 Sonnet, or equivalent. Avoid smaller models that may conflate permit with escalate under ambiguous policy language. Set temperature=0 to maximize decision consistency. Log the full prompt, the raw model response, the parsed decision, and any schema validation errors to your observability platform. This log becomes your audit trail for governance reviews and incident postmortems. If your orchestrator supports it, attach a trace ID that links the validation decision to the subsequent handoff execution or denial, so you can measure whether denied transitions were ever attempted downstream. The most common production failure is an orchestrator ignoring a deny decision due to a missing enforcement check—ensure your harness treats the validation output as authoritative and non-bypassable.