@dougbots/avenor-opencode 0.8.3 → 0.10.0

package/README.md

@@ -42,6 +42,9 @@ When a run is dispatched with `avenor_spawn`, the plugin:
 1. **Blocks by default** — the tool call stays open, updating its title and metadata as the sub-agent runs, exactly like OpenCode's own sub-agent tool calls. The tool returns when the run reaches a terminal state.
 2. **Re-prompts on completion** — when a `wait=false` (fire-and-forget) run finishes, the plugin automatically injects a completion message into the orchestrating session so the LLM picks up without manual polling.
 3. **Routes permissions** — when a sub-agent running under the `opencode-http` backend requests a permission, the plugin injects a re-prompt into the orchestrating session. The LLM can call `avenor_answer_permission` to respond; the normal permission dialog is also shown as a fallback.
+4. **Formats results** — OpenCode returns concise, bounded prose in its shared `output` for `avenor_status`, `avenor_result`, `avenor_answer_permission`, `avenor_follow_up`, `avenor_events`, `avenor_inspect`, and `avenor_shutdown`. Structured metadata stays in host/session state.
+
+MCP clients render their own results.
 
 ## Tools
 
@@ -55,17 +58,36 @@ Dispatch an agent run in the current working directory.
 
 | Argument | Required | Description |
 |---|---|---|
-| `agent` | yes | Agent name (no default — must be specified) |
+| `agent` | no | Agent name; omission uses the supplied model or runtime defaults |
 | `prompt` | no | Prompt text |
 | `prompt_file` | no | Path to a prompt file |
 | `label` | no | Human-readable label for the run |
 | `timeout` | no | Timeout duration (e.g. `3600s`, `30m`) |
 | `model` | no | Model override |
+| `thinking` | no | Run-level reasoning control; unsupported effective backends reject explicit values |
+| `backend` | no | Backend override; direct mode defaults to Avenor's `opencode-acp` backend when omitted |
+| `roster_file` | no | Path to a top-level roster map |
+| `roster_entry` | no | Key within `roster_file` |
 | `wait` | no | Block until complete (default `true`) |
 | `supervisor_id` | no | Reuse an existing supervisor by socket path |
 
 The working directory (`dir`) is injected automatically from your OpenCode session context — it is not a user-facing argument.
 
+#### Direct and roster modes
+
+Use `roster_file` plus `roster_entry` to select a complete identity. Every roster entry requires `backend` and at least one of `agent` or `model`; roster mode rejects direct `agent`, `model`, and `backend` overrides. Direct mode allows all three identity fields to be omitted independently, including backend-only selection. Roster mode does not apply the direct `opencode-acp` default.
+
+```json
+{
+  "prompt": "Review the repository",
+  "roster_file": "/repo/roster.json",
+  "roster_entry": "reviewer",
+  "wait": true
+}
+```
+
+Roster entries currently support only `backend`, `agent`, and `model`. `system` and `thinking` are rejected; `thinking` remains a run-level value and is validated against the effective backend. A resumed session cannot change backend. The plugin passes `roster_file` as supplied, so an absolute path avoids ambiguity when the OpenCode process directory differs from the project directory.
+
 ### `avenor_status`
 
 Get status of a specific run or all active runs. Use the compact `lifecycle` view for progress and pending permission checks; `full` remains the compatibility default.
@@ -89,6 +111,17 @@ Wait for a run to finish and return its complete final output without transcript
 
 A blocked run returns its pending permission instead of waiting forever. If this tool's own timeout expires, it returns the latest status with `ready: false` and `timed_out: true`.
 
+### `avenor_inspect`
+
+Use `avenor_inspect` to review a bounded snapshot. The snapshot includes transcript, completed and live tools, permissions, and final output. Use `avenor_events` when raw event records are required.
+
+| Argument | Required | Description |
+|---|---|---|
+| `run_id` | yes | Run ID to inspect |
+| `limit` | no | Max events to reduce into the snapshot |
+| `after_seq` | no | Only include events after this sequence number |
+| `supervisor_id` | no | Reuse an existing supervisor by socket path |
+
 ### `avenor_answer_permission`
 
 Answer a pending permission request. The `option_id` comes from the `pending_permission.options` array returned by `avenor_status`.

package/dist/index.d.ts

