@p4code/cli 0.1.20 → 0.1.21

package/dist/bin.mjs

@@ -233,7 +233,7 @@ const make$76 = () => {
 const layer$72 = Layer.sync(NetService, make$76);
 //#endregion
 //#region package.json
-var version = "0.1.20";
+var version = "0.1.21";
 //#endregion
 //#region src/config.ts
 /**
@@ -7889,18 +7889,35 @@ var TicketResolveError = class extends Schema$1.TaggedErrorClass()("TicketResolv
 //#endregion
 //#region ../../packages/contracts/src/threadControl.ts
 /**
-* Thread control over MCP - the self-scoped toolkit an agent uses to act on
-* the thread it is running in.
-*
-* Deliberately narrow. The reported need was an agent renaming its own thread;
-* that needs no cross-thread reach, and the per-session bearer token is the
-* only thing guarding `/mcp` on a remote-reachable server, so a capability
-* that could rename arbitrary threads would be a capability to vandalise the
-* workspace from one leaked token. Delete and create are withheld outright,
-* the same answer the task toolkit gave. Settle is absent for a structural
-* reason rather than a policy one: the decider refuses `thread.settle` while
-* the thread's session is starting or running, and a self-scoped MCP call
-* always arrives from its own live session, so the call could never succeed.
+* Thread control over MCP - the toolkit an agent uses to act on its own thread
+* and on the threads it started.
+*
+* **The scope rule.** A per-session bearer token is the only thing guarding
+* `/mcp` on a remote-reachable server, so reach is granted, never assumed. A
+* session may address its own thread and the threads it created through
+* `thread_spawn`, and nothing else. A leaked token therefore still reaches only
+* work that token itself began. The grant is held on the credential rather than
+* derived from the board, so it cannot widen because someone edited a task.
+*
+* **Delete is not exposed, and that is the decision rather than an omission.**
+* It is the one irreversible action here and a thread carries its whole
+* transcript. The task toolkit gave the same answer for the same reason, and a
+* thread is the more expensive thing to lose. An agent that wants a thread gone
+* settles it and says so; a person deletes it.
+*
+* **Spawning is one level deep.** `thread_spawn` seeds a first message and
+* starts the turn, because a create that cannot say anything is not the feature
+* anyone asked for. A thread that was itself spawned may not spawn: the depth
+* cap is what a runaway loop runs into, and one level is enough for "split this
+* task and start the pieces" while still being a structural bound rather than a
+* prompt asking nicely.
+*
+* **Settle is queued rather than refused.** The decider refuses `thread.settle`
+* while the target's session is starting or running, and an MCP call from a
+* thread's own session always arrives while that session is alive - so the
+* self-addressed case could never succeed as an immediate command. It is
+* recorded instead and applied when the session stops, which is what an agent
+* settling its own thread means anyway: finish, then close.
 *
 * Quick-append to memory lives here too: it is the other thing an agent wants
 * to do *from* a thread, and it shares the toolkit's capability and scope.
@@ -7918,6 +7935,64 @@ const ThreadRenameResult = Schema$1.Struct({
 	title: TrimmedNonEmptyString
 });
 /**
+* Which thread a control tool acts on.
+*
+* Optional, and absent means the caller's own thread. That default is what
+* keeps the common case honest: an agent adjusting itself never has to name an
+* id, so it cannot name the wrong one, and every tool below reads the same way
+* whether or not it is addressed elsewhere.
+*/
+const ControlTargetThreadId = Schema$1.optional(ThreadId.annotate({ description: "The thread to act on. Omit for this session's own thread. Only threads this session started with thread_spawn can be named here; any other id is refused." }));
+const ThreadSpawnInput = Schema$1.Struct({
+	title: TrimmedNonEmptyString.annotate({ description: "Title for the new thread. Shown on the board and in the sidebar." }),
+	prompt: TrimmedNonEmptyString.annotate({ description: "The first message to send. The thread starts its turn immediately, so this is the whole brief the new agent gets." }),
+	projectId: Schema$1.optional(ProjectId.annotate({ description: "Project to start the thread in. Defaults to this session's own project." })),
+	runtimeMode: Schema$1.optional(RuntimeMode.annotate({ description: "Permission mode for the new thread. Defaults to this session's own." })),
+	interactionMode: Schema$1.optional(ProviderInteractionMode),
+	compressMode: Schema$1.optional(CompressMode),
+	unpromptedSubagents: Schema$1.optional(Schema$1.Boolean)
+});
+const ThreadSpawnResult = Schema$1.Struct({
+	/** Watchable with `thread_watch_events`, and addressable by every tool here. */
+	threadId: ThreadId,
+	projectId: ProjectId,
+	title: TrimmedNonEmptyString
+});
+const ThreadConfigureInput = Schema$1.Struct({
+	threadId: ControlTargetThreadId,
+	title: Schema$1.optional(TrimmedNonEmptyString),
+	modelSelection: Schema$1.optional(ModelSelection),
+	runtimeMode: Schema$1.optional(RuntimeMode),
+	interactionMode: Schema$1.optional(ProviderInteractionMode),
+	compressMode: Schema$1.optional(CompressMode),
+	unpromptedSubagents: Schema$1.optional(Schema$1.Boolean)
+});
+const ThreadConfigureResult = Schema$1.Struct({
+	threadId: ThreadId,
+	/** The settings that were actually changed, in the order they were applied. */
+	applied: Schema$1.Array(Schema$1.String)
+});
+const ThreadSettleInput = Schema$1.Struct({ threadId: ControlTargetThreadId });
+/**
+* Settled now, or recorded to settle when the session stops.
+*
+* Two outcomes rather than one because the difference is the agent's to know: a
+* queued settle has not happened yet, and a thread that goes on to do more work
+* still settles at the end of it.
+*/
+const ThreadSettleResult = Schema$1.Struct({
+	threadId: ThreadId,
+	outcome: Schema$1.Literals(["settled", "queued"])
+});
+const ThreadSnoozeInput = Schema$1.Struct({
+	threadId: ControlTargetThreadId,
+	snoozedUntil: IsoDateTime.annotate({ description: "When the thread should come back, as an ISO 8601 timestamp." })
+});
+const ThreadSnoozeResult = Schema$1.Struct({
+	threadId: ThreadId,
+	snoozedUntil: IsoDateTime
+});
+/**
 * Which memory file an append lands in.
 *
 * A closed union rather than a filename, because the target directory also
@@ -8012,8 +8087,42 @@ var AssetCompressValidationFailedError = class extends Schema$1.TaggedErrorClass
 		return `The compressed ${this.path} did not validate, so nothing was written: ${this.errors.join(" ")}`;
 	}
 };
+/**
+* The named thread is outside this session's grant.
+*
+* Deliberately the same answer whether the thread does not exist or exists and
+* belongs to someone else: a caller that could tell those apart could map the
+* whole board one id at a time.
+*/
+var ThreadControlNotPermittedError = class extends Schema$1.TaggedErrorClass()("ThreadControlNotPermittedError", { threadId: ThreadId }) {
+	get message() {
+		return `This session cannot act on thread ${this.threadId}. A session may act on its own thread and on threads it started with thread_spawn.`;
+	}
+};
+/** A spawned thread asked to spawn. One level is the whole allowance. */
+var ThreadSpawnNotPermittedError = class extends Schema$1.TaggedErrorClass()("ThreadSpawnNotPermittedError", {
+	threadId: ThreadId,
+	detail: Schema$1.String
+}) {
+	get message() {
+		return `Thread ${this.threadId} cannot start another thread: ${this.detail}`;
+	}
+};
+/** The orchestration engine declined or failed a thread control command. */
+var ThreadControlRejectedError = class extends Schema$1.TaggedErrorClass()("ThreadControlRejectedError", {
+	threadId: ThreadId,
+	commandType: Schema$1.String,
+	detail: Schema$1.String
+}) {
+	get message() {
+		return `${this.commandType} on thread ${this.threadId} failed: ${this.detail}`;
+	}
+};
 const ThreadControlToolError = Schema$1.Union([
 	ThreadToolUnavailableError,
+	ThreadControlNotPermittedError,
+	ThreadSpawnNotPermittedError,
+	ThreadControlRejectedError,
 	ThreadRenameRejectedError,
 	MemoryAppendFailedError,
 	AssetCompressRefusedError,
@@ -14929,6 +15038,7 @@ const makeTaskRepository = Effect.gen(function* () {
 			...input.patch.projectId !== void 0 ? { projectId: input.patch.projectId } : {},
 			...input.patch.repositoryKey !== void 0 ? { repositoryKey: input.patch.repositoryKey } : {},
 			...input.patch.threadId !== void 0 ? { threadId: input.patch.threadId } : {},
+			...input.patch.externalRef !== void 0 ? { externalRef: input.patch.externalRef } : {},
 			...input.patch.parentTaskId !== void 0 ? { parentTaskId: input.patch.parentTaskId } : {},
 			...input.patch.title !== void 0 ? { title: input.patch.title } : {},
 			...input.patch.body !== void 0 ? { body: input.patch.body } : {},
@@ -18870,6 +18980,16 @@ function compressTurnReminderFor(mode) {
 */
 const PRESET_MAX_RESULT_ROWS = 20;
 /**
+* The tool calls a preset run is allowed.
+*
+* Fifteen because a located answer typically takes six to ten, and the runs
+* that overshoot do not overshoot slightly: measured against real transcripts,
+* the long tail sits between sixty and a hundred and thirty calls and carries
+* nearly all of the cost. A cap that a good run never reaches is a cap that only
+* ever bites the runs that had stopped making progress.
+*/
+const PRESET_MAX_TOOL_CALLS = 15;
+/**
 * Named `p4-*` on purpose.
 *
 * The directory is shared with whatever the user has written by hand, and
@@ -18899,6 +19019,34 @@ names a path that is not there, answer with the BLOCKED line below. Guessing at
 the missing half of a request produces an answer that reads as confident and is
 not checkable, which is worse than no answer.`;
 /**
+* What every preset says about the run in between.
+*
+* Three rules, each aimed at a measured failure. The cap bounds the quadratic.
+* The ban on nesting stops a bounded run from spawning an unbounded one, which
+* is the same bill again with nothing watching it. The stop-at-the-cap clause is
+* what makes the number safe to enforce: without somewhere to put a partial
+* answer, a capped subagent either grinds past the cap or throws away what it
+* had, and both are worse than a short table with a named gap.
+*/
+const WORK_BUDGET = `## What the run costs
+
+At most ${PRESET_MAX_TOOL_CALLS} tool calls. Most answers of this kind take six
+to ten, so treat the cap as the point where something has gone wrong rather than
+as a target to spend.
+
+Spend them on calls that can fail usefully: before each one, know what a hit and
+a miss would each tell you. Batch searches into one call separated by echoed
+markers rather than issuing them one at a time, bound every output with a head
+or a line count, and read a file only after a search has told you which lines
+matter, and read those lines. Never repeat a call you have already made.
+
+Do not spawn a subagent of your own. You are the bounded run; one that starts
+another has spent the budget twice with nothing watching the second half.
+
+Reaching the cap ends the run. Return the rows you have verified, and add a
+final line naming the search you would have run next. With no verified rows at
+all, that is the BLOCKED line.`;
+/**
 * What every preset says about the answer.
 *
 * The two sentinels matter as much as the table. Without `NONE` a clean run
@@ -18917,7 +19065,8 @@ const outputContract = (row, extra) => [
 	`    ${row}`,
 	"",
 	"Nothing to report: the single word NONE.",
-	"Request insufficient: BLOCKED - <what is missing>, on one line.",
+	"Request insufficient, or the budget spent before anything was verified:",
+	"BLOCKED - <what is missing>, on one line.",
 	"",
 	"Paths are repository-relative and carry a line number. A row without one is",
 	"a row you have not verified: open the file and get it.",
@@ -18929,6 +19078,11 @@ const outputContract = (row, extra) => [
 * The compression ruleset goes last so the contract above it is read first.
 * Both are instructions to the same model and neither overrides the other:
 * the contract fixes the shape, the ruleset fixes the prose inside it.
+*
+* `model` is optional, and omitting it inherits the session's. Naming a cheaper
+* tier is worth it only where the job is mechanical enough that the tier is not
+* what makes the answer right, which is true of locating a symbol and is not
+* true of deciding whether a line is a bug.
 */
 const buildPreset = (input) => {
 	const name = `${PRESET_NAME_PREFIX}${input.name}`;
@@ -18937,6 +19091,7 @@ const buildPreset = (input) => {
 		`name: ${name}`,
 		`description: ${JSON.stringify(input.description)}`,
 		`tools: ${input.tools}`,
+		...input.model === void 0 ? [] : [`model: ${input.model}`],
 		"---",
 		"",
 		input.body.trim(),
@@ -18959,12 +19114,15 @@ const AGENT_PRESETS = [buildPreset({
 	name: "investigator",
 	description: "Find where something lives in the codebase. Use when the answer is a set of locations rather than a change. Returns a fixed table of path:line rows and nothing else.",
 	tools: "Read, Grep, Glob, Bash",
+	model: "sonnet",
 	summary: "Locates code and answers with a path:line table.",
 	body: `You locate code. You do not change it, and you say no more about any location
 than the one clause that explains why it is in the list.
 
 ${INPUT_CONTRACT}
 
+${WORK_BUDGET}
+
 ${outputContract("path:line - symbol - one clause on why it matters", [
 		"",
 		"Symbol is the function, type or constant the line belongs to, not a paraphrase",
@@ -18982,6 +19140,8 @@ approval is a list that has to be re-read to find the three rows that matter.
 
 ${INPUT_CONTRACT}
 
+${WORK_BUDGET}
+
 ${outputContract("path:line - severity - what is wrong, and what it breaks", [
 		"",
 		"Severity is one of three words:",
@@ -38572,6 +38732,38 @@ const requireThreadCapability = Effect.fn("mcp.requireThreadCapability")(functio
 	});
 	return invocation;
 });
+/**
+* The thread a control tool may act on, given what it was asked to act on.
+*
+* Two checks like `requireWatchCapability`, and for the same reason: the
+* capability says this session controls threads at all, the grant says which.
+* An omitted id resolves to the session's own thread, which is always in the
+* grant and is why the common call needs no id and so cannot name a wrong one.
+*/
+const requireThreadControlTarget = Effect.fn("mcp.requireThreadControlTarget")(function* (requested) {
+	const invocation = yield* requireThreadCapability();
+	if (requested === void 0 || requested === invocation.threadId) return {
+		invocation,
+		threadId: invocation.threadId
+	};
+	if (!invocation.controlThreadIds?.has(requested)) return yield* new ThreadControlNotPermittedError({ threadId: requested });
+	return {
+		invocation,
+		threadId: requested
+	};
+});
+/**
+* The guard on starting a thread, which is a different question from acting on
+* one: it is not "which thread" but "may this session make more of them".
+*/
+const requireThreadSpawn = Effect.fn("mcp.requireThreadSpawn")(function* () {
+	const invocation = yield* requireThreadCapability();
+	if (invocation.mayCreateThreads !== true) return yield* new ThreadSpawnNotPermittedError({
+		threadId: invocation.threadId,
+		detail: "this thread was itself started by an agent, and spawning goes one level deep so a runaway loop has a bound"
+	});
+	return invocation;
+});
 //#endregion
 //#region src/mcp/PreviewAutomationBroker.ts
 var PreviewAutomationBroker = class extends Context.Service()("@p4code/cli/mcp/PreviewAutomationBroker") {};
@@ -46688,6 +46880,7 @@ const makeRemoteTaskRepository = Effect.fn("makeRemoteTaskRepository")(function*
 			...row.projectId === null ? {} : { projectId: row.projectId },
 			...row.repositoryKey === null ? {} : { repositoryKey: row.repositoryKey },
 			...row.threadId === null ? {} : { threadId: row.threadId },
+			...row.externalRef === null ? {} : { externalRef: row.externalRef },
 			...row.parentTaskId === null ? {} : { parentTaskId: row.parentTaskId },
 			title: row.title,
 			body: row.body,
@@ -47576,7 +47769,10 @@ const makeWithOptions = Effect.fn("McpSessionRegistry.make")(function* (options
 	const crypto = yield* Crypto.Crypto;
 	const environmentId = yield* (yield* ServerEnvironment).getEnvironmentId;
 	const httpServer = yield* HttpServer.HttpServer;
-	const state = yield* SynchronizedRef.make({ records: /* @__PURE__ */ new Map() });
+	const state = yield* SynchronizedRef.make({
+		records: /* @__PURE__ */ new Map(),
+		spawnedThreadIds: /* @__PURE__ */ new Set()
+	});
 	const currentTimeMillis = options.now ? Effect.sync(options.now) : Clock.currentTimeMillis;
 	const livenessWindowMs = options.livenessWindowMs ?? DEFAULT_LIVENESS_WINDOW_MS;
 	const endpoint = httpServer.address._tag === "TcpAddress" ? `http://${getHttpMcpEndpointHost(httpServer.address.hostname)}:${httpServer.address.port}/mcp` : "http://127.0.0.1/mcp";
@@ -47597,29 +47793,35 @@ const makeWithOptions = Effect.fn("McpSessionRegistry.make")(function* (options
 			"threads"
 		]);
 		if (watchThreadIds.size > 0) capabilities.add("watch");
-		const scope = {
+		const threadId = ThreadId.make(request.threadId);
+		const scopeWith = (mayCreateThreads) => ({
 			environmentId,
-			threadId: ThreadId.make(request.threadId),
+			threadId,
 			providerSessionId,
 			providerInstanceId: ProviderInstanceId.make(request.providerInstanceId),
 			capabilities,
 			...watchThreadIds.size > 0 ? { watchThreadIds } : {},
+			mayCreateThreads,
 			issuedAt
-		};
-		yield* SynchronizedRef.update(state, ({ records }) => {
+		});
+		yield* SynchronizedRef.update(state, ({ records, spawnedThreadIds }) => {
 			const next = new Map(pruneDead(records, issuedAt));
 			next.set(tokenHash, {
 				tokenHash,
-				scope,
+				scope: scopeWith(!spawnedThreadIds.has(threadId)),
+				controlThreadIds: /* @__PURE__ */ new Set(),
 				lastAliveAt: issuedAt
 			});
-			return { records: next };
+			return {
+				records: next,
+				spawnedThreadIds
+			};
 		});
 		return { config: {
 			environmentId,
-			threadId: scope.threadId,
+			threadId,
 			providerSessionId,
-			providerInstanceId: scope.providerInstanceId,
+			providerInstanceId: ProviderInstanceId.make(request.providerInstanceId),
 			endpoint,
 			authorizationHeader: `Bearer ${rawToken}`
 		} };
@@ -47628,42 +47830,76 @@ const makeWithOptions = Effect.fn("McpSessionRegistry.make")(function* (options
 		if (rawToken.length === 0) return void 0;
 		const tokenHash = yield* hashToken(rawToken);
 		const timestamp = yield* currentTimeMillis;
-		return yield* SynchronizedRef.modify(state, ({ records }) => {
+		return yield* SynchronizedRef.modify(state, ({ records, spawnedThreadIds }) => {
 			const current = pruneDead(records, timestamp);
 			const record = current.get(tokenHash);
-			if (!record) return [void 0, { records: current }];
+			if (!record) return [void 0, {
+				records: current,
+				spawnedThreadIds
+			}];
 			const next = new Map(current);
 			next.set(tokenHash, {
 				...record,
 				lastAliveAt: timestamp
 			});
-			return [record.scope, { records: next }];
+			return [record.controlThreadIds.size === 0 ? record.scope : {
+				...record.scope,
+				capabilities: /* @__PURE__ */ new Set([...record.scope.capabilities, "watch"]),
+				controlThreadIds: record.controlThreadIds,
+				watchThreadIds: /* @__PURE__ */ new Set([...record.scope.watchThreadIds ?? [], ...record.controlThreadIds])
+			}, {
+				records: next,
+				spawnedThreadIds
+			}];
 		});
 	});
 	const touch = Effect.fn("McpSessionRegistry.touch")(function* (threadId) {
 		const timestamp = yield* currentTimeMillis;
-		yield* SynchronizedRef.update(state, ({ records }) => {
+		yield* SynchronizedRef.update(state, ({ records, spawnedThreadIds }) => {
 			const current = pruneDead(records, timestamp);
 			const next = new Map(current);
 			for (const [tokenHash, record] of current) if (record.scope.threadId === threadId) next.set(tokenHash, {
 				...record,
 				lastAliveAt: timestamp
 			});
-			return { records: next };
+			return {
+				records: next,
+				spawnedThreadIds
+			};
+		});
+	});
+	const recordSpawnedThread = Effect.fn("McpSessionRegistry.recordSpawnedThread")(function* (input) {
+		yield* SynchronizedRef.update(state, ({ records, spawnedThreadIds }) => {
+			const next = new Map(records);
+			for (const [tokenHash, record] of records) if (record.scope.providerSessionId === input.providerSessionId) next.set(tokenHash, {
+				...record,
+				controlThreadIds: /* @__PURE__ */ new Set([...record.controlThreadIds, input.threadId])
+			});
+			return {
+				records: next,
+				spawnedThreadIds: /* @__PURE__ */ new Set([...spawnedThreadIds, input.threadId])
+			};
 		});
 	});
-	const revokeWhere = (predicate) => SynchronizedRef.update(state, ({ records }) => ({ records: new Map(Array.from(records).filter(([, record]) => !predicate(record))) }));
+	const revokeWhere = (predicate) => SynchronizedRef.update(state, ({ records, spawnedThreadIds }) => ({
+		records: new Map(Array.from(records).filter(([, record]) => !predicate(record))),
+		spawnedThreadIds
+	}));
 	return McpSessionRegistry.of({
 		issue,
 		resolve,
 		touch,
+		recordSpawnedThread,
 		revokeProviderSession: Effect.fn("McpSessionRegistry.revokeProviderSession")(function* (providerSessionId) {
 			yield* revokeWhere((record) => record.scope.providerSessionId === providerSessionId);
 		}),
 		revokeThread: Effect.fn("McpSessionRegistry.revokeThread")(function* (threadId) {
 			yield* revokeWhere((record) => record.scope.threadId === threadId);
 		}),
-		revokeAll: SynchronizedRef.set(state, { records: /* @__PURE__ */ new Map() })
+		revokeAll: SynchronizedRef.update(state, ({ spawnedThreadIds }) => ({
+			records: /* @__PURE__ */ new Map(),
+			spawnedThreadIds
+		}))
 	});
 });
 let activeMcpSessionRegistry;
@@ -86346,6 +86582,35 @@ const TaskToolkitHandlersLive = TaskToolkit.toLayer({
 	})
 });
 //#endregion
+//#region src/orchestration/pendingThreadSettles.ts
+/**
+* Threads that asked to settle while their session was still running.
+*
+* The decider refuses `thread.settle` for a thread whose session is starting or
+* running, and an agent settling its own thread always calls from inside that
+* session - so the command it wants can never be the command it sends. The
+* intent is recorded here instead and replayed when the session stops, which is
+* what "settle this thread" meant from the agent's side anyway: finish, then
+* close.
+*
+* A module-level set rather than a service because it has to be reachable from
+* two layer trees that do not otherwise meet - an MCP tool handler on one side,
+* the provider command reactor on the other - and threading a new service
+* through both to hold a set of ids is more wiring than the thing is worth.
+* `McpProviderSession` and the active-registry handle are the same shape for
+* the same reason. It is intentionally not durable: a queued settle belongs to
+* a session, and a server restart has already ended every session there was.
+*/
+const pending = /* @__PURE__ */ new Set();
+const queueThreadSettle = (threadId) => {
+	pending.add(threadId);
+};
+/**
+* Removes the intent and reports whether there was one, so a caller cannot
+* settle the same thread twice by reading and then forgetting to clear.
+*/
+const takeQueuedThreadSettle = (threadId) => pending.delete(threadId);
+//#endregion
 //#region src/sync/assetCompression.ts
 /**
 * Checking that a compressed asset still says what the original said.
@@ -86584,12 +86849,28 @@ const backupFileName = (input) => `${input.fileName}.${input.atIso.replace(/[:.]
 //#endregion
 //#region src/mcp/toolkits/threads/tools.ts
 /**
-* Self-scoped on purpose: neither tool takes a thread id. The thread acted on
-* is always the one in `McpInvocationScope`, exactly as `task_current` resolves
-* it, so a leaked per-session token cannot reach any other thread. Delete,
-* create and archive are deliberately not exposed; settle could never succeed
-* from here because the decider refuses it while the calling session is alive.
+* Scoped to what this session started, on purpose.
+*
+* A control tool may name a thread, but only one this session created with
+* `thread_spawn`; omitting the id means the session's own thread, which is the
+* common case and the one that cannot be got wrong. The grant lives on the
+* credential in `McpSessionRegistry`, so a leaked per-session token still
+* reaches only the work that token itself began, and its reach cannot widen
+* because something changed on the board.
+*
+* Delete and archive stay unexposed. Deletion is the one irreversible action in
+* this file and a thread carries its whole transcript, which is a worse thing
+* to lose than the task row the task toolkit withheld delete for.
+*
+* `thread_spawn` goes one level: a thread that was itself spawned is issued a
+* credential that cannot spawn, so a loop meets a bound rather than a request
+* not to loop. `thread_settle` on a live session is queued and applied when the
+* session stops, because the decider refuses an immediate settle there and a
+* call from a thread's own session always arrives while it is alive.
+*
+* @module mcp/toolkits/threads/tools
 */
+/** Self-only, and staying that way: `thread_configure` is where a title on another thread is set. */
 const ThreadRenameTool = Tool.make("thread_rename", {
 	description: "Rename this agent session's own thread. Use it when the seeded title no longer matches what the thread turned out to be about. Only the current thread can be renamed; no other thread is reachable.",
 	parameters: ThreadRenameInput,
@@ -86601,6 +86882,54 @@ const ThreadRenameTool = Tool.make("thread_rename", {
 		Crypto.Crypto
 	]
 }).annotate(Tool.Title, "Rename this thread").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true);
+const ThreadSpawnTool = Tool.make("thread_spawn", {
+	description: "Start a new agent thread and send it a first message, then return its id. Use it to hand a piece of work to a fresh thread - a subtask you just planned, a job that wants its own transcript. The new thread inherits this one's project, model and permission mode unless you say otherwise, and can then be watched with thread_watch_events and adjusted with thread_configure. A thread that was itself started this way cannot start another.",
+	parameters: ThreadSpawnInput,
+	success: ThreadSpawnResult,
+	failure: ThreadControlToolError,
+	dependencies: [
+		McpInvocationContext,
+		McpSessionRegistry,
+		OrchestrationEngineService,
+		ProjectionThreadRepository,
+		Crypto.Crypto
+	]
+}).annotate(Tool.Title, "Start a thread").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, false);
+const ThreadConfigureTool = Tool.make("thread_configure", {
+	description: "Change a thread's settings: title, model, permission mode, interaction mode, compression, and whether it may use subagents without asking. Omit threadId to configure this session's own thread; name one only if this session started it. Every field is optional and an omitted field is left alone; the settings actually changed come back in the result.",
+	parameters: ThreadConfigureInput,
+	success: ThreadConfigureResult,
+	failure: ThreadControlToolError,
+	dependencies: [
+		McpInvocationContext,
+		OrchestrationEngineService,
+		Crypto.Crypto
+	]
+}).annotate(Tool.Title, "Configure a thread").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true);
+const ThreadSettleTool = Tool.make("thread_settle", {
+	description: "Settle a thread, marking its work finished so it drops out of the active list. Omit threadId for this session's own thread; name one only if this session started it. A thread whose session is still running cannot be settled on the spot, so the request is recorded and applied when that session stops - the result says which of the two happened.",
+	parameters: ThreadSettleInput,
+	success: ThreadSettleResult,
+	failure: ThreadControlToolError,
+	dependencies: [
+		McpInvocationContext,
+		OrchestrationEngineService,
+		ProjectionThreadRepository,
+		ProjectionThreadSessionRepository,
+		Crypto.Crypto
+	]
+}).annotate(Tool.Title, "Settle a thread").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true);
+const ThreadSnoozeTool = Tool.make("thread_snooze", {
+	description: "Snooze a thread until a given time, hiding it from the active list until then. Omit threadId for this session's own thread; name one only if this session started it.",
+	parameters: ThreadSnoozeInput,
+	success: ThreadSnoozeResult,
+	failure: ThreadControlToolError,
+	dependencies: [
+		McpInvocationContext,
+		OrchestrationEngineService,
+		Crypto.Crypto
+	]
+}).annotate(Tool.Title, "Snooze a thread").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true);
 const MemoryAppendTool = Tool.make("memory_append", {
 	description: "Append a block of markdown to the user-scope memory file (CLAUDE.md by default, AGENTS.md on request). Use it to record a durable preference or fact the user asked to remember. Appends only - it never rewrites or removes existing memory.",
 	parameters: MemoryAppendInput,
@@ -86636,7 +86965,7 @@ const AssetCompressTool = Tool.make("asset_compress", {
 		Path.Path
 	]
 }).annotate(Tool.Title, "Compress an asset").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.Idempotent, false);
-const ThreadToolkit = Toolkit.make(ThreadRenameTool, MemoryAppendTool, AssetCompressTool);
+const ThreadToolkit = Toolkit.make(ThreadSpawnTool, ThreadConfigureTool, ThreadSettleTool, ThreadSnoozeTool, ThreadRenameTool, MemoryAppendTool, AssetCompressTool);
 //#endregion
 //#region src/mcp/toolkits/threads/handlers.ts
 const DEFAULT_MEMORY_APPEND_TARGET = "CLAUDE.md";
@@ -86653,7 +86982,181 @@ const COMPRESS_BACKUP_DIRNAME = "asset-compress-backups";
 const COMPRESSIBLE_EXTENSION = ".md";
 /** The same test the asset readers use: a NUL is what breaks a JSON text column. */
 const looksBinary = (content) => content.includes("\0");
+/**
+* Every control command shares this: mint an id, dispatch, and turn a decider
+* refusal into one error the agent can read.
+*/
+const dispatchControl = Effect.fn("mcp.threads.dispatchControl")(function* (command, threadId) {
+	yield* (yield* OrchestrationEngineService).dispatch(command).pipe(Effect.mapError((cause) => new ThreadControlRejectedError({
+		threadId,
+		commandType: command.type,
+		detail: cause.message
+	})));
+});
+const newCommandId = Effect.gen(function* () {
+	const crypto = yield* Crypto.Crypto;
+	return CommandId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
+});
 const ThreadToolkitHandlersLive = ThreadToolkit.toLayer({
+	thread_spawn: (input) => Effect.gen(function* () {
+		const invocation = yield* requireThreadSpawn();
+		const registry = yield* McpSessionRegistry;
+		const threads = yield* ProjectionThreadRepository;
+		const crypto = yield* Crypto.Crypto;
+		const parent = yield* threads.getById({ threadId: invocation.threadId }).pipe(Effect.mapError((cause) => new ThreadSpawnNotPermittedError({
+			threadId: invocation.threadId,
+			detail: `this thread could not be read to take its defaults from: ${cause.message}`
+		})));
+		if (Option.isNone(parent)) return yield* new ThreadSpawnNotPermittedError({
+			threadId: invocation.threadId,
+			detail: "this thread is not on the board, so there is nothing to start a thread beside"
+		});
+		const template = parent.value;
+		const projectId = input.projectId ?? template.projectId;
+		const runtimeMode = input.runtimeMode ?? template.runtimeMode;
+		const interactionMode = input.interactionMode ?? template.interactionMode;
+		const compressMode = input.compressMode ?? template.compressMode;
+		const unpromptedSubagents = input.unpromptedSubagents ?? template.unpromptedSubagents === 1;
+		const threadId = ThreadId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
+		const createdAt = DateTime.formatIso(yield* DateTime.now);
+		yield* dispatchControl({
+			type: "thread.create",
+			commandId: yield* newCommandId,
+			threadId,
+			projectId,
+			title: input.title,
+			modelSelection: template.modelSelection,
+			runtimeMode,
+			interactionMode,
+			compressMode,
+			unpromptedSubagents,
+			branch: null,
+			worktreePath: null,
+			createdAt
+		}, threadId);
+		yield* registry.recordSpawnedThread({
+			providerSessionId: invocation.providerSessionId,
+			threadId
+		});
+		yield* dispatchControl({
+			type: "thread.turn.start",
+			commandId: yield* newCommandId,
+			threadId,
+			message: {
+				messageId: MessageId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie)),
+				role: "user",
+				text: input.prompt,
+				attachments: []
+			},
+			modelSelection: template.modelSelection,
+			titleSeed: input.title,
+			runtimeMode,
+			interactionMode,
+			compressMode,
+			unpromptedSubagents,
+			createdAt
+		}, threadId);
+		return {
+			threadId,
+			projectId,
+			title: input.title
+		};
+	}),
+	thread_configure: (input) => Effect.gen(function* () {
+		const { threadId } = yield* requireThreadControlTarget(input.threadId);
+		const createdAt = DateTime.formatIso(yield* DateTime.now);
+		const applied = [];
+		if (input.title !== void 0 || input.modelSelection !== void 0) {
+			yield* dispatchControl({
+				type: "thread.meta.update",
+				commandId: yield* newCommandId,
+				threadId,
+				...input.title !== void 0 ? { title: input.title } : {},
+				...input.modelSelection !== void 0 ? { modelSelection: input.modelSelection } : {}
+			}, threadId);
+			if (input.title !== void 0) applied.push("title");
+			if (input.modelSelection !== void 0) applied.push("modelSelection");
+		}
+		if (input.runtimeMode !== void 0) {
+			yield* dispatchControl({
+				type: "thread.runtime-mode.set",
+				commandId: yield* newCommandId,
+				threadId,
+				runtimeMode: input.runtimeMode,
+				createdAt
+			}, threadId);
+			applied.push("runtimeMode");
+		}
+		if (input.interactionMode !== void 0) {
+			yield* dispatchControl({
+				type: "thread.interaction-mode.set",
+				commandId: yield* newCommandId,
+				threadId,
+				interactionMode: input.interactionMode,
+				createdAt
+			}, threadId);
+			applied.push("interactionMode");
+		}
+		if (input.compressMode !== void 0) {
+			yield* dispatchControl({
+				type: "thread.compress-mode.set",
+				commandId: yield* newCommandId,
+				threadId,
+				compressMode: input.compressMode,
+				createdAt
+			}, threadId);
+			applied.push("compressMode");
+		}
+		if (input.unpromptedSubagents !== void 0) {
+			yield* dispatchControl({
+				type: "thread.unprompted-subagents.set",
+				commandId: yield* newCommandId,
+				threadId,
+				unpromptedSubagents: input.unpromptedSubagents,
+				createdAt
+			}, threadId);
+			applied.push("unpromptedSubagents");
+		}
+		return {
+			threadId,
+			applied
+		};
+	}),
+	thread_settle: (input) => Effect.gen(function* () {
+		const { threadId } = yield* requireThreadControlTarget(input.threadId);
+		const threads = yield* ProjectionThreadRepository;
+		const session = yield* (yield* ProjectionThreadSessionRepository).getByThreadId({ threadId }).pipe(Effect.catchCause(() => Effect.succeed(Option.none())));
+		if (!(Option.isSome(session) && (session.value.status === "starting" || session.value.status === "running"))) {
+			yield* dispatchControl({
+				type: "thread.settle",
+				commandId: yield* newCommandId,
+				threadId
+			}, threadId);
+			return {
+				threadId,
+				outcome: "settled"
+			};
+		}
+		queueThreadSettle(threadId);
+		yield* threads.getById({ threadId }).pipe(Effect.orDie);
+		return {
+			threadId,
+			outcome: "queued"
+		};
+	}),
+	thread_snooze: (input) => Effect.gen(function* () {
+		const { threadId } = yield* requireThreadControlTarget(input.threadId);
+		yield* dispatchControl({
+			type: "thread.snooze",
+			commandId: yield* newCommandId,
+			threadId,
+			snoozedUntil: input.snoozedUntil
+		}, threadId);
+		return {
+			threadId,
+			snoozedUntil: input.snoozedUntil
+		};
+	}),
 	thread_rename: (input) => Effect.gen(function* () {
 		const invocation = yield* requireThreadCapability();
 		const engine = yield* OrchestrationEngineService;
@@ -88214,13 +88717,34 @@ const make$2 = Effect.gen(function* () {
 		if (providerError) return providerError.detail;
 		return Cause.pretty(cause);
 	};
+	/**
+	* Applies a settle an agent asked for while its session was still running.
+	*
+	* The decider refuses `thread.settle` for a live session, so `thread_settle`
+	* over MCP records the intent instead of failing. This is the moment it
+	* becomes legal: the session has just been written as stopped, so the same
+	* command the agent could not send now succeeds. Taken from the queue rather
+	* than read, so a second stop cannot settle the thread twice.
+	*/
+	const flushQueuedSettle = Effect.fnUntraced(function* (threadId) {
+		if (!takeQueuedThreadSettle(threadId)) return;
+		const commandId = yield* serverCommandId("queued-thread-settle");
+		yield* orchestrationEngine.dispatch({
+			type: "thread.settle",
+			commandId,
+			threadId
+		}).pipe(Effect.catchCause((cause) => Effect.logDebug("queued thread settle did not apply", {
+			threadId,
+			cause
+		})));
+	});
 	const setThreadSession = (input) => serverCommandId("provider-session-set").pipe(Effect.flatMap((commandId) => orchestrationEngine.dispatch({
 		type: "thread.session.set",
 		commandId,
 		threadId: input.threadId,
 		session: input.session,
 		createdAt: input.createdAt
-	})));
+	})), Effect.tap(() => input.session.status === "stopped" || input.session.status === "error" ? flushQueuedSettle(input.threadId) : Effect.void));
 	const setThreadSessionErrorOnTurnStartFailure = Effect.fnUntraced(function* (input) {
 		const thread = yield* resolveThread(input.threadId);
 		if (!thread) return;