Feature Request: Add Hooks for Git Workflow Automation (`PreCommit`, `PostCommit`)

Feature Request: Add Hooks for Git Workflow Automation (PreCommit, PostCommit)

Labels: enhancement, feature-request, hooks, git

Is your feature request related to a problem? Please describe.

The current hooks system in Cloud Code is incredibly powerful for automating tasks based on tool usage (e.g., PreToolUse, PostToolUse). As outlined in the "Best practices for agentic coding" documentation, Cloud Code is already proficient at handling many git operations, including writing commit messages and creating commits.

However, there is no direct way to deterministically trigger actions immediately before or after a git commit operation. The current workaround is to use a PostToolUse hook with a matcher for Bash(git commit:*). This is suboptimal because:

1. It cannot block a commit that fails a pre-check (e.g., a lint error or invalid commit message format).
2. It runs after the commit command has been attempted, making it difficult to inject information (like a Co-authored-by: tag) or perform validation beforehand.
3. Parsing the command to extract commit details within the hook script is complex and brittle.

Describe the solution you'd like

I propose introducing two new hook events to the Cloud Code hooks system, specifically for the git commit lifecycle:

1. PreCommit Hook: This hook would trigger before Cloud Code executes a git commit command.

1. PostCommit Hook: This hook would trigger after a git commit command has been executed successfully.

Use Cases for a PreCommit Hook

A PreCommit hook runs before the commit is finalized, giving it the power to validate, modify, or even block the commit.

1. Automated Code Quality Checks:

• Linting & Formatting: Automatically run a linter (like ESLint) or a formatter (like Prettier or Black) on all staged files. If the tools make changes, the hook can re-stage them. If there are linting errors that cannot be auto-fixed, the hook blocks the commit and instructs the agent to fix them.
• Running Unit Tests: Execute a quick subset of relevant unit tests based on the changed files. If any tests fail, the commit is blocked, preventing broken code from entering the repository history.

1. Commit Message Validation & Enhancement:

• Enforce Conventional Commits: Check if the commit message adheres to the Conventional Commits specification (e.g., feat:, fix:, chore:). If not, the hook blocks the commit with a helpful error message.
• Automatic Ticket Association: Scan the current branch name (e.g., feature/PROJ-123-new-login-flow) and automatically prepend PROJ-123: to the commit message if it's missing.
• Add Co-author Information: Automatically append the Co-authored-by: Claude <claude@anthropic.com> trailer to the commit message, ensuring the AI's contribution is properly attributed.

1. Security and Compliance:

• Secret Scanning: Run a quick scan on staged changes to detect accidentally included API keys, passwords, or other secrets. The hook would block the commit immediately if a potential secret is found.
• Check for TODOs or FIXMEs: Prevent commits that contain temporary comments like TODO or FIXME in the code, ensuring that unfinished work isn't committed by mistake.

Use Cases for a PostCommit Hook

A PostCommit hook runs after the commit has been successfully created, making it ideal for automation, notification, and synchronization tasks.

1. Workflow Automation:

• Automatic git push: For simple workflows, the hook can automatically push the new commit to its remote branch, saving the developer a step.
• Trigger Local Builds: Kick off a local build process or run a script to update a development server with the newly committed code.
• Clean Up Branches: After a commit is merged into main, a hook could automatically delete the local feature branch.

1. Synchronization with External Systems:

• Update Project Management Tickets: Use the commit hash and message to automatically add a comment to a corresponding Jira, Asana, or Linear ticket. (e.g., "Commit a1b2c3d pushed for this issue.")
• Log Work: Create an entry in a time-tracking or work-logging system based on the commit details.

1. Team Communication and Notifications:

• Slack/Discord Notifications: Post a message to a team channel announcing the new commit, including the author, message, and a link to view the changes.
• Update Documentation Status: If a commit touches documentation files, the hook could trigger a process that flags the documentation for review or deployment.

1. Changelog and Versioning:

• Automated Changelog Generation: Append a formatted line item to a local CHANGELOG.md file based on the commit message's type (e.g., adding to "Features" or "Bug Fixes").
• Tagging Releases: If a commit message indicates a release, the hook could automatically create a new Git tag.

Describe alternatives you've considered

As mentioned, the primary alternative is using a PostToolUse hook that matches on Bash commands for git commit. This is a coarse and indirect mechanism. It does not provide the fine-grained control needed for robust pre-commit validation or reliable post-commit actions that depend on the commit's success and details (like the resulting SHA).

Additional context

This feature would significantly enhance Cloud Code's capabilities as an agentic partner in a developer's daily workflow, making git interactions even more seamless and automated.

To facilitate implementation, the hooks could receive context via stdin as a JSON payload, similar to existing hooks.

Proposed PreCommit stdin payload:

{
  "session_id": "abc123...",
  "hook_event_name": "PreCommit",
  "cwd": "/path/to/project",
  "commit_message": "feat: implement new login flow\n\nThis commit adds the UI and logic for the new user authentication screen.",
  "diff_summary": "..." // Summary of staged changes
}

Proposed PostCommit stdin payload:

{
  "session_id": "abc123...",
  "hook_event_name": "PostCommit",
  "cwd": "/path/to/project",
  "commit_hash": "a1b2c3d4e5f6...",
  "commit_message": "feat: implement new login flow..."
}

This feature aligns perfectly with the workflows described in the documentation, such as "Explore, plan, code, commit" and "Use Claude to interact with git." It would be a powerful addition for individual developers and for teams wanting to enforce conventions automatically.

Hook Output and Behavior

Following the pattern of existing hooks, the PreCommit hook could use its exit code or a JSON output to control the commit operation:

• Exit Code 0: The commit is allowed to proceed.
• Exit Code 2 (or other non-zero): The commit is blocked. The hook's stderr would be fed back to Claude as a prompt to fix the identified issue (e.g., "Commit message does not follow conventional commit format," or "Linting errors found in staged files.").
• JSON Output: The hook could return a JSON object like {"decision": "block", "reason": "..."} for more granular control, consistent with other hooks like UserPromptSubmit.

Thank you for considering this enhancement