Security

The security layers decide which tool calls may run, isolate the ones that do, and record what happened. Turn them on when an agent can change real data or serves more than one user. Every tool call goes through a four-layer gate; each layer is configured separately and does nothing until you configure it, so you pay only for what you wire up.

Orthogonal to the tool-call gate, guardrails inspect text at the input / output / tool-result trust boundaries: injection delimiting, PII redaction, moderation, regex denylists.

Permissions and modesMode.DEFAULT / ACCEPT_EDITS / BYPASS. StandardPermissions, PerUserPermissions, custom policies, approval handlers.GuardrailsOrdered text guards at the input / output / tool_result trust boundaries. Injection delimiting, PII redaction, moderation, regex denylists.Hooks@agent.before_tool / @agent.after_tool decorators for inline review and logging.SandboxesFilesystemSandbox (path-arg validation) · SubprocessSandbox (process isolation) · OSSandbox (kernel isolation).Audit log attributionHMAC-signed JSONL with per-user_id attribution. Compliance-grade.

The four layers

1. Permissions

Decides yes / no / ask per tool call. Default AllowAll (no-op); production usually wants StandardPermissions(mode=Mode.DEFAULT), which routes destructive tools through an approval handler.

2. Hooks

@agent.before_tool runs before the call (returning a denial stops the call; a hook that raises or times out denies it too). @agent.after_tool runs after, with the ToolResult. Used for inline review, redaction, custom metrics, or whatever else doesn’t fit a standard policy.

3. Sandboxes

Wraps the tool host with isolation. FilesystemSandbox blocks path arguments that escape declared roots (symlink-aware). SubprocessSandbox runs each tool in a fresh child process for crash isolation and hard timeouts. OSSandbox adds kernel-enforced filesystem and network limits.

4. Audit log

Every tool call lands in the audit log with user_id attribution. HMAC signatures cover the entries and chain each one to the one before it, so editing, deleting, inserting or reordering entries breaks verification. See Audit log attribution.

Pick a starting profile

You want…	Start here
Dev / CI / sandbox	`permissions=StandardPermissions(mode=Mode.BYPASS)`
Single-user productivity tool	`mode=Mode.ACCEPT_EDITS` (auto-approves `write` / `edit`; other destructive tools ask), `approval_handler=...`, `audit_log=FileAuditLog(...)`
Multi-tenant SaaS	`permissions=PerUserPermissions(policies=, default=)`, `approval_handler=...`, `audit_log=...`
Coding agent with FS access	wrap tools in `FilesystemSandbox`, mode `ACCEPT_EDITS` (list custom editors in `edit_tools=`), an approval handler for `bash`, audit on

Defaults are fast. Agent ships with AllowAll permissions, no hooks, NoSandbox, and audit_log=None. The agent loop detects each layer is a no-op and skips it on the hot path. The moment you wire a real implementation, the corresponding integration point flips on. Same Agent class, same API, no flags.