Permission-Aware Error Message Prompt

This prompt is designed for developer experience (DX) and platform engineering teams who are building tool-augmented agents that interact with a permissioned execution layer. The core job-to-be-done is translating a raw, machine-readable permission denial event—such as an IAM policy rejection, a scoped API key error, or a role-based access control block—into a clear, actionable, and safe user-facing message. The ideal user is an AI application developer who needs their agent to explain what the user cannot do and why in plain language, without exposing internal resource identifiers, policy names, or the architecture of the permission system itself. This is a security-first communication task, not a generic error-formatting exercise.

You should use this prompt when your agent's tool-calling loop receives a structured denial event that you can parse into the required input fields: the action attempted, the resource type, and the specific permission string that was missing. The prompt is most effective when the denial event is already authenticated and the system has confirmed the user's identity and role. It is not a substitute for authentication failures, network timeouts, or malformed tool inputs. The prompt assumes that the agent legitimately attempted an action, the system correctly blocked it, and the only remaining task is to inform the user without aiding an attacker in reconnaissance. A concrete implementation would wire this prompt into the agent's error-handling middleware, triggered only when a 403 or PermissionDenied exception is caught from the tool execution layer.

Do not use this prompt for debugging internal errors, logging raw stack traces for developers, or handling authentication failures where the user's identity is unknown. It is also the wrong tool if your goal is to suggest alternative actions the user can take; that requires a separate capability-discovery prompt. The primary risk to manage is information leakage. Before deploying, you must validate that the output does not reveal internal resource IDs, policy names, or the existence of resources the user should not know about. The next step after implementing this prompt is to build an evaluation harness that specifically tests for this leakage, using a red-team approach that feeds the prompt with denials for non-existent resources to ensure the output remains generic and safe.

This prompt template is designed to be wired into your agent's error-handling path. When a tool invocation returns a permission-denied status, this prompt instructs the model to produce a user-facing message that explains what was blocked and why in plain language, while strictly avoiding any disclosure of internal permission models, role names, or system architecture. The goal is to maintain user trust through transparency without creating a security information leak. Replace each square-bracket placeholder with your application's specific values before sending the prompt to the model.

textCopy
You are an error message generator for a production AI agent. Your only job is to convert a permission-denied tool error into a safe, helpful user-facing message.

## CONTEXT
- User Request: [USER_REQUEST]
- Blocked Tool: [TOOL_NAME]
- Blocked Action: [BLOCKED_ACTION]
- Permission Required: [REQUIRED_PERMISSION]
- System Policy Reference: [POLICY_REFERENCE]

## CONSTRAINTS
1. Never mention internal role names, permission model details, or system architecture.
2. Do not suggest workarounds that involve escalating privileges or bypassing controls.
3. If the user's intent could be fulfilled by a permitted alternative, suggest it.
4. If no alternative exists, clearly state the action cannot be performed and direct the user to [ESCALATION_CONTACT].
5. Maintain a helpful, professional tone. Do not apologize excessively.
6. Output ONLY the user-facing message. No JSON, no metadata, no commentary.

## OUTPUT FORMAT
A single plain-text message suitable for display in a chat interface or error toast.

## EXAMPLES
User Request: "Delete the production database"
Blocked Tool: database_admin.delete_cluster
Blocked Action: DeleteCluster
Permission Required: database.admin.write
Policy Reference: ProductionGuardrail-v2
Output: I can't delete the production database because this action requires elevated permissions that aren't available in this session. If you need to perform this operation, please contact the database administration team through the standard change request process.

User Request: "Show me Q4 revenue numbers"
Blocked Tool: analytics.query
Blocked Action: RunQuery
Permission Required: analytics.finance.read
Policy Reference: FinanceDataPolicy-v1
Output: I wasn't able to pull the Q4 revenue numbers because access to financial data requires additional authorization. You can request access through the finance data portal, or I can help you with other analytics queries that don't involve financial datasets.

To adapt this template for your application, replace the placeholders with values from your actual permission-denied error payload. The [REQUIRED_PERMISSION] field should contain the human-readable permission name, not the internal enum or role ID. The [POLICY_REFERENCE] is optional but useful for audit trails—include it if your system logs policy identifiers alongside denials. Before deploying, run this prompt through your eval suite with at least 20 adversarial test cases that attempt to extract internal permission details from the generated messages. If any output reveals role names, permission hierarchies, or system internals, tighten the constraints or add explicit negative examples to the prompt.

This prompt is designed to sit inside an agent's error-handling path, not as a standalone chat interface. When a tool call returns a permission-denied error (HTTP 403, an IAM exception, or a policy engine rejection), the raw error payload is passed into this prompt's [PERMISSION_ERROR_PAYLOAD] placeholder along with the [REQUESTED_ACTION] and [ACTIVE_ROLE_SCOPE]. The prompt's job is to produce a user-facing message that explains the denial without leaking internal resource identifiers, policy ARNs, or stack traces. Wire it as a post-tool-call hook: the agent framework catches the exception, extracts the structured error fields, invokes the LLM with this prompt, and then surfaces the sanitized output to the user or logs it for support review.

Validation and safety checks are mandatory before the output reaches a user. After the LLM generates the error message, run a regex or lightweight classifier to detect leaked internal identifiers (e.g., resource IDs, account numbers, IAM role names, or file paths). A second check should confirm the message contains an actionable next step—such as 'contact your administrator to request the [permission_name] permission'—rather than a generic 'access denied.' If either check fails, fall back to a static safe message and flag the raw output for human review. For high-sensitivity environments, log the full prompt input, model response, and validation result to an audit store with the session ID and timestamp. This creates a traceable record of what the model saw and what it produced, which is essential for compliance reviews and debugging permission-boundary gaps.

Model choice and retry behavior matter here. This prompt is instruction-following and schema-constrained, so it works well with models that have strong system-prompt adherence (e.g., Claude 3.5 Sonnet, GPT-4o). Avoid small or instruction-weak models that may ignore the [OUTPUT_SCHEMA] and return unstructured text. If the model returns malformed JSON or a message that fails the leakage check, retry once with the same prompt but prepend a brief correction instruction: 'Your previous response was invalid. Ensure the output matches the required schema exactly and contains no internal identifiers.' If the retry also fails, escalate to the static fallback message and log the failure for prompt debugging. Do not retry more than once in the user-facing path—latency is noticeable here, and a stuck retry loop on an error message is worse than a generic but safe fallback.