| name | hook-persistence |
| description | Pull-based work assignment channel implementing GUPP (Get Up and Push Protocol). Manages single-active-work-item hooks per agent with filesystem persistence and atomic state transitions. |
| type | skill |
| category | state |
| status | stable |
| origin | tibsfox |
| modified | false |
| first_seen | "2026-03-06T00:00:00.000Z" |
| first_path | .claude/skills/hook-persistence/SKILL.md |
| superseded_by | null |
Hook Persistence
Filesystem-backed work assignment for multi-agent orchestration. Each agent has exactly one hook file that tracks its current work item. The hook enforces GUPP -- Get Up and Push Protocol -- meaning an agent with hooked work must execute it before accepting new assignments.
Purpose
Hook is the work assignment channel in the Gastown chipset -- the MMIO (Memory-Mapped I/O) equivalent. It is the mechanism by which the mayor dispatches work to agents and tracks assignment state. Unlike mail (which sends notifications about work) or nudge (which checks on work), the hook is the work itself -- the binding between an agent and a bead.
The hook is pull-based: the agent polls its hook file on startup and periodically thereafter. If the hook has a work item, the agent picks it up and begins execution. This pull model means agents self-schedule -- the mayor sets the hook, and the agent activates when ready.
Filesystem Contract
.chipset/state/hooks/{agent-id}.json
Each agent has exactly one hook file. The file contains the agent's current assignment state: empty (no work), pending (work assigned but not started), active (work in progress), or completed (work finished, awaiting retirement).
Example paths:
.chipset/state/hooks/polecat-alpha.json
.chipset/state/hooks/polecat-bravo.json
.chipset/state/hooks/refinery-f5g6h.json
Hook Format
{
"agent_id": "polecat-alpha",
"status": "active",
"work_item": {
"bead_id": "gt-abc12",
"title": "Add README section",
"assigned_at": "2026-03-05T10:30:00Z"
},
"last_activity":
