@namzu/sdk 39.0.0 → 41.0.0

package/src/connector/mcp/x-mcp-header.ts

@@ -0,0 +1,322 @@
+import { MCP_PARAM_HEADER_PREFIX } from '../../constants/mcp/index.js'
+
+/**
+ * The extension property a server writes into a tool parameter's schema to
+ * ask that the parameter's value be mirrored into an HTTP request header.
+ *
+ * Its value is the NAME PORTION of `Mcp-Param-{name}`, so an annotation
+ * reading `"Region"` produces `Mcp-Param-Region`. The point of mirroring is
+ * that a load balancer or a policy proxy can route and authorise a tool call
+ * without parsing JSON-RPC — which is also why a malformed annotation is not
+ * a cosmetic problem: a value carrying a line feed would end the field and
+ * let a server's own tool definition inject a header namzu never wrote.
+ */
+const X_MCP_HEADER = 'x-mcp-header'
+
+/**
+ * HTTP field-name token syntax — RFC 9110 §5.1 `1*tchar`.
+ *
+ * Non-emptiness (`+`), the absence of CR, LF and every other control
+ * character, and the absence of spaces and separators all fall out of this
+ * one expression. They are still checked separately below, in the order the
+ * spec lists them, so a refusal names the constraint that was actually
+ * broken rather than the most general one that happens to cover it.
+ */
+const FIELD_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+/** The JSON Schema keywords whose value is a MAP of schemas, not a schema. */
+const SCHEMA_MAP_KEYWORDS = new Set([
+	'properties',
+	'patternProperties',
+	'$defs',
+	'definitions',
+	'dependentSchemas',
+])
+
+/**
+ * Keywords holding INSTANCE data rather than sub-schemas.
+ *
+ * Never descended into. A `default` of `{ "x-mcp-header": "X" }` is a
+ * perfectly ordinary example value for an object-typed parameter, and
+ * reading it as an annotation would refuse a tool over a string that was
+ * never a schema at all.
+ */
+const INSTANCE_VALUE_KEYWORDS = new Set(['default', 'examples', 'example', 'const', 'enum'])
+
+/** The parameter types a value may be mirrored from. `number` is excluded. */
+const MIRRORABLE_TYPES = new Set(['string', 'boolean', 'integer'])
+
+/**
+ * One validated `x-mcp-header` annotation: which header to write, which
+ * argument to read it from, and how to spell that argument.
+ *
+ * `path` is the exact chain of `properties` keys leading to the annotated
+ * property, which is also the path into a call's `arguments` object. It is
+ * produced only by {@link validateMcpHeaderAnnotations}, so a binding cannot
+ * exist for a property that was not statically reachable.
+ */
+export interface McpParamHeaderBinding {
+	/** The full field name, prefix included — `Mcp-Param-Region`. */
+	readonly header: string
+	/** The chain of `properties` keys, read against the call's `arguments`. */
+	readonly path: readonly string[]
+	readonly type: 'string' | 'boolean' | 'integer'
+}
+
+/**
+ * Whether a tool definition may be exposed, and what it asked to mirror.
+ *
+ * A verdict about the WHOLE tool, not about one annotation: the spec makes a
+ * single bad annotation invalidate the tool definition, because a client
+ * that mirrored the rest would send a request the server then rejects for
+ * headers it cannot explain.
+ */
+export type McpHeaderAnnotationVerdict =
+	| { readonly ok: true; readonly bindings: readonly McpParamHeaderBinding[] }
+	| { readonly ok: false; readonly reason: string }
+
+const NO_BINDINGS: McpHeaderAnnotationVerdict = { ok: true, bindings: [] }
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** One annotation found anywhere in a schema, and where it was found. */
+interface FoundAnnotation {
+	readonly value: unknown
+	/** A dotted path through the raw schema, for a refusal a person reads. */
+	readonly where: string
+	/** The `properties` chain, or `undefined` when it is not reachable by one. */
+	readonly path: readonly string[] | undefined
+	/** The `type` declared beside the annotation. */
+	readonly declaredType: unknown
+}
+
+/**
+ * Every property reachable from the root through `properties` keys ALONE,
+ * mapped to its path.
+ *
+ * This is the whole of the static-reachability rule, and writing it as its
+ * own walk is deliberate. The tempting implementation — resolve `$ref`s and
+ * flatten `allOf` first, then walk the result — accepts exactly what the
+ * spec forbids: a property reached through a `$ref` looks like an ordinary
+ * `properties` child once the reference has been followed. This walk never
+ * follows one, so a `$ref`-reached annotation simply is not in this map.
+ */
+function reachableByProperties(root: Record<string, unknown>): Map<object, string[]> {
+	const reachable = new Map<object, string[]>()
+	// A schema is JSON and so is usually a tree, but nothing stops a caller
+	// building one with a shared (or cyclic) node in it, and this walk is
+	// depth-first.
+	const seen = new Set<object>([root])
+
+	const walk = (node: Record<string, unknown>, path: readonly string[]): void => {
+		const properties = node.properties
+		if (!isPlainObject(properties)) return
+		for (const [key, child] of Object.entries(properties)) {
+			if (!isPlainObject(child) || seen.has(child)) continue
+			seen.add(child)
+			const childPath = [...path, key]
+			reachable.set(child, childPath)
+			walk(child, childPath)
+		}
+	}
+
+	walk(root, [])
+	return reachable
+}
+
+/**
+ * Every `x-mcp-header` in the schema, wherever it sits.
+ *
+ * Deliberately a whole-schema scan rather than a scan of the reachable
+ * properties: an annotation under `items`, inside a `oneOf` branch or in
+ * `$defs` is not something to ignore, it is something that invalidates the
+ * tool. Finding only the reachable ones would silently admit exactly the
+ * definitions the spec says to refuse.
+ *
+ * The walk knows which keywords hold a MAP of schemas so that a parameter
+ * legitimately NAMED `x-mcp-header` is not mistaken for an annotation on the
+ * map that holds it, and refuses to descend into keywords holding instance
+ * data. Everything else is descended into generically, because a vendor
+ * keyword can nest a schema and an annotation buried in one is still
+ * unreachable and still invalid.
+ */
+function annotationsIn(root: Record<string, unknown>): FoundAnnotation[] {
+	const reachable = reachableByProperties(root)
+	const found: FoundAnnotation[] = []
+	const seen = new Set<object>()
+
+	const visit = (node: unknown, where: string): void => {
+		if (Array.isArray(node)) {
+			node.forEach((item, index) => visit(item, `${where}[${index}]`))
+			return
+		}
+		if (!isPlainObject(node) || seen.has(node)) return
+		seen.add(node)
+
+		if (Object.hasOwn(node, X_MCP_HEADER)) {
+			found.push({
+				value: node[X_MCP_HEADER],
+				where: where === '' ? 'the schema root' : where,
+				path: reachable.get(node),
+				declaredType: node.type,
+			})
+		}
+
+		for (const [key, child] of Object.entries(node)) {
+			if (key === X_MCP_HEADER || INSTANCE_VALUE_KEYWORDS.has(key)) continue
+			const childWhere = where === '' ? key : `${where}.${key}`
+			if (SCHEMA_MAP_KEYWORDS.has(key)) {
+				if (!isPlainObject(child)) continue
+				for (const [name, schema] of Object.entries(child)) visit(schema, `${childWhere}.${name}`)
+				continue
+			}
+			visit(child, childWhere)
+		}
+	}
+
+	visit(root, '')
+	return found
+}
+
+/** A value quoted into a refusal without carrying its control bytes along. */
+function quoted(value: unknown): string {
+	return typeof value === 'string' ? JSON.stringify(value) : String(value)
+}
+
+function describeType(declared: unknown): string {
+	if (declared === undefined) return 'a parameter with no declared `type`'
+	if (typeof declared !== 'string') return `a parameter whose \`type\` is ${quoted(declared)}`
+	return `a \`${declared}\` parameter`
+}
+
+function refuse(reason: string): McpHeaderAnnotationVerdict {
+	return { ok: false, reason }
+}
+
+/**
+ * Decide whether a tool may be exposed, and collect what it asked to mirror.
+ *
+ * The six constraints, in the spec's own order: non-empty; HTTP field-name
+ * token syntax; no control characters; case-insensitively unique across the
+ * whole `inputSchema`; applied only to `string`, `boolean` or `integer`
+ * (never `number`); and statically reachable through a chain of `properties`
+ * keys alone.
+ *
+ * Returns a REASON rather than throwing, because the caller's job is to drop
+ * one tool and keep the rest: a listing where one definition is malformed
+ * must still deliver the others, and an exception here would take the whole
+ * listing down with it.
+ */
+export function validateMcpHeaderAnnotations(inputSchema: unknown): McpHeaderAnnotationVerdict {
+	if (!isPlainObject(inputSchema)) return NO_BINDINGS
+
+	const found = annotationsIn(inputSchema)
+	if (found.length === 0) return NO_BINDINGS
+
+	const bindings: McpParamHeaderBinding[] = []
+	/** Lowercased name to the spelling that claimed it first. */
+	const claimed = new Map<string, string>()
+
+	for (const annotation of found) {
+		const at = `at ${annotation.where}`
+		const name = annotation.value
+
+		if (typeof name !== 'string') {
+			return refuse(`\`x-mcp-header\` ${at} is ${quoted(name)}, which is not a string`)
+		}
+		if (name.length === 0) {
+			return refuse(`\`x-mcp-header\` ${at} is empty`)
+		}
+		if (/[\r\n]/.test(name)) {
+			return refuse(
+				`\`x-mcp-header\` ${quoted(name)} ${at} contains a carriage return or line feed`,
+			)
+		}
+		if (!FIELD_NAME_TOKEN.test(name)) {
+			return refuse(
+				`\`x-mcp-header\` ${quoted(name)} ${at} is not HTTP field-name token syntax (RFC 9110 1*tchar)`,
+			)
+		}
+
+		const first = claimed.get(name.toLowerCase())
+		if (first !== undefined) {
+			return refuse(
+				`\`x-mcp-header\` ${quoted(name)} ${at} repeats ${quoted(first)}; header names are compared without regard to case`,
+			)
+		}
+		claimed.set(name.toLowerCase(), name)
+
+		if (annotation.path === undefined) {
+			return refuse(
+				`\`x-mcp-header\` ${quoted(name)} ${at} is not statically reachable: the chain from the schema root must consist solely of \`properties\` keys`,
+			)
+		}
+
+		const declared = annotation.declaredType
+		if (typeof declared !== 'string' || !MIRRORABLE_TYPES.has(declared)) {
+			return refuse(
+				`\`x-mcp-header\` ${quoted(name)} ${at} annotates ${describeType(declared)}; only \`string\`, \`boolean\` and \`integer\` may be mirrored, and \`number\` is excluded`,
+			)
+		}
+
+		bindings.push({
+			header: `${MCP_PARAM_HEADER_PREFIX}${name}`,
+			path: annotation.path,
+			type: declared as McpParamHeaderBinding['type'],
+		})
+	}
+
+	return { ok: true, bindings }
+}
+
+function readPath(root: unknown, path: readonly string[]): unknown {
+	let cursor: unknown = root
+	for (const key of path) {
+		if (!isPlainObject(cursor)) return undefined
+		cursor = cursor[key]
+	}
+	return cursor
+}
+
+/**
+ * How one argument value is spelled in a header field, or `undefined` when
+ * it is not sent at all.
+ *
+ * Four reasons a header is omitted, and only the first two are ordinary: the
+ * argument is absent, or it is `null` — both of which the spec says to omit
+ * rather than send empty. The other two are a server contradicting its own
+ * schema (a value whose runtime type is not the declared one) and an integer
+ * outside the range the spec bounds these to, ±(2^53−1) — exactly
+ * JavaScript's safe-integer range, which is the range in which the number
+ * this client parsed is still the number the server sent. Sending either
+ * would put a value on the wire that disagrees with the body it mirrors,
+ * which is the one thing a conforming server rejects outright.
+ */
+function headerValue(type: McpParamHeaderBinding['type'], value: unknown): string | undefined {
+	if (value === undefined || value === null) return undefined
+	if (type === 'string') return typeof value === 'string' ? value : undefined
+	if (type === 'boolean') return typeof value === 'boolean' ? String(value) : undefined
+	return typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : undefined
+}
+
+/**
+ * The `Mcp-Param-*` field values for one call's arguments, unencoded.
+ *
+ * Returns the values as the BODY carries them; wrapping a value that cannot
+ * be written into a header field verbatim is the envelope's job, so the
+ * sentinel rule lives in one place for `Mcp-Name` and `Mcp-Param-*` alike
+ * rather than being reimplemented here.
+ */
+export function mcpParamHeaderValues(
+	bindings: readonly McpParamHeaderBinding[],
+	args: unknown,
+): Record<string, string> {
+	const headers: Record<string, string> = {}
+	for (const binding of bindings) {
+		const written = headerValue(binding.type, readPath(args, binding.path))
+		if (written !== undefined) headers[binding.header] = written
+	}
+	return headers
+}

