How the Code-Reviewer Agent Validates Code Changes in Codebuff

The code-reviewer agent validates code changes by invoking the run_file_change_hooks tool to execute client-side hooks (tests, linters, type-checkers) and incorporates the structured results into its feedback.

The Codebuff repository implements an AI-powered code review system where specialized agents analyze modifications to ensure quality. Understanding how the code-reviewer agent validates code changes reveals the two-step validation process that ensures quality before changes are finalized.

The Two-Step Validation Architecture

The validation system operates through a clear separation of concerns between the agent's decision-making logic and the actual execution environment.

Agent Decision Logic

The code-reviewer agent, defined in agents-graveyard/opensource/reviewer.ts, uses its instructionsPrompt to determine when validation is necessary. The agent specifically looks for TypeScript/JavaScript files, test files, or any changes that could affect compilation or test execution. When these conditions are met, the agent constructs a tool call to run_file_change_hooks with the specific file paths that were modified.

Client-Side Hook Execution

Unlike traditional CI/CD pipelines that run on remote servers, Codebuff executes validation hooks directly on the developer's machine through the client. The run_file_change_hooks tool triggers client-configured hooks such as tests, linters, and type-checkers. This approach provides immediate feedback without requiring code pushes to a remote repository.

Core Implementation Files

The validation workflow relies on three primary components that define the agent behavior, tool handling, and data schemas.

Reviewer Agent Definition (agents-graveyard/opensource/reviewer.ts)

The reviewer agent configuration specifies the available tools and behavioral instructions. The toolNames array includes 'run_file_change_hooks' alongside 'end_turn', ensuring the agent can invoke validation during its review process. The instructionsPrompt explicitly directs the agent to run file change hooks after analyzing changes and to include the results in its feedback.

// agents-graveyard/opensource/reviewer.ts
toolNames: ['end_turn', 'run_file_change_hooks'],
instructionsPrompt: `
Your task is to provide helpful feedback on the last file changes made by the assistant.

IMPORTANT: After analyzing the file changes, you should:
1. Run file change hooks to validate the changes using the run_file_change_hooks tool
2. Include the hook results in your feedback …
`,

Tool Handler (packages/agent-runtime/src/tools/handlers/tool/run-file-change-hooks.ts)

The handleRunFileChangeHooks function implements the actual tool execution logic. It waits for any previous tool calls to complete using await previousToolCallFinished, then forwards the tool call to the client via requestClientToolCall(toolCall). The function returns the client's output directly, maintaining a simple pass-through architecture that keeps the agent runtime decoupled from specific hook implementations.

// packages/agent-runtime/src/tools/handlers/tool/run-file-change-hooks.ts
export const handleRunFileChangeHooks = (async ({
  previousToolCallFinished,
  toolCall,
  requestClientToolCall,
}) => {
  await previousToolCallFinished
  return { output: await requestClientToolCall(toolCall) }
}) satisfies CodebuffToolHandlerFunction<'run_file_change_hooks'>

Schema and Parameters (common/src/tools/params/tool/run-file-change-hooks.ts)

The runFileChangeHooksParams object defines the complete tool contract. The inputSchema requires a files array containing string paths of modified files. The outputSchema specifies a union type returning either successful hook results (containing stdout, stderr, exitCode, and hookName) or error objects (containing errorMessage). The endsAgentStep: true flag indicates that invoking this tool completes the current agent step.

// common/src/tools/params/tool/run-file-change-hooks.ts
const inputSchema = z.object({
  files: z.array(z.string()).describe(
    `List of file paths that were changed and should trigger file change hooks`,
  ),
})

export const runFileChangeHooksParams = {
  toolName: 'run_file_change_hooks',
  endsAgentStep: true,
  description: `Purpose: Trigger client‑configured file change hooks …`,
  inputSchema,
  outputSchema: jsonToolResultSchema(
    z.union([
      terminalCommandOutputSchema.and(z.object({ hookName: z.string() })),
      z.object({ errorMessage: z.string() }),
    ]).array(),
  ),
}

How the Validation Workflow Executes

The validation process follows a structured sequence from detection to feedback integration.

1. Change Detection: The reviewer agent receives the list of modified files for the current step, such as ['src/utils/helpers.ts', 'tests/helpers.test.ts'].

2. Tool Invocation: The agent constructs a run_file_change_hooks tool call with the files parameter populated with the changed paths.

3. Client Execution: The client receives the tool call and executes configured hooks—such as npm test, eslint src/**/*.ts, or tsc --noEmit—directly on the local development environment.

4. Result Processing: The client returns structured results to the handleRunFileChangeHooks handler, which forwards them to the agent.

5. Feedback Generation: The reviewer agent incorporates the hook results into its final output, reporting successes (e.g., "All hooks passed") or failures (e.g., "Lint failed – see error …") to the user.

Summary

• The code-reviewer agent validates changes by invoking the run_file_change_hooks tool after analyzing modified files.
• Validation executes client-side, running tests, linters, and type-checkers directly on the developer's machine for immediate feedback.
• The agent definition in agents-graveyard/opensource/reviewer.ts mandates hook execution for TypeScript/JavaScript and test files.
• The tool handler in packages/agent-runtime/src/tools/handlers/tool/run-file-change-hooks.ts provides a simple pass-through to the client.
• Results include structured output with stdout, stderr, exitCode, and hookName, enabling detailed feedback integration.

Frequently Asked Questions

What triggers the code-reviewer agent to run validation hooks?

The agent triggers validation when its instructionsPrompt detects TypeScript/JavaScript files, test files, or any changes that could affect compilation or test execution. The agent explicitly constructs a run_file_change_hooks tool call with the modified file paths to ensure validation occurs before completing the review.

How does the run_file_change_hooks tool execute validation without remote servers?

The tool leverages a client-side execution model where the handleRunFileChangeHooks function forwards the tool call to the local client via requestClientToolCall. The client then runs configured hooks—such as npm test, eslint, or tsc—directly on the developer's machine, returning structured results without requiring code pushes to external CI/CD infrastructure.

What information does the validation tool return to the reviewer agent?

The tool returns a structured array containing either successful hook results or error objects. Successful results include stdout, stderr, exitCode, and hookName, while failures return an errorMessage. This schema, defined in runFileChangeHooksParams, enables the agent to incorporate specific pass/fail details and error output into its final review feedback.

Where is the reviewer agent's validation behavior configured?

The validation behavior is defined in agents-graveyard/opensource/reviewer.ts, which specifies the toolNames array including 'run_file_change_hooks' and provides the instructionsPrompt that directs the agent to run hooks after analyzing changes. The runFileChangeHooksParams in common/src/tools/params/tool/run-file-change-hooks.ts defines the input/output schemas and the endsAgentStep: true flag that marks the tool as completing the agent step.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}