feat: [ENG-2859] background sub-agent dispatch for brv curate (#753)
* feat: [ENG-2859] background sub-agent dispatch for brv curate
Adds a saved `brv-curate` sub-agent that runs `brv curate` sessions
detached from the calling conversation, so substantive curates (10-60s
each) stop blocking the user's prompt. Two surface-specific definitions
ship under src/server/templates/agent/:
brv-curate.md — Claude Code: permissionMode: bypassPermissions,
tools: Bash/Read/Write/Edit/Grep/Glob,
background: true, model: inherit
brv-curate.toml — Codex: sandbox_mode = "workspace-write",
developer_instructions carrying the full body
Both carry the same operational protocol — per-fact session loop, /tmp
envelope file via --response-file, path-exists merge, retry cap, return
shape. The /tmp pin is load-bearing: background sub-agents have
permission prompts auto-denied (Claude) or are sandbox-gated (Codex),
and only the writable sandbox area (/tmp) is pre-authorized.
Skill docs updated to make dispatch the DEFAULT for substantive curates
(not opt-in):
curate.md `## Background Execution` — dispatch shape per surface +
saved-agent file walkthroughs + deployment table
SKILL.md `## Curate Dispatch` — decision table (1 / 2-5 / 6+ facts)
right after the Iron Law, so the calling agent routes
correctly without opening curate.md first
SkillConnector deploys the sub-agent file automatically on
`brv connectors install`:
Claude Code → .claude/agents/brv-curate.md
Codex → .codex/agents/brv-curate.toml
Other surfaces (Cursor, Windsurf, etc.) leave the agents dir untouched.
Mechanism: optional `agentFile: {source, target}` on SkillConnectorConfig,
set only on Claude Code and Codex. status() reports incomplete when the
agent file is missing; uninstall() removes the agent file before the
skill directory. 5 new unit tests cover deploy / no-op / partial-install /
uninstall cleanup (44/44 green).
* fix: [ENG-2859] address PR #753 review — TMPDIR resolution + sandbox rationale
PR #753 review surfaced two prose drifts and a missing coverage test on
the saved sub-agent templates. This commit addresses comments #1, #2, #3,
#6; comments #4 and #5 are nits and left as-is (rationale in PR replies).
#1 — `brv-curate.md` (Claude) claimed writes outside `/tmp/` are
"auto-denied silently". That framing is from a prior iteration before we
landed `permissionMode: bypassPermissions`. The real reason to pin the
envelope to the temp directory is portability + hygiene, not auto-deny.
Reworded the step-3 body and the matching hard-constraint bullets.
#2 — Claude worker now resolves `$TMP="${TMPDIR:-/tmp}"` with Bash once,
then uses `$ENVELOPE` as the literal path passed to Write and
`--response-file`. Works on Linux (where $TMPDIR is unset, falls to
/tmp), Claude Code (same), and macOS (where $TMPDIR is /var/folders/...).
#3 — Added a sibling test in `managed skill files` that enumerates every
`agentFile.source` referenced by `SKILL_CONNECTOR_CONFIGS` and asserts
the file exists under `src/server/templates/agent/`. Prevents a future
template rename from silently breaking install. 46/46 green.
#6 — `curate.md` Permission prerequisites section now explicitly states
the allow-list rules apply to the foreground / non-saved-agent path.
Under `bypassPermissions` / `workspace-write` they are inert for
dispatched curates; the callout prevents users from thinking the
allow-list alone unlocks background dispatch.
Note: the Codex `brv-curate.toml` is intentionally left at its prior
state — the TMPDIR resolution and nickname_candidates that originally
shipped on this branch were reverted per direct user direction. The
trade-offs (no Codex panel label, /tmp pinning may bite on macOS
workspace-write) are tracked as follow-ups. C
cuongdo-byterover committed
faf456d6bb47cb441b61c73051a581f4488868af
Parent: 0007ddc
Committed by GitHub <noreply@github.com>
on 6/2/2026, 1:27:40 PM