How the quality-pack hook automatically generates PR evidence in claude-code-harness

The quality-pack hook is a post-tool-use hook that executes immediately after Claude finishes a write-or-edit operation, automatically collecting machine-readable evidence of code quality checks and injecting formatted verification data into the Pull Request description.

The claude-code-harness repository provides a framework for automating code review workflows around Claude Code interactions. The quality-pack hook serves as an automated quality gate that runs without manual intervention, ensuring every file modification is accompanied by concrete evidence of formatting, type-checking, and linting results. This article examines the hook's registration mechanism, execution pipeline, and evidence generation process based on the actual source code implementation.

Hook Registration and Activation

The quality-pack hook is registered in hooks/hooks.json at approximately line 456:

{
  "name": "quality-pack",
  "command": "/bin/bash -c '… exec \"$root/bin/harness\" \"$@\"' _ hook quality-pack"
}

When the harness framework detects a write or edit operation has completed, it checks for the quality-pack hook name and launches the corresponding handler using this command template. The hook receives the operation context and file path information through standard input as a JSON payload.

Execution Path: From Shell to Go

The codebase maintains dual implementations for backwards compatibility:

• Shell implementation: scripts/posttooluse-quality-pack.sh provides the original Bash-based handler
• Go implementation: go/internal/hookhandler/posttooluse_quality_pack.go contains the native handler function hookhandler.HandlePostToolUseQualityPack

The Go version serves as the current default execution path, offering improved performance and error handling compared to the shell script. Both implementations follow the same operational logic, though the Go handler provides more robust parsing of the stdin JSON payload.

The Evidence Collection Pipeline

The handler executes a six-stage pipeline to generate PR evidence:

Configuration Loading

The hook reads the quality_pack section from .claude-code-harness.config.yaml at the project root. Default values enable all checks: prettier: true, tsc: true, and console_log: true.

File Identification and Filtering

The handler receives the edited file path via stdin in a JSON payload structure. It applies file-type filtering to restrict processing to TypeScript and JavaScript files (*.ts, *.tsx, *.js, *.jsx). Files matching other extensions bypass the quality checks entirely.

Quality Tool Execution

When mode: run is configured (the default), the hook executes three verification tools sequentially:

• Prettier: Runs ./node_modules/.bin/prettier --write <file> to auto-format the modified file. If the binary is missing, the hook emits a recommendation message instead of failing.
• TypeScript Compiler: Executes ./node_modules/.bin/tsc --noEmit <file> to surface type errors without emitting build artifacts. Error output is captured and parsed into evidence lines.
• Console Log Detector: Scans file content for console.log statements or similar debug prints, generating warnings when found.

If mode: warn is configured, the hook skips automatic formatting and only suggests commands for manual execution.

Feedback Aggregation

Each tool contributes a formatted status string to a feedback block:

🧹 Prettier: 修正済み
🧪 tsc: 0 エラー
⚠ console.log が残っています

Evidence Artifact Generation

The concatenated feedback block is written to ./.evidence-replay/<sha>.txt within the working directory. This artifact serves as the canonical evidence record for the specific file modification.

PR Integration

The harness framework injects the evidence file content into the PR description under the "PR evidence" section. The data is simultaneously stored in the JSON response fields confidence_evidence and recommendation_evidence, making it available for template rendering in templates/html/plan-brief.html.template and templates/html/accept.html.template.

Configurable Behavior

Users customize the hook behavior through the quality_pack configuration section:

quality_pack:
  enabled: true          # Master switch

  mode: warn             # "warn" suggests fixes, "run" applies them

  prettier: true
  tsc: true
  console_log: true
  exclude_paths:
    - "**/generated/**"

The exclude_paths array supports glob patterns to skip generated files or specific directories. When a file matches an exclusion pattern, the hook terminates early without producing evidence output.

Example Evidence Output

Running a write operation on src/app.ts with default configuration produces the following markdown block in the PR:

### PR evidence (quality‑pack)

* 🧹 Prettier: 修正済み
* 🧪 tsc: 0 エラー

In warn mode with console_log: false, the output changes to:

### PR evidence (quality‑pack)

* 🧹 Prettier: 推奨（例: npx prettier --write "src/app.ts"）
* 🧪 tsc: 0 エラー

Summary

• The quality-pack hook triggers automatically after every write/edit operation via registration in hooks/hooks.json
• The current implementation resides in go/internal/hookhandler/posttooluse_quality_pack.go, though a shell fallback exists at scripts/posttooluse-quality-pack.sh
• It processes only TypeScript/JavaScript files, running Prettier, tsc --noEmit, and console-log detection when enabled
• Evidence is written to ./.evidence-replay/<sha>.txt and injected into the PR description and HTML templates
• Configuration through .claude-code-harness.config.yaml supports warn vs run modes and path exclusions

Frequently Asked Questions

What triggers the quality-pack hook to run?

The hook executes as a post-tool-use callback immediately after Claude Code completes any write or edit operation. The harness framework checks hooks/hooks.json for the quality-pack entry and invokes the handler automatically without requiring manual user action.

Can I disable specific checks like Prettier or TypeScript compilation?

Yes. Set the specific tool key to false in .claude-code-harness.config.yaml under the quality_pack section. For example, setting prettier: false skips formatting while retaining tsc and console_log checks. Setting enabled: false disables the entire hook.

Where is the PR evidence stored before being injected into the description?

The evidence is temporarily stored in ./.evidence-replay/<sha>.txt within the working directory, where <sha> represents a hash of the file operation. This artifact is read by the harness framework and incorporated into both the PR description markdown and the JSON response fields consumed by HTML templates.

Does the hook work with languages other than JavaScript/TypeScript?

No. The quality-pack hook specifically filters for *.ts, *.tsx, *.js, and *.jsx extensions. Files written in other languages bypass the heavy checks (Prettier, tsc) and do not generate evidence blocks, though they still trigger the hook execution which exits silently for unsupported file types.

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