spawnSettingsOverlay

spawnSettingsOverlay(opts?): string

Per-spawn --settings overlay merged on top of the user’s settings files. Applied to every Shepherd task spawn — both create (buildSpawnArgv) and resume.

Pins remoteControlAtStartup so a global opt-in in ~/.claude/settings.json doesn’t auto-start Claude Code’s Remote Control for every Shepherd session (default false suppresses the notification noise); /remote-control in the terminal still toggles it per-session.

Pins env.ENABLE_CLAUDEAI_MCP_SERVERS = "false" to disable the claude.ai account-connector MCP servers (Gmail / Google Calendar / Google Drive / Notion / Microsoft 365) for every spawned coding agent (issue #509). Least-privilege hygiene, NOT a token win — the #499 spike measured the saving at only −132 tok/turn (connectors load as deferred, name-only tools) — but an autonomous coding agent has no business reaching the operator’s personal Gmail/Notion. Unconditional and not opt-out’able by design; the overlay env merges key-by-key over the user’s settings so the rest of their env is untouched. (Reviewer/critic/plan-gate spawns don’t use this overlay — they run --safe-mode, which disables file/plugin MCP loading + other customizations, plus enableAllProjectMcpServers in their own --settings to clear Claude’s interactive project-.mcp.json approval gate; see readonlyReviewerArgv.)

disablePlugins (trimmed auto spawns only) adds enabledPlugins: {<id>: false, ...}, which overrides the global true per-spawn and kills plugin SessionStart hooks, plugin skills, and plugin MCP for this process only. Absent/empty → key omitted entirely, so untrimmed spawns keep today’s exact overlay.

hooks (issue #704, only when config.hooksIngest) adds PostToolUse/PostToolUseFailure/ Notification/SessionStart/Stop/SessionEnd/SubagentStart/SubagentStop HTTP hooks pointing at this session’s ingest route (see buildHooksFragment). Flag off → key omitted entirely, so the overlay JSON stays byte-for-byte identical to today.

Parameters

opts?

disablePlugins?

string[]

hooks?

{ baseUrl: string; sessionId: string; token: string | null; }

hooks.baseUrl

string

hooks.sessionId

string

hooks.token

string | null

Returns

string