feat: add Stop hook example policy (closes #40)

[adarshtiwari908]

New file: examples/policies-stop.js

Demonstrates intercepting the Stop event to:

• Block the stop if there are uncommitted git changes

• Allow the stop and log a task-completion summary otherwise

Both code paths have inline comments explaining why each decision is made.

Description

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation

Checklist

• npm run lint passes
• npx tsc --noEmit passes
• npm run test:run passes
• npm run build succeeds

Summary by CodeRabbit

• Examples
  • Added a new Stop event policy hook example that validates the working tree state before allowing stop operations, checking for uncommitted changes with graceful error handling.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new example policy hook, examples/policies-stop.js, that gates agent termination based on git status cleanliness. The hook denies stops if uncommitted changes are detected, logs session completion when the working tree is clean, and degrades gracefully if git is unavailable or the repo is not initialized.

Changes

Stop Event Policy Example

Layer / File(s)	Summary
Stop event policy hook with git validation and logging examples/policies-stop.js	Complete example that registers a custom policy for the Stop event, validating git status before allowing termination and logging session data on clean stops.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related issues

• feat: add example for Stop hook — task completes and stop is actually enforced #40: Directly related; both implement the same Stop event policy hook example with git status validation and session logging functionality.

Poem

🐇 A gentle gate before the exit door,
checks if the garden's tidy, nothing more—
git status clean? then log and let it go,
with grace when tools are missing down below. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	PR description includes file overview and intent, but the provided checklist items are not marked as completed, leaving verification status unclear.	Mark the checklist items (lint, tsc, test, build) as completed to confirm all required checks have passed before merge.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a Stop hook example policy that addresses issue #40.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

examples/policies-stop.js (1)

27-27: 💤 Low value

Remove unnecessary async keyword.

The function body uses only synchronous operations (execSync, appendFileSync) and never awaits. Declaring the function as async is misleading.

♻️ Simplify function signature

-  fn: async (ctx) => {
+  fn: (ctx) => {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/policies-stop.js` at line 27, The policy handler "fn" is declared
async but contains only synchronous calls (execSync, appendFileSync) and never
awaits; remove the unnecessary async keyword from the "fn" function declaration
(change "fn: async (ctx) => { ... }" to "fn: (ctx) => { ... }") to avoid
misleading callers and potential unneeded Promise wrapping, and confirm there
are no await usages inside the function before committing the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/policies-stop.js`:
- Line 27: The policy handler "fn" is declared async but contains only
synchronous calls (execSync, appendFileSync) and never awaits; remove the
unnecessary async keyword from the "fn" function declaration (change "fn: async
(ctx) => { ... }" to "fn: (ctx) => { ... }") to avoid misleading callers and
potential unneeded Promise wrapping, and confirm there are no await usages
inside the function before committing the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a496c0b5-8ecc-4b4e-a280-86122e50a921

📥 Commits

Reviewing files that changed from the base of the PR and between 1a37c48 and 41d7dc3.

📒 Files selected for processing (1)

• examples/policies-stop.js

[adarshtiwari908]

Hey @NiveditJain 👋

I've raised a PR for this: 409

It adds examples/policies-stop.js covering all four acceptance criteria:

✅ Runnable with failproofai p -i -c
✅ Both "block the stop" (uncommitted changes → deny()) and "let it stop" (clean tree → allow()) paths
✅ Inline comments explain why, not just what
✅ Comment header includes install + test usage snippets
please review and merge if all looks good. thanks!