Skip to content

Personal AI, On Personal Devices

Python

feat: add optional before_tool_call governance hook to OrchestratorAgent (#601)

Joshua Shovana25100e7c3b7
diff --git a/src/openjarvis/agents/orchestrator.py b/src/openjarvis/agents/orchestrator.py
index 352aadbd..22ee17fb 100644
--- a/src/openjarvis/agents/orchestrator.py
+++ b/src/openjarvis/agents/orchestrator.py
@@ -14,8 +14,9 @@ from __future__ import annotations
import concurrent.futures
import json
+import logging
import re
-from typing import Any, List, Optional
+from typing import Any, Callable, List, Optional
from openjarvis.agents._stubs import AgentContext, AgentResult, ToolUsingAgent
from openjarvis.core.events import EventBus
@@ -24,6 +25,8 @@ from openjarvis.core.types import Message, Role, ToolCall, ToolResult
from openjarvis.engine._stubs import InferenceEngine
from openjarvis.tools._stubs import BaseTool
+logger = logging.getLogger(__name__)
+
@AgentRegistry.register("orchestrator")
class OrchestratorAgent(ToolUsingAgent):
@@ -62,6 +65,7 @@ class OrchestratorAgent(ToolUsingAgent):
parallel_tools: bool = True,
interactive: bool = False,
confirm_callback=None,
+ before_tool_call: Optional[Callable[[str, dict[str, Any]], bool]] = None,
) -> None:
super().__init__(
engine,
@@ -78,6 +82,7 @@ class OrchestratorAgent(ToolUsingAgent):
self._mode = mode
self._system_prompt = system_prompt
self._parallel_tools = parallel_tools
+ self._before_tool_call = before_tool_call
def run(
self,
@@ -89,6 +94,47 @@ class OrchestratorAgent(ToolUsingAgent):
return self._run_structured(input, context, **kwargs)
return self._run_function_calling(input, context, **kwargs)
+ # ------------------------------------------------------------------
+ # Governance hook
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ def _governance_denial(tool_name: str, reason: str) -> ToolResult:
+ return ToolResult(
+ tool_name=tool_name,
+ content=(
+ f"[Governance] Tool '{tool_name}' was not approved ({reason}). "
+ "Adjust your plan and try a different approach."
+ ),
+ success=False,
+ )
+
+ def _check_tool_allowed(self, tc: ToolCall) -> Optional[ToolResult]:
+ """Call before_tool_call hook if set.
+
+ Returns None to allow execution, or a denial ToolResult to inject
+ instead of running the tool. Invalid arguments and hook failures deny
+ execution so a governance integration cannot fail open.
+ """
+ if self._before_tool_call is None:
+ return None
+
+ try:
+ tool_args = json.loads(tc.arguments) if tc.arguments else {}
+ except (json.JSONDecodeError, TypeError):
+ return self._governance_denial(tc.name, "invalid tool arguments")
+ if not isinstance(tool_args, dict):
+ return self._governance_denial(tc.name, "tool arguments are not an object")
+
+ try:
+ allowed = self._before_tool_call(tc.name, tool_args)
+ except Exception:
+ logger.exception("before_tool_call hook failed for tool %s", tc.name)
+ return self._governance_denial(tc.name, "governance check failed")
+ if allowed:
+ return None
+ return self._governance_denial(tc.name, "policy denied the call")
+
# ------------------------------------------------------------------
# Structured mode (THOUGHT/TOOL/INPUT/FINAL_ANSWER)
# ------------------------------------------------------------------
@@ -148,7 +194,11 @@ class OrchestratorAgent(ToolUsingAgent):
parsed["input"],
),
)
- tool_result = self._executor.execute(tool_call)
+ denial = self._check_tool_allowed(tool_call)
+ if denial is not None:
+ tool_result = denial
+ else:
+ tool_result = self._executor.execute(tool_call)
all_tool_results.append(tool_result)
if tool_result.success:
@@ -367,7 +417,18 @@ class OrchestratorAgent(ToolUsingAgent):
# Execute each tool (with loop guard check) and append results
if self._parallel_tools and len(tool_calls) > 1:
- # Parallel execution
+ # Governance callbacks often wrap stateful policy engines and
+ # are not assumed to be thread-safe. Evaluate them in request
+ # order before dispatching the approved tool work in parallel.
+ results_map: dict[int, tuple[ToolCall, ToolResult]] = {}
+ approved_calls: list[ToolCall] = []
+ for tc in tool_calls:
+ denial = self._check_tool_allowed(tc)
+ if denial is None:
+ approved_calls.append(tc)
+ else:
+ results_map[id(tc)] = (tc, denial)
+
def _exec_tool(tc: ToolCall) -> tuple:
if self._loop_guard:
verdict = self._loop_guard.check_call(
@@ -382,14 +443,16 @@ class OrchestratorAgent(ToolUsingAgent):
)
return tc, self._executor.execute(tc)
- with concurrent.futures.ThreadPoolExecutor(
- max_workers=len(tool_calls),
- ) as pool:
- futures = {pool.submit(_exec_tool, tc): tc for tc in tool_calls}
- results_map: dict[int, tuple] = {}
- for future in concurrent.futures.as_completed(futures):
- tc_orig = futures[future]
- results_map[id(tc_orig)] = future.result()
+ if approved_calls:
+ with concurrent.futures.ThreadPoolExecutor(
+ max_workers=len(approved_calls),
+ ) as pool:
+ futures = {
+ pool.submit(_exec_tool, tc): tc for tc in approved_calls
+ }
+ for future in concurrent.futures.as_completed(futures):
+ tc_orig = futures[future]
+ results_map[id(tc_orig)] = future.result()
# Append results in original order
for tc in tool_calls:
@@ -406,6 +469,20 @@ class OrchestratorAgent(ToolUsingAgent):
else:
# Sequential execution
for tc in tool_calls:
+ # Governance hook check before execution
+ denial = self._check_tool_allowed(tc)
+ if denial is not None:
+ all_tool_results.append(denial)
+ messages.append(
+ Message(
+ role=Role.TOOL,
+ content=denial.content,
+ tool_call_id=tc.id,
+ name=tc.name,
+ )
+ )
+ continue
+
# Loop guard check before execution
if self._loop_guard:
verdict = self._loop_guard.check_call(
diff --git a/tests/agents/test_orchestrator.py b/tests/agents/test_orchestrator.py
index f3c753d0..124c569f 100644
--- a/tests/agents/test_orchestrator.py
+++ b/tests/agents/test_orchestrator.py
@@ -2,6 +2,8 @@
from __future__ import annotations
+import threading
+import time
from unittest.mock import MagicMock
from openjarvis.agents._stubs import AgentContext
@@ -568,7 +570,6 @@ class TestOrchestratorParallelTools:
def test_parallel_tool_execution(self):
"""Multiple tool calls execute in parallel and return in correct order."""
- import time
class _SlowTool(BaseTool):
tool_id = "slow"
@@ -665,3 +666,252 @@ class TestOrchestratorParallelTools:
)
result = agent.run("What is 2+2?")
assert result.content == "The answer is 4."
+
+
+class TestOrchestratorGovernanceHook:
+ """Tests for the optional before_tool_call governance hook."""
+
+ def test_no_hook_runs_tool_normally(self):
+ """Without a hook, tool execution is unchanged."""
+ engine = _make_engine_with_tool_call()
+ agent = OrchestratorAgent(
+ engine,
+ "test-model",
+ tools=[_CalculatorStub()],
+ )
+ result = agent.run("What is 2+2?")
+ assert result.content == "The answer is 4."
+ assert result.tool_results[0].success is True
+ assert result.tool_results[0].content == "4"
+
+ def test_hook_returning_true_allows_tool(self):
+ """Hook returning True allows the tool to execute normally."""
+ engine = _make_engine_with_tool_call()
+ agent = OrchestratorAgent(
+ engine,
+ "test-model",
+ tools=[_CalculatorStub()],
+ before_tool_call=lambda name, args: True,
+ )
+ result = agent.run("What is 2+2?")
+ assert result.tool_results[0].success is True
+ assert result.tool_results[0].content == "4"
+
+ def test_hook_returning_false_blocks_tool(self):
+ """Hook returning False injects a denial; the tool is never executed."""
+ executed = []
+
+ class _TrackedCalculator(_CalculatorStub):
+ def execute(self, **params) -> ToolResult:
+ executed.append(params)
+ return super().execute(**params)
+
+ engine = _make_engine_with_tool_call()
+ agent = OrchestratorAgent(
+ engine,
+ "test-model",
+ tools=[_TrackedCalculator()],
+ before_tool_call=lambda name, args: False,
+ )
+ result = agent.run("What is 2+2?")
+ assert executed == [], "tool must not be called when hook returns False"
+ assert result.tool_results[0].success is False
+ assert "[Governance]" in result.tool_results[0].content
+
+ def test_hook_receives_correct_tool_name_and_args(self):
+ """The hook is called with the exact tool name and parsed argument dict."""
+ calls: list[tuple] = []
+
+ def _hook(name: str, args: dict) -> bool:
+ calls.append((name, args))
+ return True
+
+ engine = _make_engine_with_tool_call(
+ tool_name="calculator",
+ arguments='{"expression":"3*7"}',
+ )
+ agent = OrchestratorAgent(
+ engine,
+ "test-model",
+ tools=[_CalculatorStub()],
+ before_tool_call=_hook,
+ )
+ agent.run("Calculate")
+ assert len(calls) == 1
+ assert calls[0][0] == "calculator"
+ assert calls[0][1] == {"expression": "3*7"}
+
+ def test_hook_denial_in_parallel_mode(self):
+ """Hook returning False blocks tools in the parallel execution path."""
+ executed = []
+
+ class _TrackedCalculator(_CalculatorStub):
+ def execute(self, **params) -> ToolResult:
+ executed.append(params)
+ return super().execute(**params)
+
+ engine = _make_engine_multi_tool()
+ agent = OrchestratorAgent(
+ engine,
+ "test-model",
+ tools=[_TrackedCalculator(), _ThinkStub()],
+ parallel_tools=True,
+ before_tool_call=lambda name, args: False,
+ )
+ result = agent.run("Think and calculate.")
+ assert executed == [], "no tool must execute when hook denies"
+ assert len(result.tool_results) == 2
+ assert all(not tr.success for tr in result.tool_results)
+ assert all("[Governance]" in tr.content for tr in result.tool_results)
+
+ def test_hook_denial_in_structured_mode(self):
+ """Hook returning False blocks a tool in structured (ReAct) mode."""
+ executed = []
+
+ class _TrackedCalculator(_CalculatorStub):
+ def execute(self, **params) -> ToolResult:
+ executed.append(params)
+ return super().execute(**params)
+
+ engine = MagicMock()
+ engine.engine_id = "mock"
+ engine.generate.side_effect = [
+ {
+ "content": (
+ "THOUGHT: Need to calculate.\n"
+ "TOOL: calculator\n"
+ 'INPUT: {"expression":"2+2"}'
+ ),
+ "usage": {
+ "prompt_tokens": 10,
+ "completion_tokens": 10,
+ "total_tokens": 20,
+ },
+ "model": "test-model",
+ "finish_reason": "stop",
+ },
+ {
+ "content": "THOUGHT: Blocked.\nFINAL_ANSWER: Could not calculate.",
+ "usage": {
+ "prompt_tokens": 20,
+ "completion_tokens": 10,
+ "total_tokens": 30,
+ },
+ "model": "test-model",
+ "finish_reason": "stop",
+ },
+ ]
+ agent = OrchestratorAgent(
+ engine,
+ "test-model",
+ tools=[_TrackedCalculator()],
+ mode="structured",
+ before_tool_call=lambda name, args: False,
+ )
+ result = agent.run("What is 2+2?")
+ assert executed == [], "tool must not execute when hook denies"
+ assert len(result.tool_results) == 1
+ assert result.tool_results[0].success is False
+ assert "[Governance]" in result.tool_results[0].content
+
+ def test_hook_exception_fails_closed_without_aborting_agent(self):
+ """A broken policy integration denies the call instead of crashing."""
+ executed = []
+
+ class _TrackedCalculator(_CalculatorStub):
+ def execute(self, **params) -> ToolResult:
+ executed.append(params)
+ return super().execute(**params)
+
+ def _broken_hook(name: str, args: dict) -> bool:
+ raise RuntimeError("policy service unavailable")
+
+ agent = OrchestratorAgent(
+ _make_engine_with_tool_call(),
+ "test-model",
+ tools=[_TrackedCalculator()],
+ before_tool_call=_broken_hook,
+ )
+
+ result = agent.run("What is 2+2?")
+
+ assert result.content == "The answer is 4."
+ assert executed == []
+ assert result.tool_results[0].success is False
+ assert "governance check failed" in result.tool_results[0].content
+
+ def test_parallel_hook_callbacks_are_serialized(self):
+ """Policy callbacks run deterministically before parallel tool work."""
+ state_lock = threading.Lock()
+ active_callbacks = 0
+ overlapped = False
+ callback_threads: list[int] = []
+ caller_thread = threading.get_ident()
+
+ def _stateful_hook(name: str, args: dict) -> bool:
+ nonlocal active_callbacks, overlapped
+ with state_lock:
+ active_callbacks += 1
+ overlapped = overlapped or active_callbacks > 1
+ callback_threads.append(threading.get_ident())
+ time.sleep(0.03)
+ with state_lock:
+ active_callbacks -= 1
+ return True
+
+ agent = OrchestratorAgent(
+ _make_engine_multi_tool(),
+ "test-model",
+ tools=[_CalculatorStub(), _ThinkStub()],
+ parallel_tools=True,
+ before_tool_call=_stateful_hook,
+ )
+
+ result = agent.run("Think and calculate.")
+
+ assert all(tool_result.success for tool_result in result.tool_results)
+ assert overlapped is False
+ assert callback_threads == [caller_thread, caller_thread]
+
+ def test_parallel_hook_failure_denies_only_that_call(self):
+ """One failed decision cannot abort other calls in the same batch."""
+
+ def _partially_broken_hook(name: str, args: dict) -> bool:
+ if name == "calculator":
+ raise RuntimeError("policy service unavailable")
+ return True
+
+ agent = OrchestratorAgent(
+ _make_engine_multi_tool(),
+ "test-model",
+ tools=[_CalculatorStub(), _ThinkStub()],
+ parallel_tools=True,
+ before_tool_call=_partially_broken_hook,
+ )
+
+ result = agent.run("Think and calculate.")
+
+ assert result.tool_results[0].success is False
+ assert "governance check failed" in result.tool_results[0].content
+ assert result.tool_results[1].success is True
+
+ def test_non_object_arguments_fail_closed(self):
+ """The documented dict callback never receives a list or scalar."""
+ calls = []
+
+ def _hook(name: str, args: dict) -> bool:
+ calls.append((name, args))
+ return True
+
+ agent = OrchestratorAgent(
+ _make_engine_with_tool_call(arguments='["2+2"]'),
+ "test-model",
+ tools=[_CalculatorStub()],
+ before_tool_call=_hook,
+ )
+
+ result = agent.run("What is 2+2?")
+
+ assert calls == []
+ assert result.tool_results[0].success is False
+ assert "not an object" in result.tool_results[0].content