feat(plugins): add the task.route pre-spawn hook

[bborn]

Why

Two Claude logins means a decision on every task: which account should this one spend? That decision was manual and uninformed, so one account got hammered into a 429 while the other sat idle.

This PR adds only the thing a plugin cannot do for itself: a moment, before the spawn, where something gets to choose. The policy and the usage data both live in the plugin — taskyou/plugins#1.

task.route

A new plugin hook, and the first one ty waits on. It fires before a task spawns and reads the script's stdout back as a decision:

CLAUDE_CONFIG_DIR=/Users/me/.claude-work
HOLD=1
REASON=every profile above 90%

Every other hook can only react to a task having run. A router has to answer before the command is built, so this one is synchronous, bounded at 15s, and first-answer-wins in plugin-name order.

Why it can't be a plugin-only feature. Plugins see four events, all dispatched from OnStatusChange — and the earliest, task.started, fires when execution begins, i.e. after the command is already built. (task.created exists but lives in internal/events, which drives only the legacy single-script hooks dir; plugins never receive it.) The workaround would be a service polling for queued tasks, but the daemon ticks every 2s and spawns immediately, and there's no per-task API for claude_config_dir — the HTTP API exposes it on projects only — so it would have to write SQLite directly, which docs/plugins.md explicitly warns against. Racy or wrong, either way.

How the decision is carried

Task.ClaudeConfigDir, which both command builders (daemon runClaude and the TUI's BuildCommand) have always honored. No second spawn path, and no new way for the daemon and TUI to disagree about which profile is in play — the failure mode this repo has hit before.

Session affinity comes for free, and is required. A routed task is stamped once and skipped on later passes, so a resume runs under the same profile. That isn't tidiness: a Claude session lives inside one config dir, and resuming elsewhere would find no session and quietly start a fresh conversation. The cost — a task pinned to a spent profile waits for that profile's reset rather than hopping — is the correct trade and is documented.

Routing is never a reason work doesn't happen. No router installed, a script that fails, times out, or prints nothing — every one of those spawns the task exactly as it would have before. An explicit config dir (set by hand, or by a workflow step's config_dir:) is never overruled. HOLD leaves a task queued, never blocked, so it starts by itself on a later tick; it's ignored for a manually started task, where silently refusing would read as a broken button. Repeated holds log once per distinct reason rather than once per daemon tick.

Scope

An earlier revision of this PR also carried the usage reader — a ty usage command backed by an internal/claudeusage package, ~1250 lines. That's been moved into the plugin, which reads the keychain and calls the endpoint itself. It never needed to be in core, and knowledge of someone else's endpoint is better placed where a change is a git pull rather than a ty release. What's left here is 900 lines, half of it tests.

The router in action (that plugin, driving this hook):

Testing

• internal/hooks — stdout parsing (quoting, noise, HOLD aliases, values containing =), name-order precedence, failing/timed-out/silent scripts, stderr not being parsed as a decision, nil task, cancelled context.
• internal/executor — apply-and-persist, explicit dir not overridden, resume affinity, non-Claude executors skipped, hold keeps a task queued, hold logged once across ticks, hold ignored on manual run, failing router still spawns, ~ expansion, empty executor treated as claude.
• Mutation-checked the load-bearing ones: removing the override guard and the hold-log memo each failed exactly the test that claims to cover it.
• golangci-lint run ./... clean (v2.8.0, matching CI); gofmt clean.
• Verified end-to-end against two real accounts via the plugin.

Merge order

This first, then taskyou/plugins#1. Until task.route exists the plugin loads and does nothing, since the event never fires.

🤖 Generated with Claude Code