pi-roundtable-coding 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-10-03
+
+- Add `toolText` and `presentation.list`, accept a 7–40 character sha prefix in `repo_push`, name git and gh stderr (scrubbed) in failures, carry a worker's own error text into the report, restore the earlier timeout, stop and refusal wording, stop listing declined calls as held, and report the channels the service works for.
+
+## [0.7.3] - 2026-10-03
+
+- Hook caller model/thinking/origin/channel, owner policy, clone adoption, threaded approvals and report formatting through options, and add `pushHoldText` for the held `repo_push` card.
+
 ## [0.7.2] - 2026-10-02
 
 First release published by the lockstep workflow; no changes to the package.

package/README.md

@@ -78,7 +78,9 @@ All five tools have `minTier: "owner"` and are contributed through `defineTool`
 The operator remains responsible for any tool-tier overrides.
 A custom owner claim with a restricted `ToolSelection` must include the exported `REPO_TOOLS` names; include `skill_list` separately when the host skills addon is enabled.
 The host's skills addon resolves explicit skills, or the calling agent's carried skills when omitted; an owner call carries none unless it names them.
-Missing or unknown skills refuse the task; requesting skills while the addon is off also refuses it.
+Missing or unknown skills refuse the task by default; requesting skills while the addon is off also refuses it.
+`skipUnavailableCarriedSkills: true` opts into skipping unavailable implicit skills and disclosing them in the task-start text or through `presentation.taskStarted`.
+Explicit skill requests still refuse missing or unknown skills.
 Sessions with kind `owner` get the public `skillListExtension`; agent sessions keep the core's existing `skill_list` instead of registering it twice.
 
 A worker reads the repository's instructions, edits and checks the work, and commits using repository conventions.
@@ -99,7 +101,10 @@ Shipping is separate from coding:
 
 `ownerRepos` is an exact list of `owner/repo` names, not a prefix or wildcard; its default is empty.
 Listed repositories skip the plugin's `repo_push` hold, though other host hold rules can still hold the call.
-They do not exempt shell pushes or risky worker actions.
+A trusted `isOwnerRepo(repo)` host policy can grant additional exemptions, including repositories created after startup; only literal `true` grants one.
+The package validates the repository name before consulting it.
+Never derive this policy from model input, clone files, or remote repository instructions.
+Neither exemption bypasses shell pushes, risky worker actions, or other linked host rules.
 The report and approval card name the full SHA, current default branch and credential-free push destination.
 The clone must have exactly one push destination; HTTP remote URLs with user information, query strings or fragments are refused before fetching.
 A changed HEAD, dirty clone, changed remote default branch, changed push destination, missing report or non-fast-forward remote causes refusal.
@@ -109,6 +114,9 @@ Report receipts live in memory, so request a fresh report after restarting the h
 
 Every worker tool call crosses a private Bun IPC channel to the parent process before execution.
 The parent consults `shellHoldRule`, additional `holds`, and the host's linked hold rules; a recognized risky action asks the owner's surface prompts using `approvalCard`.
+When `threads` is configured, progress and cards stay in a thread opened under the resolved run's `origin`; if no thread can open, calls remain held rather than falling back to another channel's approval cards.
+Without `threads`, the resolved report channel's prompts are used.
+`threadText` controls the initial post, held-action post, approval title and final report; the thread is archived before `onResult` is called, and a failed thread post/close does not discard result delivery.
 `promptSlot` tracks these cards and `workTimeout` excludes their waiting time from the worker's budget (one hour by default).
 `timeoutMs` must be positive and finite, and at most 2,147,483,647 ms to fit the host timer.
 An approved call runs; a declined, expired, missing or failed card blocks it and instructs the worker not to retry or work around the refusal.
@@ -129,7 +137,7 @@ This is a host coding desk, **not a sandbox**.
 The worker can run local checks, read the host's accessible files, use the network and commit changes.
 Its standing instructions delegate shipping to the calling agent; repository tools and extra package tools are not activated inside the worker.
 `repo_push` is the supported shipping route and always uses a previously reported full SHA and a non-force push.
-The public shell rule holds recognized shell pushes, destructive commands, privileged commands and recognized writes outside the clone, even for `ownerRepos`.
+The public shell rule holds recognized shell pushes, destructive commands, privileged commands and recognized writes outside the configured worker workspace (the clone by default), even for owner-owned repositories.
 It is a heuristic guard: scripts, interpreters, symlinks, Git hooks, package extensions and detached grandchildren are not an OS isolation boundary.
 A trusted package or arbitrary shell program can bypass heuristic detection; only run code and repositories you trust, under a dedicated low-privilege host user.
 Use an isolated container or VM when host access is unacceptable.
@@ -153,6 +161,18 @@ The `CODING` service exposes `shelf: RepoShelf` and `desk: CodingDesk` for trust
 | `model` | required | Worker provider/model ID. |
 | `thinking` | `medium` | Pi thinking level. |
 | `ownerRepos` | `[]` | Exact push-hold exemptions. |
