agent/codex/code/docs/hook-output-policy.md

Hook Output Policy

Consistent policy for what hook output to expose to Claude vs hide.

Principles

Always Expose

Category	Example	Reason
Test failures	FAIL: TestFoo	Must be fixed
Build errors	cannot find package	Blocks progress
Lint errors	undefined: foo	Code quality
Security alerts	HIGH vulnerability	Critical
Type errors	type mismatch	Must be fixed
Debug statements	dd() found	Must be removed
Uncommitted work	3 files unstaged	Might get lost
Coverage drops	84% → 79%	Quality regression

Always Hide

Category	Example	Reason
Pass confirmations	PASS: TestFoo	No action needed
Format success	Formatted 3 files	No action needed
Coverage stable	84% (unchanged)	No action needed
Timing info	(12.3s)	Noise
Progress bars	[=====> ]	Noise

Conditional

Category	Show When	Hide When
Warnings	First occurrence	Repeated
Suggestions	Actionable	Informational
Diffs	Small (<10 lines)	Large
Stack traces	Unique error	Repeated

Implementation

Use output-policy.sh helper functions:

source "$SCRIPT_DIR/output-policy.sh"

# Expose failures
expose_error "Build failed" "$error_details"
expose_warning "Debug statements found" "$locations"

# Hide success
hide_success

# Pass through unchanged
pass_through "$input"

Hook-Specific Policies

Hook	Expose	Hide
check-debug.sh	Debug statements found	Clean file
post-commit-check.sh	Uncommitted work	Clean working tree
check-coverage.sh	Coverage dropped	Coverage stable/improved
go-format.sh	(never)	Always silent
php-format.sh	(never)	Always silent

Aggregation

When multiple issues, aggregate intelligently:

Instead of:
- FAIL: TestA
- FAIL: TestB
- FAIL: TestC
- (47 more)

Show:
"50 tests failed. Top failures:
- TestA: nil pointer
- TestB: timeout
- TestC: assertion failed"