Metadata-Version: 2.4
Name: zeno-provider-claude
Version: 1.1.0
Summary: Claude Agent SDK provider for Zeno (Anthropic Claude with sub-agents, built-in tools, and SDK hooks).
Project-URL: Homepage, https://github.com/nkootstra/zeno
Project-URL: Repository, https://github.com/nkootstra/zeno
Project-URL: Issues, https://github.com/nkootstra/zeno/issues
Project-URL: Changelog, https://github.com/nkootstra/zeno/blob/main/CHANGELOG.md
Author: Niels Kootstra
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,claude,claude-agent-sdk,llm,zeno
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: claude-agent-sdk<0.2,>=0.1.0
Requires-Dist: zeno-core
Description-Content-Type: text/markdown

# zeno-provider-claude

Claude Agent SDK provider for Zeno. Wraps `claude-agent-sdk` (`ClaudeSDKClient`)
behind Zeno's `Provider` Protocol so an `Agent` definition stays portable
across providers.

## Install

```bash
uv add 'zeno-framework[claude]'
```

The `zeno-framework` meta-package ships Claude as the default; this extra is
the explicit form for environments that pin extras.

## Usage

```python
from zeno.agent import Agent
from zeno.app import ZenoApp
from zeno.channels.cli.channel import CliChannel
from zeno.providers.claude_sdk import ClaudeSDKProvider

app = ZenoApp(
    agent=Agent(
        name="root",
        instructions="You are a helpful personal assistant.",
        permission_mode="bypassPermissions",
    ),
    channels=[CliChannel()],
    provider=ClaudeSDKProvider(),
)
```

`ClaudeSDKProvider` reads `ANTHROPIC_API_KEY` from the environment via the
underlying SDK. Set it before `app.start()`. If the env var is unset,
`start()` logs a warning at the `zeno.providers.claude_sdk` logger
pointing at both auth paths (env var + `claude login` OAuth) — OAuth
users can ignore it; users who haven't set up either get a clear hint
before the first turn fails.

### Resuming SDK sessions

Pass a `session_lookup` callable to resume a prior SDK session keyed by
`(user_id, channel, thread_key)`:

```python
async def lookup_session(user_id: str, channel: str, thread_key: str | None) -> str | None:
    return await my_store.get_sdk_session_id(user_id, channel, thread_key)


provider = ClaudeSDKProvider(session_lookup=lookup_session)
```

When `session_lookup` returns `None` (or is omitted), each turn starts a fresh
SDK session.

## Capabilities

`ClaudeSDKProvider` is the only Zeno provider that supports:

- `sub_agents` — Claude Agent SDK dispatch via `AgentDefinition`
- `built_in_tools` — `WebSearch`, `WebFetch`, `Bash`, etc.
- `permission_mode` — `default` / `acceptEdits` / `bypassPermissions` / `plan`
- Streaming assistant text via `ctx.stream(...)`
- SDK hook bridge (`PreToolUse` / `PostToolUse` / `UserPromptSubmit` and the
  optional `SubagentStart` / `SubagentStop` / `PostToolUseFailure` hooks when
  available) translated into Zeno trace events.

## See also

- [`zeno-provider-openai`](../zeno-provider-openai/README.md) — OpenAI-compatible alternative (OpenRouter, LiteLLM, Azure, Ollama, etc.).
- [`docs/subagents.md`](../../docs/subagents.md) — orchestrator + specialist composition.
- [`docs/adapters.md`](../../docs/adapters.md) — writing your own `Provider`.

Part of the [Zeno framework](https://github.com/nkootstra/zeno).
