Why prompt rules (AGENTS.md) failed for my multitasking agent—and how I used PreToolUse/Stop lifecycle hooks + a tiny Go binary to enforce boundaries
retained text
For the past few months I've been running a single personal agent workspace (`agy-hq` on Google Antigravity) to handle both multi-repo software engineering and daily personal admin (calendar, inbox triage, notes, and investment research). At first, I tried enforcing every workflow boundary by writing stricter rules in `AGENTS.md`: - *"Keep the main chat thread responsive."* - *"Use a separate git worktree for each coding task."* - *"Update the task board after each turn."* - *"Always ask before sending external messages."* After a couple of weeks of real daily use—especially from my phone—a clear pattern emerged: **prompt instructions work on Turn 1, and silently decay by Turn 12.** Here are the 3 failure modes I kept hitting, and how moving state and boundary checks out of the prompt and into **lifecycle hooks (`SessionStart`, `PreToolUse`, `Stop`)** backed by a small zero-dependency Go binary fixed them. --- ### The 3 Failure Modes of Prompt-Only Rules 1. **The Main Thread Freezes on "Quick" Lookups:** You ask a quick question about a bug while walking to grab coffee. Instead of delegating to a background worker, the model runs 14 `grep` calls, edits two files, and kicks off `go test ./...` right inside your main conversation—locking up your intake thread for five minutes. 2. **Bookkeeping Noise and Stale State:** Asking the LLM to manually maintain `tasks.json` or a status markdown file burns tokens every turn, pollutes chat replies with bookkeeping chatter, and still drifts whenever a background subagent finishes out-of-band. 3. **Context Rot in `MEMORY.md`:** Append-only memory files quickly turn into a graveyard of stale sprint notes and contradicted facts that get injected into every new session. --- ### The Fix: Prompts as Advice, Lifecycle Hooks as Law Instead of writing longer `AGENTS.md` files, I built a tiny Go CLI (`./bin/hq`, pure Go stdlib, `0` external dependencies) wired into the agent runtime's lifecycle hooks (`hooks.json`): #### 1. A Non-Blocking "Front Desk" Enforced by `PreToolUse` Every `PreToolUse` event is piped over `stdin` into `./bin/hq hook pre-tool`. When the active `conversation_id` holds the main Front Desk lease (`local/memory/front_desk.json`): - Direct file edits (`write_file`, `edit_file`) and build/test commands (`go test`, `npm test`) are **hard-blocked** (`permissionDecision: "deny"`), returning a reason that instructs the model to dispatch a background subagent (`invoke_subagent`) or spawn a dedicated task thread in an isolated `git worktree` (`local/worktrees/<repo>-<task>/`). - Read-only inline lookups (`read_file`, `grep_search`) are **mechanically capped at 3 calls per turn** using a counter keyed by `(conversation_id, transcript_step_count)`. A 4th lookup is denied automatically so open-ended investigations have to run in the background. #### 2. 0-Token Ledger Sync on `Stop` The model is forbidden from manually editing `tasks.json` or the live status dashboard (`hq_console.md`). Instead, when a turn ends, the `Stop` hook runs `./bin/hq hook stop`, which: - Parses the ground-truth conversation transcript (`transcript.jsonl`) in pure Go (`0` LLM tokens), - Reconciles active subagents, worktrees, and armed cron triggers, and - Re-renders the pinned status dashboard automatically. #### 3. Two-Layer Git Boundary (`local/` Vault + Pre-Commit PII Gate) To keep the harness open-sourceable while storing personal data on disk: - The root repo contains only the Go CLI, skills, and hooks. - `local/` is git-ignored by the root repo and initialized as its **own separate private git repository** holding `USER.md`, `MEMORY.md`, notes, and active worktrees. - `./bin/hq ci pre-commit` scans staged root files against regex patterns (`local/` paths, emails, phone numbers, SSNs, local usernames, and personal domain names) so personal data can never leak into a public commit. #### 4. Hash-Locked 1-Tap Mobile Approvals (`propose` -> `ask_question` -> `approve`) For irreversible external actions (sending an email, posting a message, merging a PR), `./bin/hq propose` hashes the exact command payload (`sha256[:12]`) into a pending JSON file. The agent previews the full message in a Markdown blockquote and triggers a native 1-tap multiple-choice confirmation card on mobile, which verifies the `sha256` prefix before executing. --- ### 4 Takeaways for Building Long-Running Personal Agents 1. **Treat `AGENTS.md` as advice and lifecycle hooks as law:** If violating a workflow rule ruins your UX (like freezing your main chat thread or editing files in the root checkout instead of a worktree), enforce it in `PreToolUse`. 2. **Never spend LLM tokens on bookkeeping:** Let your `Stop` hook reconcile the transcript and update status artifacts deterministically in code. 3. **Keep `MEMORY.md` under 200 lines as a routing index:** Store detailed topic notes in `local/memory/topics/*.md` and use a scheduled nightly consolidation job to prune superseded facts and verify journal claims against the raw transcript. 4. **Test your `AGENTS.md` and `SKILL.md` files in `go test`:** Whenever a workflow bug happens, add a structural contract test so your prose instructions and CLI flags never drift apart (and share a single compiled binary across sandbox E2E tests via `sync.Once`, which cut our 18-test suite from `10.5s` to `1.8s`). How are you handling the boundary between prompt instructions and deterministic enforcement in your own agent harnesses?
document fetched 2026-11-12 00:19 · canonical https://reddit.com/r/AI_Agents/comments/1xtc5w3/why_prompt_rules_agentsmd_failed_for_my