# How the Code-Reviewer Agent Validates Code Changes in Codebuff

> Learn how the code-reviewer agent validates code changes in Codebuff using client-side hooks and structured results for efficient feedback.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: deep-dive
- Published: 2026-03-09

---

**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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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.

```typescript
// 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`](https://github.com/CodebuffAI/codebuff/blob/main/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.

```typescript
// 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`](https://github.com/CodebuffAI/codebuff/blob/main/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.

```typescript
// 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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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.