SIGN IN SIGN UP

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