package/src/constants/mcp/index.ts

@@ -1,26 +1,65 @@
+import type { McpLegacyVersion, McpModernVersion } from '../../types/connector/mcp.js'
+
 /**
- * The protocol version this client ADVERTISES in `initialize`.
+ * The MCP spec revisions this client speaks WITHOUT the `initialize`
+ * handshake, newest first.
  *
- * Deliberately the version namzu actually implements, not the newest one
- * published. Advertising a version whose requirements are unimplemented is
- * worse than advertising an older one honestly: the server tailors its
- * behavior to what the client claims, and the mismatch surfaces later as
- * a malformed exchange rather than a clean negotiation failure. Raising
- * this is a conformance task, not a constant edit.
+ * The modern era removes that handshake entirely: a connection is resolved
+ * by probing with `server/discover`, and every request afterwards carries
+ * its own protocol version, client capabilities and client info in `_meta`
+ * instead of inheriting them from a session. `connect()` tries the newest
+ * entry here FIRST and falls back to the legacy handshake below only when
+ * the probe says the peer does not speak it.
  */
-export const MCP_PROTOCOL_VERSION = '2024-11-05'
+export const MCP_MODERN_VERSIONS: readonly McpModernVersion[] = ['2026-07-28']
 
 /**
- * Versions this client can speak if a server negotiates down (or up) to
- * one of them, newest first.
+ * Protocol versions this client offers and accepts through the legacy
+ * `initialize` handshake, newest first.
+ *
+ * `connect()` offers `MCP_LEGACY_VERSIONS[0]` — the newest one — in a
+ * single `initialize` request. A server is free to answer with any version
+ * in `MCP_SUPPORTED_PROTOCOL_VERSIONS` below, not only the one offered:
+ * that is how the handshake is specified. namzu used to advertise and
+ * accept only `2024-11-05`, which refused the overwhelming majority of
+ * servers deployed since — every one that negotiated down to 2025-03-26,
+ * 2025-06-18 or 2025-11-25 instead of all the way to the oldest revision.
  *
- * A server is free to answer `initialize` with a version other than the one
- * the client asked for — that is how the handshake is specified. namzu used
- * to ignore the answer entirely and carry on regardless, so a server
- * responding with a version we cannot speak looked exactly like a
- * successful connection until something downstream broke oddly.
+ * This is deliberately a single round trip, never a per-version waterfall:
+ * the spec's own backward-compatibility algorithm offers one version and
+ * honors whatever the server answers
+ * (https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle).
+ * A three-step retry loop is three times the latency for a code path no
+ * server expects, and `protocol-negotiation.test.ts` counts `initialize`
+ * frames so nobody reintroduces one.
  */
