← sources

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

source: reddit (reddit:AI_Agents)published 2026-11-11 08:05ingested 2026-11-12 02:37

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