anthropics / anthropics/claude-agent-sdk-python

feat: governance hook integration for deterministic tool call authorization (TealTiger)

Offen
#1,022 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
Vorherrschende Sprache
Python
Sterne
8.1k
Forks
1.3k
Ø Merge
2 T. 31 Min.
Gemergte PRs (30 T.)
1

Beschreibung

## Summary

I'd like to propose/contribute a governance integration that works with Claude Agent SDK's `tool_permission_callback` to provide deterministic policy evaluation, cost tracking, and structured audit records for tool calls.

## Problem

The existing `tool_permission_callback` provides a binary allow/deny mechanism, but production deployments need:
- Deterministic policy evaluation (not just manual allow/deny logic)
- Cost tracking per tool call, per session, with budget enforcement
- Structured audit records for compliance
- Per-tool allowlists that can be configured without code changes
- Circuit breaking when tool providers are failing
- A "observe first, enforce later" adoption path

## Proposed Integration

```python
from claude_agent_sdk import Agent
from claude_tealtiger import TealTigerPermissionCallback

# Zero-config: observe all tool calls, track cost, detect PII (no blocking)
agent = Agent(
model="claude-sonnet-4-20250514",
tool_permission_callback=TealTigerPermissionCallback(),
)

# With governance policies
from tealtiger import TealEngine
engine = TealEngine(policies=company_policies, mode="ENFORCE")
agent = Agent(
model="claude-sonnet-4-20250514",
tool_permission_callback=TealTigerPermissionCallback(engine=engine),
)
```

## Capabilities

- Integrates with existing `tool_permission_callback` interface
- Pre-tool-call policy evaluation (<5ms, deterministic, no LLM in governance path)
- Tool allowlisting (block tools not in approved list)
- Cost tracking per session with budget enforcement
- PII detection in tool arguments
- Structured audit trail with correlation IDs
- Kill switch to halt execution
- Zero-config mode: always returns True (allow) but records everything for later analysis
- Policy mode: returns True/False based on deterministic policy evaluation

## Why Claude Agent SDK specifically

The `tool_permission_callback` is already the right hook point. This integration fills it with a production-ready governance engine instead of requiring users to write custom permission logic for each deployment.

It also provides the "observe first" adoption path: start with `TealTigerPermissionCallback()` that allows everything but tracks cost and detects PII, then later switch to `TealTigerPermissionCallback(engine=engine)` when policies are ready.

## Context

- [TealTiger](https://github.com/agentguard-ai/tealtiger) — open-source AI agent security platform (Apache-2.0, NVIDIA Inception)
- Published on PyPI (`tealtiger` v1.3.0) and npm (`tealtiger-ai-sdk` v0.1.0)
- Covers 8/10 OWASP Agentic Security Index categories
- All governance is deterministic and in-process — no external service, <5ms overhead
- Already integrated with LangChain, Vercel AI SDK, CrewAI, LlamaIndex, AG2, Haystack, Pydantic AI, Mastra, Semantic Kernel

## Contribution plan

Happy to contribute:
1. A standalone `claude-tealtiger` pip package implementing `tool_permission_callback`
2. A cookbook entry in `anthropics/claude-cookbooks` showing the integration
3. Documentation showing zero-config → policy-driven adoption path

## References

- https://github.com/agentguard-ai/tealtiger — TealTiger source (Apache-2.0)
- https://pypi.org/project/tealtiger/ — TealTiger on PyPI (v1.3.0)
- https://www.npmjs.com/package/tealtiger-ai-sdk — Vercel AI SDK middleware (v0.1.0)
- https://owasp.org/www-project-top-10-for-large-language-model-applications/ — OWASP ASI
- Existing `tool_permission_callback` example in this repo

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.