Skip to content

feat: delegation guidance as per-decision heuristic + escalating tool-cadence hook#52

Merged
arzafran merged 1 commit into
mainfrom
feat/44-delegation-heuristic
Jun 10, 2026
Merged

feat: delegation guidance as per-decision heuristic + escalating tool-cadence hook#52
arzafran merged 1 commit into
mainfrom
feat/44-delegation-heuristic

Conversation

@arzafran

Copy link
Copy Markdown
Member

What this does

The delegation reminder fired ~15 times in a single session and got reasoned past nearly every time — repetition without salience, which trains the agent to tune out all hooks. This reworks delegation from a repeated nag into one per-decision question the agent answers before each unit of work, backed by a hook that now fires at most twice per streak: one evidence-based nudge, then one escalation it can't easily skim past.

First (and scoping) PR for #44 — the delegation worked example from the Salience × Memeticity audit. Closes #44; if the same pass should run over the remaining rule set, that's a fresh issue once we've measured adherence on this one.

Summary

  • CLAUDE-FULL.md: MUST/SHOULD prose lists → one question (3+ files, 10+ calls, or security-sensitive?) with a routing table, an explicit NO branch, and loop-closing rules (re-ask when scope grows; overriding a YES requires a stated one-line reason)
  • src/hooks/tool-cadence.ts (parallelmax branch): now tracks distinct files edited as evidence; one soft nudge per streak (12 calls or 3+ files), then one escalation via PostToolUse block if the streak continues past the reminder — silent after that until an Agent call resets. Was: same paragraph every 12 calls, forever
  • config/40-hooks.json: continueOnBlock: true on tool-cadence so the escalation surfaces as a block signal without aborting the turn (already modeled in the zod schema)
  • src/hooks/delegation-detector.ts: message compressed to one line, consistent with the heuristic
  • docs/hooks-reference.md rows updated (also fixes the stale "N=8" threshold doc)

Test Plan

  • bun test — 515 pass, incl. new tests/tool-cadence.test.ts e2e suite (nudge-once, escalate-once-then-silent, 3-file trigger, Agent reset, old-shape state migration)
  • bun run typecheck / bun run lint / bun run compose
  • Measure adherence over a few live sessions before extending the pass to other rules

…alating hook

The delegation reminder fired ~15 times per session and was reasoned past
nearly every time — repetition without salience. Per the high-agency-strategy
lens (Salience x Memeticity):

- CLAUDE-FULL.md delegation block: MUST/SHOULD prose lists -> one per-decision
  question (3+ files / 10+ calls / security-sensitive?) with a routing table,
  an explicit NO branch, and loop-closing rules (re-ask on scope growth,
  one-line justification to override, no narration when delegating)
- tool-cadence parallelmax branch: tracks distinct files edited as evidence,
  fires ONE soft nudge per streak (count or 3+ files), then ONE escalation via
  PostToolUse block (continueOnBlock) if the streak continues past the
  reminder; silent after that until an Agent call resets the streak
- delegation-detector message compressed to a single high-salience line
- new tests/tool-cadence.test.ts e2e suite for the parallelmax branch
@arzafran arzafran merged commit 4c62aa5 into main Jun 10, 2026
15 checks passed
@arzafran arzafran deleted the feat/44-delegation-heuristic branch June 10, 2026 18:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Apply "high-agency strategy" (Salience × Memeticity) to agent-facing rules — start with the delegation-adherence gap

1 participant