# 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

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

registry = ToolRegistry()
register_git_tools(registry)
```

### Execution

```python
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`).