session-flow: /handoff --bg is misleading — background delegation deserves an explicit action

[kyle-sexton]

Problem

/handoff's name and default flow mean "write a save-point, /clear, paste later". The --bg flag bolts on a different job entirely: launching a fresh background session that CONTINUES the task. Two issues:

1. Semantics — "handoff" reads as save-point-for-later, not "delegate the implementation to a background agent now". Users reaching for background delegation won't find it; users invoking --bg may not realize the current session terminates as far as the task is concerned.
2. Discoverability — --bg is a flag buried in the argument hint; the behavioral difference (new claude --bg session, CLI-default model rather than the current session's model, no effort inheritance) is undocumented at the surface.

Likely inherited from the original upstream skill this was adapted from without massaging into this plugin's UX.

Direction to evaluate

• Split background delegation into its own explicitly named action/skill (naming pass required), or promote it from flag to first-class argument with clear semantics.
• Document model/effort behavior of the launched session vs the parent.
• Consider whether "keep current session alive as home base" (Agent-tool background subagent) should be a supported path alongside claude --bg.

Raised from a working session on 2026-07-16 while converting repeated prompts into skills; deferred so it isn't lost.

[kyle-sexton]

Decision brief — /handoff --bg naming (2-min read)

Human-operator lane. This is analysis only — no decision taken, no labels/state changed.

Problem (2 sentences)

--bg is bolted onto /handoff, whose name and default flow mean "save a snapshot, /clear, resume later by hand" — but --bg instead launches a detached session that continues the task now. The friction is real, but the framing "two distinct jobs crammed into one name" overstates it: --bg reuses ~95% of handoff's machinery — the honest problem is one save-point with two delivery modes, one of which (background launch) has a misleading name and no discoverable command-level entry point.

Verified today (source: plugins/session-flow/skills/handoff/SKILL.md on main, via gh api)

• --bg is a flag (argument-hint L4; args spec L48–51), recognized anywhere in the arg string, stripped before positionals.
• It composes with the normal path, not a separate one. The rails resume prompt is still emitted first; --bg only swaps the final delivery step — instead of "/clear then paste," it runs claude --bg --name "handoff-<topic>" "<resume prompt>" (L192–247). Save-point production, resume-prompt, mandatory redaction pass, and the STOP gate are all shared.
• The launched session is a fresh claude --bg session that "inherits none of the current session's CLI configuration (e.g. --mcp-config, --settings, --add-dir, --plugin-dir)" (L227–233). The skill is silent on model and effort — the issue's "CLI-default model, no effort inheritance" is a plausible inference from that fresh-session behavior but is not stated in the file; treat it as the author's claim, not a verified line.
• Repo-wide check: handoff is the only skill in the entire marketplace that launches a detached claude --bg session. session-flow:orchestrate, work-items:work, etc. delegate via in-session Agent-tool subagents, which die with the parent session. So there is no existing dedicated background-dispatch verb to align a rename to — this would set the precedent, not follow one.
• Related issues: session-flow: /handoff --bg is misleading — background delegation deserves an explicit action #233 is the sole open issue on this. (disk-hygiene: apply/handoff ask gate and unattended-stop are advisory, not deterministic — apply can run with no human #381/disk-hygiene: POSIX has no support lane (Bash denies all non-engine) and macOS manual-handoff has no deletion lane #383 disk-hygiene "handoff" = support-lane handoff, unrelated; session-flow: retro context snippet assigns literal HANDOFF_DIR=.work/handoffs, bypassing memory_dir resolution if copied as-is #420 closed, retro HANDOFF_DIR internals, unrelated.)

Two axes the issue flattens — worth separating before deciding

1. Discoverability has two sub-axes. Model-invocation is already partly handled — handoff's description triggers on "continue in the background." The genuine gaps are (a) human-typed command recall (nobody types /handoff to delegate) and (b) semantic honesty of the name. Only (a)+(b) are unaddressed today.
2. "Home base" is a separate capability axis (issue raises it). Detached claude --bg survives the parent leaving → AFK/overnight. An in-session Agent-tool subagent runs under the parent → stay-and-monitor. Different needs; see Deferred.

Options

➤ RECOMMENDED — A. Dedicated background-delegation command, implemented by composing handoff; deprecate --bg behind an alias.
A new session-flow skill (name TBD — see below) becomes the discoverable, honestly-named entry for "produce a save-point AND launch a background session that continues now." It calls handoff's save-point + resume-prompt machinery rather than reimplementing it (a new skill that duplicated the save-point logic would violate the DRY / pointer-not-copy rule — composition is mandatory, not optional). /handoff --bg stays as a deprecated alias that routes to the new skill during a transition window.

• Fixes: both discoverability sub-axes (a)+(b) and the semantic mismatch.
• Cost / risk: real design + naming work; must wire composition carefully to avoid a near-duplicate skill.
• Reversibility: adding a skill + aliasing --bg is non-breaking and reversible. The one genuinely sticky commitment is the command name — once users learn it, renaming churns muscle memory. So don't lock the name in this decision; run a naming:name-it-better pass. Directions to seed it: /delegate, /dispatch, /resume-bg, /continue-bg.

B. Keep it on /handoff, but rename the flag and surface its semantics.
Rename --bg to a clearer delivery-mode name (e.g. --launch / --continue-now) and document the fresh-session model/effort/CLI-config behavior at the surface (description + argument-hint).

• Strength (steelman): given the machinery is shared, a clearer delivery-mode name is arguably the most honest representation — it says "same save-point, delivered by launching." Cheapest, smallest blast radius, no near-duplicate skill.
• Weakness: fixes semantic honesty of the flag but not human command recall — a user wanting background delegation still won't reach for /handoff. Leaves discoverability sub-axis (a) open.
• Reversibility: very high (flags are cheap to rename again).

C. Status quo + doc-only fix (rejected as the whole answer, but its content ships regardless).
Its real content is not "do nothing" — it's "surface the launched session's model/effort/CLI-config behavior." That fix is orthogonal to A/B and should ship in whichever option wins. As a standalone answer it's rejected: it addresses the undocumented-behavior sub-issue but leaves the naming/discoverability complaint (the issue's actual title) untouched.

• Reversibility: total (docs only).

The real discriminator (the human's call)

Is "delegate the task to a background session now" a distinct enough user intent to deserve its own command name — given the underlying machinery is shared with /handoff?

• Yes → A (own entry point, composed implementation).
• "It's the same save-point, just delivered differently" → B (honest flag name on /handoff).
  Either way, ship C's model/effort/CLI-config documentation.

Deferred (record, don't decide now)

• Home-base / stay-and-monitor path: a supported "keep this session alive, run the continuation as an in-session Agent-tool subagent" mode (vs detached claude --bg). Distinct capability axis; trigger to revisit = demand for monitored/stay-put background work rather than AFK fire-and-forget.

---

Confidence in facts: high (skill read from main via gh api; repo-wide claude --bg sweep). Recommendation A is defensible but the name and the "distinct-intent?" question are deliberately left to the operator.

[kyle-sexton]

Decision record — locked contract, shipped in #924

Operator decision (2026-07-21, interview session): Direction A — background delegation gets its own command — with a clean-cut constraint. Shipped via PR #924 (squash-merged, all checks green, security-clean).

The locked contract:

1. New skill session-flow:continue-in-background (name chosen via a blind 3-lens naming pass; runners-up: relay, detach-and-continue, tag-in). Owns delivery: explicit-intent hard gate (model-invocable for discoverability, launches only on the user's explicit request — never self-elected, eval-covered), dirty-tree gate, claude --bg launch + report, fallback-on-failure, own STOP rule.
2. Shared engine, not runtime composition: save-point production + redaction + rails resume prompt extracted to plugins/session-flow/reference/save-point.md; handoff and the new skill are thin delivery wrappers citing it. No duplication; no skill-invoking-skill.
3. Hard cut: --bg removed from /handoff outright — no alias, no deprecation window. feat!, session-flow 0.13.0.
4. Trigger partition: background phrases moved from handoff's description to the new skill's; zero overlap.
5. Option C's documentation shipped inside the new skill: the launched agent is a NEW session — no CLI-flag inheritance; model/effort resolve from launch flags + launch-directory settings (agent-view / env-vars docs cited in the skill).
6. Deferred (unchanged from the brief): home-base / stay-and-monitor mode (in-session Agent-tool subagent). Trigger to revisit: demand for monitored background work rather than AFK fire-and-forget.

Side effects shipped with it: skill-quality 0.9.0 (check 3 gains a narrowly scoped trigger-move exception — required for the partition to pass CI) and the handoff structure doc moved to plugin-level reference/structure.md so the shared engine stays self-contained. Launch-command security hardening per in-PR security review (prompt passed via temp file, slug sanitized).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CvjCb4f3y2PgsR5jvgSW5J