agent-hooks

name

agent-hooks

description

Four lifecycle hooks every agent runs: on-session-start scans LESSONS-LEARNED.md, resumes checkpoints; on-pre-delegate verifies tracker issues, file partitions; on-post-delegate runs fast-review, CI checks; on-session-end executes session guard, writes logs. Use when starting a new session, running pre-flight checks before delegation, coordinating between agents, reviewing a completed handoff, or wrapping up a session. Trigger terms: multi-agent setup, delegate tasks, agent coordination, session management, run pre-flight checks, start a new session, coordinate between agents, wrap up session

Agent Lifecycle Hooks

Conventions (not auto-triggers) agents execute at specific lifecycle points. Team Lead includes hook reminders in delegation prompts; specialists follow them in their own workflow.

on-session-start → [work loop] → on-session-end
                        ↓   ↑
               on-pre-delegate → on-post-delegate

---

on-session-start

#	Action
1	rg -n "keyword" .opencastle/LESSONS-LEARNED.md
2	cat .opencastle/SESSION-CHECKPOINT.md (resume if exists)
3	rg -n "ERROR|FAIL" .opencastle/AGENT-FAILURES.md || true
4	cat .opencastle/agents/skill-matrix.json | jq '.bindings' — load domain skills

See HOOKS-REFERENCE.md for extended startup checks (approval polling, skill-matrix verification).

---

on-session-end

⛔ HARD GATE — See logging-mandatory. Load observability-logging for the Pre-Response Quality Gate.

#	Action
1	opencastle doctor --fix (session guard)
2	opencastle log --type session ...
3	Write .opencastle/SESSION-CHECKPOINT.md if work is incomplete
4	Flag for memory merge if 5+ new lessons

---

on-pre-delegate — Team Lead only

#	Check
1	Tracker issue exists (gh issue view TAS-XX)
2	File partition clean (comm -12 <(sort agent1-files) <(sort agent2-files) = empty)
3	Upstream deps Done (gh issue view TAS-XX --json state -q '.state' = CLOSED)
4	Prompt has exact file paths + acceptance criteria
5	Prompt includes "Read LESSONS-LEARNED.md first"
6	5+ files → load context-map skill

All 6 must pass before runSubagent. See HOOKS-REFERENCE.md for example commands per check.

on-post-delegate — Team Lead only

#	Action
1	⛔ opencastle log --type=delegation --issue=TAS-XX --status=complete
2	Run fast-review skill
3	pnpm lint && pnpm typecheck && pnpm test
4	gh issue view TAS-XX --json body -q '.body' — verify each AC met
5	If agent retried → verify lesson added via self-improvement
6	Move to Done or re-delegate; 3rd failure → .opencastle/AGENT-FAILURES.md

See HOOKS-REFERENCE.md for detailed verification commands.

---

Anti-Patterns

Anti-pattern	Impact
Batch-logging retrospectively	Loses per-task provenance
Partial post-delegate checks	False positives — build passes but ACs fail