-export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = ['2024-11-05']
+export const MCP_LEGACY_VERSIONS: readonly McpLegacyVersion[] = [
+	'2025-11-25',
+	'2025-06-18',
+	'2025-03-26',
+	'2024-11-05',
+]
+
+/**
+ * Every protocol version this client can speak, in any capacity — offered
+ * in `initialize`, or merely a value it will not refuse if a server
+ * answers with it.
+ *
+ * The single authority for "can we speak this?": a server negotiating to
+ * a version outside this list is refused rather than let through to break
+ * confusingly downstream. Advertising or accepting a version whose
+ * requirements are unimplemented is worse than being honest about a
+ * narrower set — the server tailors its behavior to what the client
+ * claims, and the mismatch would otherwise surface later as a malformed
+ * exchange instead of a clean negotiation failure. That reasoning is why
+ * this list once held a single entry; it now argues for the broadened set
+ * above, not against it, because every version listed here is one namzu
+ * has actually verified it can carry a legacy `initialize` handshake for.
+ */
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
+	...MCP_MODERN_VERSIONS,
+	...MCP_LEGACY_VERSIONS,
+]
 
 /**
  * Default deadline for one MCP JSON-RPC round trip.
@@ -33,3 +72,93 @@ export const DEFAULT_MCP_REQUEST_TIMEOUT_MS = 30_000
 
 /** JSON-RPC 2.0 reserved code for an unimplemented method. */
 export const JSON_RPC_METHOD_NOT_FOUND = -32601
