Bug 1: the silent permission filter

With the trace vocabulary in hand, we can walk through the two bugs that cost us the most time. This first one is the most painful bug in our build, and it is purely operational.

Symptom: the agent "thinks" but never invokes any action. Replies like "I am verifying your identity now" with no action call. The trace shows enabled_tools: [] even though the action exists in reasoning.actions:.

Cause: the agent runs as the agent's running user (a dedicated service user), not as you the admin. That user needs Apex class access on every action class. Without it, the planner silently filters the action out of the LLM's tool list.

flowchart LR
  A["Action exists in<br/>reasoning.actions:"] --> B{"Agent user has<br/>Apex class access?"}
  B -->|"No"| C["Silently dropped<br/>from enabled_tools"]
  B -->|"Yes"| D["Visible to LLM"]

Diagnosis query

sf data query --json -q "
    SELECT Id, SetupEntityId
    FROM SetupEntityAccess
    WHERE ParentId IN (
        SELECT PermissionSetId
        FROM PermissionSetAssignment
        WHERE Assignee.Username = 'coral_cloud_experience_agent...@example.com'
    )
    AND SetupEntityType = 'ApexClass'
    AND SetupEntityId IN (SELECT Id FROM ApexClass WHERE Name = 'VerifyCustomer')
"

If totalSize: 0, the agent user cannot see the class.

Fix

<!-- force-app/main/default/permissionsets/RefundAgentActions.permissionset-meta.xml -->
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <hasActivationRequired>false</hasActivationRequired>
    <label>Refund Agent Actions</label>
    <classAccesses>
        <apexClass>VerifyCustomer</apexClass>
        <enabled>true</enabled>
    </classAccesses>
    <!-- repeat for each backing class -->
</PermissionSet>

sf project deploy start --json --metadata "PermissionSet:RefundAgentActions"
sf org assign permset --json --name RefundAgentActions \
    --on-behalf-of <agent_user_username>