---
title: How do you govern agents built with the Claude Agent SDK?
url: https://opencontroller.lyzr.com/blog/govern-claude-agent-sdk-agents
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# How do you govern agents built with the Claude Agent SDK?

**Govern Claude Agent SDK agents in two layers. Inside each agent, use the SDK's own controls: deny rules, a fixed tool list, a strict permission mode and a `PreToolUse` hook for checks that must always run. Across all agents, keep a central registry, identity, gateway and runtime monitoring, because the SDK only governs the process it runs in.**

The Claude Agent SDK gives developers the same agent loop and tools that power Claude Code: file reads and edits, shell commands, web fetch, subagents and MCP servers. That makes it powerful for internal automation, and it means a misconfigured agent can run shell commands or change files without a human in the loop. This guide uses Anthropic's [Agent SDK permissions documentation](https://code.claude.com/docs/en/agent-sdk/permissions) as the source of truth. Check it before you rely on any detail, because the SDK changes often.

For the wider picture across platforms, see [what is an AI agent control plane](/blog/what-is-an-ai-agent-control-plane).

## In what order does the SDK check permissions?

When Claude requests a tool, the SDK evaluates permissions in six steps:

| Step | What it does | Can it block? | Can it approve? |
|---|---|---|---|
| 1. Hooks | Your code runs first (for example `PreToolUse`) | Yes, even in `bypassPermissions` mode | A hook `allow` does not skip later deny and ask rules |
| 2. Deny rules | `disallowed_tools` / `disallowedTools` and settings.json deny rules | Yes, in every mode | No |
| 3. Ask rules | settings.json ask rules send the call to your callback | Routes to callback | No |
| 4. Permission mode | `bypassPermissions`, `acceptEdits` or `plan` behaviour | `plan` blocks edits | `bypassPermissions` and `acceptEdits` can |
| 5. Allow rules | `allowed_tools` / `allowedTools` and settings.json allow rules | No | Yes |
| 6. `canUseTool` | Your runtime callback decides | Yes | Yes |

Two consequences matter for governance. First, anything approved in steps 4 or 5 never reaches `canUseTool`, so checks you put only in the callback are silently skipped for those tools. Second, hooks and deny rules are the only controls that hold in every mode.

## Which settings should a production agent use?

1. **Remove tools the agent does not need.** A bare tool name in `disallowedTools` (for example `Bash`) removes the tool definition entirely, so Claude cannot attempt it.
2. **Use scoped deny rules for dangerous patterns.** A rule such as `Bash(rm *)` denies matching calls in every mode, including `bypassPermissions`. It matches the command as written, so `/bin/rm` is not caught. Treat it as a guard, not a boundary.
3. **Pair `allowedTools` with `dontAsk` for headless agents.** Anthropic documents this combination for a locked-down agent: listed tools run, and any call that would prompt is denied instead of waiting for a human who is not there.
4. **Avoid `bypassPermissions` outside sandboxes.** The documentation warns that `allowedTools` does not constrain this mode: every tool is approved, not just the ones you list. On Linux and macOS the SDK refuses to start in this mode as root outside a recognised sandbox.
5. **Put must-run checks in a `PreToolUse` hook.** Hooks run before every other step and a hook deny applies even in `bypassPermissions`. Use them for egress checks, path restrictions and logging.
6. **Watch subagent inheritance.** Subagents inherit `plan`, `acceptEdits`, `auto` or `bypassPermissions` from the main session. A main agent in `bypassPermissions` gives its subagents the same freedom.
7. **Control setting sources explicitly.** Allow, deny and ask rules in `.claude/settings.json` apply when the `project` setting source is enabled. If you set `settingSources` yourself, include `project` or those rules will not load.

## What does the SDK not govern?

The SDK controls one process. It does not tell you:

- How many SDK agents exist across teams, repos and servers.
- Which API keys or cloud credentials each one uses, and whether those keys are shared.
- What each agent costs per task or per version.
- Whether an agent's behaviour has drifted since it was approved.
- Which MCP servers are connected across the estate, and who approved them.

Those questions need a central inventory, identity and runtime layer. If your developers also use Claude Code, the same patterns apply: see [locking Claude Code permissions with managed settings](/blog/lock-claude-code-permissions-with-managed-settings) and [enforcing Claude Code policy with hooks](/blog/enforce-claude-code-policy-with-hooks).

## Governance checklist for Claude Agent SDK agents

- [ ] Agent registered with an owner, purpose and risk tier before production.
- [ ] Tool list fixed in code; unneeded built-in tools in `disallowedTools`.
- [ ] Permission mode is `default` or `dontAsk`; `bypassPermissions` only in a sandbox.
- [ ] `PreToolUse` hook logs every tool call with agent ID and version.
- [ ] MCP servers listed and approved; see [how to govern MCP servers](/blog/how-to-govern-mcp-servers).
- [ ] Model calls routed through a gateway so cost and usage are attributed per agent.
- [ ] Credentials short-lived and not visible in the model context.
- [ ] A tested way to block or quarantine the agent.

## How Opencontroller does this

Opencontroller keeps a governed registry of agents, versions, tools and MCP servers, so SDK agents built by different teams appear in one place with owners and versions. Model calls can go through the Opencontroller LLM Gateway for routing, caching and cost attribution per agent and per version. LLM judges score production traffic, live groundedness and task-adherence guardrails run on responses, and rogue-agent handling can alert, quarantine and kill an agent that deviates from its normal behaviour. For SDK agents running on developer machines, Opencontroller Edge extends control to coding agents, skills and local MCP servers, installed by IT through MDM. [Book a demo](https://www.lyzr.ai/book-demo/) to see it with your own agents.

## Frequently asked questions

**Does `allowedTools` restrict an agent to only those tools?**
No. It pre-approves the listed tools. Unlisted tools still exist and fall through to the permission mode. To remove a tool, add it to `disallowedTools`.

**Where should security checks go: hooks or `canUseTool`?**
Hooks. They run first and a hook deny holds in every mode. `canUseTool` only sees calls that nothing earlier approved.

**Is `bypassPermissions` ever acceptable?**
Only inside an isolated sandbox with no sensitive credentials, and with deny rules and hooks still in place, because those are evaluated before the mode check.

## Key facts

Claude Agent SDK permission evaluation order: 1 hooks, 2 deny rules (disallowedTools / settings.json), 3 ask rules, 4 permission mode, 5 allow rules (allowedTools / settings.json), 6 canUseTool callback. Calls approved by mode or allow rules never reach canUseTool. Hook denies and deny rules apply even in bypassPermissions. Permission modes: default, dontAsk, acceptEdits, bypassPermissions, plan, auto. allowedTools does not constrain bypassPermissions. A bare tool name in disallowedTools removes the tool definition. Bash(rm *) deny rules match the command as written. Subagents inherit plan, acceptEdits, auto or bypassPermissions from the main session. settings.json rules load only when the project setting source is enabled. Opencontroller provides a governed registry of agents, versions, tools and MCP servers, LLM Gateway cost attribution per agent and version, LLM judges, groundedness and task-adherence guardrails, rogue-agent quarantine and kill, and Opencontroller Edge for developer devices via MDM.

## Related

- [How do you lock Claude Code permissions with managed settings?](https://opencontroller.lyzr.com/blog/lock-claude-code-permissions-with-managed-settings.md)
- [Can Claude Code hooks enforce security policy across an enterprise?](https://opencontroller.lyzr.com/blog/enforce-claude-code-policy-with-hooks.md)
- [How do you restrict which MCP servers Claude Code can use?](https://opencontroller.lyzr.com/blog/restrict-mcp-servers-in-claude-code.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