+| `isOwnerRepo` | none | Trusted host policy for additional push-hold exemptions; must return literal true. |
+| `pushHoldText` | repository, sha, target and branch | Trusted wording for the approval card of a held `repo_push`; it never changes who is held. |
+| `adoptClones` | `[]` | Startup `{ from, repo }` moves of standalone clones; existing shelf destinations are never replaced. |
+| `resolveRun` | configured model/thinking, caller channel | Per-caller model, thinking, report channel and optional thread origin. |
+| `postChangeReport` | caller surface reply | Post the record using the calling identity and channel. |
+| `presentation` | English package text | Separate change-report post/result text, task-start/omitted-skill wording, and the `repo_list` result (`list(repos, { shelfDir, fetched })`). |
+| `toolText` | package wording | Trusted description and argument descriptions for each repository tool, as `{ repo_task: { description, parameters: { task: "…" } } }`; it never changes a tool's arguments or approval rules. |
+| `threads` | none | Public `DispatchThreads`-compatible progress and approval thread port. |
+| `threadText` | English package text | Thread introduction, held-action notice, approval title and final report. |
+| `workerWorkspace` | individual clone | Trusted shell-policy write boundary; not an OS sandbox. |
+| `workerPrompt` | generic worker instructions | Trusted standing prompt replacement; it cannot bypass approval or cleanup. |
+| `skipUnavailableCarriedSkills` | `false` | Skip and disclose unavailable implicit skills; explicit skill requests still refuse them. |
 | `workerPackages` | `[]` | Absolute installed extension paths. |
 | `agentDir` | Pi host directory | Pi credentials and model configuration. |
 | `timeoutMs` | `3600000` | Work-time limit in ms, excluding owner wait; 0 < value <= 2147483647. |
@@ -162,6 +182,10 @@ The `CODING` service exposes `shelf: RepoShelf` and `desk: CodingDesk` for trust
 | `onResult` | surface reply | Report delivery integration. |
 
 `RepoShelf`, `CodingDesk`, `PiCodingWorker`, `CodingWorkerFailure`, `REPO_TOOLS`, `codingReport`, `reportPost` and their option/result types are exported for testing and host integrations.
+`resolveRun(turn)` receives the public `ToolTurn`, including the calling agent scope and channel.
+It returns `{ model, thinking, channel, origin? }`; skill selection still follows the caller, not the resolved report destination.
+`onResult` receives those fields plus loaded `skillNames` and the optional progress `thread` in `result.job`, so a host can enqueue its own localized conversation turn.
+`adoptClones` and `RepoShelf.adopt` keep existing clone contents and path layout without database migrations.
 No database or Discord-specific types are required.
 
 ## Development and publishing

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-coding",
-	"version": "0.7.2",
+	"version": "0.7.4",
 	"description": "Repository shelves and owner-approved Pi coding workers for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -44,7 +44,7 @@
 		"@earendil-works/pi-ai": ">=1.0.0 <2",
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
-		"pi-roundtable": "0.7.2",
+		"pi-roundtable": "0.7.4",
 		"typescript": "7.0.2"
 	}
 }

package/src/coding-desk.ts

