integrate-arcjet-guard-strands-agents

# Integrate Arcjet Guard into a Strands Agents app

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

- **An authored tool** (`tool({ callback })`) → `guardTool()`. After
  `tool()` the object is a `FunctionTool` / `ZodTool` whose runner path
  is `_callback` (`stream()` / `invoke()`). DENY returns a plain
  `ArcjetDenialResult`. Do not throw. Do not fabricate a
  `ToolResultBlock`.
- **MCP / unwrapped / vended tools** → `guardHooks()`. A Plugin whose
  `initAgent` registers `BeforeToolCallEvent` at
  `HookOrder.SDK_FIRST - 1`. On DENY it sets `event.cancel` to
  `JSON.stringify(ArcjetDenialResult)`. Already-branded tools are
  skipped. Do **not** use `BeforeToolsEvent.cancel` (that skips
  per-tool hooks).
- **Correlation** → `strandsAgentContext()` reads a field the
  integrator put on `invocationState` (`correlationId`, then
  `sessionId`, then `requestId`). It never mints a new id. It never
  reads `traceId`. It never uses `SessionManager` or `agent.id`.

This namespace is JS **`@strands-agents/sdk` `Agent` + `tool({
callback })` + Plugin / `addHook`**. Not the Python SDK. Do not also
wrap the same tool with `@arcjet/guard/vercel-ai/v7` or
`@arcjet/guard/langgraph/v1`. Zod is their peer, not ours.

## Screen inbound before `invoke()` / `stream()` — there is no inbound hook.

There is no first-class inbound channel, so there is no `guardInbound`.
Put prompt-injection (and other inbound rules) in the application
before `agent.invoke()` / `stream()`. Middleware / model hooks are not
this policy gate.

## `interrupt()` is not a policy gate.

`event.interrupt()` is human-in-the-loop. Same trap as Mastra
`requireApproval`, Claude `canUseTool`, LangGraph `interrupt()`,
OpenAI Agents `needsApproval`, and LangChain
`humanInTheLoopMiddleware`. There is no `guardApproval` /
`guardInterrupt`. Do not wrap `interrupt()` as Guard.

## Deny with `BeforeToolCallEvent.cancel` (and `guardTool` on authored callbacks). `BeforeToolsEvent.cancel` skips per-tool hooks — do not use it.

The authored `callback` is the deny point for tools you own. MCP,
vended tools, and anything not wrapped with `guardTool` skip that
callback. `guardHooks` is the invoke-wide gate for those. Official:
set `event.cancel` to a string; `tool.stream()` does not run;
`AfterToolCallEvent` still fires.

Do not use `BeforeToolsEvent.cancel`. A truthy value skips
`_toolExecutor.execute()`, so per-tool hooks never run.

## 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`. MCP / vended / tools
   you did not author get `guardHooks`.
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: none. Pass it via `metadata` on the policy. Put the
   conversation / session id you already have on
   `agent.invoke(..., { invocationState: { sessionId } })` *and* on
   `guardHooks({ sessionId })`. That id is the correlation id, not the
   user.
4. Is an Arcjet outage unacceptable? Every helper defaults to
   `onGuardError: "deny"`. Ask explicitly about inbound screening before
   `invoke()`: failing closed there means the agent does not run 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`.** Screen prompt injection before
   `agent.invoke()` / `stream()`. Middleware / model hooks are not Guard.
2. **`interrupt()` is not a policy gate.** It is HITL. Use `guardTool`
   or `guardHooks`. A denial is `event.cancel = JSON.stringify(...)`,
   not an `InterruptError`.
3. **The import path is versioned and there is no alias.**
   `@arcjet/guard/strands-agents/v1`. `@arcjet/guard/strands-agents`
   does not resolve.
4. **Correlation is read, never minted.** Do not call `createAgentContext`
   inside a hook — that generates a second id and splits the Sequence.
   Put the id you already chose on `invocationState`. Do not read
   `traceId`. Do not use `SessionManager` or `agent.id`.
5. **Do not use `BeforeToolsEvent.cancel`.** It skips the per-tool
   hooks that `guardHooks` registers. Deny on `BeforeToolCallEvent`.
6. **A denial from `guardTool` is a structured object, not a throw.**
   Wrap both `_callback` and ZodTool's `_functionTool._callback`.
   Returning a plain `ArcjetDenialResult` is correct; `FunctionTool`
   wraps objects in a `JsonBlock`. Do not fabricate a
   `ToolResultBlock`. Do not double-wrap with
   `@arcjet/guard/vercel-ai/v7` or `@arcjet/guard/langgraph/v1`.

## Step 1: Install and find the guard client

Install `@arcjet/guard` (required), plus `@strands-agents/sdk` (optional
peer, needed for `@arcjet/guard/strands-agents/v1`). Always use the
versioned path: `@arcjet/guard/strands-agents/v1` resolves;
`@arcjet/guard/strands-agents` throws
`ERR_PACKAGE_PATH_NOT_EXPORTED`. Zod is Strands' peer, not ours —
install `zod` only if the app already uses it. Node 22+.

```sh
npm install @arcjet/guard @strands-agents/sdk
```

If the agent has no guard client yet, launch one **once at module scope**:

```ts
import { launchArcjet } from "@arcjet/guard";

export const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });
```

## Step 2: Gate authored tools

```ts
import { tool } from "@strands-agents/sdk";
import { z } from "zod";
import { guardTool } from "@arcjet/guard/strands-agents/v1";
import { tokenBucket, localDetectSensitiveInfo } from "@arcjet/guard";

import { arcjet } from "./arcjet.js";

const lookupLimit = tokenBucket({
  refillRate: 10,
  intervalSeconds: 60,
  maxTokens: 10,
});
// Factory then text — same shape as `detectPromptInjection()(text)`.
// Scan free-text args (a note, reason, body). An opaque `orderNumber`
// will