devtools: add tool calling support to review-patch.py
RFC 1/1 devtools: add tool calling support to review-patch.py
Add an iterative tool-use loop to review-patch.py for the Anthropic and OpenAI providers. The reviewer can now look up additional context from the DPDK source tree when the patch alone is insufficient, rather than having to guess at surrounding code, API contracts, or function signatures.
Tool calling is enabled by default with a limit of 10 rounds. Pass '--tool-rounds 0' to disable it and restore the previous single-shot behavior. The round limit prevents runaway cost on large patches that when reached will force the model to deliver a final judgement.
Initial tool set:
- grep Searches for regex across the file system with
optional path restrictions and case-insensitive matches.
- file_read Line range read of a specific path.
Both tools are limited to the repository root to prevent path traversal. Path outputs are relative to the repo root.
The system prompt is extended when tool calling is active to encourage the model to use tools only when genuinely needed, keeping unnecessary round trips and token costs under control and to a minimum.
Internally, _common.py gains send_request_raw() (returning the raw response dict) so the tool-calling loops can inspect stop_reason / finish_reason before extracting text.
--- devtools/ai/_common.py | 66 ++++- devtools/ai/review-patch.py | 552 +++++++++++++++++++++++++++++++++++- 2 files changed, 602 insertions(+), 16 deletions(-)
devtools/ai/_common.py +54 -12
@@ -121,7 +121,8 @@ def add_token_args(parser: argparse.ArgumentParser) -> None: def print_token_summary( usage: TokenUsage, provider: str, model: str, show: bool ) -> None: - """Print token usage summary to stderr if requested and any calls were made.""" + """Print token usage summary to stderr if requested and any calls were + made.""" if not show or usage.api_calls == 0: return print("", file=sys.stderr)
@@ -173,13 +174,15 @@ def _extract_usage(provider: str, result: dict[str, Any]) -> TokenUsage: def _extract_text(provider: str, result: dict[str, Any]) -> str: - """Extract response text from a provider response. Calls error() on failure.""" + """Extract response text from a provider response. Calls error() on + failure.""" if "error" in result: error(f"API error: {result['error'].get('message', result)}") if provider == "anthropic": content = result.get("content", []) return "".join( - block.get("text", "") for block in content if block.get("type") == "text" + block.get("text", "") for block in content + if block.get("type") == "text" ) if provider == "google": candidates = result.get("candidates", [])
@@ -200,13 +203,14 @@ def _print_verbose_usage(usage: TokenUsage) -> None: print(f"Input tokens: {usage.input_tokens:,}", file=sys.stderr) print(f"Output tokens: {usage.output_tokens:,}", file=sys.stderr) if usage.cache_creation_tokens: - print(f"Cache creation: {usage.cache_creation_tokens:,}", file=sys.stderr) + print(f"Cache creation: {usage.cache_creation_tokens:,}", + file=sys.stderr) if usage.cache_read_tokens: print(f"Cache read: {usage.cache_read_tokens:,}", file=sys.stderr) print("===================", file=sys.stderr) -def send_request( +def _send_http_raw( provider: str, api_key: str, model: str,
@@ -214,13 +218,9 @@ def send_request( *, timeout: int = 120, verbose: bool = False, -) -> tuple[str, TokenUsage]: - """Send a prebuilt request to a provider and return (response_text, usage). - - The caller assembles the provider-specific request body via its own - build_*_request helpers (the prompts differ per script). This function - handles transport, error reporting, and token-usage extraction. - """ +) -> tuple[dict[str, Any], TokenUsage]: + """Shared HTTP transport layer. Returns (response_dict, usage). Calls + error() on failure.""" url, headers = _build_request_meta(provider, api_key, model) body = json.dumps(request_data).encode("utf-8") req = Request(url, data=body, headers=headers)
@@ -243,4 +243,46 @@ def send_request( usage = _extract_usage(provider, result) if verbose: _print_verbose_usage(usage) + return result, usage + + +def send_request( + provider: str, + api_key: str, + model: str, + request_data: dict[str, Any], + *, + timeout: int = 120, + verbose: bool = False, +) -> tuple[str, TokenUsage]: + """Send a prebuilt request to a provider and return (response_text, usage). + + The caller assembles the provider-specific request body via its own + build_*_request helpers (the prompts differ per script). This function + handles transport, error reporting, and token-usage extraction. + """ + result, usage = _send_http_raw( + provider, api_key, model, request_data, timeout=timeout, + verbose=verbose + ) return _extract_text(provider, result), usage + + +def send_request_raw( + provider: str, + api_key: str, + model: str, + request_data: dict[str, Any], + *, + timeout: int = 120, + verbose: bool = False, +) -> tuple[dict[str, Any], TokenUsage]: + """Send a prebuilt request and return the raw response dict plus usage. + + Used by tool-calling loops that need to inspect stop_reason / finish_reason + before extracting text. + """ + return _send_http_raw( + provider, api_key, model, request_data, timeout=timeout, + verbose=verbose + )
devtools/ai/review-patch.py +548 -4
625 lines not on this page · raw message
Signature · 1 line
2.51.0
Quoted 26 lines · Aaron Conole
Add an iterative tool-use loop to
review-patch.pyfor the Anthropic and OpenAI providers. The reviewer can now look up additional context from the DPDK source tree when the patch alone is insufficient, rather than having to guess at surrounding code, API contracts, or function signatures.Tool calling is enabled by default with a limit of 10 rounds. Pass '--tool-rounds 0' to disable it and restore the previous single-shot behavior. The round limit prevents runaway cost on large patches that when reached will force the model to deliver a final judgement.
Initial tool set:
- grep Searches for regex across the file system with
optional path restrictions and case-insensitive matches.
-file_readLine range read of a specific path.Both tools are limited to the repository root to prevent path traversal. Path outputs are relative to the repo root.
The system prompt is extended when tool calling is active to encourage the model to use tools only when genuinely needed, keeping unnecessary round trips and token costs under control and to a minimum.
Quoted 5 lines
Internally,
_common.pygainssend_request_raw()(returning the raw response dict) so the tool-calling loops can inspectstop_reason/finish_reasonbefore extracting text.Signed-off-by Aaron Conole <[email protected]>
- I got a strange comment that a (valid) sha1 (from a Fixes: tag) was unknown to the grep tool.
- Are those tools returning results on the current working directory? If so, the result may differ depending on whether you applied the series or not.
Did you consider wrapping around "git grep $pattern origin/main" / "git show origin/main:$file" ?
(determining the correct git reference may be hard..)
Signature · 1 line
David Marchand
Quoted 37 lines · David Marchand
Quoted 26 lines · Aaron Conole
Add an iterative tool-use loop to
review-patch.pyfor the Anthropic and OpenAI providers. The reviewer can now look up additional context from the DPDK source tree when the patch alone is insufficient, rather than having to guess at surrounding code, API contracts, or function signatures.Tool calling is enabled by default with a limit of 10 rounds. Pass '--tool-rounds 0' to disable it and restore the previous single-shot behavior. The round limit prevents runaway cost on large patches that when reached will force the model to deliver a final judgement.
Initial tool set:
- grep Searches for regex across the file system with
optional path restrictions and case-insensitive matches.
-file_readLine range read of a specific path.Both tools are limited to the repository root to prevent path traversal. Path outputs are relative to the repo root.
The system prompt is extended when tool calling is active to encourage the model to use tools only when genuinely needed, keeping unnecessary round trips and token costs under control and to a minimum.
Quoted 5 lines
Internally,
_common.pygainssend_request_raw()(returning the raw response dict) so the tool-calling loops can inspectstop_reason/finish_reasonbefore extracting text.Signed-off-by Aaron Conole <[email protected]>- I got a strange comment that a (valid) sha1 (from a Fixes: tag) was unknown to the grep tool.
Quoted 6 lines
- Are those tools returning results on the current working directory? If so, the result may differ depending on whether you applied the series or not.
Did you consider wrapping around "git grep $pattern origin/main" / "git show origin/main:$file" ?
(determining the correct git reference may be hard..)
I'll post a new revision. I've been testing with expended tools. Some of the errors are a result of not having the git log / git show / awk / sed commands available (model tool usage is *very* sensitive). I've added some safe versions and did quite a bit more testing. The result is quite a bit more promising.
Quoted 25 lines · On Tue, 9 Jun 2026 14:26:47 -0400 Aaron Conole <[email protected]> wrote:
Add an iterative tool-use loop to
review-patch.pyfor the Anthropic and OpenAI providers. The reviewer can now look up additional context from the DPDK source tree when the patch alone is insufficient, rather than having to guess at surrounding code, API contracts, or function signatures.Tool calling is enabled by default with a limit of 10 rounds. Pass '--tool-rounds 0' to disable it and restore the previous single-shot behavior. The round limit prevents runaway cost on large patches that when reached will force the model to deliver a final judgement.
Initial tool set:
- grep Searches for regex across the file system with
optional path restrictions and case-insensitive matches.
-file_readLine range read of a specific path.Both tools are limited to the repository root to prevent path traversal. Path outputs are relative to the repo root.
The system prompt is extended when tool calling is active to encourage the model to use tools only when genuinely needed, keeping unnecessary round trips and token costs under control and to a minimum.
Quoted 6 lines
Internally,
_common.pygainssend_request_raw()(returning the raw response dict) so the tool-calling loops can inspectstop_reason/finish_reasonbefore extracting text.Signed-off-by Aaron Conole <[email protected]>---
Well AI saw the security bypass here...
Error
=====
devtools/ai/review-patch.py: path containment check is bypassable (_tool_grep and _tool_file_read)
repo_resolved = Path(repo_root).resolve() search_path = (repo_resolved / rel_path).resolve() if not str(search_path).startswith(str(repo_resolved)):
return "Error: path is outside the repository"
str.startswith() on the resolved path string is a prefix match, not a path-component match. If repo_root resolves to /home/me/dpdk, then /home/me/dpdk-private/secrets passes the check, since the string starts with "/home/me/dpdk". The commit message states both tools are "limited to the repository root to prevent path traversal" -- that property does not hold for sibling directories sharing the name prefix. Same bug in both tool helpers.
# is_relative_to (3.9+), raises nothing, no string games if not search_path.is_relative_to(repo_resolved): return "Error: path is outside the repository"
(Absolute rel_path and ../ escapes are already caught by resolve() + this fix; only the prefix case is currently open.)
Warning
=======
devtools/ai/_common.py: unrelated reformatting mixed into a feature patch. The docstring re-wrapping in print_token_summary(), _extract_text(), _print_verbose_usage(), and the classify_review() regex reflow in review-patch.py are cosmetic churn unrelated to tool calling. Drop them or split into a separate cleanup; they inflate the diff and obscure the actual change.
devtools/ai/review-patch.py: grep --include list excludes the files the tool prompt points the model at. _tool_grep restricts to *.[ch]/*.py/*.rst/*.ini, but TOOL_PROMPT_EXTENSION explicitly directs the model to check ".ci/" scripts, meson.build, and MAINTAINERS. Those are extensionless or shell, so grep silently returns "No matches found" rather than surfacing the omission. Either widen the include set or note the restriction in the tool description so the model doesn't draw false conclusions from empty results.
Info
====
xai is OpenAI wire-compatible and already shares build_openai_request() elsewhere, but tool calling is gated to provider == "openai" in call_api() and the verbose banner. xai (and any future OpenAI-compatible provider) falls back to single-shot with no notice. Reusing call_api_with_tools_openai() for xai looks free.
send_request_raw() bypasses _extract_text(), which is where the "error" in result check lived. The tool loops read stop_reason / choices directly, so a provider error returned with HTTP 200 yields an empty string and a misleading "clean" review instead of a hard failure. Worth a guard on api_result.get("error") at the top of each loop body.
Default-on at 10 rounds is a behavior and cost change for every existing caller, and grants repo-wide read to the model by default. Reasonable for an RFC to propose, but worth calling out explicitly for the list -- some CI users may want opt-in rather than opt-out.
Quoted 99 lines · Stephen Hemminger
Quoted 25 lines · On Tue, 9 Jun 2026 14:26:47 -0400 Aaron Conole <[email protected]> wrote:
Add an iterative tool-use loop to
review-patch.pyfor the Anthropic and OpenAI providers. The reviewer can now look up additional context from the DPDK source tree when the patch alone is insufficient, rather than having to guess at surrounding code, API contracts, or function signatures.Tool calling is enabled by default with a limit of 10 rounds. Pass '--tool-rounds 0' to disable it and restore the previous single-shot behavior. The round limit prevents runaway cost on large patches that when reached will force the model to deliver a final judgement.
Initial tool set:
- grep Searches for regex across the file system with
optional path restrictions and case-insensitive matches.
-file_readLine range read of a specific path.Both tools are limited to the repository root to prevent path traversal. Path outputs are relative to the repo root.
The system prompt is extended when tool calling is active to encourage the model to use tools only when genuinely needed, keeping unnecessary round trips and token costs under control and to a minimum.
Quoted 6 lines
Internally,
_common.pygainssend_request_raw()(returning the raw response dict) so the tool-calling loops can inspectstop_reason/finish_reasonbefore extracting text.Signed-off-by Aaron Conole <[email protected]>---
Well AI saw the security bypass here...
Error
=====
devtools/ai/review-patch.py: path containment check is bypassable (_tool_grepand_tool_file_read)
repo_resolved= Path(repo_root).resolve()search_path= (repo_resolved/ rel_path).resolve() if not str(search_path).startswith(str(repo_resolved)):
return "Error: path is outside the repository"
str.startswith()on the resolved path string is a prefix match, not a path-component match. Ifrepo_rootresolves to/home/me/dpdk, then/home/me/dpdk-private/secretspasses the check, since the string starts with "/home/me/dpdk". The commit message states both tools are "limited to the repository root to prevent path traversal" -- that property does not hold for sibling directories sharing the name prefix. Same bug in both tool helpers.# is_relative_to (3.9+), raises nothing, no string games if not search_path.is_relative_to(repo_resolved): return "Error: path is outside the repository"(Absolute
rel_pathand ../ escapes are already caught byresolve()+ this fix; only the prefix case is currently open.)Warning
=======
devtools/ai/_common.py: unrelated reformatting mixed into a feature patch. The docstring re-wrapping inprint_token_summary(),_extract_text(),_print_verbose_usage(), and theclassify_review()regex reflow inreview-patch.pyare cosmetic churn unrelated to tool calling. Drop them or split into a separate cleanup; they inflate the diff and obscure the actual change.
devtools/ai/review-patch.py: grep --include list excludes the files the tool prompt points the model at._tool_greprestricts to *.[ch]/*.py/*.rst/*.ini, butTOOL_PROMPT_EXTENSIONexplicitly directs the model to check ".ci/" scripts, meson.build, andMAINTAINERS. Those are extensionless or shell, so grep silently returns "No matches found" rather than surfacing the omission. Either widen the include set or note the restriction in the tool description so the model doesn't draw false conclusions from empty results.Info
====xai is OpenAI wire-compatible and already shares
build_openai_request()elsewhere, but tool calling is gated to provider == "openai" incall_api()and the verbose banner. xai (and any future OpenAI-compatible provider) falls back to single-shot with no notice. Reusingcall_api_with_tools_openai()for xai looks free.
send_request_raw()bypasses_extract_text(), which is where the "error" in result check lived. The tool loops readstop_reason/ choices directly, so a provider error returned with HTTP 200 yields an empty string and a misleading "clean" review instead of a hard failure. Worth a guard onapi_result.get("error")at the top of each loop body.
Quoted 4 lines
Default-on at 10 rounds is a behavior and cost change for every existing caller, and grants repo-wide read to the model by default. Reasonable for an RFC to propose, but worth calling out explicitly for the list -- some CI users may want opt-in rather than opt-out.
I think I've addressed many of the above issues. Posting the 'PATCH' version.
PATCH 1/1 devtools: add read-only tool calling support to AI review scripts
In reply to Aaron ConoleAdd an iterative tool-use loop to review-patch.py and review-doc.py for Anthropic, OpenAI, and xAI providers. The AI reviewer can now look up additional context from the DPDK source tree when the patch or document alone is insufficient, rather than having to guess at surrounding code, API contracts, commit history, or function signatures.
Tool calling is enabled by default with a configurable limit (default: 10 rounds). Pass '--no-tools' to disable it and restore the previous single-shot behavior, or '--max-tool-rounds N' to adjust the limit. The round limit prevents runaway execution on complex reviews; when reached, the model delivers a final response with the context gathered so far.
Tool set (_tools.py):
- git_log View commit history with optional filters (author,
date range, path, message grep)
- git_show Display specific commits or file contents at a
given ref, with optional diffstat
- grep Search for regex patterns across files with
configurable recursion, case sensitivity, match limits, and context lines
- awk Process text with AWK programs (read-only, blocks
system(), file writes, and command execution)
- sed Process text with sed programs (read-only, -n mode
enforced, blocks write/execute/read commands)
- file_read Read file contents up to a configurable size limit
(default 1MB) with encoding support
All tools validate paths using Path().is_relative_to() to prevent directory traversal attacks. Tools are confined to the git repository root and include 30-second timeouts to prevent hanging.
The _common.py send_request() function now handles the tool-calling loop for supported providers, inspecting stop_reason (Anthropic) or finish_reason (OpenAI/xAI) to determine if tool execution is needed, then converting tool definitions between provider formats as required.
---
RFC -> PATCH:
- More (read-only) tools
- Resolve (most?) security escapes
- xAI support (since it is openAI compatible)
devtools/ai/_common.py | 273 +++++++++++++-- devtools/ai/_tools.py | 674 ++++++++++++++++++++++++++++++++++++ devtools/ai/review-doc.py | 18 + devtools/ai/review-patch.py | 22 ++ 4 files changed, 966 insertions(+), 21 deletions(-) create mode 100644 devtools/ai/_tools.py
devtools/ai/_common.py +252 -21
@@ -369,39 +369,35 @@ def _print_verbose_usage(usage: TokenUsage) -> None: print("===================", file=sys.stderr) -def send_request( +def _execute_api_call( provider: str, auth: str, model: str, request_data: dict[str, Any], - *, - timeout: int = 120, - verbose: bool = False, -) -> tuple[str, TokenUsage]: - """Send a prebuilt request to a provider and return (response_text, usage). - - The caller assembles the provider-specific request body via its own - build_*_request helpers (the prompts differ per script). This function - handles transport, error reporting, and token-usage extraction. + timeout: int, +) -> dict[str, Any]: + """Execute a single API call and return the result. Args: - provider: Provider name (anthropic, openai, xai, google) - auth: Authentication string - either "direct:<api_key>" or "vertex" + provider: Provider name + auth: Authentication string model: Model identifier - request_data: Provider-specific request payload + request_data: Request payload timeout: Request timeout in seconds - verbose: Show detailed token usage Returns: - Tuple of (response_text, token_usage) + API response as dictionary + + Raises: + Calls error() on failure (does not return) """ - url, headers, request_data = _build_request_meta(provider, auth, model, request_data) - body = json.dumps(request_data).encode("utf-8") + url, headers, req_data = _build_request_meta(provider, auth, model, request_data) + body = json.dumps(req_data).encode("utf-8") req = Request(url, data=body, headers=headers) try: with urlopen(req, timeout=timeout) as response: - result = json.loads(response.read().decode("utf-8")) + return json.loads(response.read().decode("utf-8")) except HTTPError as e: error_body = e.read().decode("utf-8") try:
@@ -421,7 +417,242 @@ def send_request( except TimeoutError: error(f"Request timed out after {timeout} seconds") - usage = _extract_usage(provider, result) + +def _handle_anthropic_tool_use( + result: dict[str, Any], + messages: list[dict[str, Any]], + verbose: bool, + round_num: int, +) -> bool: + """Handle Anthropic tool use response. + + Args: + result: API response + messages: Message history (modified in place) + verbose: Print debug info + round_num: Current round number (for logging) + + Returns: + True if tools were used, False otherwise + """ + stop_reason = result.get("stop_reason") + if stop_reason != "tool_use": + return False + + try: + from _tools import execute_tool + except ImportError: + def execute_tool(tool_name, tool_input): + raise RuntimeError(f"Cannot run {tool_name} - bad _tools.py") + + content_blocks = result.get("content", []) + tool_results = [] + + if verbose: + print(f"\n=== Tool Use Round {round_num + 1} ===", file=sys.stderr) + + for block in content_blocks: + if block.get("type") == "tool_use": + tool_name = block.get("name") + tool_input = block.get("input", {}) + tool_use_id = block.get("id") + + if verbose: + print(f"Calling tool: {tool_name}", file=sys.stderr) + print(f"Input: {json.dumps(tool_input, indent=2)}", file=sys.stderr) + + # Execute the tool + try: + tool_output = execute_tool(tool_name, tool_input) + is_error = False + except Exception as e: + tool_output = f"Tool error: {e}" + is_error = True + + if verbose: + output_preview = tool_output[:200] + "..." if len(tool_output) > 200 else tool_output + print(f"Output: {output_preview}", file=sys.stderr) + if is_error: + print(f"Error occurred", file=sys.stderr) + + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": tool_output, + "is_error": is_error, + }) + + # Add assistant message with tool use + messages.append({ + "role": "assistant", + "content": content_blocks, + }) + + # Add user message with tool results + messages.append({ + "role": "user", + "content": tool_results, + }) + + return True + + +def _handle_openai_tool_use( + result: dict[str, Any], + messages: list[dict[str, Any]], + verbose: bool, + round_num: int, +) -> bool: + """Handle OpenAI/xAI tool use response. + + Args: + result: API response + messages: Message history (modified in place) + verbose: Print debug info + round_num: Current round number (for logging) + + Returns: + True if tools were used, False otherwise + """ + choices = result.get("choices", []) + if not choices: + return False + + message = choices[0].get("message", {}) + tool_calls = message.get("tool_calls") + + if not tool_calls: + return False + if verbose: - _print_verbose_usage(usage) - return _extract_text(provider, result), usage + print(f"\n=== Tool Use Round {round_num + 1} ===", file=sys.stderr) + + # Add assistant message with tool calls + messages.append(message) + + # Execute each tool and collect results + tool_messages = [] + for tool_call in tool_calls: + tool_id = tool_call.get("id") + function = tool_call.get("function", {}) + tool_name = function.get("name") + tool_args_str = function.get("arguments", "{}") + + try: + tool_input = json.loads(tool_args_str) + except json.JSONDecodeError: + tool_input = {} + + if verbose: + print(f"Calling tool: {tool_name}", file=sys.stderr) + print(f"Input: {json.dumps(tool_input, indent=2)}", file=sys.stderr) + + # Execute the tool + try: + from _tools import execute_tool + tool_output = execute_tool(tool_name, tool_input) + except Exception as e: + tool_output = f"Tool error: {e}" + + if verbose: + output_preview = tool_output[:200] + "..." if len(tool_output) > 200 else tool_output + print(f"Output: {output_preview}", file=sys.stderr) + + tool_messages.append({ + "role": "tool", + "tool_call_id": tool_id, + "name": tool_name, + "content": tool_output, + }) + + # Add all tool results as separate messages + messages.extend(tool_messages) + return True + + +def send_request( + provider: str, + auth: str, + model: str, + request_data: dict[str, Any], + *, + timeout: int = 120, + verbose: bool = False, + enable_tools: bool = False, + max_tool_rounds: int = 10, +) -> tuple[str, TokenUsage]: + """Send a prebuilt request to a provider and return (response_text, usage). + + The caller assembles the provider-specific request body via its own + build_*_request helpers (the prompts differ per script). This function + handles transport, error reporting, and token-usage extraction. + + If enable_tools is True, implements a tool-use loop where the model can + call tools, this function executes them, and sends results back until + the model returns a text response. + + Args: + provider: Provider name (anthropic, openai, xai, google) + auth: Authentication string - either "direct:<api_key>" or "vertex" + model: Model identifier + request_data: Provider-specific request payload + timeout: Request timeout in seconds + verbose: Show detailed token usage + enable_tools: Enable tool calling support + max_tool_rounds: Maximum number of tool calling rounds (default: 10) + + Returns: + Tuple of (response_text, token_usage) + """ + # Add tools to request if enabled + if enable_tools: + if provider == "anthropic": + from _tools import get_tools_for_provider + request_data["tools"] = get_tools_for_provider(provider) + elif provider in ("openai", "xai"): + from _tools import get_tools_for_provider + request_data["tools"] = get_tools_for_provider(provider) + # Disable parallel tool calling for OpenAI/xAI (sequential execution only) + request_data["parallel_tool_calls"] = False + elif provider == "google": + # Google Gemini tool calling not yet implemented + if verbose: + print("Warning: Tool calling not yet supported for Google Gemini", file=sys.stderr) + enable_tools = False + + total_usage = TokenUsage() + messages = request_data.get("messages", []) + + # Tool use loop + for round_num in range(max_tool_rounds): + result = _execute_api_call(provider, auth, model, request_data, timeout) + + usage = _extract_usage(provider, result) + total_usage.add(usage) + + # Check if tools were used + tools_used = False + if enable_tools: + if provider == "anthropic": + tools_used = _handle_anthropic_tool_use(result, messages, verbose, round_num) + elif provider in ("openai", "xai"): + tools_used = _handle_openai_tool_use(result, messages, verbose, round_num) + + if not tools_used: + # Final response + if verbose and round_num > 0: + print(f"=== Tool Use Complete ({round_num} rounds) ===\n", file=sys.stderr) + if verbose: + _print_verbose_usage(total_usage) + return _extract_text(provider, result), total_usage + + # Update messages for next round + request_data["messages"] = messages + + # Max rounds exceeded + if verbose: + print(f"Warning: Max tool rounds ({max_tool_rounds}) exceeded", file=sys.stderr) + _print_verbose_usage(total_usage) + + # Return whatever we have + return _extract_text(provider, result), total_usage
devtools/ai/_tools.py new file +674 -0
674 lines not on this page · raw message
devtools/ai/review-doc.py +18 -0
@@ -360,6 +360,8 @@ def call_api( include_diff_markers: bool = False, verbose: bool = False, timeout: int = 120, + enable_tools: bool = True, + max_tool_rounds: int = 10, ) -> tuple[str, TokenUsage]: """Build the per-provider request body and dispatch via _common.""" if provider == "anthropic":
@@ -399,6 +401,8 @@ def call_api( request_data, timeout=timeout, verbose=verbose, + enable_tools=enable_tools, + max_tool_rounds=max_tool_rounds, )
@@ -665,6 +669,18 @@ def main() -> None: metavar="SECONDS", help="API request timeout in seconds (default: 120)", ) + parser.add_argument( + "--no-tools", + action="store_true", + help="Disable tool calling (git, grep, file read). Tools are enabled by default.", + ) + parser.add_argument( + "--max-tool-rounds", + type=int, + default=10, + metavar="N", + help="Maximum tool calling rounds (default: 10)", + ) # Email options email_group = parser.add_argument_group("Email Options")
@@ -811,6 +827,8 @@ def main() -> None: args.diff, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage)
devtools/ai/review-patch.py +22 -0
@@ -589,6 +589,8 @@ def call_api( output_format: str = "text", verbose: bool = False, timeout: int = 300, + enable_tools: bool = True, + max_tool_rounds: int = 10, ) -> tuple[str, TokenUsage]: """Build the per-provider request body and dispatch via _common.""" if provider == "anthropic":
@@ -625,6 +627,8 @@ def call_api( request_data, timeout=timeout, verbose=verbose, + enable_tools=enable_tools, + max_tool_rounds=max_tool_rounds, )
@@ -870,6 +874,18 @@ def main() -> None: metavar="SECONDS", help="API request timeout in seconds (default: 300)", ) + parser.add_argument( + "--no-tools", + action="store_true", + help="Disable tool calling (git, grep, file read). Tools are enabled by default.", + ) + parser.add_argument( + "--max-tool-rounds", + type=int, + default=10, + metavar="N", + help="Maximum tool calling rounds (default: 10)", + ) # Date and release options parser.add_argument(
@@ -1079,6 +1095,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage) all_reviews.append((patch_label, review_text))
@@ -1149,6 +1167,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage) all_reviews.append((chunk_label, review_text))
@@ -1203,6 +1223,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage)
Signature · 1 line
2.55.0
Re: [PATCH] devtools: add read-only tool calling support to AI review scripts
Hi Aaron,
Thank you for this patch. After looking at the code and testing the AI code review, there's a few things I wanted to bring up.
Firstly, I've noticed that the tool calling has been inconsistent. I ran the review on the AI tools patch without an Agents.md file, to which the AI ran a few tools and successfully gave me an output. However, when I ran it a few times after, regardless of providing the Agents.md file I was seeing no tool calls run. Could this be because the AI decided it had enough context to not need to invoke tools, or maybe even the AI does not know it has access to these tools/when to invoke them?
I've also run it using Haiku 5.5, to which the AI tried a file_read tool call to read the patch, was unable to locate the file, but still went on to review the patch as shown:
===============
=== Tool Use Round 1 ===
Calling tool: file_read
Input: {
"path": "RFC-dts-resolve-trex-driver-binding-issue.patch"
}
Output: Tool error: File not found:/home/knimoji/repos/dpdk-next-dts/RFC-dts-resolve-trex-driver-binding-issue.patch
Error occurred
=== Tool Use Complete (1 rounds) ===
=== Token Usage ===
Input tokens: 29,377
Output tokens: 2,428
Cache creation: 22,984
Cache read: 22,984
===================
=== Patch Review: RFC-dts-resolve-trex-driver-binding-issue.patch (via Claude) ===
Review date: 2026-10-08
I'll work with the patch content you've provided directly. Let me analyze it systematically.
## DPDK Code Review: RFC-dts-resolve-trex-driver-binding-issue.patch
...
Quoted 701 lines · Aaron Conole
Add an iterative tool-use loop to
review-patch.pyandreview-doc.pyfor Anthropic, OpenAI, and xAI providers. The AI reviewer can now look up additional context from the DPDK source tree when the patch or document alone is insufficient, rather than having to guess at surrounding code, API contracts, commit history, or function signatures.Tool calling is enabled by default with a configurable limit (default: 10 rounds). Pass '--no-tools' to disable it and restore the previous single-shot behavior, or '--max-tool-rounds N' to adjust the limit. The round limit prevents runaway execution on complex reviews; when reached, the model delivers a final response with the context gathered so far.
Tool set (
_tools.py):
-git_logView commit history with optional filters (author,
date range, path, message grep)
-git_showDisplay specific commits or file contents at a
given ref, with optional diffstat
- grep Search for regex patterns across files with
configurable recursion, case sensitivity, match limits, and context lines
- awk Process text with AWK programs (read-only, blocks
system(), file writes, and command execution)
- sed Process text with sed programs (read-only, -n mode
enforced, blocks write/execute/read commands)
-file_readRead file contents up to a configurable size limit
(default 1MB) with encoding supportAll tools validate paths using Path().is_relative_to() to prevent directory traversal attacks. Tools are confined to the git repository root and include 30-second timeouts to prevent hanging.
The
_common.pysend_request()function now handles the tool-calling loop for supported providers, inspectingstop_reason(Anthropic) orfinish_reason(OpenAI/xAI) to determine if tool execution is needed, then converting tool definitions between provider formats as required.Assisted-by Claude:sonnet-4.5Signed-off-by Aaron Conole <[email protected]>---
RFC -> PATCH:
- More (read-only) tools
- Resolve (most?) security escapes
- xAI support (since it is openAI compatible)devtools/ai/_common.py | 273 +++++++++++++-- devtools/ai/_tools.py | 674 ++++++++++++++++++++++++++++++++++++ devtools/ai/review-doc.py | 18 + devtools/ai/review-patch.py | 22 ++ 4 files changed, 966 insertions(+), 21 deletions(-) create mode 100644 devtools/ai/_tools.pydevtools/ai/_common.py +1
-6@@ -369,39 +369,35 @@ def _print_verbose_usage(usage: TokenUsage) -> None: print("===================", file=sys.stderr) -def send_request( +def _execute_api_call( provider: str, auth: str, model: str, request_data: dict[str, Any], - *, - timeout: int = 120, - verbose: bool = False, -) -> tuple[str, TokenUsage]: - """Send a prebuilt request to a provider and return (response_text,usage).
devtools/ai/_common.py +3
-6- - The caller assembles the provider-specific request body via its own - build_*_request helpers (the prompts differ per script). This function - handles transport, error reporting, and token-usage extraction. + timeout: int, +) -> dict[str, Any]: + """Execute a single API call and return the result. Args: - provider: Provider name (anthropic, openai, xai, google) - auth: Authentication string - either "direct:<api_key>" or"vertex"
devtools/ai/_common.py +7
-4+ provider: Provider name + auth: Authentication string model: Model identifier - request_data: Provider-specific request payload + request_data: Request payload timeout: Request timeout in seconds - verbose: Show detailed token usage Returns: - Tuple of (response_text, token_usage) + API response as dictionary + + Raises: + Calls error() on failure (does not return) """ - url, headers, request_data = _build_request_meta(provider, auth,model,
request_data)devtools/ai/_common.py +1
-1- body = json.dumps(request_data).encode("utf-8") + url, headers, req_data = _build_request_meta(provider, auth, model,
request_data)devtools/ai/_common.py +56
-2+ body = json.dumps(req_data).encode("utf-8") req = Request(url, data=body, headers=headers) try: with urlopen(req, timeout=timeout) as response: - result = json.loads(response.read().decode("utf-8")) + return json.loads(response.read().decode("utf-8")) except HTTPError as e: error_body = e.read().decode("utf-8") try:@@ -421,7 +417,242 @@ def send_request( except TimeoutError: error(f"Request timed out after {timeout} seconds") - usage = _extract_usage(provider, result) + +def _handle_anthropic_tool_use( + result: dict[str, Any], + messages: list[dict[str, Any]], + verbose: bool, + round_num: int, +) -> bool: + """Handle Anthropic tool use response. + + Args: + result: API response + messages: Message history (modified in place) + verbose: Print debug info + round_num: Current round number (for logging) + + Returns: + True if tools were used, False otherwise + """ + stop_reason = result.get("stop_reason") + if stop_reason != "tool_use": + return False + + try: + from _tools import execute_tool + except ImportError: + def execute_tool(tool_name, tool_input): + raise RuntimeError(f"Cannot run {tool_name} - bad _tools.py") + + content_blocks = result.get("content", []) + tool_results = [] + + if verbose: + print(f"\n=== Tool Use Round {round_num + 1} ===", file=sys.stderr) + + for block in content_blocks: + if block.get("type") == "tool_use": + tool_name = block.get("name") + tool_input = block.get("input", {}) + tool_use_id = block.get("id") + + if verbose: + print(f"Calling tool: {tool_name}", file=sys.stderr) + print(f"Input: {json.dumps(tool_input, indent=2)}", file=sys.stderr) + + # Execute the tool + try: + tool_output = execute_tool(tool_name, tool_input) + is_error = False + except Exception as e: + tool_output = f"Tool error: {e}" + is_error = True + + if verbose: + output_preview = tool_output[:200] + "..." if
len(tool_output)> 200 elsetool_outputdevtools/ai/_common.py +54
-2+ print(f"Output: {output_preview}", file=sys.stderr) + if is_error: + print(f"Error occurred", file=sys.stderr) + + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": tool_output, + "is_error": is_error, + }) + + # Add assistant message with tool use + messages.append({ + "role": "assistant", + "content": content_blocks, + }) + + # Add user message with tool results + messages.append({ + "role": "user", + "content": tool_results, + }) + + return True + + +def _handle_openai_tool_use( + result: dict[str, Any], + messages: list[dict[str, Any]], + verbose: bool, + round_num: int, +) -> bool: + """Handle OpenAI/xAI tool use response. + + Args: + result: API response + messages: Message history (modified in place) + verbose: Print debug info + round_num: Current round number (for logging) + + Returns: + True if tools were used, False otherwise + """ + choices = result.get("choices", []) + if not choices: + return False + + message = choices[0].get("message", {}) + tool_calls = message.get("tool_calls") + + if not tool_calls: + return False + if verbose: - _print_verbose_usage(usage) - return _extract_text(provider, result), usage + print(f"\n=== Tool Use Round {round_num + 1} ===",file=sys.stderr)
devtools/ai/_common.py +20
-0+ + # Add assistant message with tool calls + messages.append(message) + + # Execute each tool and collect results + tool_messages = [] + for tool_call in tool_calls: + tool_id = tool_call.get("id") + function = tool_call.get("function", {}) + tool_name = function.get("name") + tool_args_str = function.get("arguments", "{}") + + try: + tool_input = json.loads(tool_args_str) + except json.JSONDecodeError: + tool_input = {} + + if verbose: + print(f"Calling tool: {tool_name}", file=sys.stderr) + print(f"Input: {json.dumps(tool_input, indent=2)}",file=sys.stderr)
devtools/ai/_common.py +10
-0+ + # Execute the tool + try: + from _tools import execute_tool + tool_output = execute_tool(tool_name, tool_input) + except Exception as e: + tool_output = f"Tool error: {e}" + + if verbose: + output_preview = tool_output[:200] + "..." if
len(tool_output)> 200 elsetool_outputdevtools/ai/_common.py +26
-0+ print(f"Output: {output_preview}", file=sys.stderr) + + tool_messages.append({ + "role": "tool", + "tool_call_id": tool_id, + "name": tool_name, + "content": tool_output, + }) + + # Add all tool results as separate messages + messages.extend(tool_messages) + return True + + +def send_request( + provider: str, + auth: str, + model: str, + request_data: dict[str, Any], + *, + timeout: int = 120, + verbose: bool = False, + enable_tools: bool = False, + max_tool_rounds: int = 10, +) -> tuple[str, TokenUsage]: + """Send a prebuilt request to a provider and return (response_text,usage).
devtools/ai/_common.py +6
-0+ + The caller assembles the provider-specific request body via its own + build_*_request helpers (the prompts differ per script). This function + handles transport, error reporting, and token-usage extraction. + + If enable_tools is True, implements a tool-use loop where the modelcan
devtools/ai/_common.py +6
-0+ call tools, this function executes them, and sends results back until + the model returns a text response. + + Args: + provider: Provider name (anthropic, openai, xai, google) + auth: Authentication string - either "direct:<api_key>" or"vertex"
devtools/ai/_common.py +6
-0+ model: Model identifier + request_data: Provider-specific request payload + timeout: Request timeout in seconds + verbose: Show detailed token usage + enable_tools: Enable tool calling support + max_tool_rounds: Maximum number of tool calling rounds (default:10)
devtools/ai/_common.py +13
-0+ + Returns: + Tuple of (response_text, token_usage) + """ + # Add tools to request if enabled + if enable_tools: + if provider == "anthropic": + from _tools import get_tools_for_provider + request_data["tools"] = get_tools_for_provider(provider) + elif provider in ("openai", "xai"): + from _tools import get_tools_for_provider + request_data["tools"] = get_tools_for_provider(provider) + # Disable parallel tool calling for OpenAI/xAI (sequentialexecution only)
devtools/ai/_common.py +5
-0+ request_data["parallel_tool_calls"] = False + elif provider == "google": + # Google Gemini tool calling not yet implemented + if verbose: + print("Warning: Tool calling not yet supported for GoogleGemini", file=sys.stderr)
devtools/ai/_common.py +8
-0+ enable_tools = False + + total_usage = TokenUsage() + messages = request_data.get("messages", []) + + # Tool use loop + for round_num in range(max_tool_rounds): + result = _execute_api_call(provider, auth, model, request_data,timeout)
devtools/ai/_common.py +9
-0+ + usage = _extract_usage(provider, result) + total_usage.add(usage) + + # Check if tools were used + tools_used = False + if enable_tools: + if provider == "anthropic": + tools_used = _handle_anthropic_tool_use(result, messages,verbose,
round_num)devtools/ai/_common.py +2
-0+ elif provider in ("openai", "xai"): + tools_used = _handle_openai_tool_use(result, messages,verbose,
round_num)devtools/ai/_common.py +5
-0+ + if not tools_used: + # Final response + if verbose and round_num > 0: + print(f"=== Tool Use Complete ({round_num} rounds)===\n", file=sys.stderr)
devtools/ai/_common.py +10
-0+ if verbose: + _print_verbose_usage(total_usage) + return _extract_text(provider, result), total_usage + + # Update messages for next round + request_data["messages"] = messages + + # Max rounds exceeded + if verbose: + print(f"Warning: Max tool rounds ({max_tool_rounds}) exceeded",file=sys.stderr)
devtools/ai/_common.py +4
-0+ _print_verbose_usage(total_usage) + + # Return whatever we have + return _extract_text(provider, result), total_usagedevtools/ai/_tools.py new file +81
-0@@ -0,0 +1,674 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2026 Aaron Conole + +""" +Read-only tool calling support for DPDK AI review scripts. + +Provides secure, sandboxed tools for AI to gather additional context: +- git log: View commit history +- git show: View specific commits +- grep: Search file contents +- awk/sed: Parse and extract text (read-only) +- file_read: Read file contents + +All tools validate paths to prevent escaping the git repository. +""" + +import json +import re +import subprocess +from pathlib import Path +from typing import Any, NoReturn + + +class ToolError(Exception): + """Raised when a tool execution fails.""" + pass + + +class SecurityError(Exception): + """Raised when a security constraint is violated.""" + pass + + +def get_git_root() -> Path: + """Get the root directory of the git repository. + + Returns: + Path to the git repository root + + Raises: + ToolError: If not in a git repository + """ + try: + result = subprocess.run( + ["git", "rev-parse", "--show-toplevel"], + capture_output=True, + text=True, + check=True, + ) + return Path(result.stdout.strip()).resolve() + except (subprocess.CalledProcessError, FileNotFoundError) as e: + raise ToolError(f"Not in a git repository: {e}") from e + + +def validate_path(path_str: str, git_root: Path) -> Path: + """Validate that a path is within the git repository. + + Uses Path.is_relative_to() to prevent directory traversal attacks. + + Args: + path_str: Path string to validate + git_root: Root of the git repository + + Returns: + Resolved absolute Path object + + Raises: + SecurityError: If path escapes the git repository + """ + try: + # Convert to absolute path and resolve symlinks + if Path(path_str).is_absolute(): + resolved = Path(path_str).resolve() + else: + resolved = (git_root / path_str).resolve() + + # Check if path is within git root + if not resolved.is_relative_to(git_root): + raise SecurityError( + f"Path '{path_str}' escapes git repository root'{
git_root}'"devtools/ai/_tools.py new file +232
-0+ ) + + return resolved + + except (ValueError, OSError, RuntimeError) as e: + raise SecurityError(f"Invalid path '{path_str}': {e}") from e + + +def validate_git_ref(ref: str) -> None: + """Validate a git reference (commit hash, branch, tag). + + Args: + ref: Git reference to validate + + Raises: + SecurityError: If reference contains suspicious characters + """ + # Allow alphanumeric, -, _, /, ^, ~, @ (normal git ref characters) + # Disallow command injection characters: ; | & $ ( ) ` < > etc. + if not re.match(r'^[a-zA-Z0-9._/^~@-]+$', ref): + raise SecurityError(f"Invalid git reference: {ref}") + + +def tool_git_log(args: dict[str, Any], git_root: Path) -> str: + """Execute git log with controlled arguments. + + Args: + args: Dictionary with optional keys: + - max_count: Maximum number of commits (default: 20, max: 100) + - since: Date/time since (e.g., "2 weeks ago") + - until: Date/time until + - path: File path to filter by + - grep: Commit message grep pattern + - author: Author name/email filter + - oneline: Use oneline format (default: False) + + Returns: + Git log output as string + + Raises: + ToolError: If git command fails + SecurityError: If validation fails + """ + cmd = ["git", "log"] + + # Validate and add max_count + max_count = args.get("max_count", 20) + if not isinstance(max_count, int) or max_count < 1 or max_count > 100: + raise ToolError("max_count must be an integer between 1 and 100") + cmd.extend([f"-{max_count}"]) + + # Add optional filters + if args.get("oneline"): + cmd.append("--oneline") + else: + cmd.append("--format=%H%n%an <%ae>%n%ad%n%s%n%b%n---") + + if "since" in args: + cmd.extend(["--since", args["since"]]) + + if "until" in args: + cmd.extend(["--until", args["until"]]) + + if "author" in args: + cmd.extend(["--author", args["author"]]) + + if "grep" in args: + cmd.extend(["--grep", args["grep"]]) + + # Validate and add path filter + if "path" in args: + path = validate_path(args["path"], git_root) + cmd.extend(["--", str(path)]) + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("git log timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"git log failed: {e.stderr}") + + +def tool_git_show(args: dict[str, Any], git_root: Path) -> str: + """Show a git commit or object. + + Args: + args: Dictionary with keys: + - ref: Git reference (commit hash, branch, tag) + - path: Optional path to show specific file at that ref + - stat: Show diffstat only (default: False) + + Returns: + Git show output as string + + Raises: + ToolError: If git command fails + SecurityError: If validation fails + """ + if "ref" not in args: + raise ToolError("ref parameter is required") + + ref = args["ref"] + validate_git_ref(ref) + + cmd = ["git", "show"] + + if args.get("stat"): + cmd.append("--stat") + + # Construct the ref:path or just ref + if "path" in args: + path = validate_path(args["path"], git_root) + # Use relative path for git show + rel_path = path.relative_to(git_root) + cmd.append(f"{ref}:{rel_path}") + else: + cmd.append(ref) + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("git show timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"git show failed: {e.stderr}") + + +def tool_grep(args: dict[str, Any], git_root: Path) -> str: + """Search for pattern in files using grep. + + Args: + args: Dictionary with keys: + - pattern: Search pattern (required) + - path: File or directory path (default: current directory) + - recursive: Recursive search (default: True) + - ignore_case: Case-insensitive search (default: False) + - max_count: Maximum matches per file (default: 100) + - context: Lines of context (default: 0) + + Returns: + Grep output as string + + Raises: + ToolError: If grep fails + SecurityError: If validation fails + """ + if "pattern" not in args: + raise ToolError("pattern parameter is required") + + pattern = args["pattern"] + path = validate_path(args.get("path", "."), git_root) + + cmd = ["grep", "--color=never"] + + if args.get("ignore_case", False): + cmd.append("-i") + + if args.get("recursive", True) and path.is_dir(): + cmd.append("-r") + + max_count = args.get("max_count", 100) + if not isinstance(max_count, int) or max_count < 0: + raise ToolError("max_count must be a non-negative integer") + if max_count > 0: + cmd.extend(["-m", str(max_count)]) + + context = args.get("context", 0) + if not isinstance(context, int) or context < 0 or context > 100: + raise ToolError( + "context must be a non-negative integer not greater than 100") + cmd.extend(["-C", str(context)]) + + # Use -- to prevent pattern from being interpreted as an option + cmd.extend(["--", pattern, str(path)]) + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + timeout=30, + ) + # grep returns 1 if no matches, which is not an error + if result.returncode not in (0, 1): + raise ToolError(f"grep failed: {result.stderr}") + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("grep timed out after 30 seconds") + + +def tool_awk(args: dict[str, Any], git_root: Path) -> str: + """Execute awk for text processing (read-only). + + Args: + args: Dictionary with keys: + - program: AWK program (required) + - path: File path (required) + + Returns: + AWK output as string + + Raises: + ToolError: If awk fails + SecurityError: If validation fails or program attempts writes + """ + if "program" not in args or "path" not in args: + raise ToolError("program and path parameters are required") + + program = args["program"] + path = validate_path(args["path"], git_root) + + # Security: Disallow dangerous awk features + # Block system(), print/printf redirects, pipes, and getline + dangerous_patterns = [ + r'system\s*\(', + r'(print|printf)\s*(.*\s*)>\s*', # any print/printf redirect(with/without quotes)
+ r'(?<![|&])\|(?![|&])\s*', # pipe not preceded/followed by
another | or &
devtools/ai/_tools.py
Quoted 2 lines
devtools/ai/_tools.py new file +2
-0+ r'getline', # all getline operations + ]
I looked into the regex parsing in the tool_awk function, to which I noticed that the dangerous patterns could be bypassed if the AI passes forbidden features part by part, for example if "sys" and "tem" are passed individually, it passes the regex check, but when the command runs it concatenates the 2 strings resulting in "system" which is forbidden. For example:
part1 = "sys"
part2 = "tem"
cmd = part1 part2
@cmd("rm -rf /")
If you think this would be an issue, I would recommend looking into awk's built in '--sandbox' argument, which inherently disables commands such as system(), getline, pipes, and file redirects.
Quoted 50 lines
devtools/ai/_tools.py new file +3
-0+ for pattern in dangerous_patterns: + if re.search(pattern, program): + raise SecurityError(f"AWK program contains forbidden pattern:{pattern}")
devtools/ai/_tools.py new file +45
-0+ + if not path.exists(): + raise ToolError(f"File not found: {path}") + + cmd = ["awk", program, str(path)] + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("awk timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"awk failed: {e.stderr}") + + +def tool_sed(args: dict[str, Any], git_root: Path) -> str: + """Execute sed for text processing (read-only). + + Args: + args: Dictionary with keys: + - program: sed program (required) + - path: File path (required) + + Returns: + sed output as string + + Raises: + ToolError: If sed fails + SecurityError: If validation fails or program attempts writes + """ + if "program" not in args or "path" not in args: + raise ToolError("program and path parameters are required") + + program = args["program"] + path = validate_path(args["path"], git_root) + + # Security: Force read-only mode, disallow write/execute commands + # Block w (write), W (Write), e (execute), r/R (read from file), Q(quit with code)
devtools/ai/_tools.py line 369
Quoted 5 lines
devtools/ai/_tools.py new file +5
-0+ dangerous_patterns = [ + r'[wWeRQ]\s', # write, Write, execute, Read, Quit + r'\d+[wWeRQ]$', # write/execute/read/quit with address + r'[rR][/\s]', # read from file (with or without whitespace) + ]
When checking for dangerous commands using regex here, I was wondering if this would affect regular commands that match the patterns? Please correct me if I'm wrong, but I wanted to make sure that the specified regex patterns wouldn't block commands that would be useful.
+ for pattern in dangerous_patterns:
Quoted 456 lines
devtools/ai/_tools.py new file +2
-0+ if re.search(pattern, program): + raise SecurityError(f"sed program contains forbidden pattern:{pattern}")
devtools/ai/_tools.py new file +71
-0+ + if not path.exists(): + raise ToolError(f"File not found: {path}") + + # Always use -n (suppress automatic printing) to prevent side effects + cmd = ["sed", "-n", program, str(path)] + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("sed timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"sed failed: {e.stderr}") + + +def tool_file_read(args: dict[str, Any], git_root: Path) -> str: + """Read contents of a file. + + Args: + args: Dictionary with keys: + - path: File path (required) + - max_size: Maximum file size in bytes (default: 1MB) + - encoding: Text encoding (default: utf-8) + + Returns: + File contents as string + + Raises: + ToolError: If file read fails + SecurityError: If validation fails + """ + if "path" not in args: + raise ToolError("path parameter is required") + + path = validate_path(args["path"], git_root) + max_size = args.get("max_size", 1024 * 1024) # 1MB default + encoding = args.get("encoding", "utf-8") + + if not path.exists(): + raise ToolError(f"File not found: {path}") + + if not path.is_file(): + raise ToolError(f"Not a file: {path}") + + # Check file size + file_size = path.stat().st_size + if file_size > max_size: + raise ToolError( + f"File too large: {file_size} bytes (max: {max_size})" + ) + + try: + # Use errors='replace' to handle non-UTF8 bytes gracefully + return path.read_text(encoding=encoding, errors='replace') + except Exception as e: + raise ToolError(f"Failed to read file: {e}") from e + + +# Tool definitions for Anthropic API +TOOL_DEFINITIONS = [ + { + "name": "git_log", + "description": "View git commit history with optional filters.Use this to understand recent changes, find related commits, or trace the history of specific files.",
devtools/ai/_tools.py new file +6
-0+ "input_schema": { + "type": "object", + "properties": { + "max_count": { + "type": "integer", + "description": "Maximum number of commits to show(1-100, default: 20)",
devtools/ai/_tools.py new file +6
-0+ "minimum": 1, + "maximum": 100, + }, + "since": { + "type": "string", + "description": "Show commits more recent than date(e.g., '2 weeks ago', '2024-01-01')",
devtools/ai/_tools.py new file +8
-0+ }, + "until": { + "type": "string", + "description": "Show commits older than date", + }, + "path": { + "type": "string", + "description": "Only show commits affecting this filepath",
devtools/ai/_tools.py new file +4
-0+ }, + "grep": { + "type": "string", + "description": "Only show commits with messagesmatching this pattern",
devtools/ai/_tools.py new file +8
-0+ }, + "author": { + "type": "string", + "description": "Only show commits by this author", + }, + "oneline": { + "type": "boolean", + "description": "Use compact one-line format (default:false)",
devtools/ai/_tools.py new file +7
-0+ }, + }, + }, + }, + { + "name": "git_show", + "description": "Show the contents of a git commit or a specificfile at a given commit. Use this to examine what changed in a specific commit or to view historical file contents.",
devtools/ai/_tools.py new file +6
-0+ "input_schema": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "description": "Git reference (commit hash, branchname, tag, or HEAD~N)",
devtools/ai/_tools.py new file +4
-0+ }, + "path": { + "type": "string", + "description": "Optional: specific file path to showat this ref",
devtools/ai/_tools.py new file +12
-0+ }, + "stat": { + "type": "boolean", + "description": "Show only diffstat (default: false)", + }, + }, + "required": ["ref"], + }, + }, + { + "name": "grep", + "description": "Search for text patterns in files. Use this tofind specific code patterns, function definitions, or configuration values.",
devtools/ai/_tools.py new file +10
-0+ "input_schema": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "Search pattern (supports regex)", + }, + "path": { + "type": "string", + "description": "File or directory to search (default:current directory)",
devtools/ai/_tools.py new file +4
-0+ }, + "recursive": { + "type": "boolean", + "description": "Search recursively in directories(default: true)",
devtools/ai/_tools.py new file +4
-0+ }, + "ignore_case": { + "type": "boolean", + "description": "Case-insensitive search (default:false)",
devtools/ai/_tools.py new file +4
-0+ }, + "max_count": { + "type": "integer", + "description": "Maximum matches per file (default:100)",
devtools/ai/_tools.py new file +4
-0+ }, + "context": { + "type": "integer", + "description": "Lines of context around matches(default: 0)",
devtools/ai/_tools.py new file +8
-0+ }, + }, + "required": ["pattern"], + }, + }, + { + "name": "awk", + "description": "Process text files using AWK (read-only). Usethis to extract columns, filter lines, or perform text transformations. Write/execute operations are blocked.",
devtools/ai/_tools.py new file +18
-0+ "input_schema": { + "type": "object", + "properties": { + "program": { + "type": "string", + "description": "AWK program to execute", + }, + "path": { + "type": "string", + "description": "File to process", + }, + }, + "required": ["program", "path"], + }, + }, + { + "name": "sed", + "description": "Process text files using sed (read-only). Usethis to extract or transform text. Write/execute operations are blocked and
devtools/ai/_tools.py new file +6
-1-n flag is always enabled.", + "input_schema": { + "type": "object", + "properties": { + "program": { + "type": "string", + "description": "sed program to execute (use p commandto print)",
devtools/ai/_tools.py new file +12
-0+ }, + "path": { + "type": "string", + "description": "File to process", + }, + }, + "required": ["program", "path"], + }, + }, + { + "name": "file_read", + "description": "Read the contents of a file. Use this to examinesource code, documentation, or configuration files.",
devtools/ai/_tools.py new file +10
-0+ "input_schema": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Path to the file to read", + }, + "max_size": { + "type": "integer", + "description": "Maximum file size in bytes (default:1048576 = 1MB)",
devtools/ai/_tools.py new file +53
-1+ }, + "encoding": { + "type": "string", + "description": "Text encoding (default: utf-8)", + }, + }, + "required": ["path"], + }, + }, +] + + +# Map tool names to handler functions +TOOL_HANDLERS = { + "git_log": tool_git_log, + "git_show": tool_git_show, + "grep": tool_grep, + "awk": tool_awk, + "sed": tool_sed, + "file_read": tool_file_read, +} + + +def execute_tool(tool_name: str, tool_args: dict[str, Any]) -> str: + """Execute a tool and return its output. + + Args: + tool_name: Name of the tool to execute + tool_args: Arguments for the tool + + Returns: + Tool output as string + + Raises: + ToolError: If tool execution fails + SecurityError: If security validation fails + """ + if tool_name not in TOOL_HANDLERS: + raise ToolError(f"Unknown tool: {tool_name}") + + git_root = get_git_root() + handler = TOOL_HANDLERS[tool_name] + + try: + return handler(tool_args, git_root) + except (ToolError, SecurityError): + raise + except Exception as e: + raise ToolError(f"Tool execution failed: {e}") from e + + +def convert_tools_to_openai_format(anthropic_tools: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Convert Anthropic tool definitions to OpenAI function callingformat.
devtools/ai/_tools.py new file +37
-0+ + Args: + anthropic_tools: List of tool definitions in Anthropic format + + Returns: + List of tool definitions in OpenAI format + """ + openai_tools = [] + for tool in anthropic_tools: + openai_tool = { + "type": "function", + "function": { + "name": tool["name"], + "description": tool["description"], + "parameters": tool["input_schema"], + } + } + openai_tools.append(openai_tool) + return openai_tools + + +def get_tools_for_provider(provider: str) -> list[dict[str, Any]]: + """Get tool definitions in the format required by the provider. + + Args: + provider: Provider name (anthropic, openai, xai, google) + + Returns: + List of tool definitions in provider-specific format + """ + if provider == "anthropic": + return TOOL_DEFINITIONS + elif provider in ("openai", "xai"): + return convert_tools_to_openai_format(TOOL_DEFINITIONS) + else: + # Google Gemini uses a different format, not yet implemented + return []devtools/ai/review-doc.py +16
-0@@ -360,6 +360,8 @@ def call_api( include_diff_markers: bool = False, verbose: bool = False, timeout: int = 120, + enable_tools: bool = True, + max_tool_rounds: int = 10, ) -> tuple[str, TokenUsage]: """Build the per-provider request body and dispatch via _common.""" if provider == "anthropic":@@ -399,6 +401,8 @@ def call_api( request_data, timeout=timeout, verbose=verbose, + enable_tools=enable_tools, + max_tool_rounds=max_tool_rounds, )@@ -665,6 +669,18 @@ def main() -> None: metavar="SECONDS", help="API request timeout in seconds (default: 120)", ) + parser.add_argument( + "--no-tools", + action="store_true", + help="Disable tool calling (git, grep, file read). Tools are enabled by default.", + ) + parser.add_argument( + "--max-tool-rounds", + type=int, + default=10, + metavar="N", + help="Maximum tool calling rounds (default: 10)", + ) # Email options
email_group=parser.add_argument_group("Email Options")devtools/ai/review-doc.py +2
-0@@ -811,6 +827,8 @@ def main() -> None: args.diff, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage)devtools/ai/review-patch.py +16
-0@@ -589,6 +589,8 @@ def call_api( output_format: str = "text", verbose: bool = False, timeout: int = 300, + enable_tools: bool = True, + max_tool_rounds: int = 10, ) -> tuple[str, TokenUsage]: """Build the per-provider request body and dispatch via _common.""" if provider == "anthropic":@@ -625,6 +627,8 @@ def call_api( request_data, timeout=timeout, verbose=verbose, + enable_tools=enable_tools, + max_tool_rounds=max_tool_rounds, )@@ -870,6 +874,18 @@ def main() -> None: metavar="SECONDS", help="API request timeout in seconds (default: 300)", ) + parser.add_argument( + "--no-tools", + action="store_true", + help="Disable tool calling (git, grep, file read). Tools are enabled by default.", + ) + parser.add_argument( + "--max-tool-rounds", + type=int, + default=10, + metavar="N", + help="Maximum tool calling rounds (default: 10)", + ) # Date and release optionsparser.add_argument(devtools/ai/review-patch.py +6
-1@@ -1079,6 +1095,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage) all_reviews.append((patch_label, review_text))@@ -1149,6 +1167,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage) all_reviews.append((chunk_label, review_text))@@ -1203,6 +1223,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage) --2.55.0
Re: [PATCH] devtools: add read-only tool calling support to AI review scripts
Quoted 9 lines · Koushik Bhargav Nimoji
Hi Aaron,
Thank you for this patch. After looking at the code and testing the AI code review, there's a few things I wanted to bring up. Firstly, I've noticed that the tool calling has been inconsistent. I ran the review on the AI tools patch without an Agents.md file, to which the AI ran a few tools and successfully gave me an output. However, when I ran it a few times after, regardless of providing the Agents.md file I was seeing no tool calls run. Could this be because the AI decided it had enough context to not need to invoke tools, or maybe even the AI does not know it has access to these
tools/whento invoke them?
I've also run it using Haiku 5.5, to which the AI tried afile_readtool call to read the patch, was unable to locate the file, but still went on to review the patch as shown:
What is your path, etc? The tool calling support really only wants to run from the repo. Notice that there is a failure saying it cannot find a file you've specified:
/home/knimoji/repos/dpdk-next-dts/RFC-dts-resolve-trex-driver-binding-issue.patch
There isn't a 'find' tool call, which means if you tell it to review something and it cannot use the tools provided (grep, read, git, awk, sed) to find that detail, it will error out. Maybe after that it hallucinates. It's tough to predict how a specific model will proceed.
Quoted 1,223 lines
===============
=== Tool Use Round 1 ===
Calling tool:
file_readInput: {
"path": "RFC-dts-resolve-trex-driver-binding-issue.patch"
}
Output: Tool error: File not found:
/home/knimoji/repos/dpdk-next-dts/RFC-dts-resolve-trex-driver-binding-issue.patchError occurred
=== Tool Use Complete (1 rounds) ===
=== Token Usage ===
Input tokens: 29,377
Output tokens: 2,428
Cache creation: 22,984
Cache read: 22,984
===================
=== Patch Review: RFC-dts-resolve-trex-driver-binding-issue.patch (via Claude) ===
Review date: 2026-10-08
I'll work with the patch content you've provided directly. Let me analyze it systematically.
## DPDK Code Review: RFC-dts-resolve-trex-driver-binding-issue.patch
...
On Wed, Sep 9, 2026 at 10:14 AM Aaron Conole <[email protected]> wrote:
Add an iterative tool-use loop to
review-patch.pyandreview-doc.pyfor Anthropic, OpenAI, and xAI providers. The AI reviewer can now look up additional context from the DPDK source tree when the patch or document alone is insufficient, rather than having to guess at surrounding code, API contracts, commit history, or function signatures.Tool calling is enabled by default with a configurable limit (default: 10 rounds). Pass '--no-tools' to disable it and restore the previous single-shot behavior, or '--max-tool-rounds N' to adjust the limit. The round limit prevents runaway execution on complex reviews; when reached, the model delivers a final response with the context gathered so far.
Tool set (
_tools.py):
-git_logView commit history with optional filters (author,
date range, path, message grep)
-git_showDisplay specific commits or file contents at a
given ref, with optional diffstat
- grep Search for regex patterns across files with
configurable recursion, case sensitivity, match limits, and context lines
- awk Process text with AWK programs (read-only, blocks
system(), file writes, and command execution)
- sed Process text with sed programs (read-only, -n mode
enforced, blocks write/execute/read commands)
-file_readRead file contents up to a configurable size limit
(default 1MB) with encoding supportAll tools validate paths using Path().is_relative_to() to prevent directory traversal attacks. Tools are confined to the git repository root and include 30-second timeouts to prevent hanging.
The
_common.pysend_request()function now handles the tool-calling loop for supported providers, inspectingstop_reason(Anthropic) orfinish_reason(OpenAI/xAI) to determine if tool execution is needed, then converting tool definitions between provider formats as required.Assisted-by Claude:sonnet-4.5Signed-off-by Aaron Conole <[email protected]>---
RFC -> PATCH:
- More (read-only) tools
- Resolve (most?) security escapes
- xAI support (since it is openAI compatible)devtools/ai/_common.py | 273 +++++++++++++-- devtools/ai/_tools.py | 674 ++++++++++++++++++++++++++++++++++++ devtools/ai/review-doc.py | 18 + devtools/ai/review-patch.py | 22 ++ 4 files changed, 966 insertions(+), 21 deletions(-)create mode 100644
devtools/ai/_tools.pydiff --git
a/devtools/ai/_common.pyb/devtools/ai/_common.pyindex07a0411aaf..bdbc91034f100644
---a/devtools/ai/_common.py
+++b/devtools/ai/_common.py
@@ -369,39 +369,35 @@ def_print_verbose_usage(usage: TokenUsage)-> None:print("===================", file=sys.stderr)-def send_request(
+def _execute_api_call(
provider: str,
auth: str,
model: str,
request_data: dict[str, Any],- *, - timeout: int = 120, - verbose: bool = False, -) -> tuple[str, TokenUsage]: - """Send a prebuilt request to a provider and return (response_text, usage). - - The caller assembles the provider-specific request body via its own - build_*_request helpers (the prompts differ per script). This function - handles transport, error reporting, and token-usage extraction. + timeout: int,+) -> dict[str, Any]:
+ """Execute a single API call and return the result.Args:
- provider: Provider name (anthropic, openai, xai, google) - auth: Authentication string - either "direct:<api_key>" or "vertex" + provider: Provider name + auth: Authentication stringmodel: Model identifier
-request_data: Provider-specific request payload
+request_data: Request payload
timeout: Request timeout in seconds
- verbose: Show detailed token usageReturns:
- Tuple of (response_text,token_usage)
+ API response as dictionary
+
+ Raises:
+ Callserror()on failure (does not return)""" - url, headers, request_data = _build_request_meta(provider, auth, model, request_data) - body = json.dumps(request_data).encode("utf-8") + url, headers, req_data = _build_request_meta(provider, auth, model, request_data) + body = json.dumps(req_data).encode("utf-8")req =
Request(url, data=body, headers=headers)try:
withurlopen(req, timeout=timeout)as response:
- result = json.loads(response.read().decode("utf-8"))
+ return json.loads(response.read().decode("utf-8"))
except HTTPError as e:
error_body= e.read().decode("utf-8") try:
@@ -421,7 +417,242 @@ def send_request(
except TimeoutError:
error(f"Request timed out after {timeout} seconds")- usage =
_extract_usage(provider, result)
+
+def _handle_anthropic_tool_use(+ result: dict[str, Any], + messages: list[dict[str, Any]], + verbose: bool, + round_num: int, +) -> bool: + """Handle Anthropic tool use response. + + Args: + result: API response + messages: Message history (modified in place) + verbose: Print debug info + round_num: Current round number (for logging) + + Returns: + True if tools were used, False otherwise + """ + stop_reason = result.get("stop_reason") + if stop_reason != "tool_use": + return False + + try: + from _tools import execute_tool + except ImportError: + def execute_tool(tool_name, tool_input): + raise RuntimeError(f"Cannot run {tool_name} - bad _tools.py") + + content_blocks = result.get("content", []) + tool_results = [] + + if verbose: + print(f"\n=== Tool Use Round {round_num + 1} ===", file=sys.stderr) + + for block in content_blocks: + if block.get("type") == "tool_use": + tool_name = block.get("name") + tool_input = block.get("input", {}) + tool_use_id = block.get("id") + + if verbose: + print(f"Calling tool: {tool_name}", file=sys.stderr) + print(f"Input: {json.dumps(tool_input, indent=2)}", file=sys.stderr) + + # Execute the tool + try: + tool_output = execute_tool(tool_name, tool_input) + is_error = False + except Exception as e: + tool_output = f"Tool error: {e}" + is_error = True + + if verbose: + output_preview = tool_output[:200] + "..." if len(tool_output) > 200 else tool_output + print(f"Output: {output_preview}", file=sys.stderr) + if is_error: + print(f"Error occurred", file=sys.stderr) + + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": tool_output, + "is_error": is_error, + }) + + # Add assistant message with tool use + messages.append({ + "role": "assistant", + "content": content_blocks, + }) + + # Add user message with tool results + messages.append({ + "role": "user", + "content": tool_results, + }) + + return True + + +def _handle_openai_tool_use( + result: dict[str, Any], + messages: list[dict[str, Any]], + verbose: bool, + round_num: int, +) -> bool: + """Handle OpenAI/xAI tool use response. + + Args: + result: API response + messages: Message history (modified in place) + verbose: Print debug info + round_num: Current round number (for logging) + + Returns: + True if tools were used, False otherwise + """ + choices = result.get("choices", []) + if not choices: + return False + + message = choices[0].get("message", {}) + tool_calls = message.get("tool_calls") + + if not tool_calls: + return False + if verbose: - _print_verbose_usage(usage) - return _extract_text(provider, result), usage + print(f"\n=== Tool Use Round {round_num + 1} ===", file=sys.stderr) + + # Add assistant message with tool calls + messages.append(message) + + # Execute each tool and collect results + tool_messages = [] + for tool_call in tool_calls: + tool_id = tool_call.get("id") + function = tool_call.get("function", {}) + tool_name = function.get("name") + tool_args_str = function.get("arguments", "{}") + + try: + tool_input = json.loads(tool_args_str) + except json.JSONDecodeError: + tool_input = {} + + if verbose: + print(f"Calling tool: {tool_name}", file=sys.stderr) + print(f"Input: {json.dumps(tool_input, indent=2)}", file=sys.stderr) + + # Execute the tool + try: + from _tools import execute_tool + tool_output = execute_tool(tool_name, tool_input) + except Exception as e: + tool_output = f"Tool error: {e}" + + if verbose: + output_preview = tool_output[:200] + "..." if len(tool_output) > 200 else tool_output + print(f"Output: {output_preview}", file=sys.stderr) + + tool_messages.append({ + "role": "tool", + "tool_call_id": tool_id, + "name": tool_name, + "content": tool_output, + }) + + # Add all tool results as separate messages + messages.extend(tool_messages) + return True + + +def send_request( + provider: str, + auth: str, + model: str, + request_data: dict[str, Any], + *, + timeout: int = 120, + verbose: bool = False, + enable_tools: bool = False, + max_tool_rounds: int = 10, +) -> tuple[str, TokenUsage]: + """Send a prebuilt request to a provider and return (response_text, usage). + + The caller assembles the provider-specific request body via its own + build_*_request helpers (the prompts differ per script). This function + handles transport, error reporting, and token-usage extraction. + + If enable_tools is True, implements a tool-use loop where the model can + call tools, this function executes them, and sends results back until + the model returns a text response. + + Args: + provider: Provider name (anthropic, openai, xai, google) + auth: Authentication string - either "direct:<api_key>" or "vertex" + model: Model identifier + request_data: Provider-specific request payload + timeout: Request timeout in seconds + verbose: Show detailed token usage + enable_tools: Enable tool calling support + max_tool_rounds: Maximum number of tool calling rounds (default: 10) + + Returns: + Tuple of (response_text, token_usage) + """ + # Add tools to request if enabled + if enable_tools: + if provider == "anthropic": + from _tools import get_tools_for_provider + request_data["tools"] = get_tools_for_provider(provider) + elif provider in ("openai", "xai"): + from _tools import get_tools_for_provider + request_data["tools"] = get_tools_for_provider(provider) + # Disable parallel tool calling for OpenAI/xAI (sequential execution only) + request_data["parallel_tool_calls"] = False + elif provider == "google": + # Google Gemini tool calling not yet implemented + if verbose: + print("Warning: Tool calling not yet supported for Google Gemini", file=sys.stderr) + enable_tools = False + + total_usage = TokenUsage() + messages = request_data.get("messages", []) + + # Tool use loop + for round_num in range(max_tool_rounds): + result = _execute_api_call(provider, auth, model, request_data, timeout) + + usage = _extract_usage(provider, result) + total_usage.add(usage) + + # Check if tools were used + tools_used = False + if enable_tools: + if provider == "anthropic": + tools_used = _handle_anthropic_tool_use(result, messages, verbose, round_num) + elif provider in ("openai", "xai"): + tools_used = _handle_openai_tool_use(result, messages, verbose, round_num) + + if not tools_used: + # Final response + if verbose and round_num > 0: + print(f"=== Tool Use Complete ({round_num} rounds) ===\n", file=sys.stderr) + if verbose: + _print_verbose_usage(total_usage) + return _extract_text(provider, result), total_usage + + # Update messages for next round + request_data["messages"] = messages + + # Max rounds exceeded + if verbose: + print(f"Warning: Max tool rounds ({max_tool_rounds}) exceeded", file=sys.stderr) + _print_verbose_usage(total_usage) + + # Return whatever we have + return _extract_text(provider, result), total_usage diff --git a/devtools/ai/_tools.py b/devtools/ai/_tools.py new file mode 100644 index 0000000000..a74d354982 --- /dev/null +++ b/devtools/ai/_tools.py @@ -0,0 +1,674 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2026 Aaron Conole + +""" +Read-only tool calling support for DPDK AI review scripts. + +Provides secure, sandboxed tools for AI to gather additional context: +- git log: View commit history +- git show: View specific commits +- grep: Search file contents +- awk/sed: Parse and extract text (read-only) +- file_read: Read file contents + +All tools validate paths to prevent escaping the git repository. +""" + +import json +import re +import subprocess +from pathlib import Path +from typing import Any, NoReturn + + +class ToolError(Exception): + """Raised when a tool execution fails.""" + pass + + +class SecurityError(Exception): + """Raised when a security constraint is violated.""" + pass + + +def get_git_root() -> Path: + """Get the root directory of the git repository. + + Returns: + Path to the git repository root + + Raises: + ToolError: If not in a git repository + """ + try: + result = subprocess.run( + ["git", "rev-parse", "--show-toplevel"], + capture_output=True, + text=True, + check=True, + ) + return Path(result.stdout.strip()).resolve() + except (subprocess.CalledProcessError, FileNotFoundError) as e: + raise ToolError(f"Not in a git repository: {e}") from e + + +def validate_path(path_str: str, git_root: Path) -> Path: + """Validate that a path is within the git repository. + + Uses Path.is_relative_to() to prevent directory traversal attacks. + + Args: + path_str: Path string to validate + git_root: Root of the git repository + + Returns: + Resolved absolute Path object + + Raises: + SecurityError: If path escapes the git repository + """ + try: + # Convert to absolute path and resolve symlinks + if Path(path_str).is_absolute(): + resolved = Path(path_str).resolve() + else: + resolved = (git_root / path_str).resolve() + + # Check if path is within git root + if not resolved.is_relative_to(git_root): + raise SecurityError( + f"Path '{path_str}' escapes git repository root '{git_root}'" + ) + + return resolved + + except (ValueError, OSError, RuntimeError) as e: + raise SecurityError(f"Invalid path '{path_str}': {e}") from e + + +def validate_git_ref(ref: str) -> None: + """Validate a git reference (commit hash, branch, tag). + + Args: + ref: Git reference to validate + + Raises: + SecurityError: If reference contains suspicious characters + """ + # Allow alphanumeric, -, _, /, ^, ~, @ (normal git ref characters) + # Disallow command injection characters: ; | & $ ( ) ` < > etc. + if not re.match(r'^[a-zA-Z0-9._/^~@-]+$', ref): + raise SecurityError(f"Invalid git reference: {ref}") + + +def tool_git_log(args: dict[str, Any], git_root: Path) -> str: + """Execute git log with controlled arguments. + + Args: + args: Dictionary with optional keys: + - max_count: Maximum number of commits (default: 20, max: 100) + - since: Date/time since (e.g., "2 weeks ago") + - until: Date/time until + - path: File path to filter by + - grep: Commit message grep pattern + - author: Author name/email filter + - oneline: Use oneline format (default: False) + + Returns: + Git log output as string + + Raises: + ToolError: If git command fails + SecurityError: If validation fails + """ + cmd = ["git", "log"] + + # Validate and add max_count + max_count = args.get("max_count", 20) + if not isinstance(max_count, int) or max_count < 1 or max_count > 100: + raise ToolError("max_count must be an integer between 1 and 100") + cmd.extend([f"-{max_count}"]) + + # Add optional filters + if args.get("oneline"): + cmd.append("--oneline") + else: + cmd.append("--format=%H%n%an <%ae>%n%ad%n%s%n%b%n---") + + if "since" in args: + cmd.extend(["--since", args["since"]]) + + if "until" in args: + cmd.extend(["--until", args["until"]]) + + if "author" in args: + cmd.extend(["--author", args["author"]]) + + if "grep" in args: + cmd.extend(["--grep", args["grep"]]) + + # Validate and add path filter + if "path" in args: + path = validate_path(args["path"], git_root) + cmd.extend(["--", str(path)]) + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("git log timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"git log failed: {e.stderr}") + + +def tool_git_show(args: dict[str, Any], git_root: Path) -> str: + """Show a git commit or object. + + Args: + args: Dictionary with keys: + - ref: Git reference (commit hash, branch, tag) + - path: Optional path to show specific file at that ref + - stat: Show diffstat only (default: False) + + Returns: + Git show output as string + + Raises: + ToolError: If git command fails + SecurityError: If validation fails + """ + if "ref" not in args: + raise ToolError("ref parameter is required") + + ref = args["ref"] + validate_git_ref(ref) + + cmd = ["git", "show"] + + if args.get("stat"): + cmd.append("--stat") + + # Construct the ref:path or just ref + if "path" in args: + path = validate_path(args["path"], git_root) + # Use relative path for git show + rel_path = path.relative_to(git_root) + cmd.append(f"{ref}:{rel_path}") + else: + cmd.append(ref) + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("git show timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"git show failed: {e.stderr}") + + +def tool_grep(args: dict[str, Any], git_root: Path) -> str: + """Search for pattern in files using grep. + + Args: + args: Dictionary with keys: + - pattern: Search pattern (required) + - path: File or directory path (default: current directory) + - recursive: Recursive search (default: True) + - ignore_case: Case-insensitive search (default: False) + - max_count: Maximum matches per file (default: 100) + - context: Lines of context (default: 0) + + Returns: + Grep output as string + + Raises: + ToolError: If grep fails + SecurityError: If validation fails + """ + if "pattern" not in args: + raise ToolError("pattern parameter is required") + + pattern = args["pattern"] + path = validate_path(args.get("path", "."), git_root) + + cmd = ["grep", "--color=never"] + + if args.get("ignore_case", False): + cmd.append("-i") + + if args.get("recursive", True) and path.is_dir(): + cmd.append("-r") + + max_count = args.get("max_count", 100) + if not isinstance(max_count, int) or max_count < 0: + raise ToolError("max_count must be a non-negative integer") + if max_count > 0: + cmd.extend(["-m", str(max_count)]) + + context = args.get("context", 0) + if not isinstance(context, int) or context < 0 or context > 100: + raise ToolError( + "context must be a non-negative integer not greater than 100") + cmd.extend(["-C", str(context)]) + + # Use -- to prevent pattern from being interpreted as an option + cmd.extend(["--", pattern, str(path)]) + + try: + result = subprocess.run( + cmd, + cwd=git_root, + capture_output=True, + text=True, + timeout=30, + ) + # grep returns 1 if no matches, which is not an error + if result.returncode not in (0, 1): + raise ToolError(f"grep failed: {result.stderr}") + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("grep timed out after 30 seconds") + + +def tool_awk(args: dict[str, Any], git_root: Path) -> str: + """Execute awk for text processing (read-only). + + Args: + args: Dictionary with keys: + - program: AWK program (required) + - path: File path (required) + + Returns: + AWK output as string + + Raises: + ToolError: If awk fails + SecurityError: If validation fails or program attempts writes + """ + if "program" not in args or "path" not in args: + raise ToolError("program and path parameters are required") + + program = args["program"] + path = validate_path(args["path"], git_root) + + # Security: Disallow dangerous awk features + # Block system(), print/printf redirects, pipes, and getline + dangerous_patterns = [ + r'system\s*\(', + r'(print|printf)\s*(.*\s*)>\s*', # any print/printf redirect (with/without quotes) + r'(?<![|&])\|(?![|&])\s*', # pipe not preceded/followed by another | or & + r'getline', # all getline operations+ ]
I looked into the regex parsing in the
tool_awkfunction, to which I noticed that the dangerous patterns could be bypassed if the AI passes forbidden features part by part, for example if "sys" and "tem" are passed individually, it passes the regex check, but when the command runs it concatenates the 2 strings resulting in "system" which is forbidden. For example:part1 = "sys"
part2 = "tem"
cmd = part1 part2
@cmd("rm -rf /")
If you think this would be an issue, I would recommend looking into awk's built in '--sandbox' argument, which inherently disables commands such as
system(), getline, pipes, and file redirects.+ for pattern in
dangerous_patterns:
+ ifre.search(pattern, program):
+ raiseSecurityError(f"AWK program contains forbidden pattern: {pattern}")
+
+ if notpath.exists():
+ raiseToolError(f"File not found: {path}")
+
+ cmd = ["awk", program, str(path)]
+
+ try:
+ result = subprocess.run(+ cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("awk timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"awk failed: {e.stderr}") + + +def tool_sed(args: dict[str, Any], git_root: Path) -> str: + """Execute sed for text processing (read-only). + + Args: + args: Dictionary with keys: + - program: sed program (required) + - path: File path (required) + + Returns: + sed output as string + + Raises: + ToolError: If sed fails + SecurityError: If validation fails or program attempts writes + """ + if "program" not in args or "path" not in args: + raise ToolError("program and path parameters are required") + + program = args["program"] + path = validate_path(args["path"], git_root) + + # Security: Force read-only mode, disallow write/execute commands + # Block w (write), W (Write), e (execute), r/R (read from file), Q (quit with code) + dangerous_patterns = [ + r'[wWeRQ]\s', # write, Write, execute, Read, Quit + r'\d+[wWeRQ]$', # write/execute/read/quit with address + r'[rR][/\s]', # read from file (with or without whitespace)+ ]
When checking for dangerous commands using regex here, I was wondering if this would affect regular commands that match the patterns? Please correct me if I'm wrong, but I wanted to make sure that the specified regex patterns wouldn't block commands that would be useful.
+ for pattern in
dangerous_patterns:
+ ifre.search(pattern, program):
+ raiseSecurityError(f"sed program contains forbidden pattern: {pattern}")
+
+ if notpath.exists():
+ raiseToolError(f"File not found: {path}")
+
+ # Always use -n (suppress automatic printing) to prevent side effects
+ cmd = ["sed", "-n", program, str(path)]
+
+ try:
+ result = subprocess.run(+ cmd, + cwd=git_root, + capture_output=True, + text=True, + check=True, + timeout=30, + ) + return result.stdout + except subprocess.TimeoutExpired: + raise ToolError("sed timed out after 30 seconds") + except subprocess.CalledProcessError as e: + raise ToolError(f"sed failed: {e.stderr}") + + +def tool_file_read(args: dict[str, Any], git_root: Path) -> str: + """Read contents of a file. + + Args: + args: Dictionary with keys: + - path: File path (required) + - max_size: Maximum file size in bytes (default: 1MB) + - encoding: Text encoding (default: utf-8) + + Returns: + File contents as string + + Raises: + ToolError: If file read fails + SecurityError: If validation fails + """ + if "path" not in args: + raise ToolError("path parameter is required") + + path = validate_path(args["path"], git_root) + max_size = args.get("max_size", 1024 * 1024) # 1MB default + encoding = args.get("encoding", "utf-8") + + if not path.exists(): + raise ToolError(f"File not found: {path}") + + if not path.is_file(): + raise ToolError(f"Not a file: {path}") + + # Check file size + file_size = path.stat().st_size + if file_size > max_size: + raise ToolError( + f"File too large: {file_size} bytes (max: {max_size})" + ) + + try: + # Use errors='replace' to handle non-UTF8 bytes gracefully + return path.read_text(encoding=encoding, errors='replace') + except Exception as e: + raise ToolError(f"Failed to read file: {e}") from e + + +# Tool definitions for Anthropic API +TOOL_DEFINITIONS = [ + { + "name": "git_log", + "description": "View git commit history with optional filters. Use this to understand recent changes, find related commits, or trace the history of specific files.", + "input_schema": { + "type": "object", + "properties": { + "max_count": { + "type": "integer", + "description": "Maximum number of commits to show (1-100, default: 20)", + "minimum": 1, + "maximum": 100, + }, + "since": { + "type": "string", + "description": "Show commits more recent than date (e.g., '2 weeks ago', '2024-01-01')", + }, + "until": { + "type": "string", + "description": "Show commits older than date", + }, + "path": { + "type": "string", + "description": "Only show commits affecting this file path", + }, + "grep": { + "type": "string", + "description": "Only show commits with messages matching this pattern", + }, + "author": { + "type": "string", + "description": "Only show commits by this author", + }, + "oneline": { + "type": "boolean", + "description": "Use compact one-line format (default: false)", + }, + }, + }, + }, + { + "name": "git_show", + "description": "Show the contents of a git commit or a specific file at a given commit. Use this to examine what changed in a specific commit or to view historical file contents.", + "input_schema": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "description": "Git reference (commit hash, branch name, tag, or HEAD~N)", + }, + "path": { + "type": "string", + "description": "Optional: specific file path to show at this ref", + }, + "stat": { + "type": "boolean", + "description": "Show only diffstat (default: false)", + }, + }, + "required": ["ref"], + }, + }, + { + "name": "grep", + "description": "Search for text patterns in files. Use this to find specific code patterns, function definitions, or configuration values.", + "input_schema": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "Search pattern (supports regex)", + }, + "path": { + "type": "string", + "description": "File or directory to search (default: current directory)", + }, + "recursive": { + "type": "boolean", + "description": "Search recursively in directories (default: true)", + }, + "ignore_case": { + "type": "boolean", + "description": "Case-insensitive search (default: false)", + }, + "max_count": { + "type": "integer", + "description": "Maximum matches per file (default: 100)", + }, + "context": { + "type": "integer", + "description": "Lines of context around matches (default: 0)", + }, + }, + "required": ["pattern"], + }, + }, + { + "name": "awk", + "description": "Process text files using AWK (read-only). Use this to extract columns, filter lines, or perform text transformations. Write/execute operations are blocked.", + "input_schema": { + "type": "object", + "properties": { + "program": { + "type": "string", + "description": "AWK program to execute", + }, + "path": { + "type": "string", + "description": "File to process", + }, + }, + "required": ["program", "path"], + }, + }, + { + "name": "sed", + "description": "Process text files using sed (read-only). Use this to extract or transform text. Write/execute operations are blocked and -n flag is always enabled.", + "input_schema": { + "type": "object", + "properties": { + "program": { + "type": "string", + "description": "sed program to execute (use p command to print)", + }, + "path": { + "type": "string", + "description": "File to process", + }, + }, + "required": ["program", "path"], + }, + }, + { + "name": "file_read", + "description": "Read the contents of a file. Use this to examine source code, documentation, or configuration files.", + "input_schema": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Path to the file to read", + }, + "max_size": { + "type": "integer", + "description": "Maximum file size in bytes (default: 1048576 = 1MB)", + }, + "encoding": { + "type": "string", + "description": "Text encoding (default: utf-8)", + }, + }, + "required": ["path"], + }, + }, +] + + +# Map tool names to handler functions +TOOL_HANDLERS = { + "git_log": tool_git_log, + "git_show": tool_git_show, + "grep": tool_grep, + "awk": tool_awk, + "sed": tool_sed, + "file_read": tool_file_read, +} + + +def execute_tool(tool_name: str, tool_args: dict[str, Any]) -> str: + """Execute a tool and return its output. + + Args: + tool_name: Name of the tool to execute + tool_args: Arguments for the tool + + Returns: + Tool output as string + + Raises: + ToolError: If tool execution fails + SecurityError: If security validation fails + """ + if tool_name not in TOOL_HANDLERS: + raise ToolError(f"Unknown tool: {tool_name}") + + git_root = get_git_root() + handler = TOOL_HANDLERS[tool_name] + + try: + return handler(tool_args, git_root) + except (ToolError, SecurityError): + raise + except Exception as e: + raise ToolError(f"Tool execution failed: {e}") from e + + +def convert_tools_to_openai_format(anthropic_tools: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Convert Anthropic tool definitions to OpenAI function calling format. + + Args: + anthropic_tools: List of tool definitions in Anthropic format + + Returns: + List of tool definitions in OpenAI format + """ + openai_tools = [] + for tool in anthropic_tools: + openai_tool = { + "type": "function", + "function": { + "name": tool["name"], + "description": tool["description"], + "parameters": tool["input_schema"], + } + } + openai_tools.append(openai_tool) + return openai_tools + + +def get_tools_for_provider(provider: str) -> list[dict[str, Any]]: + """Get tool definitions in the format required by the provider. + + Args: + provider: Provider name (anthropic, openai, xai, google) + + Returns: + List of tool definitions in provider-specific format + """ + if provider == "anthropic": + return TOOL_DEFINITIONS + elif provider in ("openai", "xai"): + return convert_tools_to_openai_format(TOOL_DEFINITIONS) + else: + # Google Gemini uses a different format, not yet implemented + return [] diff --git a/devtools/ai/review-doc.py b/devtools/ai/review-doc.py index e01be077fe..a084678ec5 100755 --- a/devtools/ai/review-doc.py +++ b/devtools/ai/review-doc.py @@ -360,6 +360,8 @@ def call_api( include_diff_markers: bool = False, verbose: bool = False, timeout: int = 120, + enable_tools: bool = True, + max_tool_rounds: int = 10, ) -> tuple[str, TokenUsage]: """Build the per-provider request body and dispatch via _common.""" if provider == "anthropic": @@ -399,6 +401,8 @@ def call_api( request_data, timeout=timeout, verbose=verbose, + enable_tools=enable_tools, + max_tool_rounds=max_tool_rounds, )@@ -665,6 +669,18 @@ def
main()-> None:
metavar="SECONDS",
help="API request timeout in seconds (default: 120)",
)
+ parser.add_argument(+ "--no-tools", + action="store_true", + help="Disable tool calling (git, grep, file read). Tools are enabled by default.", + ) + parser.add_argument( + "--max-tool-rounds", + type=int, + default=10, + metavar="N", + help="Maximum tool calling rounds (default: 10)",+ )
# Email options
email_group=parser.add_argument_group("Email Options")
@@ -811,6 +827,8 @@ defmain()-> None:
args.diff,
args.verbose,
args.timeout,
+ enable_tools=not args.no_tools,
+ max_tool_rounds=args.max_tool_rounds,) total_usage.add(call_usage)diff --git
a/devtools/ai/review-patch.pyb/devtools/ai/review-patch.pyindex5f8d9ed772..a3481290be100755
---a/devtools/ai/review-patch.py
+++b/devtools/ai/review-patch.py
@@ -589,6 +589,8 @@ def call_api(
output_format: str = "text",
verbose: bool = False,
timeout: int = 300,
+enable_tools: bool = True,
+max_tool_rounds: int = 10,
) -> tuple[str, TokenUsage]:
"""Build the per-provider request body and dispatch via_common.""" if provider == "anthropic":
@@ -625,6 +627,8 @@ def call_api(
request_data,
timeout=timeout,
verbose=verbose,
+ enable_tools=enable_tools,
+ max_tool_rounds=max_tool_rounds,)@@ -870,6 +874,18 @@ def
main()-> None:
metavar="SECONDS",
help="API request timeout in seconds (default: 300)",
)
+ parser.add_argument(+ "--no-tools", + action="store_true", + help="Disable tool calling (git, grep, file read). Tools are enabled by default.", + ) + parser.add_argument( + "--max-tool-rounds", + type=int, + default=10, + metavar="N", + help="Maximum tool calling rounds (default: 10)",+ )
# Date and release options
parser.add_argument(
@@ -1079,6 +1095,8 @@ defmain()-> None:
args.output_format,
args.verbose,
args.timeout,
+ enable_tools=not args.no_tools,
+ max_tool_rounds=args.max_tool_rounds,) total_usage.add(call_usage) all_reviews.append((patch_label, review_text)) @@ -1149,6 +1167,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage) all_reviews.append((chunk_label, review_text)) @@ -1203,6 +1223,8 @@ def main() -> None: args.output_format, args.verbose, args.timeout, + enable_tools=not args.no_tools, + max_tool_rounds=args.max_tool_rounds, ) total_usage.add(call_usage)--
2.55.0