+
+/**
+ * JSON-RPC codes a server may use to say "that resource does not exist".
+ *
+ * The current spec's resource-read error path uses the application-defined
+ * `-32002`, but a server on an older version may still answer with the
+ * generic `-32602` ("Invalid params") for the same condition — and the spec
+ * explicitly says a client SHOULD keep accepting it. Both are listed so a
+ * caller distinguishing "not found" from "actually broken" does not have to
+ * special-case the older code itself.
+ */
+export const RESOURCE_NOT_FOUND_CODES: readonly number[] = [-32602, -32002]
+
+/**
+ * The method a modern server answers with its `DiscoverResult`.
+ *
+ * Mandatory for a 2026-07-28 server and optional for a client, which is
+ * exactly what makes it a usable era probe: a server that answers it speaks
+ * the modern protocol, and a legacy server answers it with an
+ * implementation-defined error — commonly `-32601` or `-32602` — or not at
+ * all.
+ */
+export const MCP_DISCOVER_METHOD = 'server/discover'
+
+/**
+ * How long an era probe waits for an answer before deciding the peer is
+ * legacy.
+ *
+ * A heuristic with no good universal value, which is why it is
+ * configurable per client (`MCPClientConfig.eraProbeTimeoutMs`). Too short
+ * and a slow-starting server is misclassified as legacy; too long and every
+ * legacy server pays the wait on every connect. Two seconds is long enough
+ * for a process that has already spawned to answer one request and short
+ * enough to sit comfortably inside an operator-facing connect deadline —
+ * and the era cache means a given origin or command pays it once, not once
+ * per connection.
+ */
+export const DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS = 2_000
+
+/**
+ * The HTTP statuses a legacy origin answers a modern request with.
+ *
+ * A status alone is NOT the fallback signal: a modern server answers an
+ * unknown method with `404` and a JSON-RPC `-32601` body specifically so a
+ * client can tell it apart from the `404` of a server that has never heard
+ * of the modern protocol. The body decides; this list only says which
+ * responses are worth reading a body from.
+ */
+export const MCP_MODERN_HTTP_FALLBACK_STATUSES: readonly number[] = [400, 404, 405]
+
+/**
+ * The reserved `_meta` keys a modern request and reply carry.
+ *
+ * `protocolVersion` and `clientCapabilities` are REQUIRED on every modern
+ * request; `clientInfo` is a SHOULD. `serverInfo` travels the other way —
+ * it is how a `DiscoverResult` names the peer, and is what `connect()`
+ * reads to synthesise the `MCPInitializeResult` a host still expects.
+ */
+export const MCP_META_PROTOCOL_VERSION = 'io.modelcontextprotocol/protocolVersion'
+export const MCP_META_CLIENT_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities'
+export const MCP_META_CLIENT_INFO = 'io.modelcontextprotocol/clientInfo'
+export const MCP_META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo'
+
+/**
+ * The request headers a modern Streamable HTTP request mirrors its body
+ * with, so an intermediary can route and authorise a call without parsing
+ * JSON-RPC.
+ *
+ * `MCP_PROTOCOL_VERSION_HEADER` is shared with the later legacy revisions,
+ * where it means the version negotiated by `initialize` rather than the one
+ * carried in this request's own `_meta`.
+ */
+export const MCP_PROTOCOL_VERSION_HEADER = 'MCP-Protocol-Version'
+export const MCP_METHOD_HEADER = 'Mcp-Method'
+export const MCP_NAME_HEADER = 'Mcp-Name'
+export const MCP_PARAM_HEADER_PREFIX = 'Mcp-Param-'
+
+/**
+ * The methods whose target is named in the `Mcp-Name` header, and the
+ * parameter each one's name is read from.
+ *
+ * Required for compliance on Streamable HTTP: an intermediary that can see
+ * WHICH tool is being called without reading the body is the whole point of
+ * mirroring it into a header.
+ */
+export const MCP_NAME_HEADER_METHODS: Readonly<Record<string, 'name' | 'uri'>> = {
+	'tools/call': 'name',
+	'prompts/get': 'name',
+	'resources/read': 'uri',
+}

