integrate-arcjet-guard-mastra

Integrate Arcjet Guard into a Mastra agent

@arcjet/guard's Mastra v1 namespace wraps the agent's existing Arcjet client. It never talks to the Arcjet API itself. Four surfaces, one decision rule:

• An authored tool (createTool({ execute })) → guardTool(). DENY is a structured tool result. Do not throw.
• Inbound / outbound text (inputProcessors / outputProcessors) → guardProcessor(). processInput + abort() on DENY raises a tripwire. processInputStep screens later agentic steps (tool continuations). Channels already hit processInput, so there is no guardInbound.
• MCP / workspace / toolsets you did not wrap → guardHooks(). beforeToolCall can return { proceed: false, output }.
• Correlation → mastraAgentContext() reads MASTRA_THREAD_ID_KEY, then resource, then run. It never mints a new id.

Mastra requireApproval is human HITL, not policy — same trap as Google ADK requireConfirmation. There is no guardApproval. Do not also wrap these tools with @arcjet/guard/vercel-ai/v7 or @arcjet/guard/claude-managed-agents/v0.

Questions to ask the human first

Ask only what you cannot infer from the code; suggest defaults.

1. Which tools are risky (external side effects, irreversible, spends money, sends messages)? Those get guardTool. Purely informational tools can be left unguarded or gated with no rules.
2. What limits? (e.g. "10 lookups/min per order" → tokenBucket.)
3. Who is the user for metadata — an opaque user/tenant ID (never PII)? Default: Mastra's resource id (MASTRA_RESOURCE_ID_KEY).
4. Is an Arcjet outage unacceptable? Every helper defaults to onGuardError: "deny". Ask explicitly about the inbound processor: failing closed there means the agent stops answering for the duration of the outage, so "allow" is a routine and legitimate choice at that one call site.

The six things readers get wrong

1. There is no guardInbound. Mastra channels already run through processInput. Screen prompt injection on guardProcessor in inputProcessors.
2. There is no guardApproval. Mastra requireApproval is a human in-the-loop pause, not a policy gate. Use guardTool or guardHooks.
3. The import path is versioned and there is no alias. @arcjet/guard/mastra/v1. @arcjet/guard/mastra does not resolve.
4. Correlation is read, never minted. Do not call createAgentContext inside a Mastra callback — that generates a second id and splits the Sequence. mastraAgentContext reads thread / resource / run and omits correlationId when none of those is a valid id.
5. Do not double-wrap with @arcjet/guard/vercel-ai/v7. Mastra tools are createTool, not AI SDK tool(). guardTool throws if the tool already carries the Arcjet protection brand.
6. A denial from guardTool is a structured result, not a throw. Prefer omitting outputSchema on guarded tools, or verify the schema accepts ArcjetDenialResult. If onDeny throws, the tool still does not run and the model still receives the default denial object.