Migrating to the Claude Agent SDK

What you will be able to do

• Run Dayflow on the Claude Agent SDK without rewriting a single tool handler
• Say precisely which parts of lessons 81-83 the SDK replaces, which it keeps, and which it quietly changes
• Lock the SDK down so a calendar assistant cannot run shell commands, read your Claude Code settings, or pick up MCP servers you did not give it
• Keep your own audit log with a hook, and know why it is no longer the source of truth for resume

Why build the loop first, then throw it away

Three lessons of hand-written loop was not a detour. You now know that an agent is awhile loop over stop_reason, that the message history is the state, that a checkpoint has to land before the next API call, and that compaction is lossy. When the SDK does those things for you, you can tell whether it is doing them well. People who start with the SDK cannot.

The SDK gives you the loop, the permission system, session persistence with resume, automatic compaction, hooks on every tool call, and the same runtime Claude Code itself uses. In exchange it runs a subprocess, decides some things for you, and ships with a default tool surface (Read, Bash, Edit, WebFetch and more) that a personal ops agent must not have. Most of this lesson is about that exchange.

The migration is one adapter, not a rewrite

Lesson 82 made the registry flat on purpose: a Tool has a name, a description, a strict property map and a handler. The SDK wants tools as an MCP server. An in-process one is a function call away, and every registry entry maps onto it mechanically:

# dayflow/sdk_agent.py
from claude_agent_sdk import tool, create_sdk_mcp_server
from dayflow.tools import REGISTRY, Tool, dispatch

SERVER = "dayflow"          # tools are addressed as mcp__dayflow__<name>

def _as_mcp_tool(t: Tool):
    schema = {"type": "object", "properties": t.properties,
              "required": list(t.properties), "additionalProperties": False}

    @tool(t.name, t.description, schema)
    async def handler(args):
        envelope = dispatch(t.name, args)        # same handler, same {"ok": ...} envelope
        return {"content": [{"type": "text", "text": envelope}]}
    return handler

def build_server(kinds=("read", "write")):
    return create_sdk_mcp_server(name=SERVER, version="0.84.0",
        tools=[_as_mcp_tool(t) for t in REGISTRY.values() if t.kind in kinds])

Read that twice. dispatch() is the lesson 82 function, unchanged. The handler that runs, the strict schema the model sees, and the bytes the model reads back are the ones the raw loop produced. The transport changed; the contract did not. That is what the lesson 82 discipline bought you.

The options block is the security boundary

Here is the whole configuration. Every line that is not obvious is doing a job, and three of them are there to take things away:

options = ClaudeAgentOptions(
    system_prompt=prompts.MORNING_BRIEF,       # ours, not the Claude Code preset
    mcp_servers={SERVER: build_server(kinds)},
    strict_mcp_config=True,                    # ignore ~/.claude.json and any .mcp.json
    setting_sources=[],                        # ignore the developer's own Claude Code settings
    tools=[],                                  # no Read/Bash/Edit/WebFetch: the registry is the whole surface
    allowed_tools=tool_names(kinds),           # auto-approve mcp__dayflow__* (lesson 86 narrows this)
    permission_mode="default",
    max_turns=max_turns,
    max_budget_usd=max_budget_usd,             # a hard stop in dollars, enforced client-side
    model=model,
    hooks={"PostToolUse": [HookMatcher(matcher="mcp__dayflow__.*", hooks=[record_step])]},
)

• tools=[] is the line you must never forget. The SDK's default surface is Claude Code's: it can read files, run shell commands and fetch URLs. Dayflow reads a calendar. Leave this out and a prompt injection in an email (lesson 88) has a shell to work with. allowed_tools does not restrict the model to those tools; it only pre-approves them. Removal is a separate decision.
• setting_sources=[] and strict_mcp_config=True keep your laptop out of production. Without them the agent inherits whatever is in your personal Claude Code settings and connects to whatever MCP servers you have configured for yourself. It worked on your machine for reasons that will not exist on the server.
• system_prompt as a plain string replaces the Claude Code preset entirely. The preset is thousands of tokens about editing code. You are not editing code.
• max_budget_usd is new. The raw loop had a token budget; this is a dollar budget computed from the model's price list, and the run stops withsubtype == "error_max_budget_usd" when it is hit. Keep both habits.

What you keep, what you lose, what moves

Hooks: the SDK calls you back

A PostToolUse hook fires after every tool call with the tool name, the input the model sent, the response your handler returned and the tool_use_id. That is exactly one row in lesson 83's steps table, so the audit log costs eleven lines:

async def record_step(hook_input, _tool_use_id, _ctx):
    step["n"] += 1
    name = hook_input["tool_name"].removeprefix("mcp__dayflow__")
    store.append_step(run_id, StepRow(
        n=step["n"], stop_reason="tool_use",
        assistant=[{"type": "tool_use", "id": hook_input["tool_use_id"], "name": name, "input": hook_input["tool_input"]}],
        tool_results=[{"type": "tool_result", "tool_use_id": hook_input["tool_use_id"],
                       "content": json.dumps(hook_input["tool_response"])}],
        input_tokens=0, output_tokens=0,       # not available per step; totals land on the run
    ))
    return {}                                   # empty dict: do not alter the flow

