Tool Safety

oy no longer exposes a native model-callable tool registry. The host owns the general tool surface: file reads/edits, bash, web fetches, task/subagent tools, questions, todos, repository cloning, and permissions.

This document covers only the deterministic tools served by oy mcp.

MCP Capability Matrix

MCP tool	Capability	Mutation	Notes
`repo_manifest`	Build gitignore-aware file/directory inventory, token estimates, language summary, optional security index	No	Skips dependencies, build outputs, lockfiles, hidden/likely-secret files
`repo_chunks`	Build deterministic file/directory chunks and optionally return one chunk’s text	No	Used by audit/review agents
`git_diff_input`	Build deterministic chunks from `git diff <target>`	No workspace mutation	Runs read-only `git` commands in the workspace
`existing_report`	Read a generated audit/review report for carry-forward comparison	No	Defaults to `ISSUES.md` or `REVIEW.md`; path stays inside the workspace
`sloc`	Count source lines with external `tokei`	No	Exposed only when `tokei` is on `PATH`; reads paths inside workspace
`outline`	Extract source definitions with external Universal Ctags	No	Exposed only when Universal Ctags is on `PATH`; reads one exact source file inside workspace
`sighthound`	Scan source with Sighthound embedded SAST rules	No workspace mutation	Explicit-focus audit use only; independent gitignore-aware discovery; fixed JSON output, timeout, finding-count limit, and byte budget
`render_audit_report`	Render markdown or SARIF audit report	Yes	Writes only to a validated workspace output path
`render_review_report`	Render markdown review report	Yes	Writes only to a validated workspace output path

Install optional local helper CLIs with:

mise use --global cargo:tokei
mise use --global github:universal-ctags/ctags
mise use --global cargo:https://github.com/Corgea/Sighthound@tag:1.0
# or: brew install tokei universal-ctags

The pinned Sighthound tag has no release binary; mise builds it from source and therefore requires Rust 1.85+.

Optional helpers are resolved once per oy mcp process to canonical absolute paths. Relative PATH entries are ignored; OY_TOKEI, OY_CTAGS, and OY_SIGHTHOUND can override discovery with an explicit absolute executable path. Probes verify successful version/capability output; calls close stdin and enforce tool-specific time and per-stream output limits. On Unix, helpers run in a dedicated process group that is terminated after direct-child exit or timeout so descendants cannot hold captured pipes open. Ctags option-file loading is disabled with --options=NONE. Sighthound is restricted to embedded rules and one worker; returned findings are stably sorted, string/array bounded, and capped below the generated host tool-output budget. Unsupported-language scopes return an empty status, and all-mode scans fall back to simple analysis when a language pack has no taint rules.

Run oy doctor to check whether the optional MCP tools are currently exposed.

What oy MCP Does Not Provide

oy mcp intentionally does not provide:

arbitrary shell execution (it does run fixed, bounded git and optional helper commands)
source edits
arbitrary file reads beyond deterministic inputs
web fetches
repository cloning
todo management
model calls
session persistence

Use built-in tools and permissions for those capabilities. When launched through oy, the generated oy, oy-plan, oy-edit, and oy-auto agents map old oy safety modes onto host permissions.

Filesystem Boundary

Workspace input tools resolve paths under the current workspace root (OY_ROOT or cwd). They accept workspace-relative paths and absolute paths that resolve inside the workspace. They reject parent traversal and resolved paths outside the workspace.

Report renderers use config::resolve_workspace_output_path, which rejects absolute paths, parent traversal, symlink ancestors that escape the workspace, and symlink final destinations.

When changing this boundary:

validate before reading or writing,
canonicalize existing paths,
keep output writes inside the workspace,
add tests for traversal and symlink cases,
avoid broadening file collection without documenting the disclosure impact.

Disclosure Boundary

The host decides what to send to the selected model. oy mcp can return repository text chunks, so returned chunk content may become model input.

The collector skips gitignored and hidden paths, common dependency/build directories, lockfiles, generated reports, likely-secret file names, binary/non-UTF-8/empty files, unreadable files, and files larger than 512 KiB. “Every chunk” therefore means every collected chunk, not every repository byte. Keep this conservative and make exclusions visible when completeness matters.

Sighthound does not use that collected file list. It has independent gitignore-aware discovery, common directory exclusions, supported-language filtering, and a larger file limit (currently 10 MiB). It can therefore inspect supported hidden source or source files omitted by oy’s size limit. Generated auditors invoke it only when focus explicitly asks for Sighthound/SAST. Treat returned snippets as an additional disclosure boundary.

Permission Boundary

The host handles user approval for its own tools. oy mcp report-writing tools are exposed as MCP tools, so permission behavior follows the host MCP/tool configuration. Keep generated agents explicit about when they call report renderers.

Adding A New MCP Tool

Only add a tool if it is deterministic repo analysis or deterministic report rendering that the host does not already provide.

Checklist:

no hidden LLM calls,
no shell/process side effects unless read-only and documented,
no network access,
bounded external-process runtime and output,
workspace path validation near entry,
clear JSON schema in src/mcp.rs,
generated agents/skills updated if the tool should be used by workflows,
tests or smoke coverage for tools/list and tools/call behavior.

Keyboard shortcuts