Agent Deadline Setup — soft budget for subagents

sonnet status / install / upgrade / enable / disable / uninstall / purge project | global opt-in user-invoked

What it does

Claude Code has no wall-clock timeout for subagents, and maxTurns — when it fires — kills the agent outright and discards its final report. /brewtools:agent-deadline-setup installs two hooks that impose a soft budget instead: at 80% of the allotted minutes the agent gets one non-blocking “wrap up” directive; past 100% every tool outside a finalization set is denied, so the agent is forced to write its report rather than lose it.

Run the skill with no arguments and it reports status first — installed scopes, wired hooks, current config — before doing anything else. Every other mode in the canonical set (install, upgrade, enable, disable, uninstall, purge) states its plan, asks only what is still unknown, then delegates the actual file and settings work to the brewcode:hook-creator agent. The extras [project|global] and [minutes] come after the mode word.

The feature is opt-in. Installing the brewtools plugin does not turn this on — these hooks are not registered in brewtools/hooks/hooks.json. Nothing runs until you invoke this skill and confirm install.

When to use

Situation	Suggested invocation
Long autonomous subagent runs where a lost final report is costly	/brewtools:agent-deadline-setup install
Want the same budget everywhere on this machine	/brewtools:agent-deadline-setup install global 30
Pick up a new hook version after a brewtools update, same budget	/brewtools:agent-deadline-setup upgrade
Check what is currently installed without changing anything	/brewtools:agent-deadline-setup
Temporarily stop enforcing without removing files	/brewtools:agent-deadline-setup disable
Fully remove hooks, settings entries and config	/brewtools:agent-deadline-setup purge

Example

/brewtools:agent-deadline-setup install project 20

Expected flow: the skill prints the current status table, states the plan (“copy 2 hook files into .claude/hooks/, write .claude/agent-deadline.json with defaultMinutes: 20, merge 2 settings.json entries”), asks only for confirmation since scope and minutes are already given, then delegates to brewcode:hook-creator and re-prints the status table showing guard=yes cleanup=yes settings_refs=2 enabled=true.

Workflow

Technical details

Modes

Mode	Effect	Hook files	settings.json	Config	State
status (default, no args)	report only	—	—	—	—
install	wire + configure	copied	entries merged	written	—
upgrade	re-emit from the current plugin version, budget preserved	re-copied	entries re-merged	values preserved	kept
enable	resume enforcement	kept	kept	enabled: true	kept
disable	pause enforcement	kept	kept	enabled: false	kept
uninstall	unwire	deleted	entries stripped	kept	kept
purge	full wipe	deleted	entries stripped	deleted	deleted

Canonical order, shared by every -setup skill: status | install | upgrade | enable | disable | uninstall | purge. upgrade asks nothing — it reads defaultMinutes, byAgentType and hardStopRatio back out of the existing config and replays the install for that scope, so a plugin update finally reaches the project with the same budget. A disabled setup stays disabled; a scope with nothing installed is routed to install.

The two hooks

Hook	Event	Behavior
agent-deadline-guard.mjs	PreToolUse on .*	Tracks elapsed time per agent_id. At 80% of budget, adds a non-blocking additionalContext warning. Past 100%, denies every tool outside the advertised finalization set: Read, Write, Edit, MultiEdit, NotebookEdit, TodoWrite, TaskUpdate. Past hardStopRatio x budget, the allowance shrinks further to Write, Edit only, with deny reason AGENT DEADLINE HARD STOP.
agent-deadline-cleanup.mjs	SubagentStop	Deletes the finished agent’s state file.

Actually allowed past 100% is 3 tools wider than what’s advertised to the agent — TaskCreate, BashOutput, TaskOutput are permitted but not named in the directive. This is deliberate: naming BashOutput invites a poll loop, while an agent that genuinely needs to harvest an already-running job still gets through. AskUserQuestion is denied outright past the deadline — a subagent parked on a human answer is exactly the unbounded wall-clock time this guard exists to stop.

Installation targets

Scope	Hooks dir	settings.json	Config
Project	<repo>/.claude/hooks/	<repo>/.claude/settings.json	<repo>/.claude/agent-deadline.json
Global	~/.claude/hooks/	~/.claude/settings.json	~/.claude/agent-deadline.json

Project config wins over global; a malformed project config is skipped and global is used instead. Global writes go through Bash only — ~/.claude/* is a protected path, blocked for Write/Edit in every permission mode.

Config shape

{
  "enabled": true,
  "defaultMinutes": 20,
  "byAgentType": {},
  "hardStopRatio": 2,
  "version": "X.Y.Z",
  "generated_by": "brewtools:agent-deadline-setup",
  "last_updated": "YYYY-MM-DD"
}

Key	Meaning
enabled	must be exactly true; anything else turns enforcement off
defaultMinutes	budget applied to every agent type; default 20
byAgentType	per-type overrides, e.g. {"Explore": 10}; empty object = one uniform limit
hardStopRatio	optional, default 2, must be > 1 — multiple of the budget past which the allowance drops to Write, Edit only
version / generated_by / last_updated	stamped by install/upgrade; /brewcode:setup-status reads them to flag a stale install

Budget resolves as byAgentType[agent_type] ?? defaultMinutes, read fresh on every hook call.

Version and ownership

install/upgrade write agent-deadline.json’s version, generated_by: "brewtools:agent-deadline-setup" and last_updated at top level, alongside the behavior keys. agent-deadline-guard.mjs and agent-deadline-cleanup.mjs each carry a matching // brewcode-meta: version=X.Y.Z generated_by=brewtools:agent-deadline-setup comment on line 2. upgrade re-stamps all three, status surfaces a stale install by comparing them against the installed plugin version.

Related