Pre-tool veto hook · PyPI 0.1.0 · Alpha · Apache-2.0
claude-agent-acgs for Claude Agent SDK.
Registers a PreToolUse hook on the Claude Agent SDK to return allow, deny, or ask permission decisions before a tool runs.
Package Specification · Inspected HEAD f606a46
- Framework maintainer
- Anthropic · code.claude.com
- Upstream repository
- anthropics/claude-agent-sdk-python
- PyPI release
- claude-agent-acgs==0.1.0
- Python requirement
- >=3.10
- Framework constraint
- claude-agent-sdk>=0.2.119,<0.3
- Governance engine pin
- acgs-lite>=3.0.1,<4
- Integration mechanic
- Pre-tool veto / intervention hook
- Hook entry point
- ACGSHook.matcher / apply (PreToolUse)
01 · Local Setup & Quickstart
Attach governance to one tool-calling agent.
Install the pinned release from PyPI alongside acgs-lite>=3.0.1,<4. Rule evaluation uses deterministic keyword and regex matching locally in Python—no external model or network call is made by the governance check.
Shell · PyPI installation
pip install "claude-agent-acgs==0.1.0"Python · Claude Agent SDK integration
src/claude_agent_acgs/hook.py#L56from claude_agent_sdk import ClaudeAgentOptions, query
from claude_agent_acgs import ACGSHook
options = ACGSHook().apply(
ClaudeAgentOptions(permission_mode="bypassPermissions")
)
async for message in query(prompt="Tidy up the build directory.", options=options):
print(message)02 · Verdict & Review Mapping
How ACGS-Lite verdicts map to Claude Agent SDK.
When a tool call is proposed, the adapter formats the tool name and arguments via format_tool_call and evaluates them against the configured Constitution. Blocking rules always take precedence over review rules.
Returns no decision by default so Claude Code's normal permission flow applies (or returns 'allow' when grant_allowed=True).
Returns a PreToolUse 'deny' permission decision that blocks execution even in bypassPermissions mode.
Returns 'deny' by default; with on_review='ask', returns 'ask' so Claude Code prompts can_use_tool or the interactive user.
03 · Public API Surface
Exported symbols and source entry points.
Each adapter keeps its public surface minimal and re-exports the shared GovernanceDecision, Verdict, and ToolCallFormatter types alongside the framework-specific hook or middleware class.
__all__ exports · claude-agent-acgs
src/claude_agent_acgs/hook.py#L56 ↗ACGSHookOnReviewGovernanceDecisionToolCallFormatterVerdictformat_tool_callPrimary hook surface: ACGSHook.matcher / apply (PreToolUse). Custom ToolCallFormatter functions may be supplied if your tool arguments require custom canonical serialization before rule matching.
04 · Scope & Bypass Boundaries
What this adapter does and does not cover.
Verify these framework-specific boundaries when integrating claude-agent-acgs into an evaluation workflow.
- 01
Never raises an unhandled Python exception inside the hook callback, because Claude Code treats hook exceptions as allow; errors always return a structured 'deny'.
- 02
Covers built-in tools (such as Bash and Write), MCP tools, and sub-agent tool calls within the hooked ClaudeAgentOptions session.
- 03
In the current
0.1.xadapter series, rule evaluation runs throughacgs-lite'sToolCallGovernorpath. If your workflow requiresSignedReceipt,ExecutionGrant, or SQLiteEffectStorereservations, wire those contracts explicitly at the tool executor boundary.
Put one real workflow under your control.
Choose one tool. Define what it may do. Inspect what happens when a request crosses the boundary.