# Stop Hook Design

**Date:** 2026-02-21
**Scope:** Project-level Claude Code hooks for Gravl

## Goal

Prevent Claude from stopping mid-session without completing its work. Two enforced conditions:

1. No uncommitted changes to tracked files
2. No unresolved conversational TODOs or promises

## Approach

Two parallel hooks registered in `.claude/settings.json` under the `Stop` event. Both run every time Claude considers stopping.

## Hook 1 — Git Clean Check (command)

**File:** `.claude/hooks/git-clean-check.sh`

Uses `git diff --name-only HEAD` to detect modified tracked files that were not committed. Untracked files (e.g. `frontend/dist/`, planning docs) are intentionally ignored to avoid false positives.

- Exit 2 + JSON to stderr → blocks Claude from stopping, feeds reason back
- Exit 0 + JSON to stdout → approves

## Hook 2 — Conversation TODO Check (prompt)

A prompt hook that reads the conversation transcript and looks for unresolved work: phrases like "I'll fix X later", "TODO:", "we should also…", or any task Claude mentioned but did not complete. Returns `approve` or `block` with a list of unresolved items.

## File Layout

```
.claude/
  settings.json           # Hook registration
  hooks/
    git-clean-check.sh    # Git dirty state check
```

## Decisions

- **Modified tracked files only (not untracked):** `frontend/dist/` and `.planning/` untracked files would cause constant false positives with a full `git status --porcelain` check.
- **Prompt hook for TODOs (not grep):** The goal is conversational promises, not code comments. A prompt hook reads the transcript and can reason about intent.
- **Project-level, not plugin:** These checks are specific to Gravl's GSD commit workflow; no plugin abstraction needed.