Skip to content

Policy & System Tools

Policy and system tools ensure governance compliance, validate paths for containerized environments, and check code against style guides.

Tools in This Category

Tool Description Tier
validate_paths Check path accessibility Community
verify_policy_integrity Verify policy files haven't been tampered with Pro
code_policy_check Check code against style guides Enterprise

validate_paths

Validate that paths are accessible before running file operations.

What It Does

validate_paths checks paths before operations:

  • Existence check: Does the path exist?
  • Permission check: Read/write access?
  • Docker awareness: Works in containerized environments
  • Suggestions: Alternative paths when not found

When AI Agents Use This

  • Before reading/writing files
  • In Docker deployments
  • When paths might not exist
  • Validating user-provided paths

Quick Reference

Property Value
Tier Community
Token Cost ~50-100 tokens

Parameters

Parameter Type Required Description
paths string[] ✓ List of paths to validate
project_root string Base directory for relative paths

Example Usage

Prompt:

"Check if src/main.py exists"

Tool Call: 

{
  "tool": "validate_paths",
  "parameters": {
    "paths": ["src/main.py"]
  }
}

Prompt:

"Verify all these configuration files exist"

Tool Call: 

{
  "tool": "validate_paths",
  "parameters": {
    "paths": [
      ".code-scalpel/config.json",
      ".code-scalpel/limits.toml",
      "pyproject.toml"
    ],
    "project_root": "/app"
  }
}

Response Format

{
  "data": {
    "results": [
      {
        "path": "src/main.py",
        "exists": true,
        "readable": true,
        "writable": true,
        "is_file": true,
        "is_directory": false
      },
      {
        "path": "src/missing.py",
        "exists": false,
        "suggestions": [
          "src/main.py",
          "src/module.py"
        ]
      }
    ],
    "all_valid": false,
    "valid_count": 1,
    "invalid_count": 1
  },
  "tier_applied": "community",
  "duration_ms": 12
}

Tier Differences

Feature Community Pro Enterprise
Available ✅ ✅ ✅
Existence check ✅ ✅ ✅
Permission check ✅ ✅ ✅
Path suggestions ✅ ✅ ✅
Bulk validation ✅ ✅ ✅

Full deep dive

verify_policy_integrity

Cryptographically verify that policy files haven't been tampered with.

What It Does

verify_policy_integrity ensures governance policies are authentic:

  • Signature verification: RSA cryptographic verification
  • Manifest validation: All required files present
  • Tamper detection: Any modifications detected
  • Audit trail: Verification timestamps

When AI Agents Use This

  • Before applying policies
  • Compliance audits
  • Security-sensitive operations
  • Verifying configuration integrity

Quick Reference

Property Value
Tier Pro
Token Cost ~50-100 tokens

Parameters

Parameter Type Required Description
policy_dir string Path to policy directory (default: .code-scalpel/)
manifest_source string "file" or "embedded" (default: "file")

Example Usage

Prompt:

"Verify our Code Scalpel policies haven't been tampered with"

Tool Call: 

{
  "tool": "verify_policy_integrity",
  "parameters": {}
}

Prompt:

"Check the policies in our custom config directory"

Tool Call: 

{
  "tool": "verify_policy_integrity",
  "parameters": {
    "policy_dir": "/app/custom-policies",
    "manifest_source": "file"
  }
}

Response Format

{
  "data": {
    "verified": true,
    "policy_dir": ".code-scalpel/",
    "files_checked": [
      {
        "file": "config.json",
        "status": "verified",
        "hash_match": true
      },
      {
        "file": "limits.toml",
        "status": "verified",
        "hash_match": true
      },
      {
        "file": "governance.yaml",
        "status": "verified",
        "hash_match": true
      }
    ],
    "manifest_valid": true,
    "signature_valid": true,
    "verification_timestamp": "2024-01-15T10:30:00Z"
  },
  "tier_applied": "pro",
  "duration_ms": 45
}

Verification States

Status Meaning
verified File matches expected hash
modified File exists but has been changed
missing Expected file not found
extra Unexpected file in policy directory

Tier Differences

Feature Community Pro Enterprise
Available — ✅ ✅
Hash verification — ✅ ✅
Signature verification — ✅ ✅
Custom manifests — — ✅
Audit logging — — ✅

Full deep dive

code_policy_check

