Metadata-Version: 2.4
Name: watchlight-claude-agent
Version: 0.2.1
Summary: Watchlight governance hooks for Claude Agent SDK agents: authorize every tool call and sub-agent spawn before it runs, fail-closed. Model turns are not authorized. Independent plugin, not affiliated with Anthropic.
Author-email: Watchlight AI <team@watchlight.ai>
License: Apache-2.0
Project-URL: Homepage, https://watchlight.ai
Project-URL: Documentation, https://docs.watchlight.ai/de
Keywords: watchlight,claude-agent-sdk,claude-code,ai-agent,agent-governance,authorization,lineage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: watchlight-agent-sdk>=0.9.4
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.0; extra == "claude"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"

# watchlight-claude-agent

Governed Claude Agent SDK agents with Watchlight: every tool call and every sub-agent launch is authorized before it runs, and refused on any doubt.

```bash
pip install watchlight-claude-agent
```

> **Independent third-party plugin.** This is an independent integration built by Watchlight AI. It is **not affiliated with, endorsed by, or sponsored by** Anthropic. `Claude Agent SDK` and related names are trademarks of Anthropic, used here nominatively only to describe compatibility.

## What it enforces

The Python Claude Agent SDK has no plugin loader, so the plugin ships its enforcement as a hook map. `plugin.governed_options(handle, options)` (or `plugin.governance_hooks(handle)`) adds these hooks to your `ClaudeAgentOptions`:

- **Every tool call** goes through a `PreToolUse` gate. The call is authorized on the handle of the agent that made it: a sub-agent's own handle for a sub-agent's call, the root handle otherwise. A deny, a needs-approval decision, an unreachable backend or any other error returns a `deny` decision, so the tool does not run. Only argument names and value types are sent for authorization, never argument values.
- **Sub-agent launches** (the `Task` / `Agent` tool) perform the governed spawn in the same `PreToolUse` gate, before the tool runs. The child gets its own credential with a scope that the server narrows to a subset of the parent's. When the spawn is refused, the sub-agent type is not a registered agent, or anything else goes wrong, the tool call is denied: the sub-agent never starts and never gets a model turn.
- A sub-agent that starts without a governed spawn, or a tool call from an agent the plugin cannot identify while a sub-agent is running, is denied.
- A starting sub-agent binds to its governed spawn by tool-use id when the SDK provides one, otherwise by sub-agent type. The SDK's `SubagentStart` input carries no tool-use id, so a second launch of a type that is still starting is denied (the two could not be told apart), including when both launches are gated at the same moment: the first one reserves its slot before the gate does any work. A launch that never starts (a later hook or a permission prompt refused it) is closed on `PostToolUse` / `PostToolUseFailure`, at `Stop`, or after 120 seconds.
- Each `PreToolUse` decision has a 45-second deadline, inside the 60-second timeout the plugin sets on its hook matchers; a decision that is not made in time is a deny.
- **Run start fails closed.** `start_run` raises `AgentNotRegistered` for an unknown agent and `GovernanceUnavailable` when the backend does not open the session. It also refuses the run, and closes the session it opened, when the backend issues no constraint manifest, unless the operator explicitly set `WATCHLIGHT_PLAN_GOVERNANCE_MODE=degrade`.
- **Egress.** When a wl-proxy URL is configured (`connect_proxy_url=` or `WATCHLIGHT_PROXY_URL`), `start_run` installs a local CONNECT proxy and sets `HTTPS_PROXY` / `HTTP_PROXY` for this process, so Python HTTP clients that honour those variables go through wl-proxy. If the backend issued no proxy token, or the proxy cannot be installed, `start_run` raises `GovernanceUnavailable` instead of running with direct egress. Clients that ignore `HTTPS_PROXY` are not covered.

What it does not do: model turns themselves are not authorized (only the tools they call), and plan validation (`handle.submit_plan`) runs only when you call it. Your own hooks are kept, but they run alongside Watchlight's: a deny from any hook stops the call, so they cannot turn a Watchlight deny into an allow.

The policy decisions run on Watchlight's compiled engine, either in-process for local development or against the governed control plane in production.

## Quickstart

For local development, the zero-infrastructure **Developer Edition** runs the compiled engine in-process (requires the `watchlight-engine` package):

```bash
pip install watchlight-claude-agent watchlight-engine
```

```python
from claude_agent_sdk import ClaudeAgentOptions, query
from watchlight_claude_agent import WatchlightClaudeAgentSDKPlugin
from watchlight_core import InProcessClient

# A Cedar policy: the research agent may execute tools. Anything not
# permitted is denied.
POLICIES = [
    {"name": "tools",
     "code": 'permit(principal == Agent::"research-agent", action == Action::"execute", resource);'},
]

plugin = WatchlightClaudeAgentSDKPlugin(governance=InProcessClient(POLICIES))

async def run_agent(question: str):
    async with await plugin.start_run("research-agent") as handle:
        # Every tool call and sub-agent launch now goes through Watchlight.
        options = plugin.governed_options(handle, ClaudeAgentOptions())
        async for message in query(prompt=question, options=options):
            print(message)
```

Each tool call is authorized as action `execute` on a resource named after the tool (for example `Read`, `Bash`, `mcp__server__tool`).

Sub-agents must be registered Watchlight agents (the `subagent_type` of the `Task` call is resolved to a registered agent). Their requested scope comes from `default_subagent_scope=` (or `WATCHLIGHT_DEFAULT_SUBAGENT_SCOPE`); when that is empty the sub-agent starts with no tools and its first tool call is denied.

### Attributing runs to an AI application

Every governed run can be attributed to the AI application the agent belongs to. Pass `application_id="<application UUID>"` to `WatchlightClaudeAgentSDKPlugin(...)`, or per run to `start_run(...)`, or set `WATCHLIGHT_APPLICATION_ID` in the environment — an explicit argument wins over the env var. The id is sent on session create and bound to the run credential and to every sub-agent the run spawns; wl-apdp refuses the session if the agent is not a member of that application. An agent in exactly one application needs nothing here. The id is explicit configuration, never inferred from prompts or names, and it is an Enterprise feature: the in-process Developer Edition engine refuses it.

## Two backends, same code

|  | Backend | Runs |
|---|---|---|
| **Developer Edition** | `InProcessClient` | The compiled engine, **in-process** — no server, no network |
| **Enterprise** | `ApdpClient` | The governed control plane — signed lineage, drift detection, fleet-wide governance |

Moving from local to production is a one-line change:

```python
import os

from watchlight_core import ApdpClient

# Read the API key from the environment or your secret manager; never
# write it into source code.
plugin = WatchlightClaudeAgentSDKPlugin(
    governance=ApdpClient(
        "https://apdp.your-company.example",
        api_key=os.environ["WATCHLIGHT_API_KEY"],
    )
)
```

## Links

- Documentation: https://docs.watchlight.ai/de
- Website: https://watchlight.ai

## License

Apache-2.0
