Skip to content

feat(tools): add read-only "git" toolset for structured repository inspection#3637

Open
dwin-gharibi wants to merge 6 commits into
docker:mainfrom
dwin-gharibi:feat/git-tool
Open

feat(tools): add read-only "git" toolset for structured repository inspection#3637
dwin-gharibi wants to merge 6 commits into
docker:mainfrom
dwin-gharibi:feat/git-tool

Conversation

@dwin-gharibi

Copy link
Copy Markdown
Contributor

Closes #3636


Summary

Adds a new built-in toolset, git, giving an agent structured, read-only access to the working repository: status, log, branches, commit details, and blame. Implemented with go-git (already a direct dependency), so it needs no git binary and is fully unit-testable.

Tools: git_status, git_log, git_branches, git_show, git_blame.

Motivation

Coding agents constantly need git context. Today the only option is the shell tool with raw git, which forces the model to parse free-form porcelain, exposes the full writable shell surface, and depends on a git binary. A dedicated read-only toolset returns clean structured output, is safe by construction, and works without shell or the binary.

What changed

File Change
pkg/tools/builtin/git/git.go New. The toolset: 5 read-only tools over go-git.
pkg/tools/builtin/git/git_test.go New. Tests build throwaway repos with go-git and exercise every tool.
pkg/teamloader/toolsets/toolsets.go Register the git creator.
pkg/teamloader/toolsets/catalog.go Add the git catalog entry (required by the drift-guard test).
docs/configuration/tools/index.md Add git to the built-in toolsets table.
docs/tools/git/index.md New. Dedicated docs page.

Design

  • Read-only by design. No add/commit/checkout — write ops are stateful, overlap shell, and raise permission questions; deferred to keep v1 safe.
  • go-git, not the CLI — pure Go, no binary dependency, deterministically testable. The repo opens at the agent's WorkingDir with DetectDotGit.
  • The catalog drift-guard test forces the catalog entry: registering the type without documenting it fails the build.

Example output

$ git_status
On branch master
1 changed file(s) [XY = staged/worktree; M=modified A=added D=deleted R=renamed ?=untracked]:
   M main.go

$ git_log
b3951c61  2026-01-02  Alice  feat: print hi
aac3216e  2026-01-02  Alice  feat: initial commit

$ git_show
commit b3951c61b84a0c298552096542bbd3bd7f58840b
Author: Alice <alice@example.com>
Date:   2026-01-02 03:04:05 +0000

feat: print hi

Changed files:
  main.go (+1, -1)

$ git_blame main.go
aac3216e alice@example.com          1| package main
b3951c61 alice@example.com          3| func main() { println("hi") }

Testing

go test ./pkg/tools/builtin/git/ ./pkg/teamloader/toolsets/
  • git_status (changed + clean), git_log (order + limit), git_branches (current marked), git_show (metadata + stats), git_blame (authorship), plus not-a-repo and missing-path error paths, and the tool-count/interface check.
  • TestBuiltinToolsetsCatalogMatchesRegistry passes with git in both registry and catalog.

All pass; gofmt -l and go vet clean. (CI runs task lint / task test.)

Scope / non-goals

  • Read-only v1 — no write operations.
  • No working-tree line diff (go-git's worktree diff is limited); git_show covers commit-level diffs. Both are noted as possible future work.

@dwin-gharibi dwin-gharibi requested a review from a team as a code owner July 14, 2026 07:19
@dwin-gharibi

Copy link
Copy Markdown
Contributor Author

Let's just continue. @aheritier @Sayt-0

@aheritier aheritier added area/docs Documentation changes area/tools For features/issues/fixes related to the usage of built-in and MCP tools kind/feat PR adds a new feature (maps to feat:). Use on PRs only. labels Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs Documentation changes area/tools For features/issues/fixes related to the usage of built-in and MCP tools kind/feat PR adds a new feature (maps to feat:). Use on PRs only.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a read-only "git" built-in toolset for structured repository inspection

2 participants