anthropics / anthropics/claude-agent-sdk-python

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

Open
#1,022 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
8.1k
Forks
1.3k
Avg merge
2d 31m
Merged PRs (30d)
1

Description

## 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

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the existing tool_permission_callback example mentioned in the issue and inspect the SDK's callback interface. Clarify with maintainers whether the intended contribution is a standalone claude-tealtiger package, a cookbook entry, documentation, or some combination; completion criteria are not defined in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.