@@ -8,6 +8,8 @@ import type {
 import {
 	AgentError,
 	approvalCard,
+	type DispatchThread,
+	type DispatchThreads,
 	promptSlot,
 	workTimeout,
 } from "pi-roundtable/kit";
@@ -20,6 +22,12 @@ export interface CodingJob {
 	repo: string;
 	task: string;
 	channel: ChannelKey;
+	/** The calling turn's channel, where a progress thread opens. */
+	origin?: ChannelKey;
+	/** Host-resolved names of the skills carried to this run. */
+	skillNames?: string[];
+	/** Progress thread, when the surface supports one. */
+	thread?: DispatchThread;
 	model: string;
 	thinking: ThinkingLevel;
 	skillFiles: string[];
@@ -40,10 +48,19 @@ export interface CodingResult {
 	state?: RepoState;
 	commits: string[];
 }
+export interface CodingThreadText {
+	initial?(job: CodingJob): string;
+	held?(entry: string, job: CodingJob): string;
+	approvalTitle?(job: CodingJob): string;
+	report?(result: CodingResult): string;
+}
 export interface CodingDeskOptions {
 	shelf: Pick<RepoShelf, "dirOf" | "state" | "commitsSince">;
 	worker: CodingWorker;
-	prompts(channel: ChannelKey): OwnerPrompts | undefined;
+	prompts?(channel: ChannelKey): OwnerPrompts | undefined;
+	/** When configured, approval cards stay in the job's thread; no thread means held. */
+	threads?: Pick<DispatchThreads, "open">;
+	threadText?: CodingThreadText;
 	deliver(result: CodingResult): Promise<void>;
 	logger: Logger;
 	timeoutMs?: number;
@@ -79,6 +96,9 @@ export class CodingDesk {
 			);
 		this.#options = options;
 	}
+	runningChannels(): ChannelKey[] {
+		return [...this.#running.values()].map(({ job }) => job.channel);
+	}
 	busy(): string[] {
 		return [...this.#running.values()].map(
 			({ job }) => `Coding #${job.id} in ${job.repo}`,
@@ -97,22 +117,30 @@ export class CodingDesk {
 		await this.idle();
 	}
 	async start(
-		request: Omit<CodingJob, "id" | "startedAt" | "startHead">,
+		request: Omit<CodingJob, "id" | "startedAt" | "startHead" | "thread">,
 	): Promise<CodingJob> {
 		if (this.#stopped) throw new AgentError("The coding desk is stopped.");
 		const task = request.task.trim();
-		if (!task || task.length > MAX_CODING_TASK_CHARS)
+		if (!task) throw new AgentError("The task is required.");
+		if (task.length > MAX_CODING_TASK_CHARS)
 			throw new AgentError(
-				`The task must contain 1–${MAX_CODING_TASK_CHARS} characters.`,
+				`The task is ${task.length} characters; keep it within ${MAX_CODING_TASK_CHARS}.`,
 			);
 		const dir = this.#options.shelf.dirOf(request.repo);
-		this.checkIdle(request.repo);
-		if (
-			[...this.#running.values()].filter(
-				({ job }) => job.channel === request.channel,
-			).length >= 3
-		)
-			throw new AgentError("This channel already has three coding workers.");
+		const busy = [...this.#running.values()].find(
+			({ job }) => job.repo === request.repo,
+		);
+		if (busy)
+			throw new AgentError(
+				`Coding task #${busy.job.id} is still working in ${request.repo}; one worker runs per repository.`,
+			);
+		const inChannel = [...this.#running.values()].filter(
+			({ job }) => job.channel === request.channel,
+		).length;
+		if (inChannel >= 3)
+			throw new AgentError(
+				`This channel already has ${inChannel} coding workers running; wait for one to report back.`,
+			);
 		const job: CodingJob = {
 			...request,
 			task,
@@ -146,6 +174,8 @@ export class CodingDesk {
 			shelf,
 			worker,
 			prompts,
+			threads,
+			threadText,
 			deliver,
 			timeoutMs = 3_600_000,
 		} = this.#options;
@@ -158,8 +188,30 @@ export class CodingDesk {
 		try {
 			job.startHead = (await shelf.state(job.repo)).head;
 			if (controller.signal.aborted)
-				throw new AgentError("The worker was stopped.");
-			slot.bind(prompts(job.channel), `Coding worker #${job.id}`);
+				throw new AgentError("the worker was stopped");
+			if (threads) {
+				try {
+					const thread = await threads.open(
+						job.origin,
+						`${job.repo} #${job.id}`,
+						threadText?.initial?.(job) ?? `Task:\n${job.task}`,
+					);
+					if (thread) job.thread = thread;
+				} catch {
+					this.#options.logger.warn(
+						{ job: job.id },
+						"Coding thread unavailable.",
+					);
+				}
+			}
+			if (controller.signal.aborted)
+				throw new AgentError("the worker was stopped");
+			slot.bind(
+				threads
+					? job.thread && prompts?.(job.thread.channel)
+					: prompts?.(job.channel),
+				`Coding worker #${job.id}`,
+			);
 			cancel = workTimeout(timeoutMs, slot, () => {
 				timedOut = true;
 				controller.abort();
@@ -168,7 +220,8 @@ export class CodingDesk {
 				let answer: HeldCallAnswer = "held";
 				try {
 					const decision = await slot.prompts?.confirm(
-						`${slot.asker} requests approval`,
+						threadText?.approvalTitle?.(job) ??
+							`${slot.asker} requests approval`,
 						approvalCard(call),
 						controller.signal,
 					);
@@ -177,15 +230,22 @@ export class CodingDesk {
 				} catch {
 					/* A failed card never authorizes the call. */
 				}
-				if (answer !== "approved") {
-					if (held.length < MAX_HELD_ENTRIES)
-						held.push(
-							bounded(
-								`${answer}: ${call.action}: ${call.tool} ${call.input}`,
-								MAX_HELD_CHARS,
-							),
+				// A call the owner declined is settled, not held for the report.
+				if (answer === "held") {
+					if (held.length < MAX_HELD_ENTRIES) {
+						const entry = bounded(
+							`${call.action}: ${call.tool} ${call.input}`,
+							MAX_HELD_CHARS,
 						);
-					else omittedHeld++;
+						held.push(entry);
+						try {
+							await job.thread?.post(
+								threadText?.held?.(entry, job) ?? `Held: ${entry}`,
+							);
+						} catch {
+							/* A failed progress post does not discard the held action. */
+						}
+					} else omittedHeld++;
 				}
 				return answer;
 			};
@@ -195,22 +255,22 @@ export class CodingDesk {
 				review,
 			);
 			if (controller.signal.aborted)
-				throw new AgentError("The worker was stopped.");
+				throw new AgentError("the worker was stopped");
 			outcome = { ok: true, report: bounded(report, MAX_REPORT_CHARS) };
 		} catch (error) {
-			// Only structured, fixed diagnostics can cross the worker boundary.
+			// The host's own refusals and the worker's scrubbed, bounded error text reach the report.
 			let message =
 				"The worker failed; inspect the clone and worker configuration on the host.";
+			if (error instanceof AgentError) message = error.message;
 			if (error instanceof CodingWorkerFailure) {
-				message = error.message;
 				this.#options.logger.warn(
 					{ job: job.id, category: error.category, exitCode: error.exitCode },
 					"Coding worker failed.",
 				);
 			}
-			if (controller.signal.aborted) message = "The worker was stopped.";
+			if (controller.signal.aborted) message = "the worker was stopped";
 			if (timedOut)
-				message = `Work timeout after ${timeoutMs} ms (owner wait excluded).`;
+				message = `the worker ran out of time (${Math.round(timeoutMs / 60_000)} minutes)`;
 			outcome = { ok: false, error: message };
 		} finally {
 			cancel();
@@ -230,7 +290,25 @@ export class CodingDesk {
 		}
 		if (omittedHeld)
 			held.push(`[${omittedHeld} more unapproved actions omitted]`);
-		await deliver({ job, outcome, held, ...(state ? { state } : {}), commits });
+		const result: CodingResult = {
+			job,
+			outcome,
+			held,
+			...(state ? { state } : {}),
+			commits,
+		};
+		try {
+			await job.thread?.close(
+				bounded(
+					threadText?.report?.(result) ??
+						codingReport(result, job.startedAt.toISOString()),
+					MAX_REPORT_CHARS,
+				),
+			);
+		} catch {
+			this.#options.logger.warn({ job: job.id }, "Coding thread close failed.");
+		}
+		await deliver(result);
 	}
 }
 

package/src/coding-plugin.ts

@@ -1,4 +1,5 @@
 import {
+	type ChannelKey,
 	definePlugin,
 	defineTool,
 	type HoldCheck,
@@ -7,29 +8,70 @@ import {
 	serviceKey,
 	type ThinkingLevel,
 	ToolRefusal,
+	type ToolTurn,
 } from "pi-roundtable";
 import {
 	AgentError,
 	checkRepoName,
+	type DispatchThreads,
 	skillListExtension,
 	zonedStamp,
 } from "pi-roundtable/kit";
 import { Type } from "typebox";
 import {
 	CodingDesk,
+	type CodingJob,
 	type CodingResult,
+	type CodingThreadText,
 	type CodingWorker,
 	codingReport,
 	MAX_CODING_TASK_CHARS,
 } from "./coding-desk.ts";
 import { PiCodingWorker } from "./pi-coding-worker.ts";
-import { type CloneCommand, RepoShelf, reportPost } from "./repo-shelf.ts";
+import {
+	type ChangeReport,
+	type CloneCommand,
+	RepoShelf,
+	type RepoSummary,
+	reportPost,
+} from "./repo-shelf.ts";
 
 export interface CodingService {
 	readonly shelf: RepoShelf;
 	readonly desk: CodingDesk;
 }
 export const CODING = serviceKey<CodingService>("coding.workbench");
+export interface CodingRun {
+	model: string;
+	thinking: ThinkingLevel;
+	channel: ChannelKey;
+	origin?: ChannelKey;
+}
+export type RepoToolName =
+	| "repo_list"
+	| "repo_add"
+	| "repo_change_report"
+	| "repo_push"
+	| "repo_task";
+/** Trusted wording of one repository tool, as the model reads it; unset fields keep the defaults. */
+export interface CodingToolText {
+	description?: string;
+	/** Argument descriptions by argument name. */
+	parameters?: Record<string, string>;
+}
+export interface CodingPresentation {
+	/** The repo_list result; unset: the managed clones as JSON. */
+	list?(
+		repos: (RepoSummary & { skills: string[] })[],
+		context: { shelfDir: string; fetched: boolean },
+	): string;
+	/** Separate the owner's posted record from the model's shipping instructions. */
+	changeReport?(
+		report: ChangeReport,
+		direct: boolean,
+	): { post: string; result: string };
+	taskStarted?(job: CodingJob, skippedSkills: string[]): string;
+}
 export interface CodingOptions {
 	shelfDir: string;
 	/** Provider/model-id, resolved with the worker's Pi host login. */
@@ -37,6 +79,26 @@ export interface CodingOptions {
 	thinking?: ThinkingLevel;
 	/** Exact owner/repo names allowed to use repo_push without a hold. Default: none. */
 	ownerRepos?: string[];
+	/** Trusted host policy for additional owner-owned repositories, including future clones.
+	 * Only literal true grants an exemption. This never bypasses linked host hold rules. */
+	isOwnerRepo?: (repo: string) => boolean;
+	/** Trusted wording for the approval card of a held `repo_push`. Default: names the repository, sha, target and branch. */
+	pushHoldText?: (repo: string, sha: string) => string;
+	/** Moves legacy standalone clones before the host reads shelf-linked skills. */
+	adoptClones?: { from: string; repo: string }[];
+	/** Resolve the calling agent/owner's run identity, independently of report posting. */
+	resolveRun?: (turn: ToolTurn) => CodingRun | Promise<CodingRun>;
+	/** Post change reports in the caller's identity/channel rather than the default surface. */
+	postChangeReport?: (turn: ToolTurn, text: string) => Promise<void>;
+	presentation?: CodingPresentation;
+	/** Trusted wording of the repository tools' descriptions and arguments. */
+	toolText?: Partial<Record<RepoToolName, CodingToolText>>;
+	threads?: Pick<DispatchThreads, "open">;
+	threadText?: CodingThreadText;
+	workerWorkspace?: string;
+	workerPrompt?: (dir: string) => string;
+	/** Opt in to skipping unavailable implicit skills; explicit requests always fail closed. */
+	skipUnavailableCarriedSkills?: boolean;
 	/** Absolute installed extension package paths. Default: none. */
 	workerPackages?: string[];
 	agentDir?: string;
@@ -66,17 +128,25 @@ export function coding(options: CodingOptions) {
 		throw new PluginError("model must be provider/model-id.");
 	const ownerRepos = new Set(options.ownerRepos ?? []);
 	for (const repo of ownerRepos) checkRepoName(repo);
+	const ownerOwned = (repo: string): boolean => {
+		checkRepoName(repo);
+		return ownerRepos.has(repo) || options.isOwnerRepo?.(repo) === true;
+	};
 	return definePlugin({
 		name: "coding",
 		provides: [CODING],
 		setup(context) {
 			const shelf = new RepoShelf(options.shelfDir, options.clone);
+			for (const adoption of options.adoptClones ?? [])
+				shelf.adopt(adoption.from, adoption.repo);
 			const skills = context.services.find(SKILLS);
 			const worker =
 				options.worker ??
 				new PiCodingWorker({
 					packages: options.workerPackages,
 					agentDir: options.agentDir,
+					workspace: options.workerWorkspace,
+					prompt: options.workerPrompt,
 					holds: (tool, input, scope) =>
 						options.holds?.(tool, input, scope) ??
 						context.sessions().holds(tool, input, scope),
@@ -86,6 +156,8 @@ export function coding(options: CodingOptions) {
 				worker,
 				timeoutMs: options.timeoutMs,
 				logger: context.logger,
+				threads: options.threads,
+				threadText: options.threadText,
 				prompts: (channel) => context.surfaces.prompts(channel),
 				deliver:
 					options.onResult ??
@@ -118,14 +190,21 @@ export function coding(options: CodingOptions) {
 				}
 			}
 			context.services.provide(CODING, { shelf, desk });
-			const repoSchema = Type.String({
-				description: "A managed repository, owner/repo.",
-			});
+			const textOf = (tool: RepoToolName) => options.toolText?.[tool];
+			const describe = (tool: RepoToolName, fallback: string) =>
+				textOf(tool)?.description ?? fallback;
+			const about = (tool: RepoToolName, name: string, fallback?: string) => {
+				const description = textOf(tool)?.parameters?.[name] ?? fallback;
+				return description ? { description } : {};
+			};
+			const repoSchema = (tool: RepoToolName) =>
+				Type.String(about(tool, "repo", "A managed repository, owner/repo."));
 			return {
 				services: [
 					{
 						name: "coding-desk",
-						busy: () => desk.busy(),
+						// The host names the channels whose work a shutdown waits for or aborts.
+						busy: () => desk.runningChannels(),
 						stop: () => desk.stop(),
 					},
 				],
@@ -148,30 +227,39 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_list",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_list",
 							"List managed clones, branch, upstream counts, dirty files, last commit, summary, CI hints and linked skills. Fetch first only when requested.",
-						parameters: Type.Object({ fetch: Type.Optional(Type.Boolean()) }),
+						),
+						parameters: Type.Object({
+							fetch: Type.Optional(Type.Boolean(about("repo_list", "fetch"))),
+						}),
 						run: ({ fetch }) =>
 							refusal(async () => {
-								const repos = await shelf.list(fetch === true);
+								const repos = (await shelf.list(fetch === true)).map(
+									(repo) => ({
+										...repo,
+										skills: skills?.linkedFrom(repo.repo) ?? [],
+									}),
+								);
+								if (options.presentation?.list)
+									return options.presentation.list(repos, {
+										shelfDir: shelf.dir,
+										fetched: fetch === true,
+									});
 								return repos.length
-									? JSON.stringify(
-											repos.map((repo) => ({
-												...repo,
-												skills: skills?.linkedFrom(repo.repo) ?? [],
-											})),
-											null,
-											2,
-										)
+									? JSON.stringify(repos, null, 2)
 									: `No managed repositories in ${shelf.dir}; use repo_add.`;
 							}),
 					}),
 					defineTool({
 						name: "repo_add",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_add",
 							"Clone owner/repo into the shelf using the host's Git login (GitHub CLI by default).",
-						parameters: Type.Object({ repo: repoSchema }),
+						),
+						parameters: Type.Object({ repo: repoSchema("repo_add") }),
 						run: ({ repo }) =>
 							refusal(
 								async () => `Cloned ${repo} into ${await shelf.add(repo)}.`,
@@ -180,34 +268,54 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_change_report",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_change_report",
 							"Fetch and report commits and changed files for the default branch. Requires a clean, ahead-only clone. Review checks before requesting this report.",
-						parameters: Type.Object({ repo: repoSchema }),
+						),
+						parameters: Type.Object({
+							repo: repoSchema("repo_change_report"),
+						}),
 						run: ({ repo }, turn) =>
 							refusal(() =>
 								ship(repo, async () => {
 									const report = await shelf.report(repo);
-									const text = reportPost(report, ownerRepos.has(repo));
-									await context.surfaces.sendReply(turn.channel, {
-										chunks: [text],
-									});
-									return text;
+									const direct = ownerOwned(repo);
+									const text = options.presentation?.changeReport?.(
+										report,
+										direct,
+									) ?? {
+										post: reportPost(report, direct),
+										result: reportPost(report, direct),
+									};
+									if (options.postChangeReport)
+										await options.postChangeReport(turn, text.post);
+									else
+										await context.surfaces.sendReply(turn.channel, {
+											chunks: [text.post],
+										});
+									return text.result;
 								}),
 							),
 					}),
 					defineTool({
 						name: "repo_push",
 						minTier: "owner",
-						description:
-							"Push the exact full SHA from the latest change report to its default branch, without force. Held for owner approval unless ownerRepos explicitly lists the clone.",
+						description: describe(
+							"repo_push",
+							"Push the SHA from the latest change report to its default branch, without force. Held for owner approval unless the trusted host policy explicitly marks the clone owner-owned.",
+						),
 						parameters: Type.Object({
-							repo: repoSchema,
-							sha: Type.String({ pattern: "^[0-9a-f]{40}$" }),
+							repo: repoSchema("repo_push"),
+							sha: Type.String({
+								pattern: "^[0-9a-f]{7,40}$",
+								...about("repo_push", "sha"),
+							}),
 						}),
 						hold: ({ repo, sha }) =>
-							ownerRepos.has(repo)
+							ownerOwned(repo)
 								? undefined
-								: shelf.pushDescription(repo, sha),
+								: (options.pushHoldText?.(repo, sha) ??
+									shelf.pushDescription(repo, sha)),
 						run: ({ repo, sha }) =>
 							refusal(() =>
 								ship(
@@ -220,15 +328,20 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_task",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_task",
 							"Start one background Pi coding worker in a clone. The worker reads repository instructions, edits, checks and commits; shipping uses a separate report and approval. Report returns to this channel.",
+						),
 						parameters: Type.Object({
-							repo: repoSchema,
+							repo: repoSchema("repo_task"),
 							task: Type.String({
 								minLength: 1,
 								maxLength: MAX_CODING_TASK_CHARS,
+								...about("repo_task", "task"),
 							}),
-							skills: Type.Optional(Type.Array(Type.String())),
+							skills: Type.Optional(
+								Type.Array(Type.String(), about("repo_task", "skills")),
+							),
 						}),
 						run: ({ repo, task, skills: names }, turn) =>
 							refusal(async () => {
@@ -242,21 +355,39 @@ export function coding(options: CodingOptions) {
 									names ??
 									(turn.agent ? skills?.carriedNames(turn.agent.name) : []) ??
 									[];
-								skills?.checkRegistered(carried);
+								if (names || !options.skipUnavailableCarriedSkills)
+									skills?.checkRegistered(carried);
 								const set = skills?.resolve(carried);
-								if (set?.missing.length)
+								if (
+									set?.missing.length &&
+									(names || !options.skipUnavailableCarriedSkills)
+								)
 									throw new AgentError(
-										"Some carried skills cannot load; inspect skill_list.",
+										`These skills cannot load: ${set.missing.map((item) => `${item.name} (${item.reason})`).join(", ")}`,
 									);
-								const job = await desk.start({
-									repo,
-									task,
+								const run = (await options.resolveRun?.(turn)) ?? {
 									channel: turn.channel,
 									model: options.model,
 									thinking: options.thinking ?? "medium",
+								};
+								if (shipping.has(repo))
+									throw new AgentError(
+										"A report or push is in progress for this repository.",
+									);
+								const job = await desk.start({
+									...run,
+									repo,
+									task,
 									skillFiles: set?.skills.map((skill) => skill.file) ?? [],
+									skillNames: set?.skills.map((skill) => skill.name) ?? [],
 								});
-								return `Started coding task #${job.id} in ${repo} on ${job.model}; its report returns to this channel.`;
+								return (
+									options.presentation?.taskStarted?.(
+										job,
+										set?.missing.map((item) => item.name) ?? [],
+									) ??
+									`Started coding task #${job.id} in ${repo} on ${job.model}; its report returns to ${job.channel}.${set?.missing.length ? ` Unavailable implicit skills skipped: ${set.missing.map((item) => item.name).join(", ")}.` : ""}`
+								);
 							}),
 					}),
 				],

package/src/index.ts

@@ -2,11 +2,19 @@ export type {
 	CodingDeskOptions,
 	CodingJob,
 	CodingResult,
+	CodingThreadText,
 	CodingWorker,
 	HeldCallAnswer,
 } from "./coding-desk.ts";
 export { CodingDesk, codingReport } from "./coding-desk.ts";
-export type { CodingOptions, CodingService } from "./coding-plugin.ts";
+export type {
+	CodingOptions,
+	CodingPresentation,
+	CodingRun,
+	CodingService,
+	CodingToolText,
+	RepoToolName,
+} from "./coding-plugin.ts";
 export { CODING, coding } from "./coding-plugin.ts";
 export type { PiCodingWorkerOptions } from "./pi-coding-worker.ts";
 export { PiCodingWorker } from "./pi-coding-worker.ts";

package/src/pi-coding-worker.ts

@@ -12,6 +12,10 @@ export interface PiCodingWorkerOptions {
 	agentDir?: string;
 	/** Additional host rules, consulted in the parent process. */
 	holds?: HoldCheck;
+	/** Trusted host policy boundary for writes; defaults to the individual clone. */
+	workspace?: string;
+	/** Trusted host standing prompt, replacing the generic worker instructions. */
+	prompt?: (dir: string) => string;
 }
 interface WorkerMessage {
 	type: string;
@@ -19,6 +23,7 @@ interface WorkerMessage {
 	tool?: string;
 	input?: Record<string, unknown>;
 	report?: string;
+	message?: string;
 }
 function isMessage(value: unknown): value is WorkerMessage {
 	return (
@@ -42,8 +47,10 @@ export class PiCodingWorker implements CodingWorker {
 	): Promise<string> {
 		if (process.platform === "win32")
 			throw new AgentError("Coding workers require a POSIX host.");
-		if (signal.aborted) throw new AgentError("The worker was stopped.");
+		if (signal.aborted) throw new AgentError("the worker was stopped");
+		const prompt = this.#options.prompt?.(job.dir);
 		let report: string | undefined;
+		let failure: string | undefined;
 		const child = Bun.spawn(
 			[
 				process.execPath,
@@ -60,15 +67,22 @@ export class PiCodingWorker implements CodingWorker {
 					if (value.type === "ready") {
 						proc.send({
 							type: "start",
-							job,
+							// Thread handles and their host callbacks never cross IPC.
+							job: { ...job, thread: undefined },
 							packages: this.#options.packages ?? [],
 							agentDir: this.#options.agentDir ?? getAgentDir(),
+							prompt,
 						});
 					} else if (
 						value.type === "report" &&
 						typeof value.report === "string"
 					) {
 						report = value.report;
+					} else if (
+						value.type === "failure" &&
+						typeof value.message === "string"
+					) {
+						failure = value.message.slice(0, 2_000);
 					} else if (
 						value.type === "call" &&
 						Number.isSafeInteger(value.id) &&
@@ -80,7 +94,9 @@ export class PiCodingWorker implements CodingWorker {
 						void (async () => {
 							let answer: HeldCallAnswer = "held";
 							try {
-								const context = { workspace: job.dir };
+								const context = {
+									workspace: this.#options.workspace ?? job.dir,
+								};
 								const action =
 									shellHoldRule.describe(tool, input, context) ??
 									this.#options.holds?.(tool, input, context);
@@ -115,7 +131,7 @@ export class PiCodingWorker implements CodingWorker {
 			if (signal.aborted) kill();
 			const code = await child.exited;
 			if (signal.aborted) throw new CodingWorkerFailure("stopped");
-			if (code !== 0) throw new CodingWorkerFailure("exit", code);
+			if (code !== 0) throw new CodingWorkerFailure("exit", code, failure);
 			if (!report?.trim()) throw new CodingWorkerFailure("missing-report");
 			return report;
 		} finally {

package/src/repo-shelf.ts

@@ -9,9 +9,10 @@ import {
 	readdirSync,
 	readSync,
 	realpathSync,
+	renameSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { AgentError, checkRepoName } from "pi-roundtable/kit";
+import { AgentError, checkRepoName, scrubDiagnostic } from "pi-roundtable/kit";
 
 /** What a clone would push to its default branch (repos-and-skills spec behavior 10). */
 export interface ChangeReport {
@@ -91,7 +92,7 @@ export const ghClone: CloneCommand = async (repo, dir) => {
 	checkRepoName(repo);
 	if (repo.startsWith("-"))
 		throw new AgentError("Repository owner cannot start with a dash.");
-	const { code } = await run([
+	const { err, code } = await run([
 		"gh",
 		"repo",
 		"clone",
@@ -102,7 +103,7 @@ export const ghClone: CloneCommand = async (repo, dir) => {
 	]);
 	if (code !== 0)
 		throw new AgentError(
-			`Cloning ${repo} failed (exit ${code}); check the host's Git login.`,
+			`Cloning ${repo} failed: ${scrubDiagnostic(err) || `exit ${code}`}`,
 		);
 };
 
@@ -179,6 +180,29 @@ export class RepoShelf {
 		this.#clone = clone;
 	}
 
+	/** Adopt an existing standalone clone at startup; an existing destination is never replaced. */
+	adopt(from: string, repo: string): boolean {
+		checkRepoName(repo);
+		const to = join(this.dir, repo);
+		if (
+			!existsSync(join(from, ".git")) ||
+			lstatSync(to, { throwIfNoEntry: false })
+		)
+			return false;
+		if (
+			!lstatSync(from).isDirectory() ||
+			!lstatSync(join(from, ".git")).isDirectory()
+		)
+			throw new AgentError("Only standalone local clones can be adopted.");
+		mkdirSync(dirname(to), { recursive: true });
+		const rel = relative(realpathSync(this.dir), realpathSync(dirname(to)));
+		if (rel.startsWith("..") || isAbsolute(rel))
+			throw new AgentError("Repository owner directory escapes the shelf.");
+		renameSync(from, to);
+		this.dirOf(repo);
+		return true;
+	}
+
 	/** Every clone as `<owner>/<repo>`, sorted. */
 	repos(): string[] {
 		if (!existsSync(this.dir)) return [];
@@ -304,7 +328,7 @@ export class RepoShelf {
 	/** A synchronous hold description from the latest report, safe to show on an owner card. */
 	pushDescription(repo: string, sha: string): string {
 		const report = this.#reports.get(repo);
-		if (!report || report.sha !== sha)
+		if (!report || !/^[0-9a-f]{7,40}$/.test(sha) || !report.sha.startsWith(sha))
 			return `Push ${repo} commit ${sha}; request a fresh change report first`;
 		return `Push ${repo} commit ${sha} to ${report.target}, branch ${report.branch}`;
 	}
@@ -314,7 +338,11 @@ export class RepoShelf {
 		const dir = this.dirOf(repo);
 		const head = await this.#git(dir, "rev-parse", "HEAD");
 		const report = this.#reports.get(repo);
-		if (!report || report.sha !== sha || head !== sha)
+		if (
+			!/^[0-9a-f]{7,40}$/.test(sha) ||
+			!report?.sha.startsWith(sha) ||
+			head !== report.sha
+		)
 			throw new AgentError(
 				`${sha} is not HEAD of ${repo} (HEAD is ${head.slice(0, 12)}); report again with repo_change_report.`,
 			);
@@ -452,10 +480,10 @@ export class RepoShelf {
 	}
 
 	async #git(dir: string, ...args: string[]): Promise<string> {
-		const { out, code } = await run(["git", "-C", dir, ...args]);
+		const { out, err, code } = await run(["git", "-C", dir, ...args]);
 		if (code !== 0)
 			throw new AgentError(
-				`git ${args[0]} failed (exit ${code}); check the clone and the host's Git login.`,
+				`git ${args[0]} failed in ${dir}: ${scrubDiagnostic(err) || `exit ${code}`}`,
 			);
 		return out;
 	}

package/src/worker-entry.ts

@@ -19,6 +19,7 @@ interface StartMessage {
 	job: CodingJob & { dir: string };
 	packages: string[];
 	agentDir: string;
+	prompt?: string;
 }
 export function codingWorkerPrompt(dir: string): string {
 	return [
@@ -33,7 +34,12 @@ export function codingWorkerPrompt(dir: string): string {
 const answers = new Map<number, (answer: HeldCallAnswer) => void>();
 let nextId = 1;
 let started = false;
-async function run({ job, agentDir, packages }: StartMessage): Promise<string> {
+async function run({
+	job,
+	agentDir,
+	packages,
+	prompt,
+}: StartMessage): Promise<string> {
 	const modelRuntime = await ModelRuntime.create({
 		authPath: join(agentDir, "auth.json"),
 		modelsPath: join(agentDir, "models.json"),
@@ -89,7 +95,7 @@ async function run({ job, agentDir, packages }: StartMessage): Promise<string> {
 				},
 			},
 		],
-		appendSystemPrompt: [codingWorkerPrompt(job.dir)],
+		appendSystemPrompt: [prompt ?? codingWorkerPrompt(job.dir)],
 	});
 	await loader.reload();
 	const { session } = await createAgentSession({
@@ -106,7 +112,7 @@ async function run({ job, agentDir, packages }: StartMessage): Promise<string> {
 		model: job.model,
 		task: job.task,
 		signal: new AbortController().signal,
-		aborted: "The worker was stopped.",
+		aborted: "the worker was stopped",
 	});
 }
 if (process.send) {
@@ -130,7 +136,14 @@ if (process.send) {
 				(report) => {
 					process.send?.({ type: "report", report }, () => process.exit(0));
 				},
-				() => process.exit(1),
+				(error: unknown) =>
+					process.send?.(
+						{
+							type: "failure",
+							message: error instanceof Error ? error.message : String(error),
+						},
+						() => process.exit(1),
+					),
 			);
 		}
 	});

package/src/worker-failure.ts

@@ -1,14 +1,18 @@
-import { AgentError } from "pi-roundtable/kit";
+import { AgentError, scrubDiagnostic } from "pi-roundtable/kit";
 
-/** Structured diagnostics never carry provider responses, stderr or credentials. */
+/** Worker diagnostics reach the owner scrubbed of credentials and bounded; stderr and raw responses never do. */
 export class CodingWorkerFailure extends AgentError {
 	constructor(
 		readonly category: "stopped" | "exit" | "missing-report",
 		readonly exitCode?: number,
+		detail?: string,
 	) {
-		let message = "The coding worker was stopped.";
+		const reason = detail ? scrubDiagnostic(detail) : "";
+		let message = "the worker was stopped";
 		if (category === "exit")
-			message = `The coding worker exited (code ${exitCode}); check its model, login and package configuration.`;
+			message =
+				reason ||
+				`The coding worker exited (code ${exitCode}); check its model, login and package configuration.`;
 		if (category === "missing-report")
 			message = "The coding worker returned no report.";
 		super(message);