agent-traffic-control

Search prior-session JSONL transcripts across worktree-namespaced project directories under `~/.claude/projects/`. Use when: (1) the user asks "find a previous session about X" or "remind me when we discussed Y" for a project that uses git worktrees, (2) you grep the canonical `~/.claude/projects/<project-dir>/*.jsonl` and the matching session isn't there, (3) you need to enumerate every conversation that touched a project regardless of which worktree it ran from. Claude Code stores each git worktree's session JSONLs under a separately-namespaced project directory (`<project-name>--claude-worktrees-<worktree-name>/`), not under the canonical `<project-name>/` directory. Searching only the canonical dir silently misses sessions run from worktrees — even though the user experienced them as "in the same project". Sister to the `git-worktree` skill family at the Claude-Code-state layer.

Code-review subagents are frequently provisioned WITHOUT a Bash tool, so they cannot run `gh pr diff`, `git diff`, or `git checkout` — and when you prompt them to "review PR #N, fetch the diff with gh pr diff" they return a BLOCKED report (no review performed), not findings. Use when: (1) dispatching feature-dev:code-reviewer / voltagent-* / Explore agents to review GitHub PRs or branches; (2) a review agent returns "I have no shell/gh/git tool" or "the PR sources are not in the working tree" or reviews `main` (which predates the PR) instead of the PR; (3) one reviewer in a parallel panel comes back BLOCKED while siblings succeeded. Fix: pre-generate per-base diffs to files + point the agent at materialized worktree paths, don't tell it to run gh/git.

A second Claude Code session (or agent/person) sharing the same working directory runs `git checkout`/`git switch`, flipping the branch for the whole working tree underneath your session and clobbering your uncommitted work. Use when: (1) a file you just edited has silently reverted — often with a "file was modified, either by the user or by a linter" system reminder, (2) `git branch --show-current` shows a branch you didn't switch to, (3) `git reflog` shows a `checkout: moving from X to Y` you never ran, (4) unfamiliar files/changes appear in `git status`. Covers detecting the collision and recovering via an isolated git worktree.

Recover gracefully when an Anthropic credit/billing failure stalls multiple in-flight parallel subagents mid-orchestration, then later resolves. Use when: (1) you've dispatched 2+ parallel subagents (Task tool with `run_in_background: true`) and a credit/billing issue, MCP outage, or other transient harness failure has frozen them, (2) the user reports the issue is now resolved and asks you to continue, (3) you're about to relaunch "resume" agents to pick up where stalled originals left off. Defends against the silent-revive trap: when API access is restored, ORIGINAL stalled subagents can auto-resume from where they froze and continue working IN PARALLEL with any "resume" agents you dispatch — leading to two agents racing on the same branch / PR / files, duplicate review comments, or one agent overwriting the other's work. Captures the diagnostic recipe (JSONL mtime + worktree-state inspection, NOT just agent status) and the safe resume pattern (state-aware briefs that detect current state and pivot to value-add if originals already recovered). Sister skill to `subagent-reports-complete-but-pr-unmerged` (different gap: completed status vs unmerged PR) and `anthropic-credit-balance-error-vs-app-bug` (different layer: diagnosing fake vs real credit errors, not recovering from real ones).

Pass design specs, handoff prompts, or any other shared artefact between two parallel Claude Code sessions that are working in different git worktrees on different branches — without merging the producing branch to main first. Use when: (1) session A produced design docs / a handoff prompt / a mockup file on branch X, (2) session B (different cwd / different worktree, on branch Y branched from main) reports "the file doesn't exist" or "I can't find the design spec you mentioned", (3) you want B unblocked NOW without a PR review cycle, (4) both worktrees are local checkouts of the same repo (share `.git`). The unblock: `git checkout <producing-branch> -- <paths>` from inside B's worktree pulls the files in as staged additions, no merge needed. Also covers the related gitignore-exception trick when the artefact files are blanket-ignored (e.g., `*.html` in a repo that produces HTML deliverables but also keeps design mockups under `docs/`). v1.1.0 (2026-05-26) adds the diagnostic-search variant: when the user says "execute <path/to/file>" but the file isn't in your worktree, use `git log --all --oneline --diff-filter=A -- "<path>"` + `git branch -a --contains <sha>` to find which branch holds it, then `git show <branch>:<path>` for read-only access without modifying your tree.