tools.read_tool_code module

Read Python tool source code from the tools/ directory.

async tools.read_tool_code.run(filename, max_lines=None, start_line=None, end_line=None, ctx=None, **_kwargs)[source]

Read the source of a Python tool file from the tools/ directory.

Entry point for the read_tool_code tool, used to inspect or debug existing tool implementations. It returns the full file or a bounded slice, after a privilege check and several safety checks that keep reads confined to tools/ and to .py files.

It first calls _check_read_tool_code(), short-circuiting with that helper’s error JSON when the caller lacks READ_TOOL_CODE. It then rejects subdirectory components and path traversal (resolving against TOOLS_ROOT and requiring the result to stay inside it), checks existence and file-ness via filepath.exists / filepath.is_file offloaded with asyncio.to_thread, and requires a .py extension. The file is read asynchronously with aiofiles; a start_line/end_line window or a max_lines head is applied, and the result is serialized with jsonutil (imported as json). Errors (permission, non-UTF-8, anything else) are logged via the module logger and returned as JSON rather than raised. This module-level run is discovered and dispatched by the tool runtime via tool_loader.py (getattr(module, "run")); no other in-repo callers.

Parameters:

  • filename (str) – Bare filename (no path) of a .py file under tools/ to read.

  • max_lines (int) – When set and no line range is given, return only the first this-many lines.

  • start_line (int) – 1-indexed first line of a range to return (with end_line).

  • end_line (int) – 1-indexed last line of a range to return (with start_line).

  • ctx (ToolContext | None) – Tool context used for the privilege check.

Returns:

A JSON document with the file content, total_lines and returned_lines on success, or a {"success": False, "error": ...} payload for an authorization failure, an invalid/missing/non-Python file, an out-of-range line selection, or a read error.

Return type:

str