Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

The person can turn agents starting agents off (#1191)

Deeccb8b773ea02
diff --git a/cli/e2e/agentClient.e2e.ts b/cli/e2e/agentClient.e2e.ts
index 23c5bda8d..4486fd0ea 100644
--- a/cli/e2e/agentClient.e2e.ts
+++ b/cli/e2e/agentClient.e2e.ts
@@ -256,4 +256,24 @@ describe('Harness for agents, end to end', () => {
server.close()
client.close()
})
+
+ it('an agent may not start a harness once the person turns that off', async () => {
+ const d = await IsolatedDaemon.create()
+ daemon = d
+ onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })
+ await d.start()
+ const dir = join(d.projectsDir, 'held')
+ mkdirSync(dir, { recursive: true })
+ // The person, at a terminal; then Claude Code in a terminal app.
+ const off = await harness(d, '', ['settings', 'agents-start-agents', 'off'])
+ expect(off.out.trim()).toBe('agents-start-agents is off.')
+ const refused = await harness(d, '', ['new', 'claude', dir, '--name', 'held', '--', 'hello'], { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'held-session' })
+ expect(refused.code, refused.out).toBe(1)
+ expect(refused.err).toContain('The person has turned off agents starting harnesses on this computer')
+ const listed = await harness(d, '', ['ps', '--json'])
+ expect(JSON.parse(listed.out).harnesses).toEqual([])
+ // The setting is the daemon's, as the window reads it.
+ const read = await fetch(`http://127.0.0.1:${d.port}/api/agent-settings`)
+ expect(await read.json()).toEqual({ agentsStartAgents: false })
+ })
})
diff --git a/cli/src/agentClient/commands.spec.ts b/cli/src/agentClient/commands.spec.ts
index 60fdda250..a2e0dccc5 100644
--- a/cli/src/agentClient/commands.spec.ts
+++ b/cli/src/agentClient/commands.spec.ts
@@ -2,9 +2,10 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { addressOf, agentOrigin, closeCommand, EXIT, parseDuration, psCommand, showCommand, spawnRefusal, SPAWN_LIMITS, waitCommand, type ClientDeps } from './commands.js'
+import { addressOf, agentOrigin, AGENTS_START_AGENTS_OFF, closeCommand, EXIT, parseDuration, psCommand, showCommand, spawnRefusal, SPAWN_LIMITS, waitCommand, type ClientDeps } from './commands.js'
import { AgentClientError, type Daemon, type Where } from './daemon.js'
import { Ledger, ledgerPath } from './ledger.js'
+import { writeAgentSettings } from '../lib/agentSettings.js'
import type { Frame } from './model.js'
const NOW = Date.parse('2026-10-11T12:00:00Z')
@@ -556,6 +557,19 @@ describe('harness new, run by an agent', () => {
await expect(unknown.check()).rejects.toThrow(/could not tell who is starting this/)
})
+ it('refuses every agent when the person has turned agents starting agents off, and never the person', async () => {
+ const d = new FakeDaemon()
+ d.frames = [frame('lead', { engine: 'claude' })]
+ writeAgentSettings(dir, { agentsStartAgents: false })
+ const inPane = (await agentOrigin(harness(d).deps))!
+ await expect(inPane.check()).rejects.toThrow(AGENTS_START_AGENTS_OFF)
+ const outside = (await agentOrigin(harness(d, { pane: undefined, env: { CODEX_THREAD_ID: 't' } }).deps))!
+ await expect(outside.check()).rejects.toThrow(AGENTS_START_AGENTS_OFF)
+ expect(await agentOrigin(harness(d, { pane: undefined }).deps)).toBeNull()
+ writeAgentSettings(dir, { agentsStartAgents: true })
+ await expect((await agentOrigin(harness(d).deps))!.check()).resolves.toBeUndefined()
+ })
+
it('refuses from what is left of an agent whose harness is gone', async () => {
const origin = (await agentOrigin(harness(new FakeDaemon(), { pane: '%gone', where: () => ({ ...where, harnessPane: true }) }).deps))!
await expect(origin.check()).rejects.toThrow(/no longer running/)
diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.ts
index eded45e87..8a9619dc9 100644
--- a/cli/src/agentClient/commands.ts
+++ b/cli/src/agentClient/commands.ts
@@ -16,6 +16,7 @@ import { randomBytes } from 'node:crypto'
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { hostname } from 'node:os'
import { join } from 'node:path'
+import { readAgentSettings } from '../lib/agentSettings.js'
import { MAX_FIRST_PROMPT_CHARS } from '../lib/engineLaunch.js'
import type { NewOrigin } from '../lib/newCommand.js'
import { engineName } from '../messages/model.js'
@@ -71,6 +72,8 @@ const STARTING_MS = 2 * 60_000
class UsageError extends Error {}
+export const AGENTS_START_AGENTS_OFF = 'The person has turned off agents starting harnesses on this computer (Harness Settings ▸ Agents). Do the work yourself.'
+
const ORPHAN = 'This pane\'s harness is no longer running, so nothing here may close or start harnesses. Only the person can.'
interface Opened {
@@ -552,6 +555,8 @@ export async function agentOrigin(deps: ClientDeps = {}, record: Rpc = messagesR
if (o.orphan) return refusing('NOT_YOURS', ORPHAN)
const caller = o.caller
if (!caller) return null
+ // The person's say, on the machine the agent runs on (Settings ▸ Agents, `harness settings`).
+ if (!readAgentSettings(o.where.dataDir).agentsStartAgents) return refusing('TURNED_OFF', AGENTS_START_AGENTS_OFF)
return {
check: async () => {
const refusal = spawnRefusal(caller, await liveFor(s, o, caller), o.ledger, o.where.machineId, s.now())
diff --git a/cli/src/agentClient/settings.spec.ts b/cli/src/agentClient/settings.spec.ts
new file mode 100644
index 000000000..c1751cebd
--- /dev/null
+++ b/cli/src/agentClient/settings.spec.ts
@@ -0,0 +1,37 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { readAgentSettings } from '../lib/agentSettings.js'
+import { settingsCommand, SETTINGS_USAGE } from './settings.js'
+
+let dir: string
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'settings-command-')) })
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+describe('harness settings', () => {
+ it('lists the settings, and turns one off and on', () => {
+ const out: string[] = [], err: string[] = []
+ const run = (...argv: string[]) => settingsCommand(argv, dir, (l) => out.push(l), (l) => err.push(l))
+ expect(run()).toBe(0)
+ expect(out.pop()).toBe('agents-start-agents on agents may start, wait for and close harnesses of their own')
+ expect(run('agents-start-agents', 'off')).toBe(0)
+ expect(out.pop()).toBe('agents-start-agents is off.')
+ expect(readAgentSettings(dir).agentsStartAgents).toBe(false)
+ expect(run()).toBe(0)
+ expect(out.pop()).toMatch(/^agents-start-agents +off /)
+ expect(run('agents-start-agents', 'on')).toBe(0)
+ expect(readAgentSettings(dir).agentsStartAgents).toBe(true)
+ })
+
+ it('refuses what it does not know with the usage, and prints it for --help', () => {
+ const out: string[] = [], err: string[] = []
+ const run = (...argv: string[]) => settingsCommand(argv, dir, (l) => out.push(l), (l) => err.push(l))
+ expect(run('nope', 'on')).toBe(2)
+ expect(run('agents-start-agents', 'maybe')).toBe(2)
+ expect(run('agents-start-agents', 'on', 'extra')).toBe(2)
+ expect(err).toEqual([SETTINGS_USAGE, SETTINGS_USAGE, SETTINGS_USAGE])
+ expect(run('--help')).toBe(0)
+ expect(out).toEqual([SETTINGS_USAGE])
+ })
+})
diff --git a/cli/src/agentClient/settings.ts b/cli/src/agentClient/settings.ts
new file mode 100644
index 000000000..be6656afd
--- /dev/null
+++ b/cli/src/agentClient/settings.ts
@@ -0,0 +1,30 @@
+/**
+ * `harness settings`: what the person lets agents do on this computer (lib/agentSettings.ts), the same switches as
+ * Settings ▸ Agents, for a terminal or a machine with no window.
+ *
+ * harness settings every setting and its state
+ * harness settings agents-start-agents off turn one on or off
+ */
+import { AGENT_SETTING_NAMES, readAgentSettings, writeAgentSettings, type AgentSettings } from '../lib/agentSettings.js'
+
+export const SETTINGS_USAGE = `Usage: harness settings [<name> on|off]
+
+What agents may do on this computer, as Settings ▸ Agents shows it:
+ agents-start-agents agents may start, wait for and close harnesses of their own, and are told how (on by default)`
+
+const ABOUT: Record<keyof AgentSettings, string> = {
+ agentsStartAgents: 'agents may start, wait for and close harnesses of their own',
+}
+
+export function settingsCommand(argv: readonly string[], dataDir: string, out: (line: string) => void = console.log, err: (line: string) => void = console.error): number {
+ if (argv.includes('--help') || argv.includes('-h')) { out(SETTINGS_USAGE); return 0 }
+ const show = (settings: AgentSettings) => Object.entries(AGENT_SETTING_NAMES)
+ .map(([name, key]) => `${name.padEnd(22)}${settings[key] ? 'on ' : 'off'} ${ABOUT[key]}`).join('\n')
+ if (!argv.length) { out(show(readAgentSettings(dataDir))); return 0 }
+ const [name, value, ...rest] = argv
+ const key = AGENT_SETTING_NAMES[name]
+ if (!key || (value !== 'on' && value !== 'off') || rest.length) { err(SETTINGS_USAGE); return 2 }
+ const next = writeAgentSettings(dataDir, { [key]: value === 'on' })!
+ out(`${name} is ${next[key] ? 'on' : 'off'}.`)
+ return 0
+}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 16848e566..6d7265e2a 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -144,6 +144,7 @@ Machine:
harness wait <name>[,<name>] wait until they stop working (--any, --timeout 30m); exit 3 = needs the person
harness close <name> [--now] save a harness's screen and stop it; an agent closes only what it started
harness mcp the agent verbs as an MCP server on stdin/stdout, for agents that use MCP
+ harness settings [<name> on|off] what agents may do here (agents-start-agents), as Settings ▸ Agents
harness machines delete <id> remove ANOTHER machine (refuses this one; use \`harness logout\`)
harness remote from a Harness terminal tile: open a terminal on another of your machines and move this tile to it
harness version print the installed version (v${VERSION})
@@ -2451,6 +2452,7 @@ import { orchestratorCommand } from './orchestrator/command.js'
import { paneOwner, sendCommand } from './messages/command.js'
import { agentOrigin, closeCommand, psCommand, showCommand, waitCommand } from './agentClient/commands.js'
import { harnessRunner, mcpCommand } from './agentClient/mcp.js'
+import { settingsCommand } from './agentClient/settings.js'
// ── arg parse ──────────────────────────────────────────────────────────────────────────────────
// `hn` is the terminal client's short name (like tmux, fzf): the same CLI, entered at `tui`. A call
@@ -2485,6 +2487,9 @@ switch (cmd) {
case 'ps':
psCommand(rest).then(code => { process.exitCode = code }).catch(onError)
break
+ case 'settings':
+ process.exitCode = settingsCommand(rest, env.ADAPTER_DATA_DIR)
+ break
case 'mcp': {
const pane = process.env.TMUX_PANE
mcpCommand({ run: harnessRunner(SCRIPT_PATH), inPane: !!pane && !!paneOwner(pane) }).then(code => { process.exitCode = code }).catch(onError)
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 71ba736ce..aa06f24e0 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -73,6 +73,7 @@ import { processSessionOf } from '../engines/sessionStores.js'
import { createHandoffDependencies } from './handoffDependencies.js'
import { TmuxBackend } from '../lib/tmuxBackend.js'
import { DEFAULT_HOST_THEME, loadHostTheme, saveHostTheme, type HostTheme } from '../lib/hostTheme.js'
+import { agentSettingsRoutes } from '../lib/agentSettings.js'
import { restoreAgents, tmuxSurvey, type RestoreAgentsDeps, type RestoreSummary } from '../lib/restoreAgents.js'
import { createRetainExitedSession } from '../lib/retainExitedSession.js'
import { createKeepAbandonedConversation } from '../lib/keepAbandonedConversation.js'
@@ -1718,6 +1719,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
})
// Which agent a hook belongs to, and what a SessionEnd means (core/engines/hooks.ts).
const engineHooks = createEngineHooks({ tmuxBackend, agentReconciler, registry, panePending: restorePanes.pending, syncSession })
+ // Settings ▸ Agents, kept in this daemon's data folder (lib/agentSettings.ts).
+ const agentSettings = agentSettingsRoutes(env.ADAPTER_DATA_DIR)
const { server: hookServer, port: hookPort, localSocket } = await startHookServer(daemonPort(), {
onAutonomousDeviceRequest: async (method, target, body) => {
// Until the pieces below are built; after, a piece that could not be is refused by the requests
@@ -1797,6 +1800,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
onAgentMessagesWrite: (tabId, body) => proxyBackend('PATCH', `/api/agent-messages/tabs/${tabId}`, body),
onExperimentalRead: () => proxyBackend('GET', '/api/experimental-settings'),
onExperimentalWrite: (body) => proxyBackend('PATCH', '/api/experimental-settings', body),
+ onAgentSettingsRead: agentSettings.read,
+ onAgentSettingsWrite: agentSettings.write,
onStore: (method, path, body) => proxyBackend(method, path, body),
}, { socketPath: localSocketPath(env.ADAPTER_DATA_DIR, env.PORT), allowPortFallback: true })
try { saveDaemonPort(env.ADAPTER_DATA_DIR, env.PORT, hookPort) } catch (error) {
diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.ts
index a4812751d..144e4a4ff 100644
--- a/cli/src/hookServer.spec.ts
+++ b/cli/src/hookServer.spec.ts
@@ -8,6 +8,7 @@ import { registry, type RegisteredSession } from './lib/registry.js'
import { env } from './config/env.js'
import { readHookCredential } from './lib/hookAuth.js'
import { ENGINES } from './engines/types.js'
+import { agentSettingsRoutes } from './lib/agentSettings.js'
import { engineHooks } from './engines/hooks.js'
let server: Server | null = null
@@ -357,6 +358,29 @@ describe('account Experimental settings proxy', () => {
})
})
+describe('what the person lets agents do', () => {
+ it('reads and writes this computer\'s agent settings, the write guarded by the local header', async () => {
+ const dataDir = mkdtempSync(join(tmpdir(), 'agent-settings-route-'))
+ try {
+ const routes = agentSettingsRoutes(dataDir)
+ const { base } = await start({ onAgentSettingsRead: routes.read, onAgentSettingsWrite: routes.write })
+ const patch = (body: string, local = true) => fetch(`${base}/api/agent-settings`, { method: 'PATCH', headers: { 'content-type': 'application/json', ...(local ? { 'x-adapter-local': '1' } : {}) }, body })
+ expect(await (await fetch(`${base}/api/agent-settings`)).json()).toEqual({ agentsStartAgents: true })
+ expect((await patch('{"agentsStartAgents":false}', false)).status).toBe(403)
+ expect(await (await patch('{"agentsStartAgents":false}')).json()).toEqual({ agentsStartAgents: false })
+ expect(await (await fetch(`${base}/api/agent-settings`)).json()).toEqual({ agentsStartAgents: false })
+ expect((await patch('{"other":1}')).status).toBe(400)
+ expect((await patch('{bad')).status).toBe(400)
+ } finally { rmSync(dataDir, { recursive: true, force: true }) }
+ })
+
+ it('answers UNAVAILABLE without a handler', async () => {
+ const { base } = await start({})
+ expect((await fetch(`${base}/api/agent-settings`)).status).toBe(503)
+ expect((await fetch(`${base}/api/agent-settings`, { method: 'PATCH', headers: { 'x-adapter-local': '1' }, body: '{}' })).status).toBe(503)
+ })
+})
+
describe('optional feature routes are absent from core', () => {
it.each(['/api/zoo', '/api/zoo/ops', '/api/hook/memory-context', '/api/hook/memory-emitted', '/api/hook/opencode-memory-runtime'])(
'does not handle %s or consult account metadata', async path => {
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index ba0055755..fa60d2703 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -171,6 +171,10 @@ export interface HookServerHandlers {
/** PATCH /api/agent-messages/tabs/:tabId — turn Agent Messages on or off for one tab; a local write, so
* CSRF-guarded like the desk's ops. */
onAgentMessagesWrite?: (tabId: string, body: unknown) => Promise<PairOutcome>
+ /** GET/PATCH /api/agent-settings — what the person lets agents do on this computer (lib/agentSettings.ts), kept by
+ * this daemon rather than the account: Settings ▸ Agents. The write is CSRF-guarded like the others. */
+ onAgentSettingsRead?: () => Promise<PairOutcome>
+ onAgentSettingsWrite?: (body: unknown) => Promise<PairOutcome>
/** The account's Experimental switches, proxied with the daemon's own identity. */
onExperimentalRead?: () => Promise<PairOutcome>
onExperimentalWrite?: (body: unknown) => Promise<PairOutcome>
@@ -1000,6 +1004,17 @@ export function startHookServer(
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
await proxied(() => handlers.onAgentMessagesWrite!(agentMessagesTab[1], body)); return
}
+ if (req.method === 'GET' && url === '/api/agent-settings') {
+ if (!handlers.onAgentSettingsRead) { json(503, { error: 'UNAVAILABLE' }); return }
+ await proxied(handlers.onAgentSettingsRead); return
+ }
+ if (req.method === 'PATCH' && url === '/api/agent-settings') {
+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
+ if (!handlers.onAgentSettingsWrite) { json(503, { error: 'UNAVAILABLE' }); return }
+ let body: unknown
+ try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
+ await proxied(() => handlers.onAgentSettingsWrite!(body)); return
+ }
if (req.method === 'GET' && url === '/api/experimental-settings') {
if (!handlers.onExperimentalRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onExperimentalRead); return
diff --git a/cli/src/lib/agentSettings.spec.ts b/cli/src/lib/agentSettings.spec.ts
new file mode 100644
index 000000000..c90880722
--- /dev/null
+++ b/cli/src/lib/agentSettings.spec.ts
@@ -0,0 +1,31 @@
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { AGENT_SETTING_NAMES, agentSettingsPath, readAgentSettings, writeAgentSettings } from './agentSettings.js'
+
+let dir: string
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'agent-settings-')) })
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+describe('what the person lets agents do', () => {
+ it('lets agents start agents until the person turns it off', () => {
+ expect(readAgentSettings(dir)).toEqual({ agentsStartAgents: true })
+ expect(writeAgentSettings(dir, { agentsStartAgents: false })).toEqual({ agentsStartAgents: false })
+ expect(readAgentSettings(dir)).toEqual({ agentsStartAgents: false })
+ expect(JSON.parse(readFileSync(agentSettingsPath(dir), 'utf8'))).toEqual({ version: 1, agentsStartAgents: false })
+ expect(statSync(agentSettingsPath(dir)).mode & 0o777).toBe(0o600)
+ expect(AGENT_SETTING_NAMES['agents-start-agents']).toBe('agentsStartAgents')
+ })
+
+ it('applies only booleans it knows, and reads a broken file as the defaults', () => {
+ expect(writeAgentSettings(dir, null)).toBeNull()
+ expect(writeAgentSettings(dir, 'off')).toBeNull()
+ expect(writeAgentSettings(dir, { agentsStartAgents: 'no', other: true })).toBeNull()
+ expect(writeAgentSettings(dir, { agentsStartAgents: false, other: true })).toEqual({ agentsStartAgents: false })
+ writeFileSync(agentSettingsPath(dir), '{"agentsStartAgents": "nope"}')
+ expect(readAgentSettings(dir)).toEqual({ agentsStartAgents: true })
+ writeFileSync(agentSettingsPath(dir), 'not json')
+ expect(readAgentSettings(dir)).toEqual({ agentsStartAgents: true })
+ })
+})
diff --git a/cli/src/lib/agentSettings.ts b/cli/src/lib/agentSettings.ts
new file mode 100644
index 000000000..7d9e5bb28
--- /dev/null
+++ b/cli/src/lib/agentSettings.ts
@@ -0,0 +1,60 @@
+/**
+ * What the person lets agents do with Harness (docs/design/2026-10-11-agent-client.md), kept by the daemon in its data
+ * folder: `agent-settings.json`. Settings ▸ Agents writes it through the daemon (`/api/agent-settings`), `harness
+ * settings` from a terminal, and the daemon and the CLI read it: the daemon when it starts an agent (whether its
+ * instructions say how to start others), `harness new` when an agent runs it (whether it may).
+ *
+ * Agents may start agents unless the person turns it off: some want every agent to work alone, under their eye.
+ * A file that is missing or that cannot be read is the defaults, never a refusal to work.
+ */
+import { chmodSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface AgentSettings {
+ /** Agents may start, wait for and close harnesses of their own, and are told how as they start. */
+ agentsStartAgents: boolean
+}
+
+export const AGENT_SETTINGS_DEFAULTS: AgentSettings = { agentsStartAgents: true }
+
+/** Each setting's name in `harness settings`, and its key. */
+export const AGENT_SETTING_NAMES: Record<string, keyof AgentSettings> = { 'agents-start-agents': 'agentsStartAgents' }
+
+export const agentSettingsPath = (dataDir: string): string => join(dataDir, 'agent-settings.json')
+
+export function readAgentSettings(dataDir: string): AgentSettings {
+ try {
+ const saved = JSON.parse(readFileSync(agentSettingsPath(dataDir), 'utf8')) as Record<string, unknown>
+ return { agentsStartAgents: typeof saved.agentsStartAgents === 'boolean' ? saved.agentsStartAgents : AGENT_SETTINGS_DEFAULTS.agentsStartAgents }
+ } catch {
+ return { ...AGENT_SETTINGS_DEFAULTS }
+ }
+}
+
+/**
+ * Applies [patch] (only the keys it knows, only booleans) and says what the settings are now; null when the patch
+ * holds nothing it can apply. Written whole and renamed into place, so a reader never sees half a file.
+ */
+export function writeAgentSettings(dataDir: string, patch: unknown): AgentSettings | null {
+ if (!patch || typeof patch !== 'object') return null
+ const known = Object.entries(patch as Record<string, unknown>).filter(([key, value]) => key in AGENT_SETTINGS_DEFAULTS && typeof value === 'boolean')
+ if (!known.length) return null
+ const next = { ...readAgentSettings(dataDir), ...Object.fromEntries(known) } as AgentSettings
+ const path = agentSettingsPath(dataDir)
+ const temporary = `${path}.${process.pid}.tmp`
+ writeFileSync(temporary, `${JSON.stringify({ version: 1, ...next })}\n`, { mode: 0o600 })
+ chmodSync(temporary, 0o600)
+ renameSync(temporary, path)
+ return next
+}
+
+/** `/api/agent-settings` for the daemon whose data folder is [dataDir]: the settings, or a write's result. */
+export function agentSettingsRoutes(dataDir: string): { read: () => Promise<{ status: number; body: Record<string, unknown> }>; write: (body: unknown) => Promise<{ status: number; body: Record<string, unknown> }> } {
+ return {
+ read: async () => ({ status: 200, body: { ...readAgentSettings(dataDir) } }),
+ write: async (body) => {
+ const next = writeAgentSettings(dataDir, body)
+ return next ? { status: 200, body: { ...next } } : { status: 400, body: { error: { code: 'BAD_REQUEST', message: 'Nothing to change: send {"agentsStartAgents": true|false}.' } } }
+ },
+ }
+}
diff --git a/docs/design/2026-10-11-agent-client.md b/docs/design/2026-10-11-agent-client.md
index 82e20dea5..67b79c54a 100644
--- a/docs/design/2026-10-11-agent-client.md
+++ b/docs/design/2026-10-11-agent-client.md
@@ -157,6 +157,9 @@ with a clear error; nothing is dropped silently.
- Depth: an agent-started harness may start harnesses; one started two levels down may not.
- `new` per harness: 20 in 10 minutes.
- An agent never answers a permission dialog, and never closes a harness it did not start.
+- The person can turn agents starting agents off on a computer (Settings ▸ Agents, `harness settings
+ agents-start-agents off`; `<data>/agent-settings.json`): then every agent's `harness new` and `harness_start` is
+ refused there, and reading, waiting and closing what it started still work. On by default.
## How it works