I shipped the wrong abstraction, then deleted it

Process-Level Git Interception for AI Agents: Replacing Fragile Hooks with a PATH Shim

Current Situation Analysis

AI coding agents are rapidly becoming standard in development workflows, but they suffer from a fundamental inefficiency: they consume tokens parsing human-oriented Git output. When an agent runs git diff, it receives a unified diff format filled with @@ hunk headers, +/- prefixes, and whitespace context. This "porcelain" output carries no semantic meaning for a model. The agent must expend tokens to reconstruct which functions changed, whether imports were modified, or if a file is generated.

Tools like git-prism address this by providing structured JSON manifests via MCP (Model Context Protocol) servers. Instead of raw text, the agent receives a payload detailing changed functions, signatures, and line ranges. This reduces token consumption and improves accuracy. However, the value proposition collapses if the agent's Git calls bypass the structured provider and hit the raw Git binary.

The industry standard approach to interception has been command-string hooks. Tools like Claude Code offer PreToolUse hooks that inspect the command string before execution. If the string matches git diff, the hook rewrites the call. This approach is widely adopted because it is easy to implement.

This approach is fundamentally flawed for agent workflows. A command-string hook operates at the shell layer, inspecting the literal text typed by the user or agent. It is not a process interceptor. In modern development, agents rarely invoke Git directly. They run build commands, test suites, and review scripts that shell out to Git internally.

• make review: The Makefile target executes git diff. The hook sees make, not git.
• Pre-push hooks: Tools like lefthook or husky run Git commands under the hood.
• Build scripts: cargo or npm scripts may query Git state.
• Nested scripts: A script calling another script that calls Git.

In all these cases, the hook is structurally blind. The Git call reaches the real binary, returning porcelain to the agent. The agent pays tokens for data it cannot parse efficiently, and the structured provider is rendered useless. This layer mismatch—inspecting strings to intercept processes—is a critical architectural error that limits the reliability of AI-augmented workflows.

WOW Moment: Key Findings

Empirical testing reveals that a PATH-based shim is a strict superset of a command-string hook. By intercepting at the process resolution layer, the shim captures every invocation the hook misses, plus the direct calls the hook handles.

The following comparison demonstrates coverage across common agent invocation patterns. The data reflects behavior observed in live agent sessions where PATH is correctly configured.

Invocation Pattern	Command Hook	PATH Shim	Why It Matters
Direct git status	✅	✅	Both work for top-level commands.
sh -c 'git log'	❌	✅	Hooks miss subshells; shims inherit PATH.
make review	❌	✅	Build tools inherit environment; hooks do not.
Pre-push hook	❌	✅	CI/CD pipelines run Git internally; shims catch this.
Script → Script → Git	❌	✅	Arbitrary nesting depth is transparent to shims.
env -i git ...	❌	❌	Explicit environment stripping bypasses both.

Why this matters: The shim approach eliminates the "blind spot" that forces developers to maintain workarounds for nested calls. It ensures that every Git call in the agent's process tree is routed to the structured provider, guaranteeing consistent token savings and data quality. The only failure mode is explicit environment manipulation (env -i), which is rare in standard agent usage.

Core Solution

The solution replaces the command-string hook with a PATH shim. This involves placing a binary named git early in the system PATH. When any process attempts to execute git, the OS resolves it to the shim first. The shim then decides whether to intercept and return structured data or pass through to the real Git binary.

Architecture Decisions

1. Multi-Call Binary Pattern: The shim and the structured provider share a single binary. At startup, the binary checks argv[0]. If invoked as git, it enters shim mode. Otherwise, it runs as the standard CLI. This follows the classic Unix pattern used by busybox and coreutils. It eliminates version skew between the shim and the provider, reduces deployment complexity, and ensures a single release artifact.
2. Cross-Process Loop Break: When the shim passes a call to the real Git, that Git process may trigger hooks or scripts that call git again. Since the shim is still first in PATH, this would cause infinite recursion. The solution is an inherited environment variable, GIT_PRISM_INSIDE_SHIM=1. The shim sets this flag on every child process it spawns. If the shim detects this flag on entry, it bypasses interception and calls the real Git directly. This variable also serves as a user-facing escape hatch for debugging.
3. Strict Classification: The shim must not intercept every Git call. It should only intercept calls relevant to AI agents, such as diff, log, show, and blame, particularly when they include a ref range (e.g., main..HEAD). Calls like git status, git commit, or git push should pass through unchanged to avoid interfering with human workflows or CI pipelines.
4. Exit Code Mapping: The shim must preserve shell semantics. If the real Git binary is found but not executable, the shim must return exit code 126. If the binary is not found, it returns 127. This ensures that scripts relying on exit codes behave correctly.

