cleveragents-core/docs/reference/skills_git.md

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:

1. No input -- uses the current working directory.
2. Absolute paths -- accepted as-is (trusted sandbox paths).
3. 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:

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