[Feature]: Lifecycle Hooks — event-driven script execution on tool calls, prompts, and session events #2562
Description
1. Why Do You NEED This Feature?
I NEED this feature because:
- AGENTS.md is stateless and static — it can describe rules but cannot enforce them at runtime. There is no mechanism to intercept what the AI does, only to suggest what it should do.
- Real-world team workflows require runtime enforcement: block reads on sensitive files before they happen, not after; inject up-to-date context (current datetime, git branch, token budget) on every prompt, not just at
session starts from a static file; persist task progress across session compactions automatically. - Without event-driven hooks, every session-level automation must be done manually or worked around with increasingly bloated AGENTS.md files. This doesn't scale past a single developer.
- The gap between "AI should do X" (AGENTS.md) and "AI is guaranteed to do X" (hooks) is exactly where production reliability breaks down.
2. What Is NOT Possible Right Now?
Currently, I cannot:
- Block a tool call before it executes — e.g., prevent reading .env or credentials.json based on filename pattern. AGENTS.md can say "don't read secrets," but cannot enforce it.
- Inject dynamic runtime context per-prompt — current datetime, active git branch, live token usage, current task from a task list. AGENTS.md is loaded once at session start; it cannot reflect runtime state.
- React to tool results — after the AI edits a file, automatically trigger a code quality check or simplification reminder. There is no PostToolUse event.
- Persist state across forge compact — when context is compacted, all accumulated session state (active tasks, decisions made, plan progress) is lost. No hook fires on compaction to save and restore it.
- Conditionally load different rule sets based on what the AI is doing — e.g., load stricter rules only when writing to src/, looser rules in scripts/.
I've tried:
- Expanding AGENTS.md — becomes 500+ lines injected in full every session; no conditional loading; still cannot block tool calls
- Skills (SKILL.md) — invoked on demand when the AI judges them relevant; not event-driven; cannot fire automatically on PreToolUse or PostToolUse
3. What WILL Be Possible With This Feature?
With this feature, I will be able to:
- Guarantee sensitive file protection: a PreToolUse hook blocks any Read/Edit matching *.env, secret, credentials — the AI physically cannot read them without explicit user approval
- Inject live context automatically: every prompt gets current datetime, git branch, token usage, active task injected from a UserPromptSubmit hook — no staleness, no manual re-injection after compact
- Auto-persist session state: a Stop hook saves the current task list and plan progress; a SessionStart hook restores it — forge compact no longer loses work context
- Enforce post-edit quality gates: after every file write, a PostToolUse hook injects a reminder to check for complexity or duplication — consistently, without relying on the AI to remember
- Conditionally apply rules at runtime: hooks can inspect FORGE_FILE_PATH and inject stricter rules only when operating on production-critical paths
Proposed Solution (User Experience)
Proposed Solution (User Experience)
- User creates scripts in ~/.forge/hooks/ (global) or .forge/hooks/ (project-level)
- Registers hooks in settings.json under event type + optional tool matcher (regex)
- PreToolUse: hook stdout injected as context; non-zero exit blocks the tool call, stderr shown to AI as reason
- PostToolUse / UserPromptSubmit / SessionStart / Stop: stdout appended to system context
- Hook scripts receive env vars: FORGE_EVENT, FORGE_TOOL_NAME, FORGE_FILE_PATH, FORGE_CWD, FORGE_SESSION_ID
- :hooks command lists all registered hooks and their last execution status
Alternatives Considered
Alternatives Considered
- AGENTS.md expansion — static, no blocking capability, context bloat scales with rules
- SKILL.md — on-demand invocation only; cannot auto-fire on tool lifecycle events; no blocking
Use Cases
- Security: PreToolUse(Read) hook blocks files matching sensitive patterns — requires explicit APPROVED: prefix before AI can proceed
- Context freshness: UserPromptSubmit hook injects live datetime, git status, token budget — context is always current, not stale from session-start load
- Reliability: Stop/SessionStart hooks persist and restore session state — forge compact becomes safe for long-running tasks
- Quality gates: PostToolUse(Edit|Write) hook fires code review checklist — consistent enforcement regardless of AI judgment
Feature Category
Code Generation/Editing
Priority/Impact
High - Would significantly improve my workflow
Examples from Other Tools
Examples from Other Tools
- Git hooks (pre-commit, post-merge): scripts that fire on VCS lifecycle events — same mental model
- Webpack/Vite plugins (buildStart, transform, buildEnd): event-driven middleware pipeline
- Express.js middleware: intercept request/response lifecycle with composable handlers
Implementation Ideas
No response
Contribution
- I'm willing to submit a PR to implement this feature
- I can help with testing
- I can help with documentation
Additional Context
No response
✅ Pre-submission Checklist
- I have clearly explained WHY I need this feature (not just that it would be nice)
- I have described what is NOT currently possible in detail
- I have explained what WILL be possible with concrete examples
- I have provided specific use cases and workflows
- I have searched existing issues to avoid duplicates