/spawn-session

name: spawn-session
description: Spawns a background Claude Code helper in the project or another folder with the configured Remote Control and the boot-written helper system prompt that a hand-built `claude --bg` omits, watches it until idle, and relays its report to the operator. Use when the operator says "spawn a helper", "spawn a new session", "run this in a background session", asks for a new session with `--model` or `--effort`, asks to switch a running helper's model or effort, or names `/spawn-session`.

Spawn Session

Launch a background Claude Code session in a folder, subscribe to its idle notice, and relay the report through `/hermitd:watch`.

Usage

/hermitd:spawn-session <prompt-or-/skill> [--cwd <abs-dir>] [--worktree] [--name <n>] [--model <m>] [--effort <e>] [--background <abs-file>] [--task <id>] [--strict-mcp-config]
/hermitd:spawn-session --switch <n> --record <T-id> [--model <m>] [--effort <e>]

From `<dir>`, the launch folder (`<abs>`, the hermit project root, unless `--cwd` names another), that composes:

claude --bg --name <n> [--worktree <n>] [--permission-mode <p>] [--no-chrome] [--remote-control <n>] [--model <m>] [--effort <e>] [--mcp-config <dir>/.mcp.json] [--strict-mcp-config] --append-system-prompt-file <abs>/.hermit/state/helper-system-prompt.md '<prompt>'

`--no-chrome` is present on fresh launches when `config.chrome` is false (absent means false). Never add it to `claude --bg --resume`: resume must remain flagless to retain saved options.

`--worktree <n>` is present only when the operator passed `--worktree`, and gives the helper its own worktree of `<dir>` from the start. `--remote-control <n>` is present when `config.json`'s `remote` is `true` and absent otherwise; `--model` and `--effort` only when the operator passed them. `--mcp-config <dir>/.mcp.json` and `--strict-mcp-config` only when the operator passed `--strict-mcp-config`: both flags when `<dir>/.mcp.json` exists, and `--strict-mcp-config` alone when it does not. Strict mode drops plugin and user-scope MCP servers from the helper. A background session cannot answer the project-server approval dialog, and a folder named by `--cwd` brings its own `.mcp.json` to that dialog. A helper report counts only when its sender's session name equals the `target` of a live `peer-idle` registry entry; the epoch-suffixed helper name is what distinguishes one spawn from a reused name. The helper never writes `tasks/`; the resident records progress and results after that sender check.

Six limits sit on that command:

• The helper starts in `<dir>`. In a repository's main checkout, Claude Code

refuses its Edit and Write until it calls `EnterWorktree`: the `worktree.bgIsolation` setting, `"worktree"` by default (https://code.claude.com/docs/en/settings-reference#worktree-bgisolation). `"none"` in that project's settings lets helpers edit the checkout directly, on whatever branch the resident has checked out; this skill never sets it. A linked worktree is edited in place under either value, and Bash git commands are not fenced by the setting. Outside a git repository the block still applies, so a non-git `<dir>` leaves the helper read-only.

• Any file the helper must Read is passed as an absolute path in the prompt,

spelled as an `@<abs-path>` mention so Claude Code injects it at launch; a worktree does not carry the hermit's untracked state.

• `<abs>/.hermit/state/helper-system-prompt.md` is written at boot

and gated like `config.json`. Pass it as `--append-system-prompt-file` (a system-prompt file is not expanded, so `@<abs-path>` mentions still belong in the prompt). The appended text reaches the helper's main conversation and forks, not its non-fork subagents.

• `--permission-mode <p>` from `config.json`'s `permission_mode` keeps the

helper in this session's permission class, which is what lets its idle notice reach here rather than being held for an operator who is not watching. `config.json` accepts one value the CLI has no choice for, `default`, so it and `null` and an absent key all mean: leave the flag off entirely and let the helper take the box default. `scripts/hermitd-start.ts` resolves `default` and `null` the same way; match that rather than inventing a second answer. It does not agree on an absent key, which it reads as `auto` rather than as no flag. `bypassPermissions` is the one value that does not pass through: it becomes `--permission-mode auto` because a helper has no approval surface of its own, and `auto` is the only mode that stays unattended behind a gate.

• The prompt is one single-quoted argument. An apostrophe in it ends the quote,

so replace every `'` with `'\''` before composing. Anything after the closing quote is a second command the operator never asked for.

• The launch is not pre-approved, and what the operator sees depends on the

mode they run in. On `auto`, the shipped default, the classifier decides and no prompt reaches them on any channel. On `acceptEdits` or `manual` the native approval is relayed to their DM and is allow-once, so every spawn asks again. On `bypassPermissions` there is none. Say what is about to be spawned before running it either way: it is the only thing that makes the launch legible when an approval does arrive, and the only record when none does.

Use only the launch options documented here. Never add bypass flags, tool preapprovals, or settings overrides to widen the helper's permissions. If launch or execution is blocked, report the blocker; do not retry through a script, alternate invocation, or weaker permission mode. The exceptions are § Follow-ups, "Resume with new instructions", for an operator follow-up, § Switch a running helper for a model or effort switch, and [untrusted-folder.md](untrusted-folder.md) for a refused workspace.

Commands

• `helper-switch`: `bun ${CLAUDE_PLUGIN_ROOT}/scripts/helper-switch.ts`
• `trust-workspace`: `bun ${CL