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.pyindex 352aadbd..22ee17fb 100644--- a/src/openjarvis/agents/orchestrator.py+++ b/src/openjarvis/agents/orchestrator.py@@ -14,8 +14,9 @@ from __future__ import annotationsimport concurrent.futuresimport json+import loggingimport re-from typing import Any, List, Optional+from typing import Any, Callable, List, Optionalfrom openjarvis.agents._stubs import AgentContext, AgentResult, ToolUsingAgentfrom openjarvis.core.events import EventBus@@ -24,6 +25,8 @@ from openjarvis.core.types import Message, Role, ToolCall, ToolResultfrom openjarvis.engine._stubs import InferenceEnginefrom 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 = modeself._system_prompt = system_promptself._parallel_tools = parallel_tools+ self._before_tool_call = before_tool_calldef 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 resultsif 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 orderfor tc in tool_calls:@@ -406,6 +469,20 @@ class OrchestratorAgent(ToolUsingAgent):else:# Sequential executionfor 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 executionif self._loop_guard:verdict = self._loop_guard.check_call(diff --git a/tests/agents/test_orchestrator.py b/tests/agents/test_orchestrator.pyindex 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 timefrom unittest.mock import MagicMockfrom 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 timeclass _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