@deepseek-ai/dsh-subagent-codex 0.1.0-rc.7 → 0.1.0-rc.8

package/lib/index.js

@@ -1,7 +1,10 @@
+import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
 import { NO_START_CAPABILITIES, assertPositiveFinite, resolveChildCwd, settleRunResult, subprocessRunHandle } from "@deepseek-ai/dsh-subagent";
 import { randomUUID } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import { JsonRpcLineTransport } from "@deepseek-ai/dsh-sdk-protocol";
 //#region lib/types/wire.js
@@ -13,6 +16,37 @@ import { JsonRpcLineTransport } from "@deepseek-ai/dsh-sdk-protocol";
 *
 * @module @deepseek-ai/dsh-subagent-codex/wire
 */
+const THREAD_PERMISSION_PARAMS = {
+	never: { approvalPolicy: "never" },
+	"approve-for-me": {
+		approvalPolicy: "on-request",
+		approvalsReviewer: "auto_review",
+		sandbox: "workspace-write"
+	},
+	"dangerously-bypass-approvals-and-sandbox": {
+		approvalPolicy: "never",
+		sandbox: "danger-full-access"
+	}
+};
+const STDERR_PERMISSION_SIGNATURES = [{
+	text: "approval policy is Never; reject command",
+	request: "command execution",
+	decision: "denied",
+	reason: "Codex rejected an escalation because the selected policy never asks for approval"
+}, {
+	text: "recorded sandbox violation:",
+	request: "sandbox execution",
+	decision: "failed",
+	reason: "Codex reported a sandbox violation"
+}];
+const STDERR_SIGNATURE_TAIL_CHARS = Math.max(...STDERR_PERMISSION_SIGNATURES.map((signature) => signature.text.length)) - 1;
+function stderrSignatureTail(value) {
+	for (let length = Math.min(STDERR_SIGNATURE_TAIL_CHARS, value.length); length > 0; length -= 1) {
+		const tail = value.slice(-length);
+		if (STDERR_PERMISSION_SIGNATURES.some((signature) => tail.length < signature.text.length && signature.text.startsWith(tail))) return tail;
+	}
+	return "";
+}
 function object(value, label) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`subagent-codex: app-server returned invalid ${label}`);
 	return value;
@@ -30,10 +64,54 @@ function unattendedDecision(params) {
 	}
 	throw new Error("subagent-codex: app-server offered no unattended approval decision");
 }