Check code against style guides, best practices, and compliance standards.

What It Does

code_policy_check validates code against policies:

  • Style guides: PEP 8, Google, custom
  • Best practices: Design patterns, anti-patterns
  • Compliance: SOC 2, ISO 27001, HIPAA rules
  • Custom rules: Organization-specific policies

When AI Agents Use This

  • Code review automation
  • Compliance audits
  • Quality gates
  • Style enforcement

Quick Reference

Property Value
Tier Enterprise
Languages Python, JavaScript, TypeScript
Token Cost ~100-500 tokens

Parameters

Parameter Type Required Description
paths string[] ✓ Files or directories to check
rules string[] Specific rules to check
compliance_standards string[] Standards to verify (SOC2, ISO27001, etc.)
generate_report bool Generate detailed report (default: false)

Example Usage

Prompt:

"Check this file against our coding standards"

Tool Call: 

{
  "tool": "code_policy_check",
  "parameters": {
    "paths": ["src/api/handlers.py"]
  }
}

Prompt:

"Verify our codebase meets SOC 2 requirements"

Tool Call: 

{
  "tool": "code_policy_check",
  "parameters": {
    "paths": ["src/"],
    "compliance_standards": ["SOC2", "HIPAA"],
    "generate_report": true
  }
}

Prompt:

"Check for logging and error handling compliance"

Tool Call: 

{
  "tool": "code_policy_check",
  "parameters": {
    "paths": ["src/services/"],
    "rules": [
      "require-structured-logging",
      "no-bare-except",
      "require-error-codes"
    ]
  }
}

Response Format

{
  "data": {
    "passed": false,
    "violations": [
      {
        "file": "src/api/handlers.py",
        "line": 45,
        "rule": "no-bare-except",
        "severity": "error",
        "message": "Bare except clause found. Specify exception type.",
        "suggestion": "except Exception as e:"
      },
      {
        "file": "src/api/handlers.py",
        "line": 78,
        "rule": "require-structured-logging",
        "severity": "warning",
        "message": "Use structured logging instead of print()",
        "suggestion": "logger.info('message', extra={'key': 'value'})"
      }
    ],
    "summary": {
      "files_checked": 15,
      "total_violations": 12,
      "errors": 3,
      "warnings": 9,
      "passed_files": 8
    },
    "compliance_status": {
      "SOC2": {
        "passed": true,
        "controls_checked": 24,
        "controls_passed": 24
      },
      "HIPAA": {
        "passed": false,
        "controls_checked": 18,
        "controls_passed": 16,
        "failed_controls": ["audit-logging", "data-encryption"]
      }
    }
  },
  "tier_applied": "enterprise",
  "duration_ms": 1250
}

Built-in Rule Categories

Category Examples
Security no-hardcoded-secrets, require-input-validation
Logging require-structured-logging, no-print-statements
Error Handling no-bare-except, require-error-codes
Documentation require-docstrings, require-type-hints
Architecture max-function-length, max-file-size

Compliance Standards

Standard Description
SOC2 Security, availability, processing integrity
ISO27001 Information security management
HIPAA Healthcare data protection
PCI-DSS Payment card data security
GDPR Data privacy and protection

Tier Differences

Feature Community Pro Enterprise
Available — — ✅
Basic style rules — — ✅
Compliance standards — — ✅
Custom rules — — ✅
Report generation — — ✅
CI/CD integration — — ✅

Full deep dive

Common Workflows

Pre-Operation Validation

1. validate_paths(["src/module.py"])
   → Ensure file exists before reading

2. extract_code(file_path="src/module.py", ...)
   → Now safe to extract

Compliance Audit

1. verify_policy_integrity()
   → Ensure policies haven't been tampered with

2. code_policy_check(paths=["src/"], compliance_standards=["SOC2"])
   → Check code against verified policies

3. [Generate audit report]

Secure Deployment

1. validate_paths(config_files)
   → All configs present

2. verify_policy_integrity()
   → Policies authentic

3. code_policy_check(paths=["src/"], generate_report=true)
   → Full compliance report for deployment sign-off

Configuration Files

Policy tools use these configuration files in .code-scalpel/:

File Purpose
config.json General configuration
limits.toml Tier-based capability limits
governance.yaml Full governance policy set
policy.yaml OPA-based policy rules
architecture.toml Dependency rules

See Configuration Guide for details.