@@ -6,7 +6,14 @@ type TrackedRun = {
   runId: string;
   runtimeId?: string;
   sessionId?: string;
-  agent: string;
+  agent?: string;
+  model?: string;
+  backend?: string;
+  rosterFile?: string;
+  rosterEntry?: string;
+  effectiveAgent?: string;
+  effectiveModel?: string;
+  effectiveBackend?: string;
   orchestratorSessionId: string;
   label: string;
   supervisorId?: string;
@@ -15,7 +22,12 @@ type TrackedRun = {
   lastSnapshot?: RunSnapshot;
 };
 declare function terminalStatus(snapshot: RunSnapshot, fallback?: StatusResult): string;
+type HostIdentityMetadataInput = Pick<TrackedRun, 'agent' | 'model' | 'backend' | 'rosterFile' | 'rosterEntry' | 'effectiveAgent' | 'effectiveModel' | 'effectiveBackend'>;
+type HostIdentityStatus = Pick<StatusResult, 'roster_file' | 'roster_entry' | 'agent' | 'model' | 'backend' | 'effective_agent' | 'effective_model' | 'effective_backend'>;
+/** Project shared spawn identity into OpenCode metadata without resolving rosters here. */
+declare function hostIdentityMetadata(run?: HostIdentityMetadataInput, status?: HostIdentityStatus): Record<string, unknown>;
+declare function buildSnapshotMetadata(snapshot: RunSnapshot, run?: HostIdentityMetadataInput, status?: HostIdentityStatus): Record<string, unknown>;
 declare function buildWaitingText(run: TrackedRun, snapshot: RunSnapshot): string;
 declare const AvenorPlugin: Plugin;
 //#endregion
-export { AvenorPlugin, buildWaitingText, terminalStatus };
+export { AvenorPlugin, buildSnapshotMetadata, buildWaitingText, hostIdentityMetadata, terminalStatus };

package/dist/index.js

@@ -1,6 +1,414 @@
 import { tool } from "@opencode-ai/plugin";
 import * as crypto from "node:crypto";
-import { Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
+import { Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool, validateSpawnSelection } from "@dougbots/avenor-core";
+//#region src/render.ts
+const FINAL_OUTPUT_CHARS$1 = 1500;
+const SCALAR_CHARS = 240;
+const EVENT_CHARS = 600;
+const PREVIEW_LINES = 12;
+const STATUS_ROWS = 12;
+const COLLECTION_ITEMS = 8;
+const INSPECT_ITEMS = 5;
+const CLEANUP_ITEMS = 8;
+const TERMINAL_STATUSES$1 = new Set([
+	"done",
+	"failed",
+	"timeout",
+	"killed"
+]);
+const ANSI_PATTERN = /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function stringValue(value) {
+	return typeof value === "string" && value.trim() ? value : void 0;
+}
+function numberValue(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) return Number(value);
+}
+function sanitizeText(text) {
+	return text.replace(ANSI_PATTERN, "").replaceAll("	", "  ").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "");
+}
+function itemMarker(count) {
+	return `… ${count} items omitted`;
+}
+function lineMarker(count) {
+	return `… ${count} lines omitted`;
+}
+function characterMarker(count) {
+	return `[preview clipped: ${count} characters omitted]`;
+}
+function cleanMultiline(value) {
+	if (typeof value !== "string") return void 0;
+	return sanitizeText(value).trim() || void 0;
+}
+function tailClip(value, limit) {
+	if (value.length <= limit) return { text: value };
+	let markerLength = characterMarker(value.length).length;
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const visibleLength = Math.max(0, limit - markerLength);
+		const nextMarkerLength = characterMarker(value.length - visibleLength).length;
+		if (nextMarkerLength === markerLength) return {
+			text: value.slice(value.length - visibleLength),
+			omitted: value.length - visibleLength
+		};
+		markerLength = nextMarkerLength;
+	}
+	const visibleLength = Math.max(0, limit - markerLength);
+	return {
+		text: value.slice(value.length - visibleLength),
+		omitted: value.length - visibleLength
+	};
+}
+function scalar(value, fallback = "unknown", limit = SCALAR_CHARS) {
+	const clean = cleanMultiline(typeof value === "string" ? value : void 0);
+	if (!clean) return fallback;
+	const clipped = tailClip(clean.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim(), limit);
+	return clipped.omitted === void 0 ? clipped.text : `${clipped.text}${characterMarker(clipped.omitted)}`;
+}
+function optionalScalar(value, limit = SCALAR_CHARS) {
+	const clean = cleanMultiline(typeof value === "string" ? value : void 0);
+	return clean ? scalar(clean, "unknown", limit) : void 0;
+}
+function preview(value, limit) {
+	const clean = cleanMultiline(value);
+	if (!clean) return void 0;
+	const clipped = tailClip(clean, limit);
+	const lines = clipped.text.split("\n").slice(-PREVIEW_LINES);
+	const omittedLines = Math.max(0, clean.split("\n").length - lines.length);
+	return [
+		...lines,
+		...clipped.omitted === void 0 ? [] : [characterMarker(clipped.omitted)],
+		...omittedLines === 0 ? [] : [lineMarker(omittedLines)]
+	];
+}
+function selected(record, key, fallback, defaultValue = "unknown") {
+	return scalar(stringValue(record?.[key]) ?? stringValue(fallback), defaultValue);
+}
+function selectedOptional(record, key) {
+	return optionalScalar(record?.[key]);
+}
+function hasStatusIdentity(record) {
+	return !!record && !!(stringValue(record.run_id) || stringValue(record.label) || stringValue(record.status));
+}
+function fallback(tool) {
+	return [`Avenor ${tool} result unavailable.`, "Retry the tool or use avenor_status/avenor_inspect."];
+}
+function output(lines, tool) {
+	return (lines ?? fallback(tool)).join("\n");
+}
+function isTerminal(status) {
+	return TERMINAL_STATUSES$1.has(status);
+}
+function permission(record) {
+	return asRecord(record?.pending_permission);
+}
+function permissionOptions(record) {
+	const options = record?.options;
+	return Array.isArray(options) ? options.map(asRecord).filter((value) => !!value) : [];
+}
+function optionRows(options) {
+	return options.slice(0, COLLECTION_ITEMS).map((option) => `${selected(option, "option_id")} (${selected(option, "label")})`).join(", ");
+}
+function optionLine(prefix, options) {
+	const rows = optionRows(options);
+	const omitted = options.length - Math.min(options.length, COLLECTION_ITEMS);
+	return `${prefix}${rows ? ` ${rows}` : ""}${omitted > 0 ? ` ${itemMarker(omitted)}` : ""}`;
+}
+function guidance(status, pending, runId) {
+	if (status === "waiting") {
+		const options = permissionOptions(pending);
+		if (options.length > 0) return `Guidance: Call avenor_answer_permission with run_id "${runId}" and option_id "${selected(options[0], "option_id")}".`;
+		if (pending) return `Guidance: Permission input is required, but no options are available; call avenor_inspect with run_id "${runId}".`;
+		return `Guidance: Call avenor_follow_up or avenor_status with run_id "${runId}".`;
+	}
+	if (isTerminal(status)) return `Guidance: Call avenor_result or avenor_events with run_id "${runId}".`;
+	return `Guidance: Call avenor_result with run_id "${runId}".`;
+}
+function statusExpanded(status) {
+	return [
+		["Phase", "phase"],
+		["Phase label", "phase_label"],
+		["Session", "session_id"],
+		["Backend", "backend"],
+		["Agent", "agent"],
+		["Model", "model"],
+		["Latest sequence", "latest_seq"],
+		["Stop reason", "stop_reason"]
+	].flatMap(([label, key]) => {
+		const value = key === "latest_seq" ? numberValue(status[key])?.toString() : selectedOptional(status, key);
+		return value === void 0 ? [] : [`${label}: ${value}`];
+	});
+}
+function statusLines(details, args) {
+	if (Array.isArray(details)) {
+		const statuses = details.map(asRecord);
+		if (statuses.some((status) => !hasStatusIdentity(status))) return void 0;
+		const displayed = statuses.slice(0, STATUS_ROWS);
+		const lines = [
+			`Avenor status — ${statuses.length} runs`,
+			...displayed.map((status) => {
+				const runId = selected(status, "run_id", args.run_id);
+				return `${selected(status, "label", void 0, runId)} — ${selected(status, "status")} (run_id: ${runId})`;
+			}),
+			...statuses.length > displayed.length ? [itemMarker(statuses.length - displayed.length)] : []
+		];
+		for (const status of displayed) {
+			const runId = selected(status, "run_id", args.run_id);
+			lines.push(`Run: ${runId}`, `Label: ${selected(status, "label", void 0, runId)}`, `Status: ${selected(status, "status")}`, ...statusExpanded(status));
+		}
+		return lines;
+	}
+	const status = asRecord(details);
+	if (!hasStatusIdentity(status)) return void 0;
+	const runId = selected(status, "run_id", args.run_id);
+	const label = selected(status, "label", void 0, runId);
+	const state = selected(status, "status");
+	const pending = permission(status);
+	const options = permissionOptions(pending);
+	const finalPreview = preview(status.final_output, FINAL_OUTPUT_CHARS$1);
+	return [
+		`Status: ${label} — ${state}`,
+		`Run: ${runId}`,
+		...pending ? [`Permission: ${selected(pending, "description")}`, optionLine("Options:", options)] : [],
+		...status.final_output_truncated === true ? [`Warning: final output preview is truncated; call avenor_result with run_id "${runId}".`] : [],
+		...finalPreview ? ["Final output:", ...finalPreview] : ["Final output: unavailable."],
+		guidance(state, pending, runId),
+		...statusExpanded(status)
+	];
+}
+function resultLines(details, args) {
+	const result = asRecord(details);
+	if (!hasStatusIdentity(result)) return void 0;
+	const runId = selected(result, "run_id", args.run_id);
+	const label = selected(result, "label", void 0, runId);
+	const state = selected(result, "status");
+	const pending = permission(result);
+	const finalPreview = preview(result.output, FINAL_OUTPUT_CHARS$1);
+	const session = selectedOptional(result, "session_id");
+	const stopReason = selectedOptional(result, "stop_reason");
+	return [
+		`Result: ${label} — ${state}`,
+		`Run: ${runId}`,
+		...result.timed_out === true ? ["Warning: wait timed out; the run is still active."] : [],
+		...pending ? [`Permission: ${selected(pending, "description")}`] : [],
+		guidance(state, pending, runId),
+		...result.output_truncated === true ? [stringValue(result.output_event_path) ? `Warning: final output may be truncated; retry avenor_result or read the durable event path "${scalar(result.output_event_path)}".` : `Warning: final output may be truncated; call avenor_events with run_id "${runId}".`] : [],
+		...finalPreview ? ["Final output:", ...finalPreview] : ["Final output: unavailable."],
+		...session ? [`Session: ${session}`] : [],
+		...stopReason ? [`Stop reason: ${stopReason}`] : []
+	];
+}
+function permissionLines(details, args) {
+	const result = asRecord(details);
+	if (!result || typeof result.ok !== "boolean") return void 0;
+	const runId = scalar(args.run_id);
+	return [
+		`Permission answer: ${result.ok ? "accepted" : "failed"}.`,
+		`Run: ${runId}`,
+		`Option: ${scalar(args.option_id)}`,
+		...stringValue(args.request_id) ? [`Request: ${scalar(args.request_id)}`] : [],
+		`Guidance: Call avenor_status with run_id "${runId}" to verify the permission state.`
+	];
+}
+function followUpLines(details, args) {
+	const result = asRecord(details);
+	if (!result || !stringValue(result.run_id) || !stringValue(result.label)) return void 0;
+	const runId = selected(result, "run_id", args.run_id);
+	const label = selected(result, "label", args.label, runId);
+	return [
+		`Follow-up: ${label} — dispatched.`,
+		`Source run: ${scalar(args.run_id)}`,
+		`Run: ${runId}`,
+		`Label: ${label}`,
+		`Guidance: Call avenor_status with run_id "${runId}".`
+	];
+}
+function eventSequence(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	return typeof value === "string" && value.trim() && Number.isFinite(Number(value)) ? value : void 0;
+}
+function eventRow(value) {
+	const name = stringValue(value.event) ?? stringValue(value.type) ?? "unknown";
+	const sequence = eventSequence(value.seq);
+	const text = extractEventText(value);
+	const previewText = text ? scalar(text, "unknown", EVENT_CHARS) : void 0;
+	return `Event ${sequence ?? "?"}: ${scalar(name)}${previewText ? ` — ${previewText}` : ""}`;
+}
+function eventsLines(details, args) {
+	const result = asRecord(details);
+	if (!result || !Array.isArray(result.events) || result.events.some((event) => !asRecord(event))) return void 0;
+	const events = result.events.map((event) => event);
+	const runId = scalar(args.run_id);
+	const types = Array.isArray(args.types) ? args.types : [];
+	const displayedTypes = types.slice(0, COLLECTION_ITEMS).map((type) => scalar(type)).join(", ");
+	const lines = [`Events: ${runId} — ${events.length} events`, ...types.length > 0 ? [`Filter: ${displayedTypes}${types.length > COLLECTION_ITEMS ? ` ${itemMarker(types.length - COLLECTION_ITEMS)}` : ""}`] : []];
+	if (events.length === 0) return [...lines, "No events."];
+	const displayed = events.slice(0, STATUS_ROWS);
+	lines.push(...displayed.map(eventRow));
+	if (events.length > displayed.length) lines.push(itemMarker(events.length - displayed.length));
+	return lines;
+}
+function inspectTranscriptRow(value) {
+	const kind = stringValue(value.kind);
+	const text = optionalScalar(value.text);
+	if (!kind) return void 0;
+	if (kind === "tool") {
+		const title = selected(value, "title", stringValue(value.kind) ?? stringValue(value.key));
+		const status = optionalScalar(value.status);
+		return `${title}${status ? ` (${status})` : ""}${text ? `: ${text}` : ""}`;
+	}
+	if (!text) return void 0;
+	if ([
+		"assistant",
+		"thought",
+		"user",
+		"permission",
+		"status",
+		"session"
+	].includes(kind)) return `${kind}: ${text}`;
+}
+function inspectToolRow(prefix, value) {
+	const title = selected(value, "title", stringValue(value.kind) ?? stringValue(value.key));
+	const status = optionalScalar(value.status);
+	const text = optionalScalar(value.preview);
+	return `${prefix}: ${title}${status ? ` (${status})` : ""}${text ? `: ${text}` : ""}`;
+}
+function inspectPermissionRow(value) {
+	const description = scalar(stringValue(value.description) ?? stringValue(value.question) ?? stringValue(value.tool) ?? stringValue(value.kind));
+	const options = permissionOptions(value);
+	const rows = optionRows(options);
+	return `Permission: ${description} (request_id: ${selected(value, "request_id")}); options:${rows ? ` ${rows}` : ""}${options.length > COLLECTION_ITEMS ? ` ${itemMarker(options.length - COLLECTION_ITEMS)}` : ""}`;
+}
+function inspectGroup(title, values, row) {
+	const rows = (Array.isArray(values) ? values.map(asRecord).filter((value) => !!value) : []).map(row).filter((value) => !!value);
+	return [
+		`${title}:`,
+		...rows.slice(0, INSPECT_ITEMS),
+		...rows.length > INSPECT_ITEMS ? [itemMarker(rows.length - INSPECT_ITEMS)] : []
+	];
+}
+function inspectLines(details, args) {
+	const inspect = asRecord(details);
+	const status = asRecord(inspect?.status);
+	if (!inspect || !status || !hasStatusIdentity(inspect) && !hasStatusIdentity(status)) return void 0;
+	const runId = selected(inspect, "run_id", args.run_id);
+	const label = selected(inspect, "label", void 0, runId);
+	const state = selected(status, "status");
+	const finalPreview = preview(inspect.final_output, FINAL_OUTPUT_CHARS$1);
+	const transcript = Array.isArray(inspect.transcript) ? inspect.transcript : [];
+	const tools = Array.isArray(inspect.tools) ? inspect.tools : [];
+	const liveTools = Array.isArray(inspect.live_tools) ? inspect.live_tools : [];
+	const permissions = Array.isArray(inspect.permissions) ? inspect.permissions : [];
+	return [
+		`Inspect: ${label} — ${state}`,
+		`Run: ${runId}`,
+		`Counts: transcript=${transcript.length}, tools=${tools.length}, live_tools=${liveTools.length}, permissions=${permissions.length}`,
+		...finalPreview ? ["Final output:", ...finalPreview] : ["Final output: unavailable."],
+		`Guidance: Call avenor_events with run_id "${runId}" for raw events.`,
+		...inspectGroup("Transcript", transcript, inspectTranscriptRow),
+		...inspectGroup("Tools", tools, (value) => inspectToolRow("Tool", value)),
+		...inspectGroup("Live tools", liveTools, (value) => inspectToolRow("Live tool", value)),
+		...inspectGroup("Permissions", permissions, inspectPermissionRow)
+	];
+}
+function shutdownLines(details, args) {
+	const result = asRecord(details);
+	if (!result || typeof result.ok !== "boolean" || !Array.isArray(result.cleaned_up)) return void 0;
+	const paths = result.cleaned_up.filter((path) => typeof path === "string");
+	const supervisor = stringValue(args.supervisor_id) ? scalar(args.supervisor_id) : "singleton";
+	return [
+		`Avenor shutdown: ${result.ok ? "succeeded" : "failed"}.`,
+		`Supervisor: ${supervisor}`,
+		`Mode: ${args.force === true ? "force" : "graceful"}`,
+		paths.length > 0 ? `Cleanup: ${paths.length} paths` : "Cleanup: none",
+		...!result.ok ? ["Warning: shutdown did not complete.", "Guidance: retry avenor_shutdown."] : [],
+		...paths.slice(0, CLEANUP_ITEMS).map((path) => `Cleanup path: ${scalar(path)}`),
+		...paths.length > CLEANUP_ITEMS ? [itemMarker(paths.length - CLEANUP_ITEMS)] : []
+	];
+}
+function formatStatusOutput(args, result) {
+	const statuses = Array.isArray(result) ? result : void 0;
+	if (statuses) return {
+		title: `Avenor status — ${statuses.length} runs`,
+		output: output(statusLines(statuses, args), "status"),
+		metadata: {
+			results: statuses,
+			count: statuses.length
+		}
+	};
+	const record = result;
+	return {
+		title: `${selected(record, "label", void 0, selected(record, "run_id", args.run_id))} — ${selected(record, "status")}`,
+		output: output(statusLines(result, args), "status"),
+		metadata: { ...result }
+	};
+}
+function formatResultOutput(args, result) {
+	const record = result;
+	return {
+		title: `${selected(record, "label", void 0, selected(record, "run_id", args.run_id))} — ${selected(record, "status")}${result.timed_out === true ? " (wait timed out)" : ""}`,
+		output: output(resultLines(result, args), "result"),
+		metadata: { ...result }
+	};
+}
+function formatAnswerPermissionOutput(args, result) {
+	return {
+		title: `${scalar(args.run_id)} — permission answered`,
+		output: output(permissionLines(result, args), "answer_permission"),
+		metadata: {
+			...result,
+			run_id: args.run_id,
+			option_id: args.option_id,
+			request_id: args.request_id
+		}
+	};
+}
+function formatFollowUpOutput(args, result) {
+	const record = result;
+	const runId = selected(record, "run_id", args.run_id);
+	return {
+		title: `${selected(record, "label", args.label, runId)} — dispatched`,
+		output: output(followUpLines(result, args), "follow_up"),
+		metadata: {
+			...result,
+			source_run_id: args.run_id
+		}
+	};
+}
+function formatEventsOutput(args, result) {
+	return {
+		title: `${scalar(args.run_id)} — ${result.events.length} events`,
+		output: output(eventsLines(result, args), "events"),
+		metadata: {
+			...result,
+			run_id: args.run_id,
+			count: result.events.length
+		}
+	};
+}
+function formatInspectOutput(args, result) {
+	const record = result;
+	const status = result.status;
+	return {
+		title: `${selected(record, "label", void 0, selected(record, "run_id", args.run_id))} — ${selected(status, "status")}`,
+		output: output(inspectLines(result, args), "inspect"),
+		metadata: { ...result }
+	};
+}
+function formatShutdownOutput(args, result) {
+	return {
+		title: "Avenor — shut down",
+		output: output(shutdownLines(result, args), "shutdown"),
+		metadata: {
+			...result,
+			supervisor_id: args.supervisor_id,
+			force: args.force ?? false
+		}
+	};
+}
+//#endregion
 //#region src/plugin.ts
 const TERMINAL_STATUSES = new Set([
 	"done",
@@ -54,7 +462,20 @@ function formatTranscriptPreview(snapshot) {
 	if (lines.length === 0) return void 0;
 	return clipTail(lines.join("\n"), METADATA_TEXT_CHARS);
 }
-function buildSnapshotMetadata(snapshot) {
+/** Project shared spawn identity into OpenCode metadata without resolving rosters here. */
+function hostIdentityMetadata(run = {}, status) {
+	const metadata = {};
+	const add = (key, value) => {
+		if (typeof value === "string" && value.length > 0) metadata[key] = value;
+	};
+	add("roster_file", status?.roster_file ?? run.rosterFile);
+	add("roster_entry", status?.roster_entry ?? run.rosterEntry);
+	add("effective_agent", status?.effective_agent ?? status?.agent ?? run.effectiveAgent);
+	add("effective_model", status?.effective_model ?? status?.model ?? run.effectiveModel);
+	add("effective_backend", status?.effective_backend ?? status?.backend ?? run.effectiveBackend);
+	return metadata;
+}
+function buildSnapshotMetadata(snapshot, run, status) {
 	const metadata = {};
 	if (snapshot.phase) metadata.phase = snapshot.phase;
 	if (snapshot.latest_seq !== void 0) metadata.latest_seq = snapshot.latest_seq;
@@ -64,6 +485,7 @@ function buildSnapshotMetadata(snapshot) {
 	if (transcriptPreview) metadata.transcript_preview = transcriptPreview;
 	const pendingPermission = clipTail(snapshot.pending_permission?.description ?? snapshot.pending_permission?.question ?? snapshot.phase_label, METADATA_TEXT_CHARS);
 	if (pendingPermission) metadata.pending_permission = pendingPermission;
+	Object.assign(metadata, hostIdentityMetadata(run, status));
 	return metadata;
 }
 function buildWaitingText(run, snapshot) {
@@ -136,6 +558,16 @@ const AvenorPlugin = async (ctx) => {
 		if (snapshot.latest_seq !== void 0) run.latestSeq = snapshot.latest_seq;
 		registerSessionId(snapshot.identity.session_id, snapshot.identity.runtime_id, run.runId);
 	}
+	function updateRunIdentity(run, status) {
+		run.rosterFile = status.roster_file ?? run.rosterFile;
+		run.rosterEntry = status.roster_entry ?? run.rosterEntry;
+		run.effectiveAgent = status.effective_agent ?? status.agent ?? run.effectiveAgent;
+		run.effectiveModel = status.effective_model ?? status.model ?? run.effectiveModel;
+		run.effectiveBackend = status.effective_backend ?? status.backend ?? run.effectiveBackend;
+		run.agent = run.effectiveAgent ?? run.agent;
+		run.model = run.effectiveModel ?? run.model;
+		run.backend = run.effectiveBackend ?? run.backend;
+	}
 	async function primeTrackedRun(run, options = {}) {
 		try {
 			const raw = await statusTool({
@@ -145,6 +577,7 @@ const AvenorPlugin = async (ctx) => {
 			const status = Array.isArray(raw) ? raw[0] : raw;
 			if (!status) return void 0;
 			registerSessionId(status.session_id, status.runtime_id, run.runId);
+			updateRunIdentity(run, status);
 			if (status.latest_seq !== void 0 && options.captureLatestSeq) run.latestSeq = status.latest_seq;
 			return status;
 		} catch {
@@ -170,10 +603,12 @@ const AvenorPlugin = async (ctx) => {
 	}
 	async function loadInspection(run) {
 		try {
-			return await inspectTool({
+			const inspection = await inspectTool({
 				runId: run.runId,
 				supervisorId: run.supervisorId
 			});
+			updateRunIdentity(run, inspection.status);
+			return inspection;
 		} catch {
 			return;
 		}
@@ -432,33 +867,54 @@ const AvenorPlugin = async (ctx) => {
 		},
 		tool: {
 			avenor_spawn: tool({
-				description: "Dispatch an agent run via avenor. Blocks by default, showing live progress as an updating tool call. Set wait=false for fire-and-forget — you will be re-prompted automatically on completion.",
+				description: "Dispatch an agent run via avenor. Optional thinking accepts off, minimal, low, medium, high, xhigh, or max; unsupported backends reject explicit values. Blocks by default, showing live progress as an updating tool call. Set wait=false for fire-and-forget — you will be re-prompted automatically on completion.",
 				args: {
-					agent: tool.schema.string().describe("Agent name (required, no default)"),
+					agent: tool.schema.string().optional().describe("Optional agent name; omission uses the supplied model or runtime defaults"),
 					prompt: tool.schema.string().optional().describe("Prompt text"),
 					prompt_file: tool.schema.string().optional().describe("Path to prompt file"),
 					dir: tool.schema.string().optional().describe("Working directory for the run (defaults to the session project directory)"),
 					label: tool.schema.string().optional().describe("Human-readable label for the run"),
 					timeout: tool.schema.string().optional().describe("Timeout duration (e.g. 3600s)"),
 					model: tool.schema.string().optional().describe("Model override"),
+					thinking: tool.schema.enum([
+						"off",
+						"minimal",
+						"low",
+						"medium",
+						"high",
+						"xhigh",
+						"max"
+					]).optional().describe("Thinking level; omission uses the backend default"),
 					backend: tool.schema.string().optional().describe("Backend override"),
+					roster_file: tool.schema.string().optional().describe("Path to the roster map"),
+					roster_entry: tool.schema.string().optional().describe("Roster entry to select"),
 					server_url: tool.schema.string().optional().describe("Backend server URL"),
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path"),
 					wait: tool.schema.boolean().default(true).describe("Block until complete with live status updates. False = fire-and-forget.")
 				},
 				async execute(args, context) {
-					const ownerRunId = ensureParentRunId();
-					const result = await spawnTool({
+					validateSpawnSelection({
 						agent: args.agent,
-						prompt: args.prompt,
-						promptFile: args.prompt_file,
-						label: args.label,
-						dir: args.dir ?? context.directory,
-						timeout: args.timeout,
 						model: args.model,
 						backend: args.backend,
-						serverUrl: args.server_url,
-						supervisorId: args.supervisor_id,
+						roster_file: args.roster_file,
+						roster_entry: args.roster_entry
+					});
+					const ownerRunId = ensureParentRunId();
+					const result = await spawnTool({
+						...args.agent !== void 0 ? { agent: args.agent } : {},
+						...args.prompt !== void 0 ? { prompt: args.prompt } : {},
+						...args.prompt_file !== void 0 ? { promptFile: args.prompt_file } : {},
+						...args.label !== void 0 ? { label: args.label } : {},
+						dir: args.dir ?? context.directory,
+						...args.timeout !== void 0 ? { timeout: args.timeout } : {},
+						...args.model !== void 0 ? { model: args.model } : {},
+						...args.thinking !== void 0 ? { thinking: args.thinking } : {},
+						...args.backend !== void 0 ? { backend: args.backend } : {},
+						...args.roster_file !== void 0 ? { rosterFile: args.roster_file } : {},
+						...args.roster_entry !== void 0 ? { rosterEntry: args.roster_entry } : {},
+						...args.server_url !== void 0 ? { serverUrl: args.server_url } : {},
+						...args.supervisor_id !== void 0 ? { supervisorId: args.supervisor_id } : {},
 						parent_run_id: ownerRunId
 					});
 					if (result.broker_url) brokerUrl = result.broker_url;
@@ -467,6 +923,10 @@ const AvenorPlugin = async (ctx) => {
 						runId: result.run_id,
 						runtimeId: result.runtime_id,
 						agent: args.agent,
+						model: args.model,
+						backend: args.backend,
+						rosterFile: args.roster_file,
+						rosterEntry: args.roster_entry,
 						orchestratorSessionId: context.sessionID,
 						label: result.label,
 						supervisorId: result.supervisor_id || args.supervisor_id,
@@ -479,7 +939,8 @@ const AvenorPlugin = async (ctx) => {
 						monitorRun(run).catch(console.error);
 						return {
 							title: `${result.label} — dispatched`,
-							output: `Dispatched "${result.label}" (run_id: ${result.run_id}). Completion will be delivered automatically; use avenor_status with view "lifecycle" for progress or avenor_result to wait for the final result.`
+							output: `Dispatched "${result.label}" (run_id: ${result.run_id}). Completion will be delivered automatically; use avenor_status with view "lifecycle" for progress or avenor_result to wait for the final result.`,
+							metadata: hostIdentityMetadata(run)
 						};
 					}
 					context.metadata({ title: `Starting ${result.label}…` });
@@ -488,7 +949,7 @@ const AvenorPlugin = async (ctx) => {
 						onSnapshot: (snapshot) => {
 							context.metadata({
 								title: snapshot.pending_permission ? `[blocked] ${result.label}` : result.label,
-								metadata: buildSnapshotMetadata(snapshot)
+								metadata: buildSnapshotMetadata(snapshot, run)
 							});
 						}
 					});
@@ -503,7 +964,7 @@ const AvenorPlugin = async (ctx) => {
 								run_id: result.run_id,
 								session_id: inspection?.status.session_id ?? snapshot.identity.session_id,
 								final_output: clipTail(inspection?.final_output ?? snapshot.final_output, FINAL_OUTPUT_CHARS),
-								...buildSnapshotMetadata(snapshot)
+								...buildSnapshotMetadata(snapshot, run, inspection?.status)
 							}
 						};
 					}
@@ -516,20 +977,26 @@ const AvenorPlugin = async (ctx) => {
 							metadata: {
 								run_id: result.run_id,
 								session_id: inspection?.status.session_id ?? snapshot.identity.session_id,
-								...buildSnapshotMetadata(snapshot)
+								...buildSnapshotMetadata(snapshot, run, inspection?.status)
 							}
 						};
 					}
 					if (outcome.kind === "error") return {
 						title: `${result.label} — monitoring error`,
 						output: `Monitoring failed: ${outcome.error ?? "unknown error"}. The run may still be active — use avenor_status to check.`,
-						metadata: { run_id: result.run_id }
+						metadata: {
+							run_id: result.run_id,
+							...hostIdentityMetadata(run)
+						}
 					};
 					unregisterRun(result.run_id);
 					return {
 						title: `${result.label} — aborted`,
 						output: `Monitoring of "${result.label}" (run_id: ${result.run_id}) was interrupted. The run may still be active — use avenor_status to check.`,
-						metadata: { run_id: result.run_id }
+						metadata: {
+							run_id: result.run_id,
+							...hostIdentityMetadata(run)
+						}
 					};
 				}
 			}),
@@ -541,12 +1008,11 @@ const AvenorPlugin = async (ctx) => {
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
 				},
 				async execute(args, _context) {
-					const result = await statusTool({
+					return formatStatusOutput(args, await statusTool({
 						runId: args.run_id,
 						supervisorId: args.supervisor_id,
 						view: args.view
-					});
-					return JSON.stringify(result, null, 2);
+					}));
 				}
 			}),
 			avenor_result: tool({
@@ -570,7 +1036,7 @@ const AvenorPlugin = async (ctx) => {
 						});
 						if (result.ready) unregisterRun(args.run_id);
 						else if (run) monitorRun(run).catch(console.error);
-						return JSON.stringify(result, null, 2);
+						return formatResultOutput(args, result);
 					} catch (error) {
 						if (run) monitorRun(run).catch(console.error);
 						throw error;
@@ -587,14 +1053,13 @@ const AvenorPlugin = async (ctx) => {
 					message: tool.schema.string().optional().describe("Optional write-in response text. Required only when the selected option declares requiresMessage: true.")
 				},
 				async execute(args, _context) {
-					const result = await answerPermissionTool({
+					return formatAnswerPermissionOutput(args, await answerPermissionTool({
 						runId: args.run_id,
 						optionId: args.option_id,
 						requestId: args.request_id,
 						supervisorId: args.supervisor_id,
 						message: args.message
-					});
-					return JSON.stringify(result, null, 2);
+					}));
 				}
 			}),
 			avenor_follow_up: tool({
@@ -624,7 +1089,7 @@ const AvenorPlugin = async (ctx) => {
 					trackedRuns.set(result.run_id, run);
 					await primeTrackedRun(run);
 					monitorRun(run).catch(console.error);
-					return JSON.stringify(result, null, 2);
+					return formatFollowUpOutput(args, result);
 				}
 			}),
 			avenor_events: tool({
@@ -636,13 +1101,12 @@ const AvenorPlugin = async (ctx) => {
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
 				},
 				async execute(args, _context) {
-					const result = await eventsTool({
+					return formatEventsOutput(args, await eventsTool({
 						runId: args.run_id,
 						types: args.types,
 						limit: args.limit,
 						supervisorId: args.supervisor_id
-					});
-					return JSON.stringify(result, null, 2);
+					}));
 				}
 			}),
 			avenor_inspect: tool({
@@ -654,13 +1118,12 @@ const AvenorPlugin = async (ctx) => {
 					supervisor_id: tool.schema.string().optional().describe("Reuse an existing supervisor by socket path")
 				},
 				async execute(args, _context) {
-					const result = await inspectTool({
+					return formatInspectOutput(args, await inspectTool({
 						runId: args.run_id,
 						limit: args.limit,
 						after_seq: args.after_seq,
 						supervisorId: args.supervisor_id
-					});
-					return JSON.stringify(result, null, 2);
+					}));
 				}
 			}),
 			avenor_shutdown: tool({
@@ -671,15 +1134,14 @@ const AvenorPlugin = async (ctx) => {
 				},
 				async execute(args, _context) {
 					await stopTrackedRuns((run) => !args.supervisor_id || run.supervisorId === args.supervisor_id);
-					const result = await shutdownTool({
+					return formatShutdownOutput(args, await shutdownTool({
 						supervisorId: args.supervisor_id,
 						force: args.force
-					});
-					return JSON.stringify(result, null, 2);
+					}));
 				}
 			})
 		}
 	};
 };
 //#endregion
-export { AvenorPlugin, buildWaitingText, terminalStatus };
+export { AvenorPlugin, buildSnapshotMetadata, buildWaitingText, hostIdentityMetadata, terminalStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-opencode",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "^0.8.3"
+    "@dougbots/avenor-core": "^0.10.0"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "1.15.3"