-function isContextWindowExceeded(turn) {
-	if (turn.status !== "failed") return false;
+function numericHttpStatus(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 65535 ? value : void 0;
+}
+function objectFailureInfo(value) {
+	const keys = Object.keys(value);
+	const category = keys[0];
+	if (keys.length !== 1 || category === void 0) return { category: "unknown" };
+	const detail = value[category];
+	if (detail === null || typeof detail !== "object" || Array.isArray(detail)) return { category: "unknown" };
+	const fields = detail;
+	switch (category) {
+		case "httpConnectionFailed":
+		case "responseStreamConnectionFailed":
+		case "responseStreamDisconnected":
+		case "responseTooManyFailedAttempts": {
+			const httpStatus = numericHttpStatus(fields.httpStatusCode);
+			return httpStatus === void 0 ? { category } : {
+				category,
+				httpStatus
+			};
+		}
+		case "activeTurnNotSteerable": return { category };
+		default: return { category: "unknown" };
+	}
+}
+function failureInfo(turn) {
+	if (turn.status !== "failed") return { category: "unknown" };
 	const error = turn.error;
-	return error !== null && typeof error === "object" && !Array.isArray(error) && error.codexErrorInfo === "contextWindowExceeded";
+	if (error === null || typeof error !== "object" || Array.isArray(error)) return { category: "unknown" };
+	const info = error.codexErrorInfo;
+	if (typeof info === "string") switch (info) {
+		case "contextWindowExceeded":
+		case "sessionBudgetExceeded":
+		case "usageLimitExceeded":
+		case "serverOverloaded":
+		case "cyberPolicy":
+		case "internalServerError":
+		case "unauthorized":
+		case "badRequest":
+		case "threadRollbackFailed":
+		case "sandboxError":
+		case "other": return { category: info };
+		default: return { category: "unknown" };
+	}
+	return info !== null && typeof info === "object" && !Array.isArray(info) ? objectFailureInfo(info) : { category: "unknown" };
+}
+function unattendedDiagnostic(mode, request, decision, reason) {
+	return `Codex unattended decision (mode: ${mode}; request: ${request}; decision: ${decision}): ${reason}`;
 }
 function thrown$1(value) {
 	/* v8 ignore next -- typed protocol and stream failures reject with Error. */
@@ -69,6 +147,7 @@ async function raceAbort(pending, signal) {
 */
 var CodexAppServerWire = class {
 	input;
+	permissionMode;
 	transport;
 	fatal = Promise.withResolvers();
 	threadId;
@@ -78,9 +157,18 @@ var CodexAppServerWire = class {
 	earlyTurnNotifications = [];
 	lastFinalAnswer;
 	lastUnphasedAnswer;
+	diagnostic;
+	failure;
+	diagnosticOrder = 0;
+	observationOrder = 0;
+	pendingDiagnostic;
+	stderrTail = "";
+	inputEnded = false;
+	terminalObserved = false;
 	closed = false;
-	constructor(input, output) {
+	constructor(input, output, permissionMode) {
 		this.input = input;
+		this.permissionMode = permissionMode;
 		this.transport = new JsonRpcLineTransport(input, output);
 		this.fatal.promise.catch(() => {});
 		this.transport.onRequest((method, params) => this.handleServerRequest(method, params));
@@ -100,6 +188,13 @@ var CodexAppServerWire = class {
 		this.transport.start();
 	}
 	/**
+	* Whether protocol output ended before a terminal turn notification.
+	* @returns `true` only for an early protocol close without a terminal turn.
+	*/
+	endedBeforeTerminal() {
+		return this.inputEnded && !this.terminalObserved;
+	}
+	/**
 	* Perform the required app-server initialize/initialized handshake.
 	* @param signal - unpublished-start cancellation.
 	*/
@@ -126,7 +221,8 @@ var CodexAppServerWire = class {
 	async startThread(cwd, signal) {
 		const thread = object(object(await this.guarded(this.transport.request("thread/start", {
 			cwd,
-			ephemeral: true
+			ephemeral: true,
+			...THREAD_PERMISSION_PARAMS[this.permissionMode]
 		}, signal), signal), "thread/start response").thread, "thread/start thread");
 		const id = string(thread.id, "thread/start thread id");
 		if (thread.ephemeral !== true) throw new Error("subagent-codex: app-server did not create an ephemeral thread");
@@ -143,27 +239,62 @@ var CodexAppServerWire = class {
 		const completion = Promise.withResolvers();
 		this.turnCompleted = completion;
 		const threadId = this.threadId;
-		const turn = object(object(await this.guarded(this.transport.request("turn/start", {
-			threadId,
-			input: texts.map((text) => ({
-				type: "text",
-				text,
-				text_elements: []
-			}))
-		}, signal), signal), "turn/start response").turn, "turn/start turn");
-		this.commitTurnId(string(turn.id, "turn/start turn id"));
-		const terminal = object((await this.guarded(completion.promise, signal)).turn, "turn/completed turn");
+		try {
+			const turn = object(object(await this.guarded(this.transport.request("turn/start", {
+				threadId,
+				input: texts.map((text) => ({
+					type: "text",
+					text,
+					text_elements: []
+				}))
+			}, signal), signal), "turn/start response").turn, "turn/start turn");
+			this.commitTurnId(string(turn.id, "turn/start turn id"));
+		} catch (error) {
+			this.recordFailure({
+				stage: "turn-start",
+				category: "unknown"
+			});
+			throw error;
+		}
+		let completed;
+		let terminal;
+		try {
+			completed = await this.guarded(completion.promise, signal);
+			terminal = object(completed.params.turn, "turn/completed turn");
+		} catch (error) {
+			this.recordFailure({
+				stage: "turn",
+				category: "unknown"
+			});
+			throw error;
+		}
 		const status = terminal.status;
-		if (isContextWindowExceeded(terminal)) return {
-			output: this.collectOutput(),
-			stopReason: "max-tokens"
-		};
 		if (status !== "completed") {
-			const detail = status === "failed" ? `: ${JSON.stringify(terminal.error)}` : "";
+			const parsed = failureInfo(terminal);
+			this.recordFailure(parsed.httpStatus === void 0 ? {
+				stage: "turn",
+				category: parsed.category
+			} : {
+				stage: "turn",
+				category: parsed.category,
+				httpStatus: parsed.httpStatus
+			});
+			if (parsed.category === "sandboxError") this.recordDiagnostic("sandbox execution", "failed", "Codex reported a sandbox failure", completed.order);
+			if (parsed.category === "contextWindowExceeded") return {
+				output: this.collectOutput(),
+				stopReason: "max-tokens"
+			};
+			const detail = status === "failed" ? `: ${parsed.category}` : "";
 			throw new Error(`subagent-codex: Codex turn ended with status ${String(status)}${detail}`);
 		}
 		const output = this.collectOutput();
-		if (output.length === 0) throw new Error("subagent-codex: Codex completed without a final answer");
+		if (output.length === 0) {
+			this.recordFailure({
+				stage: "turn",
+				category: "unknown"
+			});
+			throw new Error("subagent-codex: Codex completed without a final answer");
+		}
 		return {
 			output,
 			stopReason: "completed"
@@ -191,6 +322,40 @@ var CodexAppServerWire = class {
 			text: selected
 		}] : [];
 	}
+	/**
+	* The latest safe unattended permission fact observed for this run.
+	* @returns provider-authored diagnostic text, when one was observed.
+	*/
+	collectDiagnostic() {
+		return this.diagnostic;
+	}
+	/**
+	* The structured failure fact observed for this published turn.
+	* Call only after a non-completed return or rejection from {@link runTurn}.
+	* @returns the fixed stage/category pair and optional HTTP status.
+	*/
+	collectFailure() {
+		return this.failure;
+	}
+	/**
+	* Observe product stderr while retaining only enough tail to recognize fixed
+	* permission signatures. The raw text is never copied into the diagnostic.
+	* @param chunk - one decoded stderr chunk already forwarded to the host.
+	*/
+	observeStderr(chunk) {
+		const observed = `${this.stderrTail}${chunk}`;
+		let latestIndex = -1;
+		let latest;
+		for (const signature of STDERR_PERMISSION_SIGNATURES) {
+			const index = observed.lastIndexOf(signature.text);
+			if (index > latestIndex) {
+				latestIndex = index;
+				latest = signature;
+			}
+		}
+		if (latest !== void 0) this.recordDiagnostic(latest.request, latest.decision, latest.reason);
+		this.stderrTail = stderrSignatureTail(observed);
+	}
 	/** Detach JSON-RPC listeners and reject outstanding requests. Idempotent. */
 	close() {
 		if (this.closed) return;
@@ -211,6 +376,7 @@ var CodexAppServerWire = class {
 		this.fail(error);
 	};
 	onInputEnd = () => {
+		this.inputEnded = true;
 		this.fail(/* @__PURE__ */ new Error("subagent-codex: app-server protocol stream closed"));
 	};
 	observePendingTurnId(id) {
@@ -221,37 +387,90 @@ var CodexAppServerWire = class {
 	commitTurnId(id) {
 		if (this.pendingTurnId !== void 0 && this.pendingTurnId !== id) throw new Error("subagent-codex: turn/start response did not match the active turn");
 		this.turnId = id;
+		const pendingDiagnostic = this.pendingDiagnostic;
+		this.pendingDiagnostic = void 0;
+		if (pendingDiagnostic !== void 0) this.recordDiagnostic(pendingDiagnostic.request, pendingDiagnostic.decision, pendingDiagnostic.reason, pendingDiagnostic.order);
 		const notifications = this.earlyTurnNotifications.splice(0);
-		for (const notification of notifications) this.handleNotification(notification.method, notification.params);
+		for (const notification of notifications) this.handleNotification(notification.method, notification.params, notification.order);
 	}
+	/**
+	* Validate the request's thread and turn association.
+	* @returns `true` when the matching turn is still provisional, so the caller
+	* defers its diagnostic until `commitTurnId()`.
+	*/
 	validateRunIds(params, nullableTurn = false) {
 		if (params.threadId !== this.threadId) throw new Error("subagent-codex: app-server request referenced another thread");
-		if (nullableTurn && params.turnId === null) return;
+		if (nullableTurn && params.turnId === null) return false;
 		const id = string(params.turnId, "server request turn id");
 		if (this.turnId === void 0) {
 			this.observePendingTurnId(id);
-			return;
+			return true;
 		}
 		if (id !== this.turnId) throw new Error("subagent-codex: app-server request referenced another turn");
+		return false;
+	}
+	recordRequestDiagnostic(provisional, request, decision, reason) {
+		const order = this.nextObservationOrder();
+		if (provisional) {
+			this.pendingDiagnostic = {
+				order,
+				request,
+				decision,
+				reason
+			};
+			return;
+		}
+		this.recordDiagnostic(request, decision, reason, order);
+	}
+	recordDiagnostic(request, decision, reason, order = this.nextObservationOrder()) {
+		if (order < this.diagnosticOrder) return;
+		this.diagnosticOrder = order;
+		this.diagnostic = unattendedDiagnostic(this.permissionMode, request, decision, reason);
+	}
+	recordFailure(facts) {
+		this.failure = facts;
+	}
+	nextObservationOrder() {
+		this.observationOrder += 1;
+		return this.observationOrder;
+	}
+	recordDeclinedItem(item, order) {
+		if (item.type === "commandExecution" && item.status === "declined") {
+			this.recordDiagnostic("command execution", "declined", "Codex declined the command under the selected permission mode", order);
+			return true;
+		}
+		if (item.type === "fileChange" && item.status === "declined") {
+			this.recordDiagnostic("file change", "declined", "Codex declined the file change under the selected permission mode", order);
+			return true;
+		}
+		return false;
 	}
 	handleServerRequest(method, params) {
 		try {
 			switch (method) {
-				case "item/commandExecution/requestApproval":
-				case "item/fileChange/requestApproval":
-					this.validateRunIds(params);
-					return Promise.resolve({ decision: unattendedDecision(params) });
+				case "item/commandExecution/requestApproval": {
+					const provisional = this.validateRunIds(params);
+					const decision = unattendedDecision(params);
+					this.recordRequestDiagnostic(provisional, "command approval", decision === "cancel" ? "cancelled" : "declined", "the provider does not grant interactive approval");
+					return Promise.resolve({ decision });
+				}
+				case "item/fileChange/requestApproval": {
+					const provisional = this.validateRunIds(params);
+					const decision = unattendedDecision(params);
+					this.recordRequestDiagnostic(provisional, "file approval", decision === "cancel" ? "cancelled" : "declined", "the provider does not grant interactive approval");
+					return Promise.resolve({ decision });
+				}
 				case "item/permissions/requestApproval":
-					this.validateRunIds(params);
+					this.recordRequestDiagnostic(this.validateRunIds(params), "permission grant", "denied", "the provider grants no additional turn permissions");
 					return Promise.resolve({
 						permissions: {},
 						scope: "turn"
 					});
 				case "item/tool/requestUserInput":
-					this.validateRunIds(params);
+					this.recordRequestDiagnostic(this.validateRunIds(params), "user input", "empty response", "the provider does not collect interactive answers");
 					return Promise.resolve({ answers: {} });
 				case "mcpServer/elicitation/request":
-					this.validateRunIds(params, true);
+					this.recordRequestDiagnostic(this.validateRunIds(params, true), "MCP elicitation", "declined", "the provider does not collect interactive MCP input");
 					return Promise.resolve({
 						action: "decline",
 						content: null,
@@ -265,7 +484,7 @@ var CodexAppServerWire = class {
 			return Promise.reject(normalized);
 		}
 	}
-	handleNotification(method, params) {
+	handleNotification(method, params, order) {
 		if (method === "turn/started") {
 			if (string(params.threadId, "turn/started thread id") !== this.threadId) return;
 			const turn = object(params.turn, "turn/started turn");
@@ -280,13 +499,15 @@ var CodexAppServerWire = class {
 					this.observePendingTurnId(id);
 					this.earlyTurnNotifications.push({
 						method,
-						params
+						params,
+						order: this.nextObservationOrder()
 					});
 				}
 				return;
 			}
 			if (id !== this.turnId) return;
 			const item = object(params.item, "item/completed item");
+			if (this.recordDeclinedItem(item, order)) return;
 			if (item.type !== "agentMessage") return;
 			const text = typeof item.text === "string" ? item.text : (() => {
 				throw new Error("subagent-codex: app-server returned an invalid agent message");
@@ -306,17 +527,22 @@ var CodexAppServerWire = class {
 			this.observePendingTurnId(id);
 			this.earlyTurnNotifications.push({
 				method,
-				params
+				params,
+				order: this.nextObservationOrder()
 			});
 			return;
 		}
 		if (id !== this.turnId) return;
+		this.terminalObserved = true;
 		if (![
 			"completed",
 			"interrupted",
 			"failed"
 		].includes(String(turn.status))) throw new Error(`subagent-codex: app-server returned invalid terminal turn status ${String(turn.status)}`);
-		turnCompleted.resolve(params);
+		turnCompleted.resolve({
+			params,
+			order: order ?? this.nextObservationOrder()
+		});
 	}
 };
 //#endregion
@@ -331,26 +557,56 @@ var CodexAppServerWire = class {
 */
 /** Default POSIX grace between subprocess termination tiers. */
 const DEFAULT_DISPOSE_GRACE_MS = 3e3;
+const codexPackageJsonPath = createRequire(import.meta.url).resolve("@openai/codex/package.json");
+const codexPackageManifest = JSON.parse(readFileSync(codexPackageJsonPath, "utf8"));
+/** Absolute package-local JavaScript wrapper selected by the package manifest. */
+const CODEX_PACKAGE_BIN = resolve(dirname(codexPackageJsonPath), codexPackageManifest.bin.codex);
+/** Native non-interactive Codex modes mapped to official `thread/start` fields. */
+const CODEX_PERMISSION_MODES = [
+	"never",
+	"approve-for-me",
+	"dangerously-bypass-approvals-and-sandbox"
+];
+/** Safe default for unattended Codex runs. */
+const DEFAULT_CODEX_PERMISSION_MODE = "never";
+function failureDiagnostic(facts) {
+	const fields = [
+		"product: Codex",
+		`stage: ${facts.stage}`,
+		`category: ${facts.category}`
+	];
+	if (facts.httpStatus !== void 0) fields.push(`HTTP status: ${facts.httpStatus}`);
+	const processFields = [["exit code", facts.outcome?.exitCode], ["signal", facts.outcome?.signal]];
+	for (const [label, value] of processFields) if (value !== null && value !== void 0) fields.push(`${label}: ${value}`);
+	return `Product subagent failure (${fields.join("; ")})`;
+}
+var CodexRunFailure = class extends Error {
+	facts;
+	constructor(facts, cause) {
+		super(`subagent-codex: ${failureDiagnostic(facts)}`, cause === void 0 ? void 0 : { cause });
+		this.facts = facts;
+		this.name = "CodexRunFailure";
+	}
+};
 /**
-* Resolve the fixed app-server command for a platform.
-*
-* Windows npm and pnpm installs expose `codex.cmd`, which requires `cmd.exe`;
-* the argv is constant so no task or configuration text enters the
-* shell boundary.
-* @param platform - host platform used to select the executable boundary.
-* @returns argv for the fixed Codex app-server command.
+* Hide an unpublished Host failure behind fixed safe startup facts.
+* @param cause Original Host failure retained for internal diagnostics.
+* @returns A startup failure whose message contains only fixed safe facts.
 */
-function codexAppServerArgv(platform = process.platform) {
-	return platform === "win32" ? [
-		"cmd.exe",
-		"/d",
-		"/s",
-		"/c",
-		"codex",
-		"app-server",
-		"--stdio"
-	] : [
-		"codex",
+function codexStartupFailure(cause) {
+	return new CodexRunFailure({
+		stage: "initialize",
+		category: "unknown"
+	}, cause);
+}
+/**
+* Fixed package-local app-server command, independent of the host `PATH`.
+* @returns Node, the official wrapper, and the fixed app-server arguments.
+*/
+function codexAppServerArgv() {
+	return [
+		process.execPath,
+		CODEX_PACKAGE_BIN,
 		"app-server",
 		"--stdio"
 	];
@@ -382,16 +638,30 @@ function textTask(prompt) {
 */
 async function disposeCodexChild(wire, child) {
 	wire.close();
-	if (child.pid <= 0) {
-		await child.done.catch(() => {});
-		return;
-	}
-	try {
-		child.stdin?.end();
-	} catch {}
-	child.terminate();
-	await child.waitForExit();
-	await child.done;
+	if (child.pid > 0) {
+		let outcome;
+		child.done.then(
+			(value) => {
+				outcome = value;
+			},
+			/* v8 ignore next -- a positive pid excludes spawn-level done rejection. */
+			() => {}
+		);
+		try {
+			child.stdin?.end();
+		} catch {}
+		child.terminate();
+		try {
+			await child.waitForExit();
+		} catch (error) {
+			throw new CodexRunFailure({
+				stage: "teardown",
+				category: "unknown",
+				outcome
+			}, thrown(error));
+		}
+		await child.done;
+	} else await child.done.catch(() => {});
 }
 /**
 * Start the real `codex app-server --stdio` child and publish its one-shot run.
@@ -402,20 +672,62 @@ async function disposeCodexChild(wire, child) {
 async function startCodexRun(request, spec) {
 	const texts = textTask(request.prompt);
 	if (request.signal.aborted) throw new Error("subagent-codex: request was aborted before app-server startup");
-	const child = spec.spawn({
-		argv: codexAppServerArgv(),
-		cwd: spec.cwd,
-		stdio: {
-			stdin: "pipe",
-			stdout: "pipe",
-			stderr: "inherit"
-		},
-		graceMs: spec.disposeGraceMs,
-		env: spec.env
+	let child;
+	try {
+		child = spec.spawn({
+			argv: codexAppServerArgv(),
+			cwd: spec.cwd,
+			stdio: {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe"
+			},
+			graceMs: spec.disposeGraceMs,
+			env: spec.env
+		});
+	} catch (error) {
+		throw new CodexRunFailure({
+			stage: "initialize",
+			category: "unknown"
+		}, thrown(error));
+	}
+	const wire = new CodexAppServerWire(child.stdout, child.stdin, spec.permissionMode);
+	const onStderr = (chunk) => {
+		const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+		wire.observeStderr(bytes.toString());
+		try {
+			writeFileSync(process.stderr.fd, bytes);
+		} catch {}
+	};
+	const onStderrError = () => {};
+	child.stderr?.on("data", onStderr);
+	child.stderr?.on("error", onStderrError);
+	const disposeProcess = async () => {
+		try {
+			await disposeCodexChild(wire, child);
+			await new Promise((resolve) => {
+				setImmediate(resolve);
+			});
+		} finally {
+			child.stderr?.off("data", onStderr);
+			child.stderr?.off("error", onStderrError);
+		}
+	};
+	let processFailureFacts;
+	const processFailure = child.done.then((outcome) => {
+		processFailureFacts = {
+			stage: "process",
+			category: "process-exit",
+			outcome
+		};
+		throw new CodexRunFailure(processFailureFacts);
+	}, (error) => {
+		processFailureFacts = {
+			stage: "process",
+			category: "unknown"
+		};
+		throw new CodexRunFailure(processFailureFacts, thrown(error));
 	});
-	const wire = new CodexAppServerWire(child.stdout, child.stdin);
-	const disposeProcess = () => disposeCodexChild(wire, child);
-	const processFailure = child.done.then((outcome) => Promise.reject(/* @__PURE__ */ new Error(`subagent-codex: app-server exited before the run settled (code ${String(outcome.exitCode)}, signal ${String(outcome.signal)})`)), (error) => Promise.reject(thrown(error)));
 	processFailure.catch(() => {});
 	const runAbort = new AbortController();
 	const requestCancel = () => {
@@ -427,24 +739,86 @@ async function startCodexRun(request, spec) {
 		requestCancel();
 	};
 	request.signal.addEventListener("abort", onAbort, { once: true });
+	let startupStage = "initialize";
 	try {
 		wire.start();
 		await Promise.race([wire.initialize(request.signal), processFailure]);
+		startupStage = "thread-start";
 		await Promise.race([wire.startThread(spec.cwd, request.signal), processFailure]);
 	} catch (error) {
 		request.signal.removeEventListener("abort", onAbort);
+		const cancelledBeforeCleanup = runAbort.signal.aborted;
+		if (!(error instanceof CodexRunFailure) && !cancelledBeforeCleanup) await new Promise((resolve) => {
+			setImmediate(resolve);
+		});
+		const failure = new CodexRunFailure({
+			stage: startupStage,
+			category: "unknown",
+			outcome: error instanceof CodexRunFailure ? error.facts.outcome : processFailureFacts?.outcome
+		}, thrown(error));
 		try {
 			await disposeProcess();
 		} catch (disposeError) {
-			throw new AggregateError([thrown(error), thrown(disposeError)], "subagent-codex: startup failed and app-server cleanup also failed");
+			const cleanupFailure = thrown(disposeError);
+			throw new AggregateError([failure, cleanupFailure], `${failure.message}; ${cleanupFailure.message}`);
+		}
+		if (cancelledBeforeCleanup) throw new Error("subagent-codex: request was aborted before run publication");
+		try {
+			request.signal.throwIfAborted();
+		} catch {
+			throw new Error("subagent-codex: request was aborted before run publication");
 		}
-		if (runAbort.signal.aborted) throw new Error("subagent-codex: request was aborted before run publication");
-		throw thrown(error);
+		throw failure;
 	}
 	const collectOutput = () => wire.collectOutput();
+	let diagnostic;
+	const recordFailureDiagnostic = (facts) => {
+		const failure = failureDiagnostic(facts);
+		const permission = wire.collectDiagnostic();
+		diagnostic = permission === void 0 ? failure : `${failure}\n${permission}`;
+		return diagnostic;
+	};
+	const withProcessOutcome = (facts) => {
+		const outcome = processFailureFacts?.outcome;
+		return outcome === void 0 ? facts : {
+			...facts,
+			outcome
+		};
+	};
+	const publishedProcessFailure = processFailure.catch(async (error) => {
+		await new Promise((resolve) => {
+			setImmediate(resolve);
+		});
+		throw error;
+	});
 	const result = settleRunResult({
-		attempt: () => Promise.race([wire.runTurn(texts, runAbort.signal), processFailure]),
+		attempt: async () => {
+			try {
+				const terminal = await Promise.race([wire.runTurn(texts, runAbort.signal), publishedProcessFailure]);
+				if (terminal.stopReason === "completed") return terminal;
+				await new Promise((resolve) => {
+					setImmediate(resolve);
+				});
+				const facts = withProcessOutcome(wire.collectFailure());
+				return {
+					...terminal,
+					diagnostic: recordFailureDiagnostic(facts)
+				};
+			} catch (error) {
+				await new Promise((resolve) => {
+					setImmediate(resolve);
+				});
+				const endedBeforeTerminal = wire.endedBeforeTerminal();
+				if (endedBeforeTerminal && processFailureFacts === void 0 && !runAbort.signal.aborted) try {
+					if (await child.waitForExit(AbortSignal.timeout(Math.ceil(spec.disposeGraceMs)))) await child.done;
+				} catch {}
+				const facts = error instanceof CodexRunFailure ? error.facts : endedBeforeTerminal && processFailureFacts !== void 0 ? processFailureFacts : withProcessOutcome(wire.collectFailure());
+				recordFailureDiagnostic(facts);
+				throw error instanceof CodexRunFailure ? error : new CodexRunFailure(facts, thrown(error));
+			}
+		},
 		collectOutput,
+		collectDiagnostic: () => diagnostic,
 		cancelled: () => runAbort.signal.aborted,
 		onError: spec.onError,
 		signal: request.signal,
@@ -462,52 +836,69 @@ async function startCodexRun(request, spec) {
 //#endregion
 //#region lib/types/index.js
 /**
-* Fixed Codex one-shot subagent provider. Every accepted run starts a fresh
-* official `codex app-server --stdio` process in the delegating Session's
-* workspace and publishes only after an ephemeral thread exists.
+* Profile-named Codex one-shot subagent provider. Every accepted run starts a
+* fresh official package-local Codex wrapper with `app-server --stdio` in the
+* delegating Session's workspace and publishes only after an ephemeral thread exists.
 *
 * @module @deepseek-ai/dsh-subagent-codex
 */
 const name = "subagent-codex";
 const inject = ["subagents", "subprocess"];
+const DEFAULT_PROVIDER_NAME = "codex";
 const Config = z.object({
+	providerName: z.string().min(1).default(DEFAULT_PROVIDER_NAME),
 	env: z.dict(z.string()).default({}),
+	permissionMode: z.union([...CODEX_PERMISSION_MODES]).default(DEFAULT_CODEX_PERMISSION_MODE),
 	disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
 });
 var CodexProvider = class {
+	name;
 	ctx;
 	config;
-	name = "codex";
 	capabilities = NO_START_CAPABILITIES;
 	inheritsParentContext = false;
-	constructor(ctx, config) {
+	constructor(name, ctx, config) {
+		this.name = name;
 		this.ctx = ctx;
 		this.config = config;
 	}
 	start(request) {
 		const parentCwd = request.parent.session.header.cwd;
 		if (parentCwd === void 0) throw new Error("subagent-codex: no working directory for the child — delegate from a parent session that has one");
+		let cwd;
+		try {
+			cwd = resolveChildCwd("subagent-codex", void 0, parentCwd);
+		} catch (error) {
+			if (request.signal.aborted) throw new Error("subagent-codex: request was aborted before app-server startup");
+			throw codexStartupFailure(error);
+		}
 		return startCodexRun(request, {
-			cwd: resolveChildCwd("subagent-codex", void 0, parentCwd),
+			cwd,
+			permissionMode: this.config.permissionMode,
 			env: this.config.env,
 			disposeGraceMs: this.config.disposeGraceMs,
 			spawn: (spawnSpec) => this.ctx.subprocess.spawn(spawnSpec),
 			onError: (error, stopReason) => {
-				this.ctx.logger.warn(`subagent-codex: child run failed (${stopReason}): ${error.message}`);
+				this.ctx.logger.warn(`subagent-codex "${this.name}": child run failed (${stopReason}): ${error.message}`);
 			}
 		});
 	}
 };
 /**
-* Register the fixed `codex` provider.
+* Register one Profile-named Codex provider.
 * @param ctx - context carrying shared subagent and subprocess services.
-* @param config - explicit child environment and disposal grace.
+* @param config - registry name, permission mode, child environment, and disposal grace.
 */
 function apply(ctx, config) {
-	const resolved = config;
+	const resolved = {
+		providerName: config.providerName ?? DEFAULT_PROVIDER_NAME,
+		env: config.env,
+		permissionMode: config.permissionMode ?? "never",
+		disposeGraceMs: config.disposeGraceMs
+	};
 	assertPositiveFinite("subagent-codex", "disposeGraceMs", resolved.disposeGraceMs);
 	if (resolved.disposeGraceMs > MAX_TIMER_DELAY_MS) throw new Error(`subagent-codex: disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
-	ctx.subagents.registerProvider(new CodexProvider(ctx, resolved));
+	ctx.subagents.registerProvider(new CodexProvider(resolved.providerName, ctx, resolved));
 }
 //#endregion
 export { Config, apply, inject, name };