Skip to main content

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/authorize
  • sigil-agent-hooks-ironclaw β€” a native IronClaw Hook trait adapter
The Rust crates share contract fixtures with the TypeScript @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

Minimum supported Rust version: 1.92.

Generic Rust Client

Use SigilClient 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.
The adapter maps common tool aliases to Sigil action names: 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 through metadata.model_usage on model.inference checks. sigil-agent-hooks-core ships Rust-native helpers for this flow:
  • record_model_usage
  • get_model_usage_report
  • clear_model_usage
  • check_model_budget
  • normalize_model_usage
The helper accumulates per-task usage for 24 hours, serializes the cumulative report as 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 share contract-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.

Source

github.com/Sigil-Core/agent-hooks-rs β€” MIT License