Implementation Example (TypeScript)

The following TypeScript example demonstrates the shim logic. In production, this would be compiled to a native binary or distributed as a Node.js executable.

import { spawn, SpawnOptions } from 'child_process';
import { env, argv, exit, platform } from 'process';
import { resolve } from 'path';
import { accessSync, constants } from 'fs';

// Configuration
const REAL_GIT_PATH = resolve('/usr/bin/git'); // Resolved dynamically in production
const INSIDE_SHIM_VAR = 'GIT_PRISM_INSIDE_SHIM';
const INTERCEPTABLE_SUBCOMMANDS = new Set(['diff', 'log', 'show', 'blame', 'pickaxe']);

/**
 * Determines if a Git invocation should be intercepted.
 * Intercepts AI-relevant subcommands with ref ranges.
 */
function isInterceptable(args: string[]): boolean {
    if (args.length === 0) return false;
    
    const subcommand = args[0];
    if (!INTERCEPTABLE_SUBCOMMANDS.has(subcommand)) return false;

    // Check for ref range pattern (e.g., main..HEAD)
    const hasRefRange = args.some(arg => /\.\./.test(arg));
    return hasRefRange;
}

/**
 * Spawns the real Git binary with loop-break protection.
 */
function passthroughToRealGit(args: string[]): void {
    const spawnOpts: SpawnOptions = {
        stdio: 'inherit',
        env: {
            ...env,
            [INSIDE_SHIM_VAR]: '1',
        },
    };

    const git = spawn(REAL_GIT_PATH, args, spawnOpts);

    git.on('error', (err) => {
        if (err.code === 'ENOENT') {
            console.error(`git: command not found`);
            exit(127);
        } else if (err.code === 'EACCES') {
            console.error(`git: permission denied`);
            exit(126);
        } else {
            console.error(`git: failed: ${err.message}`);
            exit(1);
        }
    });

    git.on('close', (code) => {
        exit(code ?? 0);
    });
}

/**
 * Returns structured JSON for intercepted calls.
 * In production, this calls the MCP server or local logic.
 */
function returnStructuredManifest(args: string[]): void {
    // Mock payload; real implementation generates JSON manifest
    const manifest = {
        path: 'src/example.rs',
        language: 'rust',
        change_type: 'modified',
        functions_changed: [
            {
                name: 'process_data',
                change_type: 'modified',
                signature: 'fn process_data(input: &str) -> Result<(), Error>',
                start_line: 42,
                end_line: 58,
            },
        ],
    };

    console.log(JSON.stringify(manifest, null, 2));
    exit(0);
}

/**
 * Main entry point.
 */
function main(): void {
    // argv[0] is node, argv[1] is script, argv[2+] are git args
    const gitArgs = argv.slice(2);

    // Loop break: if we are already inside the shim, call real git
    if (env[INSIDE_SHIM_VAR] === '1') {
        passthroughToRealGit(gitArgs);
        return;
    }

    // Classification: intercept or pass through
    if (isInterceptable(gitArgs)) {
        returnStructuredManifest(gitArgs);
    } else {
        passthroughToRealGit(gitArgs);
    }
}

main();

Rationale

• TypeScript/Node.js: While the source implementation uses Rust for performance, the logic is language-agnostic. TypeScript demonstrates the control flow clearly. For production, a compiled binary is preferred to minimize startup latency.
• argv[0] Dispatch: The code assumes the binary is invoked as git. In a multi-call binary, the entry point would check path.basename(argv[0]) to determine mode.
• Loop Break: The INSIDE_SHIM_VAR check is the first operation. This prevents recursion immediately, before any classification logic runs.
• Exit Codes: The error handler maps OS errors to standard shell exit codes (126, 127), ensuring compatibility with scripts that check for specific failure modes.

Pitfall Guide

Implementing a PATH shim introduces unique challenges. The following pitfalls are derived from production experience with agent interception layers.

1. Infinite Recursion

   • Explanation: The shim calls the real Git, which triggers a hook that calls git, re-entering the shim. Without mitigation, this loops until stack overflow.
   • Fix: Always set a loop-break environment variable (e.g., GIT_PRISM_INSIDE_SHIM=1) on child processes. Check for this variable at the very start of the shim.

