[XieX]

Summary

This is the Python side of the core half of launchdarkly/ai-sdks-monorepo#59 (TESTING.md §2.x "Claude Agents Handler — host options and built-in tool set"). The TypeScript side is launchdarkly/js-ai-sdk#135.

• tools=[] when a config attaches no NativeTool (§2.x.2). This reverses 50e82fd. With the key omitted, every Python run got the full Claude Code built-in set (Read, Bash, Skill and the rest), and the read-only tools in it need no permission. A config now turns a built-in on by attaching its sentinel, which is what TypeScript has always done. User-defined tools still go through the in-process MCP server and allowed_tools, whatever tools holds.
• create_claude_agents_handler(*, capture_content=None, cwd=None, setting_sources=None) (§2.x.1). Both options are forwarded to every query() on the blocking and streaming paths.
  • setting_sources not given sends []. The Agent SDK reads None as "load every source", which put the host's plugins, skills, hooks, permission rules and CLAUDE.md into every run (AIC-3584).
  • cwd is sent only when given.
  • capture_content=None still follows configure().
  • A config can't set or override either option: since fix!: pass AI Config model parameters through to every provider handler #107 the handler forwards only allowlisted model.parameters, and both keys are on the excluded list. A test pins that.
• The wrappers and the native adapter take both options too, matching feat(claude-agents)!: accept trusted cwd and settingSources options, and load no host settings by default js-ai-sdk#135:
  • claude_agents() and claude_graph() take cwd / setting_sources keyword-only and build the handler with them. Neither reaches config() / graph().
  • to_claude_agents() reads them from opts and sends _host_query_options(...) to every node's query(), root and sub-agents. It already sent tools=[] with no native tools, and a test now pins that too.
  • All four entry points default to setting_sources=[] and no cwd.
• The README has a migration note. [] also drops the settings-file env (ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK / _VERTEX, proxy variables), apiKeyHelper and model. A deployment that reaches Bedrock, Vertex or a gateway through ~/.claude/settings.json needs setting_sources=["user"] or those variables in the process environment.

Breaking

Two changes in runtime behaviour:

• A run has no Claude Code built-ins unless its config attaches them.
• A run loads no host Claude Code settings unless the application passes setting_sources.

This needs to land before the 1.0 freeze, because changing either default after 1.0 would be breaking.

Tests

• TestBuiltinsSurviveAnEmptyToolList is replaced. Its "omits the key" test asserted the behaviour this PR reverses.
• TestHostOptionsAndBuiltinToolSet adds nine tests, each run on both the invoke and stream paths.
• TestToClaudeAgentsHostIsolation adds four, including root and leaf for the default and for given values.
• TestConvenienceExportHostOptions and TestClaudeGraphHostOptions add two each: the default, and given values reaching query() but not config() / graph().
• The API report is regenerated for the three new signatures.

Checks:

• uv run pytest: every claude-agents test passes. The one failure in the full suite is opencode-agents test_a_fake_opencode_is_started_spoken_to_and_stopped, a macOS /private/var vs /var temp-path mismatch already on main.
• make lint, make format-check and make typecheck are clean.

🤖 Generated with Claude Code

---

Note

Overview
Breaking: Python Claude agent runs no longer inherit the Agent SDK’s implicit defaults for built-in tools or host Claude Code settings.

Runs now pass tools=[] when the flag config attaches no NativeTool sentinel, which turns off Claude Code built-ins (Read, Bash, etc.) unless you explicitly enable them via ClaudeRead, ClaudeBash, and similar in tool_handlers. User-defined tools still use the in-process MCP server unchanged.

Host isolation: create_claude_agents_handler, claude_agents, claude_graph, and to_claude_agents gain app-only cwd and setting_sources (via _host_query_options), forwarded on every query() (invoke, stream, and graph nodes). Default setting_sources=[] stops loading ~/.claude/settings.json, project CLAUDE.md, plugins, hooks, and settings-file env (Bedrock/Vertex gateways may break until you opt in or set process env). Flag model.parameters cannot override these options.

README/agents.md document migration; tests replace the old “omit tools” expectation and add coverage for host options and built-in tool sets across invoke/stream/graph paths.

^{Reviewed by Cursor Bugbot for commit bcbde98. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jeffdupont]

Two things so this matches js #135 (launchdarkly/js-ai-sdk#135), which is now approved. I'm asking spec #59 to make the same change.

1. The wrappers and the native adapter should take cwd and setting_sources.
At the moment claude_agents(), claude_graph() and to_claude_agents() hard-code setting_sources=[] (native_graph.py, _run_query), so a wrapper user can't opt back in to host settings. JS now takes both options on all four entry points, and these signatures freeze at 1.0. Please:

• In claude_agents and claude_graph, take cwd / setting_sources keyword-only, build the handler with them, and don't pass them on to config() / graph().
• In to_claude_agents, take both options and send _host_query_options(...) to every Anthropic node's query(), root and sub-agents, in place of the hard-coded [].
• Add tests: [] and no cwd by default, and a given value reaching query(), for each entry point. For the graph, check root and leaf.
• Update the README line "claude_agents(), claude_graph() and to_claude_agents() don't take cwd or setting_sources" and the matching sentence in agents.md §2a.
• Run make api-report and commit the report diff, because the public signatures change.

2. Add a migration note to the README.
[] also drops the settings-file env (ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK / _VERTEX, proxy variables), apiKeyHelper and model. A deployment that reaches Bedrock, Vertex or a gateway through ~/.claude/settings.json fails to authenticate after the upgrade, and nothing in the docs says why. The "Migrating from a version that loaded host settings" section in js #135's README can be copied over with setting_sources=["user"] examples.

[jeffdupont]

Approved after the GA 1.0 PR audit. Every earlier review point is addressed and the API report is regenerated. The CI failure is the flaky opencode boot-timeout test, so I'm rerunning it.