package/src/manager/agent/lifecycle.ts

@@ -254,6 +254,7 @@ export class AgentManager {
 				depth: context.depth,
 				...(options.planId ? { planId: options.planId } : {}),
 				...(options.planStepId ? { planStepId: options.planStepId } : {}),
+				...displayLabels(options),
 			})
 			entry.ready = true
 		} catch (error) {
@@ -548,6 +549,7 @@ export class AgentManager {
 						depth: context.depth,
 						...(options.planId ? { planId: options.planId } : {}),
 						...(options.planStepId ? { planStepId: options.planStepId } : {}),
+						...displayLabels(options),
 					})
 
 				const lineage: Lineage = {
@@ -1588,6 +1590,33 @@ export class AgentManager {
 	}
 }
 
+/**
+ * The display grouping a host supplied at spawn, in the shape `agent_pending`
+ * carries it.
+ *
+ * Present only when named. A blank workflow spread onto the event would make a
+ * host that grouped nothing indistinguishable from one that grouped everything
+ * under an empty label, and the two are different answers to a consumer
+ * rebuilding the operator's view.
+ *
+ * Nothing in this file reads the values back: they are display annotations
+ * only; they do not create dependencies, barriers, or serial execution.
+ * Admission, ordering and capacity are decided above without consulting them.
+ */
+function displayLabels(options: DelegationDisplayLabels): DelegationDisplayLabels {
+	return {
+		...(options.workflow ? { workflow: options.workflow } : {}),
+		...(options.phase ? { phase: options.phase } : {}),
+		...(options.phaseDetail ? { phaseDetail: options.phaseDetail } : {}),
+		...(options.phaseOrder !== undefined ? { phaseOrder: options.phaseOrder } : {}),
+	}
+}
+
+type DelegationDisplayLabels = Pick<
+	SendMessageOptions,
+	'workflow' | 'phase' | 'phaseDetail' | 'phaseOrder'
+>
+
 /**
  * Maps a {@link BaseAgentResult} to {@link SessionSummaryOutcome}. Phase 6
  * INTERPRETATION: `completed` → `succeeded`; any other status → `failed`.

package/src/manager/run/persistence.ts

@@ -489,6 +489,18 @@ export class RunPersistence {
 		this.run.abandonedTaskIds = [...taskIds]
 	}
 
+	/**
+	 * Name the awaited background jobs this run ended without waiting for.
+	 *
+	 * See {@link Run.abandonedJobIds}. The same rule as the task list above:
+	 * recording, never stopping — what happens to a job is decided by whoever
+	 * owns it, not by the run that gave up waiting.
+	 */
+	setAbandonedJobIds(jobIds: readonly string[]): void {
+		if (jobIds.length === 0) return
+		this.run.abandonedJobIds = [...jobIds]
+	}
+
 	setSteps(steps: readonly StepResult[]): void {
 		this.run.steps = steps
 	}

