Git Operation Skills (C4.git)

This document describes the built-in git operation skills that agents can use to inspect repository state safely. All git tools are read-only -- no destructive operations (commit, push, reset, checkout) are available in the MVP.

Tools

Tool	Description	Read-only
`builtin/git-status`	Show working tree status	Yes
`builtin/git-diff`	Show changes in working tree	Yes
`builtin/git-log`	Show commit log	Yes
`builtin/git-blame`	Show line-by-line file attribution	Yes

Safety Settings

All git tools run with the following environment variables to ensure deterministic output and prevent interactive prompts:

Variable	Value	Purpose
`GIT_PAGER`	`cat`	Disable paging
`GIT_TERMINAL_PROMPT`	`0`	Disable interactive credential input
`GIT_ASKPASS`	(empty)	Disable GUI credential helpers
`NO_COLOR`	`1`	Strip ANSI colour codes
`GIT_CONFIG_NOSYSTEM`	`1`	Ignore system-wide config
`TERM`	`dumb`	Prevent terminal escape sequences

Additionally, git commands are run with --no-pager -c color.ui=never flags, and the target directory is marked as safe.directory via environment-based git config injection.

Path Guards

All tools accept an optional repo_path parameter. Path validation follows these rules:

No input -- uses the current working directory.
Absolute paths -- accepted as-is (trusted sandbox paths).
Relative paths -- resolved against cwd, then checked for .. traversal. Paths that escape the sandbox root are rejected with a ValueError.

Error Mapping

Common git errors are translated to user-friendly messages:

Git Error Pattern	Friendly Message
`not a git repository`	The specified path is not a git repository.
`fatal: bad default revision`	No commits exist in this repository yet.
`HEAD detached`	Repository is in a detached HEAD state; some operations may ...
`pathspec`	The specified file or path does not exist in the repository.
`unknown revision or path`	Unknown revision or path not in the working tree.

Usage

Registration

from cleveragents.tool.builtins import register_git_tools
from cleveragents.tool.registry import ToolRegistry

registry = ToolRegistry()
register_git_tools(registry)

Execution

from cleveragents.tool.runner import ToolRunner

runner = ToolRunner(registry)

# Show working tree status
result = runner.execute("builtin/git-status", {"repo_path": "/sandbox/repo"})
print(result.output["output"])

# Show diff with stat summary
result = runner.execute("builtin/git-diff", {
    "repo_path": "/sandbox/repo",
    "stat": True,
})

# Show last 5 commits in oneline format
result = runner.execute("builtin/git-log", {
    "repo_path": "/sandbox/repo",
    "max_count": 5,
    "oneline": True,
})

# Blame a specific file range
result = runner.execute("builtin/git-blame", {
    "repo_path": "/sandbox/repo",
    "path": "src/main.py",
    "line_start": 10,
    "line_end": 20,
})

Security Rationale

Only read-only operations are exposed because:

Agents should observe repository state, not mutate it directly.
Mutations (commits, merges, pushes) must go through the plan lifecycle -- strategize, execute, apply -- with human review gates.
Limiting the git tool surface prevents accidental data loss from agent hallucinations (e.g. git reset --hard).

4.1 KiB Raw Blame History