Coding Standards, Security, and Contributor Policy: Hook and Lifecycle Conventions

Overview

This section documents the hook rules that shape contributor workflow across the repository’s language-specific rule sets. The shared baseline defines when hooks run, how much automation is acceptable, and how TodoWrite is used to keep multi-step work visible and steerable.

The language-specific files then narrow that baseline into concrete post-edit and stop-time conventions: formatters, analyzers, build checks, and warnings that protect against risky edits such as debug prints, secret-bearing config changes, or oversized web edits. The result is a consistent contributor policy that still leaves room for each language’s normal tooling.

Shared Hook Lifecycle

The common rule set establishes the lifecycle that every other hook file extends:

• PreToolUse: runs before tool execution for validation and parameter modification.
• PostToolUse: runs after tool execution for auto-formatting and checks.
• Stop: runs when the session ends for final verification.

It also defines the permission model for automation:

• Enable auto-accept only for trusted, well-defined plans.
• Disable it for exploratory work.
• Never use the dangerously-skip-permissions flag.
• Configure allowedTools in ~/.claude.json instead.

TodoWrite is treated as a contributor control surface rather than a convenience feature. The common guidance uses it to track progress on multi-step tasks, verify instruction understanding, enable real-time steering, and expose mismatched task granularity, missing steps, unnecessary steps, or misread requirements.

Language-Specific Hook Rules

Contributor Policy by Lifecycle Stage

Before Tool Use

The shared baseline treats permissive automation as a controlled exception, not a default. The approved path is allowedTools, not dangerously-skip-permissions.

The hook system treats pre-tool behavior as a place for validation and parameter adjustment rather than output formatting. That keeps edits and automation bounded before any tool runs.

The only explicit trust boundary in the shared rules is the auto-accept policy. It is allowed only when the work is narrowly defined and trusted, and it is explicitly discouraged for exploratory changes.

After Tool Use

The post-tool stage is where the language-specific files do most of their work. Most rule sets use this point for formatting, linting, static analysis, and targeted compile checks, so the contributor sees issues immediately after a change rather than after a later manual review.

The web rules are stricter about local execution. They prefer the repository’s own formatter entrypoint after edits and reject oversized writes over 800 lines, which keeps hook-triggered changes inside a reviewable module size.

At Session Stop

The shared baseline reserves Stop for final verification. TypeScript adds a console.log audit here, and C# adds a final dotnet build. The C# rules also instruct the hook system to warn about edits to appsettings*.json, which ties the stop phase to secret hygiene.

Security and Review Guardrails

The hook files encode several concrete safety checks that contributors are expected to respect:

• rules/common/hooks.md forbids dangerously-skip-permissions and routes approved automation through allowedTools.
• rules/csharp/hooks.md warns on appsettings*.json edits to reduce secret leakage risk.
• rules/php/hooks.md warns on debug output helpers and on raw SQL or disabled CSRF and session protections.
• rules/python/hooks.md warns about print() in edited files and steers output to logging.
• rules/perl/hooks.md warns about print in non-script .pm files and prefers say or logging.
• rules/swift/hooks.md warns about print() and prefers os.Logger or structured logging.
• rules/typescript/hooks.md warns about console.log and audits it again at session stop.
• rules/web/hooks.md blocks writes that exceed 800 lines, which keeps file-level changes from becoming unreviewable.

These rules do not replace the language toolchains; they bind contributor behavior to specific checks so the edit loop stays fast, local, and auditable.

Hook File Reference