Agent Definitions¶

hachimoku’s review agents are defined in TOML files. It adopts a data-driven architecture that allows adding and customizing agents without code changes. Built-in agents are provided as standard, and project-specific custom agents can also be added.

Built-in Agents ¶

The following agents are included in the package.

Agent Name	Description	Output Schema	Phase	Applicability
breaking-change-detector	Detection of breaking changes in public APIs, data models, CLI interfaces, and configuration formats	severity_classified	main	content_patterns
code-reviewer	Code quality and bug detection	scored_issues	main	Always applied
dependency-auditor	Dependency security and health auditing	severity_classified	main	content_patterns
silent-failure-hunter	Detection of silent failures	severity_classified	main	content_patterns
pr-test-analyzer	Test coverage assessment	test_gap_assessment	main	file_patterns
type-design-analyzer	Practical analysis of type annotations and type safety	multi_dimensional_analysis	main	file_patterns + content_patterns
comment-analyzer	Comment accuracy analysis	category_classification	final	content_patterns
code-simplifier	Code simplification suggestions	improvement_suggestions	final	Always applied

See Output Schemas for details on output schemas.

Selector Agent ¶

The selector agent is a specialized agent that analyzes the review target and selects which review agents to run. Like review agents, its configuration is managed via a TOML definition file.

SelectorDefinition ¶

Field	Type	Required	Description
`name`	`str`	Yes	Selector name (fixed as `"selector"`)
`description`	`str`	Yes	Description of the selector
`model`	`str \| None`	No	LLM model name. Default: `None` (resolved via model resolution priority)
`system_prompt`	`str`	Yes	Selector’s system prompt
`allowed_tools`	`list[str]`	No	Allowed tool categories. Default: empty. The built-in `selector.toml` sets `git_read`, `gh_read`, `file_read` (3 categories, `web_fetch` not included)

Unlike AgentDefinition for review agents, there are no output_schema, phase, or applicability fields. The selector’s output is always fixed to SelectorOutput (list of selected agent names with reasons).

Model Resolution Priority ¶

The selector agent’s model is resolved in the following priority order:

model in [selector] configuration (see Configuration)
model in the selector definition
Global model setting (default: "claudecode:claude-opus-4-7")

Built-in Selector Definition ¶

A built-in selector.toml is included in the package. Placing a custom selector.toml at .hachimoku/agents/selector.toml overrides the built-in.

selector.toml (built-in)¶

name = "selector"
description = "Analyzes review targets and selects optimal review agents"
model = "claudecode:claude-opus-4-7"
allowed_tools = ["git_read", "gh_read", "file_read"]
system_prompt = """
You are an agent selector for code review. Your role is twofold:
1. Select the most applicable review agents from the available list.
2. Provide analysis metadata that will be forwarded to the selected review agents.

## Input Format

For diff and PR modes, the user message contains a diff summary (not the full diff) with:
- A table of changed files with their status (modified/new/deleted/renamed/binary) and addition/deletion counts
- A brief preview of the first few changed lines per file

This summary provides enough context for agent selection decisions. If you need to examine specific changes in detail for your metadata analysis, use the run_git tool to access the full diff.

## File Navigation

The user message includes a "Directory Tree" section under "Pre-fetched Context" that lists all source files in the project. **Always refer to this directory tree before using the read_file tool** to verify that the file path exists. If you need to explore a directory not covered by the tree, use the list_directory tool first to discover available files before calling read_file. Never guess file paths.

## Agent Selection
Analyze the review target provided in the user message. Consider each agent's description, applicability rules (file_patterns, content_patterns), and phase when making your selection. Return the selected agent names and your reasoning.

## Metadata for Review Agents
Populate the following fields to provide context that review agents cannot easily derive on their own:

### change_intent
Summarize the purpose and intent of the changes. What problem is being solved? What design decisions were made? This helps review agents focus on whether the implementation achieves its stated goal.

### affected_files
List file paths OUTSIDE the diff that may be affected by these changes. Investigate with your tools:
- Trace imports and call sites of modified functions/classes
- Check configuration files that reference changed values
- Look for tests that reference changed APIs
Only include files you have verified exist and are actually affected. Do not speculate.

### relevant_conventions
List project conventions relevant to this review. Check CLAUDE.md, .hachimoku/config.toml, and project documentation for applicable rules. This helps agents avoid suggesting changes that contradict project policies.

### issue_context
If an issue number is provided and issue context is NOT already available in the pre-fetched data (check the user message for '## Pre-fetched Context > ### Issue Context'), use the run_gh tool to fetch the issue details. If issue context has been pre-fetched, summarize it directly from the provided data. Include relevant requirements, acceptance criteria, and discussion points that help review agents understand the broader context.

### referenced_content
When the diff or associated context mentions external references (Issue numbers like "#152", file paths like "src/foo.py", or quoted passages attributed to a source), fetch the referenced content and include it in this field. For each reference:
- Set reference_type to the kind of reference: "issue", "file", "spec", or "other".
- Set reference_id to the identifier (e.g., "#152", "src/hachimoku/models/_base.py").
- Set content to the relevant text from the referenced source.

Before fetching, check if the referenced content is already available in the pre-fetched data. Use the run_gh tool to fetch issue bodies, the read_file tool to read files. **When a reference mentions a path you are not certain exists, use the list_directory tool to verify the actual directory structure before calling read_file.** Only include references you successfully fetched. If a reference cannot be resolved, omit it.

This data enables review agents to verify consistency between the diff text and its referenced sources (e.g., correct quoting, accurate paraphrasing, matching terminology).
"""

