Role Transition User Approval Prompt Template

This prompt is designed for product teams building human-in-the-loop (HITL) agent handoffs. Use it when your orchestrator has determined that a role transition is necessary, but policy, risk level, or regulation requires explicit user consent before the handoff executes. The prompt generates a clear, user-facing message that explains why the change is happening, what the new role will access, what the user should expect, and how they can approve or decline. This is not a prompt for deciding whether a handoff should occur. That decision belongs to your orchestrator logic and role transition validation prompts. This prompt handles the communication layer: turning a machine-level handoff decision into a trustworthy user interaction.

The ideal user is an AI product engineer or platform developer integrating this prompt into an agent harness. The required context includes the current role name, the proposed role name, the reason for the transition, the new role's capabilities and data access scope, and the user's available actions (approve, decline, ask questions). You must also provide the system's transparency policy level—whether the system should disclose technical details or keep the explanation high-level. This prompt is essential for regulated deployments, high-risk actions, financial services, healthcare workflows, and any product where transparency and user control are non-negotiable.

Do not use this prompt when the handoff is low-risk, purely internal, or already covered by a blanket user agreement. Do not use it to decide if a handoff is safe—that's the job of a Role Transition Validation Prompt. Do not use it for agent-to-agent handoffs where no user is in the loop. If your product operates in a jurisdiction requiring specific consent language (e.g., GDPR, HIPAA), you must review the generated message against your legal requirements. This prompt produces the message text; your application must handle the consent capture, timeout, and escalation logic. Always log the generated message, the user's response, and the timestamp for audit trails.

This template produces a structured approval request that explains why a role change is needed, what the new role will access, and what the user should expect. It is designed for human-in-the-loop agent handoffs where transparency and consent are required before the system transitions control to a different sub-agent with elevated permissions or different data access scope. Replace every square-bracket placeholder with live data from your orchestrator and session state before sending the prompt to the model.

textCopy
You are generating a user-facing approval request for a role transition in an AI-assisted application. Your output must be clear, honest, and actionable. Do not minimize risks or overpromise capabilities.

Generate an approval request using the following inputs:

CURRENT_ROLE: [CURRENT_ROLE_NAME]
CURRENT_ROLE_DESCRIPTION: [CURRENT_ROLE_DESCRIPTION]
PROPOSED_ROLE: [PROPOSED_ROLE_NAME]
PROPOSED_ROLE_DESCRIPTION: [PROPOSED_ROLE_DESCRIPTION]
TRANSITION_REASON: [WHY_TRANSITION_IS_NEEDED]
NEW_ACCESS_SCOPE: [WHAT_DATA_OR_TOOLS_THE_NEW_ROLE_CAN_ACCESS]
ACCESS_SCOPE_DIFFERENCE: [WHAT_CHANGES_FROM_CURRENT_ACCESS]
EXPECTED_OUTCOME: [WHAT_THE_USER_SHOULD_EXPECT_AFTER_TRANSITION]
OPT_OUT_PATH: [HOW_THE_USER_CAN_DECLINE_AND_WHAT_HAPPENS_IF_THEY_DO]
REGULATORY_CONTEXT: [APPLICABLE_REGULATIONS_OR_COMPLIANCE_NOTES_OR_NONE]

OUTPUT_SCHEMA:
{
  "approval_request": {
    "title": "string (brief heading for the approval dialog)",
    "summary": "string (one-sentence explanation of what is changing)",
    "whats_happening": "string (plain-language description of the role transition)",
    "why_now": "string (reason the transition is needed at this point)",
    "what_changes": {
      "new_capabilities": ["string (list of new actions the role can take)"],
      "new_data_access": ["string (list of data categories the role can access)"],
      "limitations": ["string (list of what the role still cannot do)"]
    },
    "risks_and_considerations": ["string (honest list of risks, limitations, or things to watch)"],
    "opt_out": {
      "available": true,
      "how_to_decline": "string (specific action the user takes to decline)",
      "what_happens_if_declined": "string (what the system will do instead)"
    },
    "regulatory_note": "string or null (compliance disclosure if applicable)",
    "consent_language": "string (explicit consent statement the user must agree to)"
  }
}

CONSTRAINTS:
- Use plain language suitable for a non-technical user.
- Do not hide risks behind optimistic language.
- If REGULATORY_CONTEXT is not NONE, include a specific compliance disclosure.
- The consent_language field must be a clear, standalone statement that can be presented next to an 'I Agree' button.
- If OPT_OUT_PATH indicates no opt-out is available, set opt_out.available to false and explain why.
- Never claim the new role can do something not listed in NEW_ACCESS_SCOPE.
- If the transition involves personal, financial, health, or legal data, add a specific warning in risks_and_considerations.

Adapt this template by adjusting the OUTPUT_SCHEMA fields to match your application's approval dialog design. If your product requires multi-language support, add a [LOCALE] placeholder and include translation instructions in the constraints. For regulated deployments, ensure the REGULATORY_CONTEXT field is populated from your compliance layer and that the generated regulatory_note is reviewed by a human before display. Always log the full prompt, the generated approval request, and the user's consent decision for audit purposes. If the model produces an approval request that minimizes risks or omits the opt-out path, reject the output and retry with a stronger constraint on honesty and completeness.

This prompt is not a standalone chat interaction; it is a synchronous gate inside a multi-agent orchestration pipeline. The application must invoke it immediately after the orchestrator decides a role transition is necessary but before the handoff executes. The prompt receives the proposed transition details, the current session context, and the user's communication preferences, and it returns a structured approval request payload. The calling system is responsible for rendering this payload to the user, capturing the user's decision, and enforcing the outcome—either proceeding with the handoff or routing to the opt-out path. Because this prompt governs a human-in-the-loop control point, the harness must treat it as a blocking operation with a defined timeout and a safe default behavior (typically: deny the transition if no user response is received).

The implementation should wrap the model call in a validation layer that checks the output against a strict JSON schema before the approval request is shown to the user. Required fields include transition_summary, new_role_name, new_role_access_list, expected_behavior_change, consent_prompt_text, opt_out_instructions, and transparency_notice. If the model returns malformed JSON, missing required fields, or an opt_out_instructions field that is empty or vague, the harness should retry once with a repair prompt that includes the validation error. After two failures, the system must escalate to a fallback approval template (a pre-reviewed static message) and log the incident for prompt debugging. For regulated deployments, add a human review queue step: any approval request where the new_role_access_list includes scopes marked as sensitive in the application's policy config must be reviewed by a human operator before the user ever sees it. This prevents the model from accidentally promising access it shouldn't.

Model choice matters here. The prompt requires instruction-following precision and structured output reliability, not creative fluency. Use a model with strong JSON mode or structured output support (e.g., GPT-4o with response_format, Claude 3.5 Sonnet with tool-use-as-structured-output, or equivalent). Set temperature low (0.0–0.2) to minimize variation in consent language. Log every invocation: the input context hash, the model version, the raw output, the validation result, the rendered approval text shown to the user, the user's decision, and the timestamp. This audit trail is essential for compliance reviews and for debugging cases where users report confusing or misleading transition messages. Wire the user's decision back into the orchestrator as a boolean gate (transition_approved: true/false) with the timestamp and any user-provided notes. If the user opts out, the orchestrator must route to the opt_out_path specified in the original transition plan, not silently continue. The prompt is the gate; the harness enforces it.