-
Notifications
You must be signed in to change notification settings - Fork 162
feat(tools): typed git and GitHub operations #3384
Description
Git and GitHub work reaches the model as text it has to parse. git status, git diff, git log and git branch are allowlisted and do work today, and gh is reachable with a grant — so this is not a reachability gap. It is a reliability one.
The agent gets human-readable output whose shape varies by git version, locale and config, and has to infer structure from it. That is a class of misread state with real consequences: believing it is on a different branch than it is, or misreading which files a diff touches, is one of the ways an edit lands somewhere the user did not expect.
Typed operations returning structured data remove the parsing step entirely, and let the tool own version differences instead of the model.
Acceptance criteria
- Typed read operations returning structured data: status, diff, log, current branch; PR list, view, and checks.
- Write operations (commit, push, PR create/comment) keep an explicit confirmation gate and are not auto-approved.
- Structured returns, not parsed stdout — the tool owns the parsing.
- Typed tools map onto the existing read-vs-confirmable-write tiering rather than inventing a parallel one, so the two cannot drift.
- The shell path keeps working for anything not covered; this is additive.
- Absence of
gitorghon the machine is an actionable error naming what to install, not a silent empty result.
🔍 Technical details
SAFE_GIT_COMMANDS (src/gaia/agents/tools/shell_tools.py:111-123) already permits status, log, show, diff, branch, remote, ls-files, ls-tree, describe, rev-parse — so the read operations named above are reachable via run_shell_command today.
gh is not in ALLOWED_COMMANDS but is grantable via shell:execute:gh, and gh pr checks is in the read-only set at src/gaia/skills/binaries.py:406.
policy_refusal_for_call and skill_grant_covers_call already encode the read-vs-confirmable-write distinction; that tiering is what typed tools should reuse.
Prior art. cpp/include/gaia/git_tools.h already ships typed read-only git_status / git_diff / git_log / git_show returning structured JSON — most of the read half of AC #1, designed and built on the other tree. Not covered there: current-branch and the entire gh/PR surface, which is what keeps this issue worth doing.