Agent Deadline — soft budget for subagents

sonnet install / configure / remove project | global opt-in

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 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 (install, disable, enable, 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 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 install
Want the same budget everywhere on this machine	/brewtools:agent-deadline install global 30
Check what is currently installed without changing anything	/brewtools:agent-deadline
Temporarily stop enforcing without removing files	/brewtools:agent-deadline disable
Fully remove hooks, settings entries and config	/brewtools:agent-deadline purge

Example

/brewtools:agent-deadline 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

Технические детали

Modes

Mode	Effect	Hook files	settings.json	Config	State
status (default, no args)	report only	—	—	—	—
install	wire + configure	copied	entries merged	written	—
disable	pause enforcement	kept	kept	enabled: false	kept
enable	resume enforcement	kept	kept	enabled: true	kept
uninstall	unwire	deleted	entries stripped	kept	kept
purge	full wipe	deleted	entries stripped	deleted	deleted

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
}

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

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

Связанное