Safety-First Automation: Your First Guarded Helper via Official Claude Agent SDK (2026)

Anthropic’s Claude Agent SDK lets you embed the same tool loop as Claude Code in your own Python or TypeScript app. Beginner rule: start read-only, add an honesty system_prompt, then widen allowed_tools only after audit logs look correct.

See also: Claude Code over SSH, Cursor Rules vs Skills, Opus 4.8 agent benchmarks.

Why start with the official SDK

Wrappers often hide which tools run and what leaves your machine. The SDK documents Read, Edit, Bash, permissions, hooks, and sessions on code.claude.com.

A cloud Mac is optional for 24/7 schedules; your laptop is enough for a first guarded helper.

How the SDK is structured

From June 15, 2026, subscription plans meter Agent SDK via a separate credit pool—budget unattended loops.

Eight-step guarded runbook

Step 1 — Prerequisites

python3 --version   # 3.10+
pip install claude-agent-sdk

Step 2–3 — Project + install

mkdir my-guarded-agent && cd my-guarded-agent
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk

Step 4 — API key

# .env (gitignore this file)
ANTHROPIC_API_KEY=sk-ant-...

Step 5–6 — Honesty prompt + read-only run

from claude_agent_sdk import query, ClaudeAgentOptions

HONEST = """Say "I don't know" when data is missing.
Never invent paths or command output."""

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
    system_prompt=HONEST,
)

Run: python3 agent.py — per quickstart.

Step 7–8 — Audit hook, then edits

Add PostToolUse hooks to audit.log before enabling Edit with permission_mode="acceptEdits". Optional: AskUserQuestion for clarifications.

Troubleshooting

API key not found

Fix: Export ANTHROPIC_API_KEY in the same shell; never commit .env.

pip: No matching distribution

Fix: Use Python 3.10+; recreate .venv.

thinking.type.enabled not supported

Fix: Upgrade Agent SDK to v0.2.111+ for Opus 4.7+ ([quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart)).

Unexpected file edits

Fix: Revert with git; return to dontAsk + read-only tools until hooks prove safe.

FAQ