Agent SDK capability matrix
Permissions, hooks, MCP, SessionStore, cost tracking, OpenTelemetry, secure deployment and cache strategy.
Agent SDK starts the Claude Code loop and coordinates models, tools, permissions, hooks, MCP, sessions and telemetry. This page organizes the detailed official SDK documentation into a production capability matrix.
For custom tools, prompts, streaming, structured output, approvals and SDK slash commands, see runtime patterns.
Use the CLI for a person working in a terminal. SDK permission, session, observability and isolation design matters when embedding agents in products, CI, background jobs or multitenant services.
#Capability overview
| Capability | Problem solved | Production concern |
|---|---|---|
| Permission modes | Control automatic execution | allowedTools preapproves; it does not define the entire inventory |
| canUseTool | Runtime user or business approval | Understand rules that can resolve requests before the callback |
| Hooks | Intercept tools, lifecycle and stopping | Prefer PreToolUse for mandatory auditing and blocking |
| MCP | Internal APIs, databases, browsers and SaaS | Use tool search for large catalogs; control auth and output size |
| SessionStore | Cross-host transcript recovery | Does not store workspaces, CLAUDE.md or checkpoint blobs |
| Cost tracking | Tokens, model usage and estimates | Client estimates are not final bills |
| OpenTelemetry | Metrics, logs and traces | Never use console exporters on SDK stdout |
| Secure deployment | File, network, credential and tenant isolation | Separate cwd, config, environment and egress per tenant |
#Permission evaluation order
SDK tool requests follow this order:
| Order | Layer | Result |
|---|---|---|
| 1 | Hooks | Can deny, record or rewrite input |
| 2 | Deny rules | Matching scoped rules such as Bash(rm *) block even in bypass mode |
| 3 | Ask rules | Delegate to canUseTool for user/business approval |
| 4 | Permission mode | Global bypassPermissions, acceptEdits, plan, dontAsk policies |
| 5 | Allow rules | Matching requests are approved automatically |
| 6 | canUseTool | Invoked only if unresolved above |
Common misconceptions:
| Configuration | Actual behavior |
|---|---|
| allowedTools: [Read] + bypassPermissions | Read is allowed; other tools can still pass through bypass |
| disallowedTools: [Bash] | Removes Bash's definition entirely |
| disallowedTools: [Bash(rm *)] | Bash remains visible but matching commands are blocked |
| dontAsk with a small allowlist | Suitable for read-only or narrow tasks; other actions denied |
| Relying only on canUseTool | Earlier rules or modes may approve without calling it |
#Use hooks
Hooks place security, audit and business rules before or after model actions.
| Scenario | Recommendation |
|---|---|
| Block dangerous commands | Inspect Bash in PreToolUse and deny matches |
| Audit every tool | Record tool, session, agent and result summary before/after use |
| Format or validate files | Run formatters/tests after Edit or Write |
| Inject short-lived credentials | External broker injects before execution; keep long-lived secrets out of prompts |
| Notify on completion | Stop/completion events can trigger messages, webhooks or ticket updates |
A hook's allow does not bypass later deny, ask or permission rules. Put mandatory checks in PreToolUse rather than only canUseTool.
#Connect MCP
MCP supplies external tools. Plan production transport, authentication and output limits according to catalog size.
| Design area | Recommendation |
|---|---|
| Transport | stdio locally; HTTP/SSE/WebSocket remotely |
| Auth | OAuth or short-lived tokens; no secrets in prompts or repositories |
| Tool search | Enable for large inventories instead of sending every schema upfront |
| Output size | Bound results; provide pagination or summaries |
| Human approval | requires-user-interaction or ask rules for high-risk tools |
| Gateway | Verify tool search/deferred tools forwarding to avoid cache misses |
Tool output becomes conversation context. Long logs, full-table queries and complete HTML increase subsequent costs.
#SessionStore
Transcripts default to ~/.claude/projects/. SessionStore can mirror them to S3, Redis, a database or a custom backend so another worker can resume.
| Method | Required? | Purpose |
|---|---|---|
| append | Yes | Append entries externally after local transcript writes |
| load | Yes | Load history before resume |
| listSessions | Optional | List or continue recent sessions |
| delete | Optional | Delete a session; append-only stores may implement a no-op |
| listSubkeys | Optional | Restore subagent transcripts |
Boundaries:
| Not managed by SessionStore | Your responsibility |
|---|---|
| Workspace files | Persistent volumes, object storage or per-task directories |
| CLAUDE.md and auto memory | Isolate or disable separately |
| Checkpoint blobs | Persist separately for cross-host rewind |
| MCP server state | Managed by the server/external service |
Monitor mirror_error. The agent may keep running after external append failure, while recovery is already incomplete.
#Cost tracking
The message stream exposes per-step and per-model usage plus a total estimate at query completion.
| Field/concept | Purpose |
|---|---|
| Assistant usage | Input/output tokens per step |
| Result total_cost_usd | Client-side estimate for one query |
| Result model_usage | Per-model accounting for multiple models or fallback |
| cache_creation_input_tokens | Inputs written to cache this turn |
| cache_read_input_tokens | Inputs read from cache this turn |
Parallel tool calls may produce multiple assistant messages sharing one message ID and usage. Deduplicate by ID for step-level accounting.
SDK costs are local estimates affected by version, model recognition and price updates. Use them for observability and budget alerts, not as the sole basis for customer billing or settlement.
#OpenTelemetry
Enable OTLP in production to connect agent execution to existing observability.
CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318| Signal | What it shows |
|---|---|
| Metrics | Sessions, tokens, costs, tool decisions and changed lines |
| Log events | Prompt/API/tool/error summaries |
| Traces | Model, tool, hook and agent-step latency chains |
SDK subprocess communication uses stdout/stderr. A console OTEL exporter can contaminate that channel; do not use it.
#Secure deployment
Agents read files, execute commands, access networks and call services. Use least privilege, isolation and layered controls.
| Resource | Control |
|---|---|
| Filesystem | Separate cwd per tenant/task; read-only mounts where appropriate |
| Network | Egress allowlists, proxies or offline sandboxes |
| Credentials | Broker-injected short-lived credentials rather than long-lived keys |
| Settings | settingSources: [] with explicit options for multitenancy |
| Config directory | Per-tenant CLAUDE_CONFIG_DIR |
| Auto memory | Disable in shared environments with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 |
| Process | Docker, sandbox-runtime, gVisor, Firecracker or CI isolation |
Treat prompt injection as part of the normal threat model for uploads, websites, issues and READMEs. Network and credential boundaries are more dependable than assuming the model will ignore malicious instructions.
#Five-minute / one-hour cache strategy
| SDK scenario | Recommendation |
|---|---|
| Single query() | Steps reuse prefixes naturally; avoid switching model/effort mid-run |
| Repeated query() with resume | Same session, model and effort improve reuse |
| Multiple workers with SessionStore | Transcript recovery does not guarantee provider cache beyond TTL or across keys |
| API key / Passion8 / Bedrock / Vertex | Design around a five-minute default TTL |
| Claude subscription | Plans commonly support one-hour intervals |
| Many MCP tools | Tool search stabilizes prefixes and avoids full schema repetition |
| Permission/settings changes | Changed tools/system prefixes may rebuild cache |
| Subagents | Independent contexts and caches; cost scales with agent count |
Translate /usage into telemetry and business metrics by tenant, session, agent, model, tool and cache reads/writes.
#Official references
Support
Need help?
For setup, billing, or model issues, email us. Check the status page for uptime.
WeChat / QQ support is available at the bottom right.
