Overview
agent-hooks-rs is the Rust integration surface for Sigil pre-tool authorization. It provides:
sigil-agent-hooks-coreβ a generic Rust client for Sigil Sign/v1/authorizesigil-agent-hooks-ironclawβ a native IronClawHooktrait adapter
@sigilcore/agent-hooks package, so both implementations emit the same /v1/authorize request bodies for the same intents.
Scope today: agent-hooks-rs covers generic Rust authorization and the native
IronClaw tool-call hook. It does not cover Hermes, Codex, OpenRouter, AgentPay,
or other JavaScript host integrations. Those use the TypeScript package today.
HTTP note: Rust hosts emit typed http only when the intercepted input explicitly provides a valid method. Missing methods remain web_fetch; no GET inference is permitted.
Installation
Generic Rust Client
UseSigilClient directly when you want framework-agnostic pre-tool authorization in any Rust host.
IronClaw Hook
For IronClaw agents,IronclawSigilHook implements the Hook trait and registers on BeforeToolCall.
Unknown tools pass through as lowercase strings. To customize mapping, implement
ToolIntentMapper and pass it to IronclawSigilHook::builder(client).mapper(...).
Model Budget Status
Execution Limits v2 added model spend and token caps throughmetadata.model_usage on model.inference checks. sigil-agent-hooks-core
ships Rust-native helpers for this flow:
record_model_usageget_model_usage_reportclear_model_usagecheck_model_budgetnormalize_model_usage
metadata.model_usage, and sends action: "model.inference" with the
resolved task id. Spend accumulation uses integer microdollar math internally.
IronClawβs native hook currently sees BeforeToolCall events only. If your
IronClaw host owns the model provider call, wrap that provider call with the
core helpers above. Do not claim automatic IronClaw model-budget enforcement
unless your host has recorded provider usage and called check_model_budget.
Configuration
The IronClaw builder rebinds the default
FrameworkId::AgentHooks to FrameworkId::Ironclaw, so IronClaw authorize requests carry the correct framework identifier.
Fail Modes
agent-hooks-rs defaults to FailMode::Closed.
Unreachability includes network errors, DNS failures, refused connections, request timeouts, 5xx responses, non-JSON response bodies, and responses larger than 64 KiB. Authentication failures (
401 or 403) return SIGIL_AUTH_FAILURE, not SIGIL_UNREACHABLE.
Wire Parity
The Rust and TypeScript packages sharecontract-fixtures/v1/ files that pin the exact JSON wire format of /v1/authorize request bodies. Both test suites verify the fixture SHA-256 checksums and byte-compare generated request bodies against the fixtures.