adachsoft/git-tool

Git tool adapter for adachsoft/ai-tool-call built on top of adachsoft/gitlib.

v0.3.0 2026-02-04 21:01 UTC

Requires

• adachsoft/ai-tool-call: *
• adachsoft/gitlib: ^1.2
• adachsoft/normalized-safe-path: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: 2.1.34
• phpunit/phpunit: ^12.4
• rector/rector: 2.3.3

MIT

• Arkadiusz Adach

• git
• adapter
• spi
• ai-tool-call
• ai-tool

README

Git tool adapter for adachsoft/ai-tool-call.

This library exposes a small, well-defined subset of Git operations as AI-callable tools. It is built on top of adachsoft/gitlib and is intended to be used by agents via the SPI layer of adachsoft/ai-tool-call.

There are currently two main SPI tools provided:

• GitTool – full Git tool with both read and write operations.
• ReadOnlyGitTool – read-only Git tool exposing only non-mutating operations.

Supported operations

Common operation model

Both tools share the same conceptual parameters shape:

{
  "operation": "operation-name",
  "options": {
    // operation-specific
  }
}

GitTool operations (read & write)

• status – read repository status (branch, staged/modified/untracked/deleted files, raw output).
• add – stage files in the index.
• commit – create a new commit with a message.
• push – push commits or tags to a remote.
• tag_list – list tags (optionally filtered by pattern).
• tag_create – create a new tag (lightweight or annotated, optional signing and force).
• tag_delete – delete a local tag.
• checkout – switch branches/tags/commits and optionally create a new branch.
• show – show details of a Git object (commit, tag, etc.).
• diff – show changes for a given path or commit range.
• remote_list – list configured remotes with their URLs.

ReadOnlyGitTool operations (read-only)

The read-only tool exposes only non-mutating operations:

• status
• tag_list
• show
• diff
• remote_list

This is useful for agents that must never change repository state but still need rich visibility into the Git history and configuration.

Installation

Install via Composer:

composer require adachsoft/git-tool

This package depends on:

• adachsoft/ai-tool-call – SPI + public API for calling tools from agents.
• adachsoft/gitlib – Git operations backend.

Check their respective composer.json files for exact PHP version requirements.

Architecture overview

The package is intentionally small and split into three main layers:

• SPI Tools (integration layer)
  • AdachSoft\GitTool\Tool\GitTool – implementation of AdachSoft\AiToolCall\SPI\ToolInterface.
  • AdachSoft\GitTool\Tool\GitToolFactory – implementation of AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface.
  • AdachSoft\GitTool\Tool\ReadOnlyGitTool – read-only tool implementation of ToolInterface.
  • AdachSoft\GitTool\Tool\ReadOnlyGitToolFactory – factory for the read-only tool.
• Service layer
  • AdachSoft\GitTool\Service\GitToolService / GitToolServiceInterface.
  • AdachSoft\GitTool\Service\GitOperationRegistry / GitOperationRegistryInterface.
• DTOs & Exceptions
  • AdachSoft\GitTool\Dto\GitToolRequestDto, GitToolResultDto.
  • Domain-specific exceptions under AdachSoft\GitTool\Exception.

The SPI layer knows only about the generic operation and options structure. The service layer maps these operations to concrete calls on Adachsoft\GitLab\Contracts\GitRepositoryInterface from adachsoft/gitlib.

Configuration: base_path

The Git repository location is configured once, when the tool is created by the factory. It is not provided per call.

GitToolFactory::create() and ReadOnlyGitToolFactory::create() accept an AdachSoft\AiToolCall\SPI\Collection\ConfigMap with the following option:

• base_path (string, optional)
  • Base path of the Git repository.
  • When omitted, the current working directory (getcwd()) is used.
  • When provided, it must be a non-empty string and an existing directory.

Example:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\GitTool\Tool\GitToolFactory;
use AdachSoft\GitTool\Tool\ReadOnlyGitToolFactory;

$config = new ConfigMap([
    'base_path' => '/path/to/your/git/repository',
]);

$writeFactory = new GitToolFactory();
$writeTool = $writeFactory->create($config); // AdachSoft\GitTool\Tool\GitTool

$readOnlyFactory = new ReadOnlyGitToolFactory();
$readOnlyTool = $readOnlyFactory->create($config); // AdachSoft\GitTool\Tool\ReadOnlyGitTool

The hosting application is responsible for wiring the factories into the SPI infrastructure of adachsoft/ai-tool-call (see that package's documentation for exact integration steps).

Tool interface: operations and options

The tool parameters are described by GitTool::getDefinition() and ReadOnlyGitTool::getDefinition() via SpiToolDefinitionDto. Conceptually, the parameters have the following shape:

{
  "operation": "status | add | commit | push | tag_list | tag_create | tag_delete | checkout | show | diff | remote_list",
  "options": {
    // operation-specific
  }
}

Refer to the PHPDoc blocks in GitTool and ReadOnlyGitTool for the exact list of parameters and result structures.

Result format

Every successful tool call returns a ToolCallResultDto that wraps a KeyValueMap with the following structure:

{
  "operation": "operation-name",
  "data": { /* operation-specific result */ }
}

Examples:

// status
{
  "operation": "status",
  "data": {
    "branch": "main",
    "staged": ["src/GitTool.php"],
    "modified": [],
    "untracked": ["README.md"],
    "deleted": [],
    "raw_output": "On branch main..."
  }
}

// remote_list
{
  "operation": "remote_list",
  "data": {
    "remotes": [
      {
        "name": "origin",
        "fetch_url": "[e-mail]:adachsoft/git-tool.git",
        "push_url": "[e-mail]:adachsoft/git-tool.git"
      }
    ]
  }
}

Error handling

The tools validate input at the SPI boundary:

• missing or empty operation – InvalidToolCallException.
• non-array options – InvalidToolCallException.
• unsupported operation for the given tool (e.g. write operation on read-only tool) – InvalidToolCallException.

Domain-level errors are mapped to ToolExecutionException:

• unsupported operation value in the registry.
• invalid per-operation options (e.g. missing message for commit).
• failures coming from the underlying Git library.

The original domain exception is attached as the previous exception for easier debugging.

Development & tests

The repository includes a set of PHPUnit tests covering:

• the SPI tools (GitTool, ReadOnlyGitTool).
• the factories (GitToolFactory, ReadOnlyGitToolFactory).
• the service layer (GitToolService).
• the operation registry (GitOperationRegistry).

Run the test suite with:

composer install
vendor/bin/phpunit