Claude Agent SDK (TypeScript)

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

@dynamoprotocol/claude-agent-sdk adds Dynamo to the Claude Agent SDK for TypeScript (query() with agents). It is the TypeScript twin of the Python Claude Agent SDK plugin. Every agent run gets its own capped slice of one budget. A sub-agent the run launches through the Agent tool (alias Task) runs on a child slice, which can never exceed what its parent has left. A run or a launch that would go over its slice is refused before it starts.

The SDK reports cost once per query and has no hook before each model call, so this plugin reserves per run and per sub-agent launch (the spawn-scoped profile), not per model call.

The plugin is not published. It is used from a clone of the repository.

Install and try it

These are the commands from the plugin README. They build the workspace and run the offline containment demo: the real SDK query() over a scripted stand-in for the Claude Code CLI, so Claude Code is never launched, no key is needed and no model is called. You need Node 22.12 or later and pnpm 9.

cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/core-host... -r build
pnpm --filter "@dynamoprotocol/claude-agent-sdk..." build
node packages/plugin-claude-agent-sdk-ts/examples/containment.mjs

The Claude Agent SDK is a peer dependency. The README installs it next to the package:

npm install @anthropic-ai/claude-agent-sdk@0.3.293

The SDK is published by its vendor under the vendor's own terms; installing it means accepting those terms.

Wrap an agent run in a budget

This is packages/plugin-claude-agent-sdk-ts/examples/app/with-dynamo.mjs: a small two-agent app with Dynamo added. It needs DYNAMO_CORE_URL and DYNAMO_OWNER_TOKEN set to a running core. make test-plugin-claude-agent-sdk-ts runs it against a local core (test/examples.test.ts).

// SPDX-License-Identifier: Apache-2.0
// A small multi-agent app on the Claude Agent SDK — with Dynamo.
// Runs offline: the scripted CLI stands in for Claude Code and the model.

import { DynamoClaude, usd } from "@dynamoprotocol/claude-agent-sdk";
import { ScriptedClaudeCli, scriptedOptions, spawn, text } from "@dynamoprotocol/claude-agent-sdk/testing";

const dyn = await DynamoClaude.connect({ cap: usd("5"), mandate: { categories: ["research", "writing"], maxDepth: 3 },
  agents: { orchestrator: { slice: usd("2"), category: "writing" }, researcher: { slice: usd("1"), category: "research" } },
  runBudgets: { orchestrator: usd("0.10"), researcher: usd("0.10") } });
const cli = new ScriptedClaudeCli();
cli.entry = "orchestrator";
cli.script("orchestrator", spawn("researcher", "grid-scale storage"), text("brief written"));
cli.script("researcher", text("three sources found"));
const agents = { researcher: { description: "Researches a topic.", prompt: "You research." } };
const options = scriptedOptions(cli, { model: "mock/scripted-1", agents });

let answer = "";
for await (const message of dyn.query("orchestrator", { prompt: "Write a brief on grid-scale storage", options })) {
  if (message.type === "result") answer = message.result;
}
console.log(answer);

of agent. Before launch it reserves runBudgets[agent] on the agent's stream.

offline; in your app, pass your own query() options.

What a refusal looks like

A refusal is a plain Error subclass (the SDK exports no error base class to extend): DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied, DynamoAmendmentRefused and DynamoPermissionModeUnsafe, each with reason, streamId and headroom.

A refused sub-agent launch is denied by the PreToolUse hook with continue: false, so the CLI never launches it and stops the run; an unexpected error in the hook is a denial (admission_failed). The refusal is thrown after the run is settled; its result holds the result message and its receipts what the run was billed. A run that would start with permission checks bypassed is refused with DynamoPermissionModeUnsafe (permission_mode_unsafe) before anything is reserved or launched.

Funding modes

always a Control Mode budget: every check runs and no money moves. The quickstart and every test of this plugin use one.

budget by id (budgetId). The plugin does not refuse it, but no test runs the plugin on one. In those modes the core requires signed hops by default, and a sub-agent's slice opened without its delegator's signature is refused hop_unsigned. Pass hops (a LayerHops from @dynamoprotocol/agents: the delegator's key and each payee's own signed offer) so the plugin signs every hop it opens.

operator allows it, and real-money settlement is not released.

Known limits

Read packages/plugin-claude-agent-sdk-ts/KNOWN-LIMITS.md in the repository before you rely on the plugin.