What you will be able to do
- Explain the security gaps created when an agent runs on a shared service credential instead of per-user credentials
- Keep credentials outside the agent's boundary with egress injection and an isolated proxy
- Work out which Agent SDK permission layers still apply under bypassPermissions and where a canUseTool callback is never reached
1.Shared service identity versus acting on behalf of each user
Every tool call an agent makes runs under some identity. Often that identity is a single service credential that all users share. Two gaps follow from that choice. Each user gets whatever that credential can reach, not what they personally are allowed to reach. And downstream audit logs show one service account, so nobody can tell which end user caused an action. The safer design is for the agent to act as each user, holding a token issued to that user.
Claude Managed Agents builds this model into vaults. A vault is the collection of credentials for one end user. You register it once and pass its ID when you create a session, so the agent definition stays shared while the credentials change per session. MCP credentials (mcp_oauth, static_bearer) are keyed by mcp_server_url and injected automatically when the agent connects to that server. For mcp_oauth, Anthropic refreshes the access token on your behalf if you supply a refresh block. Credential values are write-only and never returned by the API. In Claude Code, managed MCP configuration supports the same pattern: OAuth or per-user headers let each user authenticate as themselves.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
title="Alice's Slack digest",
)Three runtime rules decide whose identity a call actually uses, and each one can open a gap if you overlook it:
- If no credential matches the server URL, the connection is attempted unauthenticated. It fails only if the server requires authentication, so a server that allows anonymous access will quietly serve anonymous data.
- If several vaults hold a matching credential, the first vault with a match wins. Passing a shared vault ahead of a user's vault makes every call run as the shared identity.
- In multiagent sessions, vault credentials apply to every thread. Every subagent whose definition declares that server acts as the same user.
Checkpoint 1 of 7· Fill the gap
One agent definition is shared by all users. Which session parameter makes this session's MCP calls run with Alice's own credentials instead of a shared service identity?
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
? =[vault.id],
title="Alice's Slack digest",
)Each end user's credentials live in a vault. You attach the vault per session by passing vault_ids, so the agent definition stays shared while the credentials change for each user.
Source: platform.claude.comCheckpoint 2 of 7· Check yourself
A session is created with vault_ids=[team_shared_vault.id, alice_vault.id]. Both vaults hold an mcp_oauth credential for https://mcp.slack.com/mcp. Whose identity do the agent's Slack MCP calls use?
Vault order decides which credential is used: the first vault with a match wins. Putting a shared vault ahead of the user's vault makes every call run as the shared identity. That brings back both gaps: users get the shared credential's access, and the audit logs can't tell which user did what.
“When multiple vaults contain a matching credential, the first vault with a match wins.”Source: platform.claude.com
2.Keeping credentials outside the agent's boundary
An agent that reads untrusted content can be prompt-injected. If it holds a secret, an injected instruction can try to send that secret somewhere. The robust fix is to make sure the agent never has the secret. Vault environment-variable credentials work this way. The sandbox holds only an opaque placeholder, which is swapped for the real value at egress, so the agent never sees the secret value. Setting injection_location to header-only narrows this further. Request bodies are often built from content the agent is working with, so the body is the larger exposure surface.
Substitution only applies to requests going out. If a client uses the stored secret to fetch a session token, for example through an OAuth client-credentials grant, the returned token arrives in the sandbox unredacted. For exchange-based flows, perform the exchange yourself and store the resulting token in the vault.
Self-hosted Agent SDK deployments get the same property from a proxy outside the agent's container. Run the container with --network none, which removes every network interface, and mount a Unix socket connected to a proxy on the host. The proxy injects credentials, enforces an endpoint allowlist and logs every request. The agent sees only the tool interface. A prompt-injected request to an attacker's domain then has no network path except through a proxy that refuses it.
Two details decide whether the proxy actually works. First, injecting a credential into HTTPS traffic means the proxy has to read the request, so it must terminate TLS, for example with mitmproxy. The proxy's CA certificate then goes into the agent's trust store. A plain forward proxy only relays the encrypted tunnel and can neither inspect nor inject. Second, setting HTTP_PROXY/HTTPS_PROXY on its own is not a boundary, because not every tool reads those variables: plain ssh and most database drivers ignore them. Removing the network interface enforces the boundary whatever the tool does. Give the agent's service account minimal IAM permissions, not broad ones, and route sensitive access through the proxy where possible.
Checkpoint 3 of 7· Check yourself
Your agent reads untrusted web content. It holds a client secret as a vault environment_variable credential, and inside the sandbox it runs an OAuth client-credentials grant to get an API access token. A reviewer flags this as a gap. Why, and what is the fix?
Placeholder substitution only applies to outbound requests. A token that comes back from an exchange lands in the sandbox as a real value, where a prompt-injected instruction could send it out. Doing the exchange yourself and storing the token in the vault keeps it outside the agent's boundary.
“the returned token arrives in the sandbox unredacted. For exchange-based flows, perform the exchange yourself and store the resulting token in the vault instead.”Source: platform.claude.com
Checkpoint 4 of 7· Exam question
A security architect is designing an Agent SDK deployment that will process untrusted third-party documents and must prevent credential exfiltration even if a prompt injection convinces the agent to try to send data to an attacker-controlled endpoint. Which combination of controls together address this threat, given that TLS-encrypted traffic through a plain forward proxy cannot be inspected or have credentials injected into it? (Select 3)(Select 3)
Correct answers: A, B, C — Run the agent in a container with --network none and route all outbound calls through a Unix socket to a proxy on the host, so the agent has no direct network interface at all; Keep credentials outside the agent's security boundary entirely, injecting them at a proxy so the agent only ever sends requests without the underlying secret; Deploy a TLS-terminating proxy with its CA certificate trusted in the agent's environment so encrypted HTTPS traffic can be inspected and have credentials injected before re-encryption
- A. Correct. Removing the network namespace and forcing all traffic through a Unix socket to a host-side proxy means the agent has no path to reach arbitrary destinations directly, which is the architecture recommended for defense against prompt-injection-driven exfiltration.
- B. Correct. The proxy pattern keeps the actual credential outside the agent's trust boundary; the agent can make calls but never sees the secret, so even a fully compromised agent process can't leak the credential itself.
- C. Correct. A plain forward proxy only sees an opaque CONNECT tunnel for HTTPS and cannot modify or inspect its contents; injecting credentials into arbitrary HTTPS services requires terminating TLS at the proxy and having the agent trust its certificate.
- D. Not every tool respects HTTP_PROXY/HTTPS_PROXY, and even when they do, a standard forward proxy cannot see or modify HTTPS contents without terminating TLS, so it cannot inject credentials into an encrypted tunnel on its own.
- E. Granting broad IAM permissions directly to the agent process is the opposite of least privilege and increases the blast radius of a prompt injection rather than mitigating it.
- F. Relying on model judgment alone is not a security boundary; defense in depth requires network-level enforcement that holds even when the model's decision-making is manipulated.
3.Which permission layer actually decides a tool call
Credentials control what the agent can reach. The Agent SDK's permission flow controls which calls it actually makes. The flow is a fixed sequence, and the first step that resolves a call ends the evaluation. A security control placed late in the sequence only sees calls that no earlier step settled.
| Step | What it does | Under bypassPermissions |
|---|---|---|
| 1. Hooks | Run custom code to allow, deny or modify the request | Still run; a deny is enforced |
| 2. Deny rules | Block matching calls (disallowed_tools) | Still enforced |
| 3. Ask rules | Send matching calls for approval | Still route the call to canUseTool |
| 4. Permission mode | Mode-based approvals | Approves everything reaching it except rm/rmdir of a critical path |
| 5. Allow rules | Auto-approve listed tools (allowed_tools) | Rarely reached |
| 6. canUseTool callback | Runtime approval when no earlier step resolved the call | Reached only by calls that fall through |
The sequence explains a common audit finding. A team sets permission_mode="bypassPermissions" and adds a canUseTool callback that logs requests and denies anything touching a credentials directory. The callback almost never runs. It is invoked only when the flow falls through to a prompt, and calls auto-approved by allowedTools, allow rules or the permission mode never reach it. The deny logic is skipped, and the audit log is missing most of the calls. A control that must see every call belongs in a hook, because hooks run first and their decisions hold in every mode.
Under bypassPermissions, the steps that run before the mode check still apply. Deny rules, explicit ask rules and hooks all still work: a hook's deny is enforced, and an ask rule still sends the call to canUseTool. disallowed_tools still has teeth too. A bare name such as "Bash" removes the tool from the request entirely, so Claude cannot even attempt it, and a scoped rule such as "Bash(rm *)" denies matching calls in every mode. allowed_tools, on the other hand, gives no protection here: it lists tools to auto-approve and does not restrict Claude to only these tools. Nor is plan mode a variant of bypass. In plan mode, file-edit and shell-write calls go to canUseTool regardless of allow rules.
Tool reach is an authorization question too. An agent that can load any MCP server can call tools no one has reviewed, so the gap is closed by deciding which servers and tools exist at all, through controlling MCP servers, plugins and hooks through policy. At the SDK and settings level, one deny rule removes every MCP tool, across all servers, until specific ones are approved.
{
"permissions": {
"deny": [
"mcp__*"
]
}
}Checkpoint 5 of 7· Fill the gap
To block every MCP tool from every server until specific ones are approved, which permission key completes this settings block?
{
"permissions": {
" ? ": [
"mcp__*"
]
}
}Only a deny rule removes the tools. Deny rules run early in the permission flow and still apply under bypassPermissions. An allow rule only auto-approves the tools it lists and leaves unlisted tools available. An ask rule still lets each call go ahead once it is approved.
Source: code.claude.comCheckpoint 6 of 7· Exam question
While auditing an Agent SDK integration, you find allowed_tools=["Read", "Glob", "Grep", "Bash"] combined with permission_mode="bypassPermissions", and a canUseTool callback that logs every request and denies anything touching a credentials directory. The developer believed this callback was their safety net. What should the audit conclude?
Correct answer: A — The callback is shadowed: calls approved earlier in the order, including everything bypassPermissions approves, never reach canUseTool; a PreToolUse hook is needed if every call must be checked
- A. Correct. The SDK evaluates hooks, then deny rules, then ask rules, then permission mode, then allow rules, and only then calls canUseTool. With bypassPermissions set, the mode step approves every call that reaches it, so Bash and everything else never falls through to the callback. A logic check that must run on every call belongs in a PreToolUse hook instead, since hooks run first and a hook deny applies even in bypassPermissions mode.
- B. bypassPermissions is not scoped only to unlisted tools; it approves every call that reaches the permission-mode step, listed or not, so Bash calls are approved before the callback is ever consulted.
- C. This reverses the evaluation order. Hooks, deny rules, ask rules, and permission mode are all checked before allow rules and canUseTool, so canUseTool is one of the last steps, not the first.
- D. The requiresUserInteraction exception applies to AskUserQuestion and specially annotated MCP tools, but it does not change the outcome for the ordinary built-in tools in this scenario, which are fully shadowed by bypassPermissions regardless of that flag.
Checkpoint 7 of 7· Exam question
A CISO reviewing an Agent SDK rollout learns that permission_mode is set to bypassPermissions in a batch-processing pipeline and asks which authorization controls, if any, still constrain the agent under that mode. Based on how bypassPermissions is evaluated, which of the following statements are accurate? (Select 2)(Select 2)
Correct answers: A, B — Hooks still execute and a hook that denies a call is still enforced, because hooks are evaluated before the permission mode step in the flow; An explicit ask rule configured in settings.json still forces the call through the canUseTool callback, even though the mode would otherwise auto-approve it
- A. Correct. Hooks run first in the evaluation order, ahead of deny rules, ask rules, and the permission mode step, so a hook denial still blocks the call even under bypassPermissions.
- B. Correct. Explicit ask rules are checked before the permission mode step, so a matching ask rule still routes the call to canUseTool for confirmation even when bypassPermissions would otherwise auto-approve it.
- C. allowed_tools only pre-approves the tools it lists; unlisted tools still fall through to the permission mode, where bypassPermissions approves them too. Listing a narrow set in allowed_tools does not scope or limit what bypassPermissions itself approves.
- D. disallowed_tools entries are deny rules, and deny rules are evaluated before the permission mode step and still block matching calls even in bypassPermissions mode; they are not overridden by it.
- E. plan mode explicitly routes file-edit and shell-write tools to canUseTool regardless of allow rules, while bypassPermissions auto-approves those same operations at the mode step; the two modes produce opposite outcomes for edits, not identical ones.
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“lose track of which end user an agent acted on behalf of”
↩︎ Shared service identity versus acting on behalf of each user“A vault is the collection of credentials associated with an end user.”
↩︎ Shared service identity versus acting on behalf of each user“When no MCP credential matches by mcp_server_url, the connection is attempted unauthenticated and will error if the server requires authentication.”
↩︎ Shared service identity versus acting on behalf of each user“In multiagent sessions, vault credentials apply to every thread.”
↩︎ Shared service identity versus acting on behalf of each user“The agent never sees the secret value.”
↩︎ Keeping credentials outside the agent's boundary“Most services read an API key from a request header, so enabling only header is the narrower configuration.”
↩︎ Keeping credentials outside the agent's boundary“the returned token arrives in the sandbox unredacted”
↩︎ Keeping credentials outside the agent's boundary“When multiple vaults contain a matching credential, the first vault with a match wins.”
↩︎ Checkpoint“the returned token arrives in the sandbox unredacted. For exchange-based flows, perform the exchange yourself and store the resulting token in the vault instead.”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/managed-mcpOfficial docs
“OAuth or per-user headers so each user authenticates as themselves.”
↩︎ Shared service identity versus acting on behalf of each user - 3.
“Removes all network interfaces; the agent communicates through the mounted Unix socket below”
↩︎ Keeping credentials outside the agent's boundary“Credentials stay outside: The agent only sees the tool interface, not the underlying credentials”
↩︎ Keeping credentials outside the agent's boundary“mitmproxy: TLS-terminating proxy for inspecting and modifying HTTPS traffic”
↩︎ Keeping credentials outside the agent's boundary - 4.https://code.claude.com/docs/en/sandboxingOfficial docs
“plain ssh, most database drivers, and similar tools can’t connect, even to an allowed host”
↩︎ Keeping credentials outside the agent's boundary“the proxy substitutes the real value inside request contents, so it has to see them.”
↩︎ Exam trap 3 - 5.
“In bypassPermissions mode, Claude Code approves everything that reaches this step except rm and rmdir removals targeting a critical path, which fall through instead.”
↩︎ Which permission layer actually decides a tool call“Deny rules, explicit ask rules, and hooks are evaluated before the mode check and can still block a tool.”
↩︎ Which permission layer actually decides a tool call“canUseTool callback: prompt users for approval at runtime, when no earlier step resolves the call.”
↩︎ Which permission layer actually decides a tool call“Claude does not see the tool and cannot attempt it.”
↩︎ Which permission layer actually decides a tool call“In plan mode, Claude Code sends file-edit and shell-write tools to your canUseTool callback regardless of allow rules”
↩︎ Which permission layer actually decides a tool call“Other tools not listed here still exist, and calls to them that need approval fall through to the permission mode and canUseTool.”
↩︎ Prediction - 6.https://code.claude.com/docs/en/agent-sdk/agent-loopOfficial docs
“Runs all allowed tools without asking, except tools matched by an explicit ask rule”
↩︎ Which permission layer actually decides a tool call - 7.https://code.claude.com/docs/en/agent-sdk/typescriptOfficial docs
“Not invoked for calls auto-approved by allowedTools, allow rules, or permissionMode.”
↩︎ Which permission layer actually decides a tool call“Not invoked for calls auto-approved by allowedTools, allow rules, or permissionMode.”
↩︎ Exam trap 1“This does not restrict Claude to only these tools.”
↩︎ Exam trap 2