load_selector()¶

Loads the selector definition. When custom_dir is specified and a selector.toml exists in that directory, it overrides the built-in.

from hachimoku.agents import load_selector

definition = load_selector()
print(definition.name)  # "selector"

TOML Definition File Format ¶

Agent definitions are written as TOML files in the following format.

code-reviewer.toml (built-in)¶

name = "code-reviewer"
description = "Comprehensive review of code quality, bugs, and best practices"
model = "claudecode:claude-opus-4-7"
output_schema = "scored_issues"
phase = "main"
allowed_tools = ["git_read", "gh_read", "file_read"]
system_prompt = """
You are code-reviewer, an expert code quality analyst. Analyze code changes for bugs, security issues, and best practice violations.

## Review Methodology
1. Use run_git(["diff", "--name-only"]) to list changed files.
2. Use run_git(["diff"]) to examine the full diff for each changed file.
3. Use read_file(path) to read surrounding context when the diff alone is insufficient.
4. Check for bugs, logical errors, race conditions, and off-by-one errors.
5. Identify security vulnerabilities: injection, authentication bypass, data exposure.
6. Evaluate error handling: missing exception handling, swallowed errors.
7. Assess performance: unnecessary allocations, N+1 queries, blocking I/O.
8. Review naming, structure, and adherence to coding standards.

## Investigation Protocol
When a diff changes a function signature, class interface, or public API, always trace callers outside the diff. Use run_git(["ls-files"]) to list project files, then read_file(path) to check call sites in files not included in the diff. Report broken callers as bugs.
When a diff modifies error handling or changes the exceptions a function can raise, focus on whether the change breaks callers. Use read_file(path) to read direct callers and verify they handle the new exception type. Leave error-silencing analysis to silent-failure-hunter.
When a diff adds or modifies a return type, use run_git(["log", "-p", "-S", "the_function_name", "--", "path/to/file"]) (substituting the actual function name and file path from the diff) to check if the function's contract changed. Verify callers handle the new return shape.
Do not report caller impact speculatively. Only flag issues where you have read the caller code and confirmed the incompatibility.
If you cannot complete the investigation due to tool call limits, list the files or callers you were unable to verify in your output.

## Turn Budget Strategy
You have a limited number of tool calls available. Exceeding this limit terminates your execution and discards all findings. Producing a complete result with partial investigation is always better than exhaustive investigation with no result.
Follow these rules to manage your budget:
1. Quick scan phase: Start with run_git(["diff", "--name-only"]) and run_git(["diff"]) for changed files only. Do not use run_git(["ls-files"]) or read unrelated files until you have assessed the diff.
2. Scope your investigation: Limit cross-file verification (caller tracing, exception handling checks) to at most 5 read_file calls beyond the changed files. If more files need checking, list the unverified files in your output instead of reading them.
3. Documentation-only changes: When the diff contains only documentation files (.md, .rst, .txt, .adoc), skip call-site verification entirely. Focus on content accuracy and structural issues.
4. Output priority: After your investigation, you must produce your structured output. Never spend your remaining budget on additional verification at the expense of producing a result.

## Severity Criteria
- Critical: Security vulnerabilities, data corruption, crashes in production paths.
- Important: Bugs causing incorrect behavior, missing error handling for likely failures.
- Suggestion: Readability improvements, minor optimizations, non-idiomatic patterns.
- Nitpick: Formatting, naming conventions, trivial style preferences.

## Scoring Guidelines
Set overall_score on a 0.0-10.0 scale:
- 9-10: No issues or only nitpicks. Production-ready.
- 7-8: Minor issues that do not block merge.
- 4-6: Significant issues requiring changes before merge.
- 0-3: Critical problems. Do not merge.

## Tool Usage
- run_git(args): Read git history and diffs. Allowed: diff, log, show, status, merge-base, rev-parse, branch, ls-files.
- run_gh(args): Read PR metadata. Allowed: pr view, pr diff, issue view, api (GET only).
- read_file(path): Read file contents for full context.
- list_directory(path, pattern=None): Discover project structure and related files.

## Output Format
- Set agent_name to "code-reviewer" in every ReviewIssue.
- Provide location (file_path + line_number) whenever possible.
- Write a concrete suggestion for each issue explaining how to fix it.
- Use category to classify: "bug", "security", "performance", "error-handling", "style".

## Confidence Filtering
Before reporting each finding, assign it an internal confidence score (0-100) representing how certain you are that it is a genuine, actionable issue.

### Confidence Scale
- 91-100: Confirmed bugs, verified security vulnerabilities, or clear rule violations found by reading the actual code.
- 76-90: Likely bugs or important best-practice violations supported by code evidence, but with some ambiguity in context.
- 51-75: Valid concerns that are context-dependent or low-impact; the code works but could be improved.
- 26-50: Stylistic preferences or patterns that are acceptable in context; likely not worth changing.
- 0-25: Speculative issues with no evidence from the code; probably false positives.

### Reporting Threshold
Only report findings with confidence >= 80. Silently discard anything below this threshold.
The confidence score is for your internal reasoning only — do not include it in the output.

## Self-Filtering Rules
- Do NOT report an issue if your own analysis concludes that no change is needed, the current code is acceptable as-is, or no action is required.
- Every reported issue must be actionable — it must clearly require a code change, documentation fix, or other concrete developer action.
- If you investigate a potential concern but determine it is acceptable in context, omit it entirely from your output.
- Before reporting any finding, confirm you have used read_file to read the relevant code and verified the issue exists. Do not report issues based on assumptions about code you have not read.
- Do not use uncertain language in suggestions: "should", "probably", "seems to", "might", "could potentially". State only confirmed facts. If you are not certain, do not report the finding.
- Do not report issues that only "might become a problem in the future" or "could cause issues at scale". Only report issues where the problem is present now and demonstrably affects the current code.

## Quality Principles
- Only report issues you are confident about. Omit uncertain findings.
- Be language-agnostic. Do not assume a specific programming language.
- Focus on substance over style. Prefer fewer high-quality findings over many trivial ones.
"""