package/src/prompt/coding-agent-doctrine.ts

@@ -94,6 +94,17 @@ You are in plan mode. Read, search and think; do not change anything. \`read\`,
 
 When you have understood the task, reply with the plan: what you would change, in which files, in what order, and what you would verify. Be concrete — name files and functions — and short enough to read in one screen. Then stop and wait; the user will leave plan mode to have the plan carried out, and that switch is their approval.`
 
+/**
+ * Appended after {@link CODING_AGENT_DELEGATION_DOCTRINE} only for a host
+ * session that has an orchestration mode turned on. See
+ * {@link CodingAgentDoctrineOptions.orchestrate}: this text is a stronger
+ * restatement of the existing delegation rule, not a new capability — it
+ * creates no roster, starts no work by itself, and names no tool the base
+ * doctrine did not already name.
+ */
+export const CODING_AGENT_ORCHESTRATE_DOCTRINE = `### Orchestrate mode
+This session has orchestrate mode on: treat delegation through \`Agent\` as the default for substantive work, not the exception. Before doing multi-step work yourself, ask whether an independent piece of it — a lookup, a draft, a check — could run as its own delegation, and prefer delegating it when the answer is yes. This changes only how eagerly you reach for \`Agent\` on work you would otherwise do inline; it does not mount a roster or start any delegation by itself.`
+
 export const CODING_AGENT_DOCTRINE_CONTRIBUTION_ID = 'namzu.coding-agent-doctrine'
 
 export interface CodingAgentDoctrineOptions {
@@ -103,6 +114,17 @@ export interface CodingAgentDoctrineOptions {
 	 * `task_create`, passes `false`.
 	 */
 	delegation?: boolean
+	/**
+	 * Append {@link CODING_AGENT_ORCHESTRATE_DOCTRINE} after the delegation
+	 * rules, for a host session whose operator turned on an orchestration
+	 * mode. Default `false`, and ignored when `delegation` is `false` — a
+	 * sub-agent prompt never carries delegation guidance of any strength.
+	 * Display/prompt-only: it creates no scheduling, no roster and no kernel
+	 * behaviour change, the same guarantee the `workflow`/`phase` labels on
+	 * `agent_pending` make. With this left at its default the rendered text
+	 * is byte-identical to before this option existed.
+	 */
+	orchestrate?: boolean
 }
 
 /**
@@ -114,10 +136,15 @@ export interface CodingAgentDoctrineOptions {
 export function codingAgentDoctrineContribution(
 	options: CodingAgentDoctrineOptions = {},
 ): PromptContribution {
-	const text =
-		options.delegation === false
-			? CODING_AGENT_WORKING_DOCTRINE
-			: `${CODING_AGENT_WORKING_DOCTRINE}\n\n${CODING_AGENT_DELEGATION_DOCTRINE}`
+	const text = [
+		CODING_AGENT_WORKING_DOCTRINE,
+		options.delegation === false ? undefined : CODING_AGENT_DELEGATION_DOCTRINE,
+		options.delegation !== false && options.orchestrate
+			? CODING_AGENT_ORCHESTRATE_DOCTRINE
+			: undefined,
+	]
+		.filter((part): part is string => Boolean(part))
+		.join('\n\n')
 	return {
 		id: CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
 		placement: 'static',

package/src/prompt/index.ts

@@ -16,6 +16,7 @@ export type {
 export {
 	CODING_AGENT_DELEGATION_DOCTRINE,
 	CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
+	CODING_AGENT_ORCHESTRATE_DOCTRINE,
 	CODING_AGENT_WORKING_DOCTRINE,
 	PLAN_MODE_DOCTRINE,
 	codingAgentDoctrineContribution,