feat(core): GovernanceCallbackHandler for tool execution authorization

[Devon Generally (devongenerally-png)]

Summary

Adds GovernanceCallbackHandler — a callback handler that enforces deterministic governance policies on tool calls using the existing on_tool_start / raise_error mechanism. No core changes required.

What it does

Implements a three-phase authorization pipeline for tool calls:

• PROPOSE: Converts each on_tool_start invocation into a structured intent object with a SHA-256 content hash
• DECIDE: Evaluates the intent against user-defined policy rules — pure function, no LLM involvement, no interpretation ambiguity
• PROMOTE: Allows approved calls to proceed normally; raises ToolExecutionDenied for denied calls (propagated via raise_error=True)

Policy format

policy = {
    "default": "deny",  # fail-closed
    "rules": [
        {"tools": ["search", "wikipedia"], "verdict": "approve"},
        {"tools": ["shell"], "verdict": "deny"},
        {
            "tools": ["python_repl"],
            "verdict": "approve",
            "constraints": {"blocked_patterns": ["os.system", "subprocess"]},
        },
    ],
}
handler = GovernanceCallbackHandler(policy=policy, witness_path="witness.jsonl")
agent.invoke(inputs, config={"callbacks": [handler]})

Witness logging

Optional hash-chained audit trail (witness_path parameter). Each entry links to the previous via SHA-256, making tampering detectable. Includes verify_witness_log() utility for independent chain verification.

Changes

• libs/core/langchain_core/callbacks/governance.py — handler implementation
• libs/core/tests/unit_tests/callbacks/test_governance.py — 24 unit tests

Design decisions

• raise_error = True by default — the handler must be able to block tool execution. This uses the existing handle_event exception propagation, requiring zero changes to the callback manager.
• Fail-closed default — when no rule matches a tool, the default verdict is deny. Unknown tools require explicit policy approval.
• Static methods for propose/decide — both phases are pure functions, independently testable without handler instantiation.

Test plan

• 24 unit tests covering: intent hashing, policy evaluation, constraint matching, exception propagation, witness chain integrity, tamper detection
• Verify no existing tests regress

For a more complete standalone implementation with YAML policy files and adversarial test coverage, see Governance-Guard.

This PR was developed with AI assistance.

[codspeed-hq]

Merging this PR will not alter performance

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

✅ 13 untouched benchmarks
⏩ 23 skipped benchmarks¹

---

_{Comparing devongenerally-png:governance-callback-handler (cd78744) with master (cdf140e)}

Footnotes

1. 23 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