The matcher mcp__dayflow__.* is a regex on the tool name. With tools=[] it is redundant, since nothing else can fire, but write it anyway: when lesson 85 adds a subagent with its own tools you will want this hook to stay scoped.

PreToolUse is the other half: it runs before the call and can return a decision that blocks it. That is lesson 86's human-in-the-loop gate, and it is why the registry has carried akind: read | write flag since lesson 82. The hook will read it.

The live run on lesson-84: both engines, same fixtures, back to back

$ dayflow brief -v                       # raw loop, lessons 81-83
[step 1] stop=tool_use in=1260 out=190
[step 2] stop=tool_use in=2720 out=527
[step 3] stop=end_turn in=3422 out=675
[3 steps · 6 tool calls · 7402 in / 1392 out · run 04c8c46806c0]

$ dayflow brief -v --engine sdk          # this lesson
  ↳ read_inbox({"limit": 20})
  ↳ read_calendar({"range": "week"})
  ↳ read_tasks({"include_done": false})
  ↳ create_task({"title": "Confirm vendor sign-off to Priya (procurement lock-in)",
                 "due": "2026-09-10", "idempotency_key": "confirm-vendor-signoff-priya-2026-09-10"})
[sdk · 5 turns · 4 tool calls · 6 in (+5000 cached) / 1150 out · $0.0213
 · run 4b4f59b9033a · session a7801a51-1a08-4681-8807-69d0b7545a19]

$ sqlite3 dayflow.db "select id, kind, status, input_tokens, output_tokens from runs"
04c8c46806c0|brief|done|7402|1392
4b4f59b9033a|brief-sdk|done|5006|1150

Three things in that transcript are worth more than the rest of the lesson:

1. "6 in (+5000 cached)". The SDK put a cache breakpoint on the system prompt and tool definitions without being asked, so turns 2 to 5 re-read them at a tenth of the price. Your raw loop sent 7402 uncached input tokens for the same job. Lesson 90 adds caching to the raw loop; for now, notice that a default did something your code did not.
2. 3 steps with 6 calls versus 5 turns with 4 calls. The raw loop received paralleltool_use blocks and ran them together; the SDK session called tools one at a time. Neither is wrong. It is a reminder that "steps" and "turns" are different units and your budgets must say which one they count.
3. The run row has a session_id. dayflow runs now shows two kinds of run, and only one kind can be resumed through your own code.

The bug the migration found

The first TypeScript SDK run produced a brief that began: "read_calendar returned only one event, dated 2026-09-07, not today's actual date (2026-11-04)", then flagged every task and email as overdue. It was right. The fixtures are a static week starting on a Monday in September, and nothing in three lessons ever told the model what day it was. The raw loop and the Python SDK run happened to assume the fixture date. The TypeScript run assumed the wall clock. All three were guessing.

The fix is small and belongs in the prompt, not the fixtures: a clock.today() that prefers DAYFLOW_TODAY, then the fixture Monday under MOCK=1, then the real date; and a user turn that states it. prompts.brief_request(today) now renders Today is 2026-09-07. Give me my morning brief for today. Both engines use it.

TypeScript: the one real difference

The TypeScript SDK's tool() takes a Zod shape, not JSON Schema. The registry declares four property shapes (integer, string, string enum, string-or-null), so the translation is a twelve-line function and the registry stays the single source:

function zodFor(p: Prop): ZodTypeAny {
  const types = Array.isArray(p.type) ? p.type : [p.type]
  const nullable = types.includes('null')
  const base = types.find(t => t !== 'null') ?? 'string'
  let s: ZodTypeAny =
    p.enum ? z.enum(p.enum as [string, ...string[]])
    : base === 'integer' ? z.number().int()
    : base === 'boolean' ? z.boolean()
    : z.string()
  if (p.description) s = s.describe(p.description)
  return nullable ? s.nullable() : s
}

Everything else mirrors Python line for line: buildServer, toolNames, thePostToolUse hook, tools: [], strictMcpConfig, settingSources: [].npm run brief -- --engine sdk -v.

What this lesson deliberately does not do

• Delete the raw loop. It stays as --engine raw. It is the control group for every SDK behaviour you want to check, and lesson 90 instruments it to show what caching and tracing cost.
• Use ClaudeSDKClient. The stateful client gives you multi-turn conversations and interrupt(). A morning brief is one turn. Lesson 85 introduces it when an orchestrator needs to talk to a running agent.
• Gate the write tool. create_task is still auto-approved. The PreToolUse hook that asks a human first is lesson 86, and the kind flag is waiting for it.
• Resume an SDK run. The session_id is stored; wiring resume= into the CLI belongs with the retry policy in lesson 91, because a resume without a policy for when is a footgun.