Dogwood Authorization
Dogwood Authorization evaluates a Dogwood policy set before each tool call. Dogwood is Cedar with temporal conditions, so a policy can decide based on what the agent already did in this session, not only on the call in front of it. Approve a refund after a fraud check ran. Allow a delete once the record was read.
For access control that depends only on the current call, use Cedar Authorization instead. It has no wasm peer dependency and both SDKs support it.
How it works
Section titled “How it works”The handler spans both halves of a tool call. Before the call it submits a request event
and enforces the verdict. After the call it records a response event, or an error
event if the tool threw, which is what later temporal rules match against.
| Dogwood concept | Maps to | Example |
|---|---|---|
| Principal | User identity | User::"alice" |
| Action | Tool name | Action::"search" |
| Resource | The agent itself | Resource::"agent" |
| context.input | Tool arguments | { query: "quarterly report" } |
| Event history | Calls and results so far | formerly within 1h …::response{} |
A generated schema declares its actions and entities at the top level, so policies name
Action::"search" and the default principal is User::"anonymous". Pass
namespace: 'Acme' to declare them under your own domain instead, which every rule then
qualifies as Acme::Action::"search". A hand-written actionSchema declares its own
namespace, so the option is only valid with tools.
Policies are default deny: a tool with no matching permit is blocked, and the agent
receives the denial reason as feedback.
Basic usage
Section titled “Basic usage”import { Agent, tool } from '@strands-agents/sdk'import { DogwoodAuthorization } from '@strands-agents/sdk/vended-interventions/dogwood'import { z } from 'zod'
const dogwood = new DogwoodAuthorization({ policies: 'permit(principal, action == Action::"search", resource);', tools: [searchTool, deleteTool],})
const agent = new Agent({ tools: [searchTool, deleteTool], interventions: [dogwood],})
await agent.invoke('Search for quarterly reports, then delete record 42')// search runs; delete_record is denied because no permit matches itPassing tools generates the Cedar action schema from your tool specs, and the
constructor type-checks the policy set against it. A misspelled tool name, in a permit
or inside a temporal predicate, throws immediately rather than leaving the rule silently
unenforced. Pass actionSchema instead when you maintain the schema yourself.
Generated action ids are the tool names verbatim, so every tool name must be a legal Cedar
identifier. A name containing -, ., or a space fails schema generation and throws.
A hand-written actionSchema must declare the entity types the handler actually sends:
Resource for the resource, which is always Resource::"agent" under whatever namespace
the schema declares, and User for the default principal. A policy that names an entity
type the schema does not declare fails validation in the constructor.
A condition compares the tool arguments as the model emitted them, and a generated schema
is typed to match: write context.input.method == "DELETE" for a z.enum() parameter and
context.input.retries > 3 for a z.number() one. A misspelled value is just another
string, so it fails to match rather than failing to compile.
Reading a parameter the tool does not mark required needs a has guard,
context has input.retries && context.input.retries == 3, or the constructor throws. A
z.number() parameter is declared as a whole number, so comparing a fractional argument
with <, >, <=, or >= is an evaluation error and denies the call. Equality is
unaffected: == 3 simply does not match 3.5. See the
Dogwood language reference for the full type
rules.
Rules that depend on history
Section titled “Rules that depend on history”when temporal conditions match against the event history the handler accumulates:
import { Agent, tool } from '@strands-agents/sdk'import { DogwoodAuthorization } from '@strands-agents/sdk/vended-interventions/dogwood'import { z } from 'zod'
const dogwood = new DogwoodAuthorization({ policies: ` permit(principal, action == Action::"search", resource);
permit(principal, action == Action::"delete_record", resource) when temporal { formerly within 1h Action::"search"::response{} }; `, tools: [searchTool, deleteTool],})
const agent = new Agent({ tools: [searchTool, deleteTool], interventions: [dogwood], // The default concurrent executor decides every call in a turn before recording // any result, so the rule above would not see the search when the model emits // both calls at once. toolExecutor: 'sequential',})
// Denied: nothing has been searched yet in this sessionawait agent.invoke('Delete record 42')
// Permitted: the search completed less than an hour agoawait agent.invoke('Find record 42, then delete it')Match on response events for rules that mean “this already happened and finished”, and
on error events for “this failed”. Dogwood records an event into history before deciding
it, so a rule written against request events also matches the call being decided and
satisfies itself on the first call.
A rule that unlocks one tool with another’s response needs the calls ordered. The
default concurrent tool executor decides every call in a turn before recording any
result, so the rule above does not fire when the model emits both calls at once. Set
toolExecutor: 'sequential' on the agent, as the example does, and each call is decided
after the previous one has been recorded.
Each recorded event carries the action, the principal, and the tool’s arguments, so a
temporal predicate can key on an argument, as in response{ input.query: "audit" }. It
does not carry the tool’s return value: a predicate on a result field, such as
response{ output.hits: 0 }, type-checks cleanly against a tool that declares an
outputSchema and then never matches, so the rule looks enforced and silently is not.
The same holds for the requestId and sessionId fields the default event schema
declares. Write response{} or error{}, optionally narrowed by input.*.
Dogwood itself supports result-keyed rules; this handler not recording output is the
limitation, because a tool result is arbitrary content rather than a value shaped like
the declared outputSchema.
An error event is recorded only when the tool threw. A result that merely carries an
error status records nothing at all, because that is also how the executor reports a
call a later handler blocked. A tool that catches its own failure and returns an error
result, including an MCP tool returning isError: true, leaves no event in the history.
Identity and session fields
Section titled “Identity and session fields”Multi-tenant agents resolve the principal per request, and policies often need fields the tool arguments do not carry:
import { Agent, tool } from '@strands-agents/sdk'import { DogwoodAuthorization } from '@strands-agents/sdk/vended-interventions/dogwood'import { z } from 'zod'
const dogwood = new DogwoodAuthorization({ policies: ` permit(principal, action, resource) when { context.session.role == "admin" };
permit(principal, action == Action::"search", resource) when { context.session.role == "analyst" }; `, tools: [searchTool, deleteTool], principalResolver: (state) => state.userId ? { type: 'User', id: String(state.userId) } : undefined, contextEnricher: ({ invocationState }) => ({ role: String(invocationState.role ?? 'none'), }),})
const agent = new Agent({ tools: [searchTool, deleteTool], interventions: [dogwood],})
await agent.invoke('Delete record 42', { invocationState: { userId: 'alice', role: 'admin' },})
// Denied: an analyst may only searchawait agent.invoke('Delete record 42', { invocationState: { userId: 'bob', role: 'analyst' },})contextEnricher adds fields to the session group of the request context, which a
policy reads as context.session.<field>. Those fields reach the when { … } condition
only, because the event schema declares a tool’s arguments and nothing else, so a
temporal predicate cannot reference an enriched field.
Correlating history by principal needs no enricher. Every temporal predicate is pinned to the principal being decided, so one handler instance serves many users without their histories mixing: a search alice ran never unlocks a delete for bob.
When principalResolver returns undefined, the handler denies the call. No identity, no
access.
A generated schema declares User as its only principal type, qualified by namespace,
so a resolver returning any other type denies the call and a static principal of another
type throws at construction. An undeclared type is not an error to Dogwood: a rule that
scopes the principal simply never matches, so a forbid would silently not apply.
Policies in files
Section titled “Policies in files”policies and actionSchema each take either source text or a path. A value ending in
.dw or .cedarschema is read from disk:
import { DogwoodAuthorization } from '@strands-agents/sdk/vended-interventions/dogwood'
const dogwood = new DogwoodAuthorization({ policies: './policies/agent.dw', actionSchema: './policies/agent.cedarschema',})The extension is what selects file over text, so a path with any other suffix is read as source and fails to parse rather than reporting a missing file.
Files are read, parsed, and validated in the constructor. There is no re-read at runtime, so an edited policy file takes effect the next time the handler is constructed.
History and memory
Section titled “History and memory”History is never pruned, at roughly 1.7 KB per event in wasm. reset() drops it and
keeps the handler deciding:
import { Agent, tool } from '@strands-agents/sdk'import { DogwoodAuthorization } from '@strands-agents/sdk/vended-interventions/dogwood'import { z } from 'zod'
// One agent per session, because reset() clears every principal's historyconst dogwood = new DogwoodAuthorization({ policies: 'permit(principal, action == Action::"search", resource);', tools: [searchTool], principal: { type: 'User', id: 'alice' },})
const agent = new Agent({ tools: [searchTool], interventions: [dogwood] })
await agent.invoke('Search for quarterly reports')
// The session is over: forget what the agent did, keep the policy setdogwood.reset()Calling reset() means holding the handler in a variable, as the example does, rather
than constructing it inline in the interventions array: an agent exposes no way to
reach an intervention back once it is built.
reset() clears every principal the instance has decided for, not one user’s history.
A multi-tenant handler that resets when one session ends discards everyone else’s, and
interventions are fixed at construction, so isolating histories means one agent per
session rather than one handler per session.
History lives in memory only. It does not survive a process restart, and it is not part of an agent’s session state, so a resumed conversation starts with an empty history and a rule waiting on an earlier call will not fire.
When a decision fails closed
Section titled “When a decision fails closed”Dogwood forces a deny on any evaluation error and clears the determining rules, so an error means something went wrong rather than the policy saying no. The handler reports the two cases with different denial reasons.
Tool arguments come from the model, so a request event can be malformed by a prompt. A decision that throws is treated as no decision and denies. A wasm trap denies that call and every call after it, since a trapped module cannot be trusted to decide anything.
onError controls what happens when the handler itself throws, for example when
principalResolver raises:
'throw'(default): rethrows to the caller'deny': treats the failure as a denial'proceed': runs the tool with no authorization check
Installation
Section titled “Installation”Dogwood evaluation runs in wasm through an optional peer dependency:
npm install @strands-agents/sdk @aws/dogwood-wasmThe handler imports @aws/dogwood-wasm at module load, so the import throws when the
package is missing. The module is about 9.4 MB on disk (2.9 MB gzipped).
Dogwood’s authors describe the implementation as a reference interpreter rather than a production one, and the wasm bindings inherit that, so treat this handler as experimental.
Dogwood policy syntax
Section titled “Dogwood policy syntax”For the temporal operators, information providers, and event schema DSL, see the Dogwood language reference.