[applicability]
always = true

Field List ¶

Field	Type	Required	Description
`name`	`str`	Yes	Agent name. Only lowercase letters, digits, and hyphens (`^[a-z0-9-]+$`)
`description`	`str`	Yes	Agent description
`model`	`str`	Yes	LLM model name to use
`output_schema`	`str`	Yes	Schema name registered in SCHEMA_REGISTRY
`system_prompt`	`str`	Yes	Agent’s system prompt
`allowed_tools`	`list[str]`	No	List of allowed tool categories. Default: empty
`phase`	`str`	No	Execution phase. Default: `"main"`
`max_turns`	`int \| None`	No	Agent-specific maximum turns. Default: `None` (uses global setting). Must be positive
`timeout`	`int \| None`	No	Agent-specific timeout in seconds. Default: `None` (uses global setting). Must be positive

[applicability] table:

Field	Type	Default	Description
`always`	`bool`	`false`	Always-applied flag
`file_patterns`	`list[str]`	`[]`	List of fnmatch patterns
`content_patterns`	`list[str]`	`[]`	List of regex patterns

When the [applicability] table is omitted, always = true is applied as the default.

Phase (Execution Phase)¶

Phases that control the execution order of agents. Agents are executed in phase order, and within the same phase, in alphabetical order by name.

