langchain - 💡(How to fix) Fix Governance callback handler for tool call authorization, cost tracking, and audit trails

Submission checklist

• This is a feature request, not a bug report or usage question.
• I added a clear and descriptive title that summarizes the feature request.
• I used the GitHub search to find a similar feature request and didn't find it.
• I checked the LangChain documentation and API reference to see if this feature already exists.
• This is not related to the langchain-community package.

Package (Required)

• langchain
• langchain-openai
• langchain-anthropic
• langchain-classic
• langchain-core
• langchain-model-profiles
• langchain-tests
• langchain-text-splitters
• langchain-chroma
• langchain-deepseek
• langchain-exa
• langchain-fireworks
• langchain-groq
• langchain-huggingface
• langchain-mistralai
• langchain-nomic
• langchain-ollama
• langchain-openrouter
• langchain-perplexity
• langchain-qdrant
• langchain-xai
• Other / not sure / general

Feature Description

LangChain agents execute tools autonomously but there's no standard callback pattern for governance — authorization, cost enforcement, and audit trails before/after tool execution.

Requesting a GovernanceCallbackHandler (or similar pattern) that enables:

• Tool call authorization (allowlist/denylist per agent identity)
• Cost tracking and budget enforcement per session/agent
• Audit trail with correlation IDs for every tool invocation
• Prompt injection detection on inputs before they reach the model

This would be a BaseCallbackHandler implementation that hooks into on_tool_start and on_tool_end to evaluate governance policy before execution proceeds.

Use Case

Teams deploying LangChain agents in production need governance controls:

1. Authorization: "Agent X can use search_tool but not file_delete_tool"
2. Cost limits: "Block requests if session cost exceeds $5"
3. Audit: "Every tool call must produce a traceable evidence record"
4. Safety: "Block tool calls that contain PII or prompt injection patterns"

Currently, teams implement this ad-hoc by wrapping individual tools or subclassing agents. A standard callback-based pattern would make governance composable and reusable across any agent architecture (ReAct, tool-calling, plan-and-execute).

Real-world example: an enterprise customer support agent that can search knowledge bases but must not access customer PII export tools, with every decision logged for compliance audit.

Proposed Solution

A callback handler that evaluates governance policy on tool events:

from langchain_core.callbacks import BaseCallbackHandler

class GovernanceCallbackHandler(BaseCallbackHandler):
    def on_tool_start(self, serialized, input_str, **kwargs):
        tool_name = serialized.get("name")
        decision = self.policy_engine.evaluate(
            action="tool.execute",
            tool=tool_name,
            agent_id=kwargs.get("run_id")
        )
        if not decision.allowed:
            raise ToolExecutionError(f"Blocked by governance: {decision.reason}")

    def on_tool_end(self, output, **kwargs):
        self.cost_tracker.record(kwargs.get("run_id"), output)
        self.audit_log.emit(kwargs.get("run_id"), output)


This keeps governance decoupled from agent logic — add/remove governance by adding/removing the callback. No changes to existing agent code required.

I maintain TealTiger (https://github.com/agentguard-ai/tealtiger), an open-source governance SDK (Apache 2.0) that provides the policy engine, cost tracker, and audit layer. Happy to submit a PR implementing this as a community integration if the pattern is welcome.

### Alternatives Considered

1. Wrapping individual tools with governance logic — works but doesn't compose well across agents and requires modifying every tool.

2. Subclassing AgentExecutor — tightly couples governance to a specific agent type, breaks when switching between ReAct/tool-calling/plan-and-execute.

3. Custom middleware layer outside LangChain — loses access to LangChain's internal state (run_id, serialized tool info, parent chain context).

The callback approach is preferred because it's composable, non-invasive, and works with any agent architecture that uses the standard callback system.

### Additional Context

- We have a working LangChain integration example: https://github.com/agentguard-ai/tealtiger
- OWASP Agentic Top 10 (https://owasp.org/www-project-top-10-for-agentic-applications/) identifies tool misuse (ASI-02) and access control failures (ASI-03) as top risks for agentic applications
- Similar patterns exist in other frameworks: CrewAI has tool-level hooks, AutoGen has message interceptors
- Happy to submit a PR if this direction aligns with LangChain's extension model