2. Frozen PATH Snapshots

   • Explanation: Some agent runtimes snapshot the PATH at launch time. If the shim is installed after the agent starts, the snapshot does not include the shim, and interception fails.
   • Fix: Install the shim and update the shell RC file before launching the agent. The installation script must explicitly warn the user to restart the agent session.

3. Over-Interception

   • Explanation: Intercepting commands like git status or git commit can break human workflows or CI pipelines that expect standard output.
   • Fix: Implement a strict classifier. Only intercept subcommands that benefit from structured data (diff, log, show) and only when a ref range is present. Pass through all other calls.

4. Exit Code Mismatch

   • Explanation: The shim may return 0 on error or fail to propagate the real Git exit code, causing scripts to misinterpret success/failure.
   • Fix: Map IO errors to standard exit codes (126 for not executable, 127 for not found). Ensure the shim exits with the same code as the real Git when passing through.

5. Classifier Drift

   • Explanation: If the shim and the structured provider use different logic to decide what to intercept, behavior becomes inconsistent.
   • Fix: Share the classification logic between the shim and the provider. In a multi-call binary, this is trivial. In separate binaries, use a shared library or identical configuration.

6. Performance Overhead

   • Explanation: Spawning a shim for every Git call adds latency. If the shim is slow to start, it degrades the developer experience.
   • Fix: Optimize the fast path. The classification and loop-break check should be O(1). Avoid heavy initialization for pass-through calls. Consider a persistent daemon mode for high-frequency scenarios.

7. CI/CD Interference

   • Explanation: The shim may intercept Git calls in CI pipelines, returning JSON instead of expected output, breaking builds.
   • Fix: Detect CI environments (e.g., CI=true env var) and disable interception automatically. Alternatively, use a whitelist of agent environments rather than a blacklist.

Production Bundle

Action Checklist

• Install Shim Binary: Place the shim binary in a directory like ~/.git-prism/bin.
• Update PATH: Add export PATH="$HOME/.git-prism/bin:$PATH" to your shell RC file (~/.zshrc, ~/.bashrc).
• Restart Agent: Close and reopen the AI agent session to pick up the new PATH.
• Verify Resolution: Run which git to confirm it points to the shim.
• Test Nested Calls: Run make review or a build script to verify interception of subprocesses.
• Check Exit Codes: Run git diff nonexistent..HEAD and verify the exit code matches expectations.
• Monitor Logs: Enable debug logging to inspect intercepted calls and ensure classification is accurate.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
AI Agent Workflow	PATH Shim	Captures all invocations, including nested calls. Maximizes token savings.	Low setup cost; high token ROI.
Human-Only Dev	No Shim	Humans prefer standard Git output. Shim adds unnecessary complexity.	Zero cost.
CI/CD Pipeline	No Shim	CI requires deterministic, standard Git behavior. Interception risks breakage.	Zero cost.
Hybrid Workflow	Shim + CI Detection	Shim works for agents; auto-disables in CI via env var detection.	Minimal overhead.
Legacy Systems	Command Hook	If PATH manipulation is restricted, hooks are the fallback.	High risk of missed calls.

Configuration Template

Shell RC Configuration:

# ~/.zshrc or ~/.bashrc

# Git-Prism Shim Installation
export GIT_PRISM_HOME="$HOME/.git-prism"
export PATH="$GIT_PRISM_HOME/bin:$PATH"

# Optional: Disable shim in CI environments
if [ -n "$CI" ]; then
    # Remove shim from PATH in CI
    export PATH=$(echo "$PATH" | sed "s|$GIT_PRISM_HOME/bin:||g")
fi

Shim Classification Config (JSON):

{
  "interceptable_subcommands": ["diff", "log", "show", "blame", "pickaxe"],
  "require_ref_range": true,
  "loop_break_var": "GIT_PRISM_INSIDE_SHIM",
  "exit_codes": {
    "not_found": 127,
    "not_executable": 126
  }
}

Quick Start Guide

1. Download: Obtain the shim binary from the release artifact.
2. Install: Run git-prism shim install to set up the binary and update your RC file.
3. Restart: Restart your AI agent to load the new PATH.
4. Verify: Run git diff main..HEAD and confirm you receive structured JSON output.
5. Test: Run a nested command like make review to verify subprocess interception.

By moving interception from the command-string layer to the process layer, you eliminate the blind spots that plague hook-based solutions. The PATH shim provides comprehensive coverage, ensures consistent structured data delivery, and integrates seamlessly with existing workflows when implemented with proper loop-break and classification safeguards.