Value	Execution Order	Description
`early`	0	Pre-processing phase
`main`	1	Main review phase
`final`	2	Post-processing phase

from hachimoku.agents import Phase, PHASE_ORDER

assert PHASE_ORDER[Phase.EARLY] < PHASE_ORDER[Phase.MAIN] < PHASE_ORDER[Phase.FINAL]

ApplicabilityRule ¶

Rules that determine whether an agent is applied to the review target.

Condition evaluation logic:

If always = true, always applied
If any file_patterns match the filename (basename), applied
If any content_patterns match the content, applied
If none of the above conditions are met, not applied

file_patterns and content_patterns have an OR relationship.

Built-in Agent Applicability ¶

Agent	Condition	Patterns
breaking-change-detector	content_patterns	`def\s+\w+\s\(`, `class\s+\w+`, `async\s+def\s+\w+`, `__all__\s=`, `app\.command`, `typer\.Option`, `typer\.Argument`, `BaseModel`, `\[tool\.`, `\[project\]`
code-reviewer	`always = true`	-
dependency-auditor	content_patterns	`\[dependencies\]`, `\[project\.dependencies\]`, `\[project\.optional-dependencies\]`, `\[tool\.uv`, `uv\.lock`, `requirements`, `\[build-system\]`, `"dependencies"\s:`, `"devDependencies"\s:`, `\[dependencies\.\w+\]`, `\[dev-dependencies\]`
silent-failure-hunter	content_patterns	`try\s:`, `except\s`, `catch\s\(`, `\.catch\s*\(`
pr-test-analyzer	file_patterns	`test_.py`, `_test.py`, `.test.ts`, `.test.js`, `.spec.ts`, `.spec.js`
type-design-analyzer	file_patterns + content_patterns	Files: `.py`, `.ts`, `.tsx` / Content: `class\s+\w+`, `interface\s+\w+`, `type\s+\w+\s=`
comment-analyzer	content_patterns	`"""`, `'''`, `/\\`, `//\sTODO`, `#\sTODO`
code-simplifier	`always = true`	-

LoadError ¶

Holds error information that occurs when loading agent definition files. Individual agent definitions that fail to load are skipped, and loading of other agents continues.

Field	Type	Constraint
`source`	`str`	Non-empty. Error origin (file path, etc.)
`message`	`str`	Non-empty. Error message

LoadResult ¶

The result of loading agent definitions. Holds successfully loaded definitions and skipped error information separately.

Field	Type	Constraint
`agents`	`tuple[AgentDefinition, ...]`	Successfully loaded agent definitions
`errors`	`tuple[LoadError, ...]`	Default empty tuple. Load error information

Loading Agents ¶

load_builtin_agents()¶

Loads built-in agent definitions included in the package.

from hachimoku.agents import load_builtin_agents

result = load_builtin_agents()

load_custom_agents(custom_dir)¶

Loads *.toml files in the specified directory as custom agent definitions. Returns an empty LoadResult if the directory does not exist.

from pathlib import Path
from hachimoku.agents import load_custom_agents

result = load_custom_agents(Path(".hachimoku/agents"))

load_agents(custom_dir=None)¶

Loads and merges built-in and custom agent definitions. When a custom definition has the same name as a built-in, the custom overrides the built-in.

from pathlib import Path
from hachimoku.agents import load_agents

# Built-in only
result = load_agents()

# Merged with custom
result = load_agents(custom_dir=Path(".hachimoku/agents"))

for agent in result.agents:
    print(f"{agent.name}: {agent.description}")

# Check load errors
for error in result.errors:
    print(f"Skipped {error.source}: {error.message}")

Creating Custom Agents ¶

Steps to add project-specific custom agents:

Create the .hachimoku/agents/ directory
Place agent definition files in TOML format

.hachimoku/agents/security-checker.toml¶

name = "security-checker"
description = "Detect security vulnerabilities"
model = "anthropic:claude-opus-4-7"
output_schema = "scored_issues"
allowed_tools = ["git_read", "gh_read", "file_read"]
system_prompt = """
You are security-checker, a security vulnerability specialist.
Analyze the code for injection, authentication, and data exposure issues.
"""

[applicability]
always = true

Specify a schema name registered in SCHEMA_REGISTRY for output_schema. Placing a file with the same name as a built-in overrides the built-in definition.