@danypops/pi-papyrus 0.40.0 → 0.42.0

package/README.md

@@ -10,14 +10,14 @@ The `papyrus_*` tools are the low-level graph-store API:
 - **`papyrus_graph`** — link artifacts, perform bounded traversal, or read the mutation event log
 - **`papyrus_show`** — read nested metadata and bounded edges, optionally running gates
 
-Agent-facing domain tools own lifecycle invariants and sit above this store API:
-
-- **`tasks`** — create/update/list/show/plan, manage the singleton active focus, replace evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort
-- **`notes`** — capture/list/show deferred human intent, mark it consumed, promote it to an existing Task/Doc/Rule/Skill, or archive it with an explicit disposition
-- **`docs`** — create/update/list/show, activate/archive/reopen, and document-safe graph links; Note mutations remain behind the Notes facade
-- **`rules`** — create/update/list/show/preview, enable/disable, and attach governance gates to tasks
-- **`skills`** — create/update/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
-- **`playbooks`** — a completely different beast from Skills at the authoring level (a trigger and an ordered list of steps, written as prose), but `invoke` recycles the same materialization engine workflow Skills use: it compiles the steps and any `contain`/`depend` composition into real Tasks (one per step, plus a container task per playbook in the tree), wires them with `dependsOn` so completing one auto-focuses the next, and focuses the first one. No text dump — one step surfaces at a time, as it becomes the focused task, same as any other Task. `contain`/`uncontain` nest a child Playbook inside a parent (its steps run after the parent's own, as part of it); `depend`/`undepend` chain a prerequisite Playbook before another (it must fully complete first). `preview` renders the whole tree as text with no side effects, for reading before invoking. A Playbook can declare named arguments (`{name, description?, required?}`, required defaults true; referenced in step text as `{{name}}`); invoking with a required one unsupplied creates nothing and reports exactly which are still missing, directing the agent to ask via `discuss` with `live:true` rather than guess
+Agent-facing domain tools own lifecycle invariants and sit above this store API. `discuss` is still a single tool with an `action` parameter -- `live:true` needs an interactive UI round-trip a stateless Vehicle operation can't express. `notes`, `docs`, `rules`, `skills`, `playbooks`, and `tasks` are projected from Papyrus's own Vehicle as one real tool per operation (`notes_capture`, `rules_create`, `skills_run`, `playbooks_invoke`, `tasks_complete`, and so on) -- no `action` dispatch, each with its own schema:
+
+- **tasks** (`tasks_create`, `tasks_update`, `tasks_list`, `tasks_show`, `tasks_plan`, `tasks_graph`, `tasks_focus`, `tasks_pause`, `tasks_unpause`, `tasks_clear_focus`, `tasks_start`, `tasks_submit`, `tasks_complete`, `tasks_reject`, `tasks_retry`, `tasks_cancel`, `tasks_cancel_subtree`, `tasks_run_gates`, `tasks_set_checklist`, `tasks_set_gates`, `tasks_depend`, `tasks_undepend`, `tasks_contain`, `tasks_uncontain`, `tasks_claim`, `tasks_heartbeat_lease`, `tasks_release_lease`, `tasks_lease`, `tasks_context`, `tasks_event_feed`, `tasks_scope`, `tasks_set_scope`, `tasks_assign_project`, `tasks_active`, `tasks_focused`, `tasks_history`) — manages the singleton active focus, evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort. `project_root` is required wherever a plain `tasks` call would otherwise need one (list/graph/plan/active/focused/scope/context/create) -- there is no ambient Pi cwd server-side. `tasks_focus`/`tasks_pause`/`tasks_unpause`/`tasks_clear_focus` still authorize their write via this session's own cached secret, and still broadcast `papyrus.task-focus.v1` on Pi's own event bus for a sibling extension to observe, exactly as before
+- **notes** (`notes_capture`, `notes_list`, `notes_show`, `notes_consume`, `notes_promote`, `notes_archive`) — capture/list/show deferred human intent, mark it consumed, promote it to an existing Task/Doc/Rule/Skill, or archive it with an explicit disposition
+- **docs** (`docs_create`, `docs_list`, `docs_show`, `docs_activate`, `docs_archive`, `docs_reopen`, `docs_link`, `docs_assign_project`, `docs_update`) — activate/archive/reopen and document-safe graph links; Note mutations remain behind the Notes facade
+- **rules** (`rules_create`, `rules_list`, `rules_show`, `rules_preview`, `rules_enable`, `rules_disable`, `rules_gate`, `rules_assign_project`, `rules_update`) — enable/disable and attach governance gates to tasks
+- **skills** (`skills_create`, `skills_create_template`, `skills_list`, `skills_show`, `skills_invoke`, `skills_run`, `skills_enable`, `skills_disable`, `skills_instantiate`, `skills_assign_project`, `skills_update`) — `skills_run` atomically instantiates a parameterized workflow run; `skills_instantiate` instantiates a compatibility artifact-template
+- **playbooks** (`playbooks_create`, `playbooks_list`, `playbooks_show`, `playbooks_invoke`, `playbooks_preview`, `playbooks_enable`, `playbooks_disable`, `playbooks_assign_project`, `playbooks_update`, `playbooks_contain`, `playbooks_uncontain`, `playbooks_depend`, `playbooks_undepend`) — a completely different beast from Skills at the authoring level (a trigger and an ordered list of steps, written as prose), but `playbooks_invoke` recycles the same materialization engine workflow Skills use: it compiles the steps and any `contain`/`depend` composition into real Tasks (one per step, plus a container task per playbook in the tree), wires them with `dependsOn` so completing one auto-focuses the next, and focuses the first one. No text dump — one step surfaces at a time, as it becomes the focused task, same as any other Task. `playbooks_contain`/`playbooks_uncontain` nest a child Playbook inside a parent (its steps run after the parent's own, as part of it); `playbooks_depend`/`playbooks_undepend` chain a prerequisite Playbook before another (it must fully complete first). `playbooks_preview` renders the whole tree as text with no side effects, for reading before invoking. A Playbook can declare named arguments (`{name, description?, required?}`, required defaults true; referenced in step text as `{{name}}`); invoking with a required one unsupplied creates nothing and reports exactly which are still missing, directing the agent to ask via `discuss` with `live:true` rather than guess
 
 Every tool operation is registered in the daemon's `/api/v1/ops` registry; parity is verified in tests. The task consumer uses the `tasks.graph` operation, which returns task nodes with explicit parent, child, and dependency IDs rather than leaking SQLite rows or asking the UI to reconstruct relationships.
 

package/extension/src/domain-tools.ts

@@ -1,34 +1,18 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
-	PROOF_TYPES,
 	readDiscussionExtra,
 	type Artifact,
 	type DiscussionAndRounds,
 	type DiscussionRound,
-	type GateResult,
 	type OperationName,
-	type PlaybookInvocationResult,
-	type PlaybookMissingArguments,
-	type WorkflowRunResult,
-	type TaskCompletion,
-	type TaskExecutionPlan,
-	type TaskGraph,
-	type TaskHistoryPage,
-	type TaskLease,
-	type TaskViewSelection,
 } from "@danypops/papyrus";
 import { askQuestion } from "./discuss-ask-view.ts";
-import { emitTaskFocusEvent } from "./task-focus-events.ts";
-import { sessionSecretField } from "./session-identity.ts";
 import { callService } from "./service-client.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
 import {
 	createArtifactDetails,
 	createArtifactListDetails,
-	createGateRunDetails,
-	createGraphDetails,
-	createInvocationDetails,
 	createModelContent,
 	createPreviewDetails,
 } from "./tool-rendering/render-model.ts";
@@ -115,15 +99,6 @@ export function artifactLines(artifacts: Artifact[]): string[] {
 	return artifacts.map((artifact) => (titleCounts.get(artifact.title)! > 1 ? `${artifactLine(artifact)} (${artifact.id})` : artifactLine(artifact)));
 }
 
-/** Resolves internal ids for model text; ids resurface only when equal titles need disambiguation. */
-async function artifactLabelsById(ids: readonly string[]): Promise<Map<string, string>> {
-	const uniqueIds = [...new Set(ids)];
-	const artifacts = (await Promise.all(uniqueIds.map((id) => callService<Record<string, unknown>, Artifact | null>("artifact.show", { id })))).filter((artifact): artifact is Artifact => artifact !== null);
-	const titleCounts = new Map<string, number>();
-	for (const artifact of artifacts) titleCounts.set(artifact.title, (titleCounts.get(artifact.title) ?? 0) + 1);
-	return new Map(artifacts.map((artifact) => [artifact.id, titleCounts.get(artifact.title)! > 1 ? `${artifact.title} (${artifact.id})` : artifact.title]));
-}
-
 /**
  * Exact, case-insensitive, trimmed title match against an already-fetched candidate set. Throws
  * a clear "not found" or "ambiguous -- use id" error rather than guessing at a fuzzy match -- id
@@ -185,23 +160,6 @@ async function resolveArtifactIdByName(listOperation: OperationName, baseRequest
 	}
 }
 
-/**
- * Playbook `arguments` is intentionally untyped in this tool's schema (an array on create, a
- * {name: value} map on invoke) -- unlike every other JSON-shaped field here, which has a concrete
- * array/record schema the calling layer can serialize correctly. A genuinely schema-less field can
- * arrive pre-serialized as JSON text instead of a parsed value; parse it back in place before it
- * reaches the service, the same tolerance the CLI's own --arguments-json/--*-json flags already give.
- */
-export function normalizeJsonEncodedField(params: Record<string, unknown>, key: string): void {
-	const value = params[key];
-	if (typeof value !== "string") return;
-	try {
-		params[key] = JSON.parse(value);
-	} catch {
-		throw new Error(`${key} must be valid JSON`);
-	}
-}
-
 /**
  * Resolves every {nameKey -> idKey} pair present and not already satisfied by an explicit id, in
  * place. `notes`, when given, collects a message for each name that only resolved by widening
@@ -276,464 +234,9 @@ async function handleArtifactRemoveRestore(action: unknown, params: Record<strin
 	return null;
 }
 
-const proofReferenceSchema = Type.Object({
-	type: Type.Union(PROOF_TYPES.map((type) => Type.Literal(type))),
-	target: Type.String(),
-	expect: Type.Optional(Type.String()),
-});
-
-const checklistCriterionSchema = Type.Object({
-	proof: Type.Array(proofReferenceSchema, { minItems: 1 }),
-});
-
-export function registerTasksTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "tasks",
-		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, context, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, cancel_subtree, run_gates, set_checklist, set_gates, depend, undepend, contain, uncontain, remove, remove_subtree, restore, claim, heartbeat_lease, release_lease, lease, event_feed. Lifecycle: todo → in-progress → review → done; review failure → rejected → retry → in-progress; canceled is terminal. Focus and lease are independent of lifecycle and of each other -- multiple sessions can focus the same task while only one holds its lease (claim throws if a different owner already holds one; release/heartbeat need the exact token claim returned; owner defaults to this session's id). context returns the full plan (the system prompt itself only carries a one-line pointer) -- call it explicitly after a compaction or before reconciling. complete runs gates + checklist-proof review, then focuses one ready successor. cancel_subtree cancels a task and its whole containment subtree in one call, skipping tasks already done/canceled. remove/restore use a time-gated trash (refuses the live Focus); remove_subtree trashes a whole `contains` subtree in one call; undepend/uncontain are idempotent no-ops when the edge is already absent. update recovers an accidentally-terminal task via status=todo + reason, without rewriting real history; update never touches gates (title/body/labels/status only) -- use set_gates to replace a task's gate commands after creation. Prefer `name` (exact title) over `id` -- id is a backend detail, resolved automatically, needed only to disambiguate a shared title; `parent_name`/`child_name`/`root_task_name` are the same pattern for their `_id` counterparts. For a prerequisite, use `dependency_name` (singular, resolved to `dependency_id`) with the `depend`/`undepend` actions; `depends_on_names` (plural array, resolved to `depends_on`) is only for `create`'s initial dependency set -- passing the wrong one of the two to `depend` leaves `dependency_id` unset and fails with a `dependency_id is required` error. A name resolved outside this call's own project scope (e.g. depending on a task in a different project) is retried once against every project before failing, and the response notes when that happened.",
-		parameters: Type.Object({
-			action: Type.String(),
-			id: Type.Optional(Type.String()),
-			name: Type.Optional(Type.String()),
-			title: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()),
-			status: Type.Optional(Type.String()),
-			text: Type.Optional(Type.String()),
-			limit: Type.Optional(Type.Number()),
-			cursor: Type.Optional(Type.Number()),
-			direction: Type.Optional(Type.Union([Type.Literal("asc"), Type.Literal("desc")])),
-			reason: Type.Optional(Type.String()),
-			session_id: Type.Optional(Type.String()),
-			labels: Type.Optional(Type.Array(Type.String())),
-			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-			gates: Type.Optional(Type.Array(Type.Record(Type.String(), Type.Unknown()))),
-			checklist: Type.Optional(Type.Record(Type.String(), checklistCriterionSchema)),
-			template_id: Type.Optional(Type.String()),
-			parent_id: Type.Optional(Type.String()),
-			parent_name: Type.Optional(Type.String()),
-			child_id: Type.Optional(Type.String()),
-			child_name: Type.Optional(Type.String()),
-			dependency_id: Type.Optional(Type.String()),
-			dependency_name: Type.Optional(Type.String()),
-			depends_on: Type.Optional(Type.Array(Type.String())),
-			depends_on_names: Type.Optional(Type.Array(Type.String())),
-			project_root: Type.Optional(Type.String()),
-			scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("graph"), Type.Literal("all")])),
-			root_task_id: Type.Optional(Type.String()),
-			root_task_name: Type.Optional(Type.String()),
-			owner: Type.Optional(Type.String()),
-			token: Type.Optional(Type.String()),
-			ttl_ms: Type.Optional(Type.Number()),
-			note: Type.Optional(Type.String()),
-			event_types: Type.Optional(Type.Array(Type.String())),
-		}),
-		renderCall(args, theme) { return renderPapyrusToolCall("Tasks", args, theme); },
-		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				// Defaults to this Pi session's own id so Focus reads/writes are isolated per agent
-				// without depending on the model to know or supply its own session identity.
-				// session_secret is looked up by the resolved session_id itself (not blindly the
-				// current session's), so a model that explicitly overrides session_id to a DIFFERENT
-				// session never gets this session's secret smuggled in on its behalf -- the cache only
-				// ever holds this extension's own registered session anyway (see session-identity.ts).
-				const resolvedSessionId = params.session_id ?? ctx.sessionManager.getSessionId();
-				const baseRequest = { project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "pi-tool", session_id: resolvedSessionId, ...sessionSecretField(resolvedSessionId as string) };
-				// Collects a note whenever a name field below only resolved by widening past this call's
-				// own project scope (see resolveArtifactIdByName) -- surfaced at the end of this action's
-				// own response text rather than resolved silently, since a cross-project depend/contain
-				// is exactly the case a shared per-call scope can't otherwise express.
-				const notes: string[] = [];
-				// Resolve the graph root first: every other name lookup must use the caller's final
-				// project/scope/root selection, otherwise `scope: all|graph` silently collapses back
-				// to the current project and forces callers to reach for an id.
-				await resolveNameFields(params, [
-					{ nameKey: "root_task_name", idKey: "root_task_id", listOperation: "tasks.list", baseRequest: { ...baseRequest, scope: "project" } },
-				], notes);
-				const resolutionRequest = {
-					...baseRequest,
-					...(params.scope === undefined ? {} : { scope: params.scope }),
-					...(params.root_task_id === undefined ? {} : { root_task_id: params.root_task_id }),
-				};
-				// The daemon remains keyed by stable ids; the agent facade resolves names against the
-				// exact requested view before dispatching those internal ids.
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "tasks.list", baseRequest: resolutionRequest },
-					{ nameKey: "dependency_name", idKey: "dependency_id", listOperation: "tasks.list", baseRequest: resolutionRequest },
-					{ nameKey: "parent_name", idKey: "parent_id", listOperation: "tasks.list", baseRequest: resolutionRequest },
-					{ nameKey: "child_name", idKey: "child_id", listOperation: "tasks.list", baseRequest: resolutionRequest },
-				], notes);
-				await resolveNameArrayField(params, "depends_on_names", "depends_on", "tasks.list", resolutionRequest, notes);
-				const request = { ...params, ...baseRequest };
-				const result = await (async (): Promise<ReturnType<typeof text>> => {
-				if (action === "create") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.create", request);
-					return text(`Created task ${artifactLine(artifact)}`, createArtifactDetails("tasks.create", artifact));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("tasks.list", request);
-					return text(rows.length ? artifactLines(rows).join("\n") : "No tasks found.", createArtifactListDetails("tasks.list", rows));
-				}
-				if (action === "show") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.show", params);
-					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("tasks.show", artifact));
-				}
-				if (action === "history") {
-					const page = await callService<Record<string, unknown>, TaskHistoryPage>("tasks.history", request);
-					const lines = page.events.map((event) => `${event.occurredAt} ${event.type} ${event.fromStatus ?? "∅"} → ${event.toStatus ?? "∅"} · ${event.actor}/${event.source}${event.reason ? ` · ${event.reason}` : ""}`);
-					const output = lines.join("\n") || "No recorded history for this task.";
-					return text(output, createPreviewDetails("tasks.history", "Task history", output));
-				}
-				if (action === "scope") {
-					const selection = await callService<Record<string, unknown>, TaskViewSelection>("tasks.scope", request);
-					return text(`Task scope: ${selection.label}`, createPreviewDetails("tasks.scope", "Task scope", selection.label));
-				}
-				if (action === "active") {
-					const artifact = await callService<Record<string, unknown>, Artifact | null>("tasks.active", request);
-					return artifact
-						? text(`Active: ${artifactLine(artifact)}`, createArtifactDetails("tasks.active", artifact))
-						: text("No active task.", createPreviewDetails("tasks.active", "Active task", "No active task."));
-				}
-				if (action === "focused") {
-					const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string } | null>("tasks.focused", request);
-					return focus
-						? text(`Focused (${focus.status}): ${artifactLine(focus.artifact)}`, createArtifactDetails("tasks.focused", focus.artifact))
-						: text("No focused task.", createPreviewDetails("tasks.focused", "Focused task", "No focused task."));
-				}
-				if (action === "pause" || action === "unpause") {
-					const operation = action === "pause" ? "tasks.pause" : "tasks.unpause";
-					const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string }>(operation, request);
-					emitTaskFocusEvent({ taskId: focus.artifact.id, sessionId: request.session_id as string, status: action === "pause" ? "paused" : "unpaused" });
-					return text(`Focused (${focus.status}): ${artifactLine(focus.artifact)}`, createArtifactDetails(operation, focus.artifact));
-				}
-				if (action === "clear_focus") {
-					const result = await callService<Record<string, unknown>, { cleared: boolean }>("tasks.clear_focus", request);
-					if (result.cleared) emitTaskFocusEvent({ taskId: null, sessionId: request.session_id as string, status: "cleared" });
-					const output = result.cleared ? "Task focus cleared." : "No focused task.";
-					return text(output, createPreviewDetails("tasks.clear_focus", "Task focus", output));
-				}
-				if (action === "graph") {
-					const graph = await callService<Record<string, unknown>, TaskGraph>("tasks.graph", request);
-					const dependencies = graph.nodes.reduce((count, node) => count + node.dependencyIds.length, 0);
-					const containment = graph.nodes.reduce((count, node) => count + node.childIds.length, 0);
-					const edges = graph.nodes.flatMap((node) => [
-						...node.dependencyIds.map((dependencyId) => ({ from: node.task.id, relation: "depends_on", to: dependencyId })),
-						...node.childIds.map((childId) => ({ from: node.task.id, relation: "contains", to: childId })),
-					]);
-					return text(
-						`Task graph: ${graph.nodes.length} nodes, ${graph.rootIds.length} roots, ${dependencies} dependencies, ${containment} containment edges.`,
-						createGraphDetails("tasks.graph", graph.nodes.map((node) => node.task), edges),
-					);
-				}
-				if (action === "plan") {
-					const plan = await callService<Record<string, unknown>, TaskExecutionPlan>("tasks.plan", request);
-					const byId = new Map(plan.nodes.map((node) => [node.id, node]));
-					const titleCounts = new Map<string, number>();
-					for (const node of plan.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
-					const nodeLabel = (id: string): string => {
-						const node = byId.get(id);
-						if (!node) return "unknown task";
-						return (titleCounts.get(node.title) ?? 0) > 1 ? `${node.title} (${node.id})` : node.title;
-					};
-					const lines = plan.layers.flatMap((layer, index) => [
-						`Layer ${index + 1}`,
-						...layer.map((id) => {
-							const node = byId.get(id);
-							return `  [${node?.state ?? "unknown"}] ${nodeLabel(id)}`;
-						}),
-					]);
-					if (plan.cycleIds.length > 0) lines.push(`Invalid cycle: ${plan.cycleIds.map(nodeLabel).join(", ")}`);
-					const output = lines.join("\n") || "No tasks in execution plan.";
-					return text(output, createPreviewDetails("tasks.plan", "Task execution plan", output));
-				}
-				if (action === "context") {
-					const summary = await callService<Record<string, unknown>, string | null>("tasks.context", { ...request, verbosity: "full" });
-					const output = summary ?? "No open tasks.";
-					return text(output, createPreviewDetails("tasks.context", "Task reconciliation context", output));
-				}
-				if (action === "set_checklist") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_checklist", params);
-					return text(`Updated checklist: ${artifactLine(artifact)}`, createArtifactDetails("tasks.set_checklist", artifact));
-				}
-				if (action === "set_gates") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_gates", params);
-					return text(`Updated gates: ${artifactLine(artifact)}`, createArtifactDetails("tasks.set_gates", artifact));
-				}
-				if (action === "complete") {
-					const result = await callService<Record<string, unknown>, TaskCompletion>("tasks.complete", request);
-					const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
-					const checklist = result.checklist.map((item) => `${item.accepted ? "✓" : "✗"} proof: ${item.item}${item.reason ? ` — ${item.reason}` : ""}`).join("\n");
-					const focused = result.focused ? `\nActive: ${artifactLine(result.focused)}` : "";
-					const blockedLines = artifactLines(result.blocked.map((entry) => entry.artifact));
-					const dependencyLabels = await artifactLabelsById(result.blocked.flatMap((entry) => entry.dependencyIds));
-					const blocked = result.blocked.length > 0
-						? `\nBlocked: ${result.blocked.map((entry, index) => `${blockedLines[index]} waits for ${entry.dependencyIds.map((id) => dependencyLabels.get(id) ?? "unknown task").join(", ")}`).join("; ")}`
-						: "";
-					const output = `${result.completed ? "Completed" : "Rejected"}: ${artifactLine(result.artifact)}${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`;
-					return text(output, createPreviewDetails("tasks.complete", "Task completion", output));
-				}
-				if (action === "run_gates") {
-					const [gates, task] = await Promise.all([
-						callService<Record<string, unknown>, GateResult[]>("tasks.run_gates", request),
-						callService<Record<string, unknown>, Artifact>("tasks.show", { id: params.id }),
-					]);
-					return text(
-						gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n") || "No gates configured.",
-						createGateRunDetails("tasks.run_gates", (params.id as string | undefined) ?? "", task.title, gates.map((gate) => ({
-							passed: gate.passed, type: gate.gate.type, target: gate.gate.target, output: gate.output,
-						}))),
-					);
-				}
-				if (action === "event_feed") {
-					const page = await callService<Record<string, unknown>, { events: Array<{ id: number; occurredAt: string; taskId: string; type: string }>; nextCursor?: number }>("tasks.event_feed", { cursor: params.cursor, limit: params.limit, event_types: params.event_types });
-					const output = page.events.length === 0 ? "No events." : page.events.map((event) => `${event.id} ${event.occurredAt} ${event.taskId} ${event.type}`).join("\n");
-					return text(page.nextCursor !== undefined ? `${output}\n\n(more available -- resume with cursor: ${page.nextCursor})` : output, createPreviewDetails("tasks.event_feed", "Task event feed", output));
-				}
-				if (action === "claim" || action === "heartbeat_lease" || action === "release_lease" || action === "lease") {
-					const leaseRequest = { ...request, owner: (params.owner as string | undefined) ?? resolvedSessionId };
-					if (action === "release_lease") {
-						const released = await callService<Record<string, unknown>, { released: boolean }>("tasks.release_lease", leaseRequest);
-						const output = released.released ? "Lease released." : "No live lease to release.";
-						return text(output, createPreviewDetails("tasks.release_lease", "Task lease", output));
-					}
-					const operation = action === "claim" ? "tasks.claim" : action === "heartbeat_lease" ? "tasks.heartbeat_lease" : "tasks.lease";
-					const lease = await callService<Record<string, unknown>, TaskLease | null>(operation, leaseRequest);
-					const output = lease ? `Leased by "${lease.owner}" until ${lease.leaseExpiresAt} (token ${lease.token}).` : "No live lease.";
-					return text(output, createPreviewDetails(operation, "Task lease", output));
-				}
-				if (action === "cancel_subtree") {
-					const outcome = await callService<Record<string, unknown>, { canceled: string[]; skipped: string[] }>("tasks.cancel_subtree", request);
-					const output = `Canceled ${outcome.canceled.length} task(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-terminal` : ""}.`;
-					return text(output, createPreviewDetails("tasks.cancel_subtree", "Cancel task subtree", JSON.stringify(outcome, null, 2)));
-				}
-				const trashResult = await handleArtifactRemoveRestore(action, params);
-				if (trashResult) return trashResult;
-				const operations = {
-					focus: "tasks.focus",
-					start: "tasks.start",
-					submit: "tasks.submit",
-					reject: "tasks.reject",
-					retry: "tasks.retry",
-					cancel: "tasks.cancel",
-					update: "tasks.update",
-					set_scope: "tasks.set_scope",
-					assign_project: "tasks.assign_project",
-					depend: "tasks.depend",
-					undepend: "tasks.undepend",
-					contain: "tasks.contain",
-					uncontain: "tasks.uncontain",
-				} as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown tasks action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, request);
-				if (operation === "tasks.focus") emitTaskFocusEvent({ taskId: artifact.id, sessionId: request.session_id as string, status: "focused" });
-				return text(artifactLine(artifact), createArtifactDetails(operation, artifact));
-				})();
-				if (notes.length > 0 && result.content[0]?.type === "text") result.content[0].text += `\n\n${notes.join("\n")}`;
-				return result;
-			} catch (error) {
-				throw new Error(`tasks failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
-
-// notes.*, rules.*, docs.*, and the shared artifact.* are registered as Vehicles
-// (see ../vehicle-notes-client.ts and @danypops/papyrus's src/vehicle/papyrus-vehicle.ts),
-// not pi.registerTool()s in this file.
-
-export function registerPlaybooksTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "playbooks",
-		label: "Playbooks",
-		description: "Playbook domain tool -- a completely different beast from the skills tool at the AUTHORING level (a Playbook is prose: a trigger and an ordered list of steps), but invoke recycles the exact same materialization engine workflow Skills use: it compiles the Playbook's steps and its contains/depends_on composition tree into real Tasks (one per step, plus one container task per playbook in the tree), wires them with dependsOn so completing one auto-focuses the next, and focuses the first one -- no text dump, one step (page) surfaces at a time as it becomes the focused task, exactly like any other Task. contain/uncontain nest a child Playbook inside a parent (its steps run AFTER the parent's own, as part of it); depend/undepend chain a prerequisite Playbook before another (it must fully complete FIRST). Both are bounded; a composition cycle is a hard invoke-time error (real Tasks would otherwise be created in a loop), unlike preview's degrade-to-a-marker. ACTIONS: create, list, show, invoke, preview, enable, disable, assign_project, update, contain, uncontain, depend, undepend, remove, remove_subtree, restore. project_root is optional everywhere (omitted = unscoped). On create, `arguments` declares named inputs the Playbook needs: [{name, description?, required?}] (required defaults true) -- referenced in step text as `{{name}}`, substituted at invoke time. On invoke, `arguments` supplies known values as {name: value}; if any declared REQUIRED argument is still missing, invoke creates nothing and returns `missingArguments` -- ask the human for these (discuss tool, live:true) and invoke again, never guess or invent a value. A successful invoke returns `entryTaskId` (now focused) and `created.tasks` -- drive it forward with the tasks tool (start/submit/complete) like any other Task; contains/depends_on wiring auto-focuses each next step on completion. preview renders the whole tree as text with no side effects, for a human who just wants to read it first. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Playbook to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline; remove_subtree extends this to the whole nested-Playbook tree in one call. PREFER `name` (the playbook's exact title) over `id`, and `parent_name`/`child_name`/`dependency_name` over `parent_id`/`child_id`/`dependency_id` for contain/uncontain/depend/undepend -- all are backend implementation details, resolved from name automatically.",
-		parameters: Type.Object({
-			action: Type.String(), id: Type.Optional(Type.String()), name: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
-			tools: Type.Optional(Type.Array(Type.String())), labels: Type.Optional(Type.Array(Type.String())),
-			arguments: Type.Optional(Type.Unknown()),
-			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
-			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()),
-			parent_id: Type.Optional(Type.String()), parent_name: Type.Optional(Type.String()),
-			child_id: Type.Optional(Type.String()), child_name: Type.Optional(Type.String()),
-			dependency_id: Type.Optional(Type.String()), dependency_name: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
-		}),
-		renderCall(args, theme) { return renderPapyrusToolCall("Playbooks", args, theme); },
-		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				// Name resolution must search regardless of project scope -- a Playbook itself is
-				// commonly unscoped (e.g. a cross-repo lab-deploy playbook), so resolutionRequest
-				// uses the caller's ORIGINAL project_root (undefined unless explicitly given), never
-				// the invoke-specific default applied below -- that default is only for where the
-				// resulting TASKS land, not for finding the playbook artifact itself.
-				const resolutionRequest = { project_root: params.project_root };
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
-					{ nameKey: "parent_name", idKey: "parent_id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
-					{ nameKey: "child_name", idKey: "child_id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
-					{ nameKey: "dependency_name", idKey: "dependency_id", listOperation: "playbooks.list", baseRequest: resolutionRequest },
-				]);
-				// invoke ends by calling tasks.focus server-side -- that focus write must land in the
-				// SAME session scope the tasks tool reads from (ctx.sessionManager.getSessionId()),
-				// the same resolution the tasks tool itself always applies, or the entry task's focus
-				// is invisible to tasks(action=focused/active) despite invoke reporting it as focused.
-				// project_root defaults to ctx.cwd for the same reason: the tasks tool always scopes
-				// its OWN reads to ctx.cwd unless told otherwise, so an unscoped playbook-materialized
-				// task is invisible to tasks(action=focused) even with the right session -- confirmed
-				// live (the focus_set event existed with the correct sessionId, but Tasks.focused's own
-				// project-scope filter silently excluded the unscoped task from a cwd-scoped read).
-				// Applied AFTER name resolution: it must never affect finding the playbook itself.
-				if (action === "invoke") {
-					const resolvedSessionId = params.session_id ?? ctx.sessionManager.getSessionId();
-					Object.assign(params, {
-						project_root: params.project_root ?? ctx.cwd,
-						session_id: resolvedSessionId,
-						...sessionSecretField(resolvedSessionId as string),
-					});
-				}
-				if (action === "create" || action === "invoke" || action === "preview") normalizeJsonEncodedField(params, "arguments");
-				if (action === "create") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("playbooks.create", params);
-					return text(`Created playbook ${artifactLine(artifact)}`, createArtifactDetails("playbooks.create", artifact));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("playbooks.list", params);
-					return text(rows.length ? artifactLines(rows).join("\n") : "No playbooks found.", createArtifactListDetails("playbooks.list", rows));
-				}
-				if (action === "preview") {
-					const rendered = await callService<Record<string, unknown>, string>("playbooks.preview", params);
-					return text(rendered, createPreviewDetails("playbooks.preview", "Playbook preview", rendered));
-				}
-				if (action === "invoke") {
-					const invocation = await callService<Record<string, unknown>, PlaybookInvocationResult | PlaybookMissingArguments>("playbooks.invoke", params);
-					if ("missingArguments" in invocation) {
-						const message = `Missing required argument(s): ${invocation.missingArguments.join(", ")}. Nothing was created -- ask the human for these (discuss tool, live:true), then invoke again.`;
-						return text(message, createInvocationDetails("playbooks.invoke", invocation.playbookId, { tasks: [], docs: [], rules: [], roots: [] }));
-					}
-					const nodeTitleCounts = new Map<string, number>();
-					for (const node of invocation.execution.nodes) nodeTitleCounts.set(node.title, (nodeTitleCounts.get(node.title) ?? 0) + 1);
-					const execution = invocation.execution.nodes.map((node) => (nodeTitleCounts.get(node.title) ?? 0) > 1
-						? `  [${node.state}] ${node.title} (${node.id})`
-						: `  [${node.state}] ${node.title}`).join("\n");
-					const nodeById = new Map(invocation.execution.nodes.map((node) => [node.id, node]));
-					const rootLabels = invocation.rootTaskIds.map((id) => nodeById.get(id)?.title ?? "unknown task");
-					const entryLabel = nodeById.get(invocation.entryTaskId)?.title ?? invocation.entryTaskId;
-					const createdLabels = await artifactLabelsById([...invocation.created.docs, ...invocation.created.rules]);
-					return text([
-						`Invoked playbook run ${invocation.runId}: ${invocation.created.tasks.length} task(s), ${invocation.created.rules.length} rule(s), ${invocation.created.docs.length} doc(s) created.`,
-						`Entry task now focused: ${entryLabel}. Drive it forward with the tasks tool (start/submit/complete) -- contains/depends_on wiring auto-focuses each next step.`,
-						`Ready roots: ${rootLabels.join(", ") || "none"}.`,
-						`Context docs: ${invocation.created.docs.map((id) => createdLabels.get(id) ?? "unknown document").join(", ") || "none"}.`,
-						`Scoped rules: ${invocation.created.rules.map((id) => createdLabels.get(id) ?? "unknown rule").join(", ") || "none"}.`,
-						...(execution ? ["Execution:", execution] : []),
-					].join("\n"), createInvocationDetails("playbooks.invoke", invocation.runId, {
-						tasks: invocation.created.tasks,
-						docs: invocation.created.docs,
-						rules: invocation.created.rules,
-						roots: invocation.rootTaskIds,
-					}));
-				}
-				const trashResult = await handleArtifactRemoveRestore(action, params);
-				if (trashResult) return trashResult;
-				const operations = {
-					show: "playbooks.show", enable: "playbooks.enable", disable: "playbooks.disable", assign_project: "playbooks.assign_project", update: "playbooks.update",
-					contain: "playbooks.contain", uncontain: "playbooks.uncontain", depend: "playbooks.depend", undepend: "playbooks.undepend",
-				} as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown playbooks action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
-				return text(`${artifactLine(artifact)}${action === "show" ? `\n\n${artifact.body}` : ""}`, createArtifactDetails(operation, artifact));
-			} catch (error) {
-				throw new Error(`playbooks failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
-
-export function registerSkillsTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "skills",
-		label: "Skills",
-		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project, update, remove, remove_subtree, restore. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Skill to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline; remove_subtree extends this to a whole `contains` subtree in one call. PREFER `name` (the skill's exact title) over `id`, and `template_name` over `template_id` for instantiate -- both are backend implementation details, resolved from name automatically.",
-		parameters: Type.Object({
-			action: Type.String(), id: Type.Optional(Type.String()), name: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
-			tools: Type.Optional(Type.Array(Type.String())), definition: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-			arguments: Type.Optional(Type.Record(Type.String(), Type.Unknown())), run_id: Type.Optional(Type.String()),
-			labels: Type.Optional(Type.Array(Type.String())),
-			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
-			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()), template_id: Type.Optional(Type.String()),
-			template_name: Type.Optional(Type.String()),
-			target_kind: Type.Optional(Type.String()), defaults: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-			required: Type.Optional(Type.Array(Type.String())), kind: Type.Optional(Type.String()), subtype: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
-		}),
-		renderCall(args, theme) { return renderPapyrusToolCall("Skills", args, theme); },
-		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				const request = { ...params, project_root: params.project_root ?? ctx.cwd };
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "skills.list", baseRequest: { project_root: params.project_root } },
-					{ nameKey: "template_name", idKey: "template_id", listOperation: "skills.list", baseRequest: { project_root: params.project_root } },
-				]);
-				if (action === "create" || action === "create_template") {
-					const operation = action === "create" ? "skills.create" : "skills.create_template";
-					const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
-					return text(`Created skill ${artifactLine(artifact)}`, createArtifactDetails(operation, artifact));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("skills.list", params);
-					return text(rows.length ? artifactLines(rows).join("\n") : "No skills found.", createArtifactListDetails("skills.list", rows));
-				}
-				if (action === "invoke") {
-					const invocation = await callService<Record<string, unknown>, string>("skills.invoke", params);
-					return text(invocation, createPreviewDetails("skills.invoke", "Skill invocation", invocation));
-				}
-				if (action === "run") {
-					const run = await callService<Record<string, unknown>, WorkflowRunResult>("skills.run", request);
-					const runTitleCounts = new Map<string, number>();
-					for (const node of run.execution.nodes) runTitleCounts.set(node.title, (runTitleCounts.get(node.title) ?? 0) + 1);
-					const execution = run.execution.nodes.map((node) => (runTitleCounts.get(node.title) ?? 0) > 1
-						? `  [${node.state}] ${node.title} (${node.id})`
-						: `  [${node.state}] ${node.title}`).join("\n");
-					const nodeById = new Map(run.execution.nodes.map((node) => [node.id, node]));
-					const rootLabels = run.rootTaskIds.map((id) => nodeById.get(id)?.title ?? "unknown task");
-					const createdLabels = await artifactLabelsById([...run.created.docs, ...run.created.rules]);
-					return text([
-						`Created Skill run ${run.runId}: ${run.created.tasks.length} tasks, ${run.created.rules.length} rules, ${run.created.docs.length} docs.`,
-						`Ready roots: ${rootLabels.join(", ") || "none"}.`,
-						`Context docs: ${run.created.docs.map((id) => createdLabels.get(id) ?? "unknown document").join(", ") || "none"}.`,
-						`Scoped rules: ${run.created.rules.map((id) => createdLabels.get(id) ?? "unknown rule").join(", ") || "none"}.`,
-						...(execution ? ["Execution:", execution] : []),
-					].join("\n"), createInvocationDetails("skills.run", run.runId, {
-						tasks: run.created.tasks,
-						docs: run.created.docs,
-						rules: run.created.rules,
-						roots: run.rootTaskIds,
-					}));
-				}
-				const trashResult = await handleArtifactRemoveRestore(action, params);
-				if (trashResult) return trashResult;
-				const operations = { show: "skills.show", enable: "skills.enable", disable: "skills.disable", instantiate: "skills.instantiate", assign_project: "skills.assign_project", update: "skills.update" } as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown skills action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, action === "instantiate" ? request : params);
-				return text(`${artifactLine(artifact)}${action === "show" ? `\n\n${artifact.body}` : ""}`, createArtifactDetails(operation, artifact));
-			} catch (error) {
-				throw new Error(`skills failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
+// notes.*, rules.*, docs.*, skills.*, playbooks.*, tasks.*, and the shared artifact.* are
+// registered as Vehicles (see ../vehicle-notes-client.ts and @danypops/papyrus's
+// src/vehicle/papyrus-vehicle.ts), not pi.registerTool()s in this file.
 
 export function registerDiscussTool(pi: ExtensionAPI): void {
 	pi.registerTool({
@@ -838,13 +341,11 @@ export function registerDiscussTool(pi: ExtensionAPI): void {
 }
 
 /** Thin orchestrator: each domain's tool is independently navigable/testable via its own registerXTool function. */
-// docs and rules are no longer registered here -- both migrated onto Vehicle
-// (registerNotesVehicle in vehicle-notes-client.ts, wired at session_start in
-// index.ts), replacing their own pi.registerTool() mega-tools. See
-// @danypops/papyrus's src/vehicle/papyrus-vehicle.ts for the server side.
+// notes, rules, docs, skills, playbooks, and tasks are no longer registered here -- all migrated
+// onto Vehicle (registerNotesVehicle in vehicle-notes-client.ts, wired at session_start in
+// index.ts), replacing their own pi.registerTool() mega-tools. See @danypops/papyrus's
+// src/vehicle/papyrus-vehicle.ts for the server side. discuss remains here -- live:true needs an
+// interactive UI round-trip a stateless Vehicle operation can't express.
 export function registerDomainTools(pi: ExtensionAPI): void {
-	registerTasksTool(pi);
-	registerPlaybooksTool(pi);
-	registerSkillsTool(pi);
 	registerDiscussTool(pi);
 }

package/extension/src/vehicle-notes-client.ts

@@ -1,6 +1,7 @@
 /**
- * Registers every Vehicle-projected domain (notes.*, rules.*, docs.*, artifact.*)
- * as real Pi tools -- see @danypops/papyrus's src/vehicle/papyrus-vehicle.ts.
+ * Registers every Vehicle-projected domain (notes.*, rules.*, docs.*, skills.*,
+ * playbooks.*, tasks.*, artifact.*) as real Pi tools -- see @danypops/papyrus's
+ * src/vehicle/papyrus-vehicle.ts.
  *
  * Fails silently on a stale/unreachable daemon handle instead of aborting extension
  * setup: Papyrus's daemon doesn't auto-spawn, and a tool that failed to register
@@ -14,8 +15,17 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
 import { registerVehicleTools } from "@danypops/vehicle-client-pi";
 import { currentVehicleClientTarget } from "./service-client.ts";
+import { sessionSecretField } from "./session-identity.ts";
+import { emitTaskFocusEvent } from "./task-focus-events.ts";
 
-const REGISTERED_PERMISSIONS = ["notes:read", "notes:write", "rules:read", "rules:write", "docs:read", "docs:write", "artifact:read", "artifact:write"];
+const REGISTERED_PERMISSIONS = [
+	"notes:read", "notes:write", "rules:read", "rules:write", "docs:read", "docs:write",
+	"skills:read", "skills:write", "playbooks:read", "playbooks:write", "tasks:read", "tasks:write",
+	"artifact:read", "artifact:write",
+];
+
+/** Task Focus's own internal write needs a real, per-session secret -- see below. Every other tasks.* operation reads session_id purely for read-scoping and needs no secret. */
+const FOCUS_MUTATION_OPERATIONS = new Set(["tasks.focus", "tasks.pause", "tasks.unpause", "tasks.clear_focus"]);
 
 export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
 	const target = currentVehicleClientTarget();
@@ -25,6 +35,52 @@ export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
 		await registerVehicleTools(pi, client, {
 			permissions: REGISTERED_PERMISSIONS,
 			principal: { id: "pi-papyrus" },
+			// playbooks.invoke's own module handler, and tasks.focus/pause/unpause/clear_focus's
+			// own module handlers, authorize an internal Task Focus write via
+			// sessionIdentity.assertAuthorized(session_id, session_secret) -- see
+			// @danypops/papyrus's src/vehicle/playbooks-vehicle.ts and tasks-vehicle.ts. That
+			// secret must never be a model-visible input field (the model has no business
+			// knowing or supplying it), so it travels here instead, in principal.claims, from
+			// this extension's own already-cached secret (registered at session_start -- see
+			// index.ts) -- the same value sessionSecretField() used to thread through as a raw
+			// RPC input field before these operations moved onto Vehicle.
+			resolveInvocation: ({ descriptor, input, context }) => {
+				if (descriptor.name !== "playbooks.invoke" && !FOCUS_MUTATION_OPERATIONS.has(descriptor.name)) return {};
+				// tasks.* defaults session_id to this Pi session's own id, same as the removed
+				// hand-rolled tool -- but the secret cache is keyed by whichever session_id is
+				// actually being authorized, not blindly this session's, so a model that
+				// explicitly overrides session_id to a DIFFERENT session never gets this
+				// session's secret smuggled in on its behalf.
+				const requestedSessionId = (input as { session_id?: unknown } | undefined)?.session_id;
+				const sessionId = typeof requestedSessionId === "string" && requestedSessionId.length > 0 ? requestedSessionId : context.sessionManager.getSessionId();
+				const { session_secret: sessionSecret } = sessionSecretField(sessionId);
+				// Omit sessionSecret entirely when nothing is cached (unregistered session) --
+				// {sessionSecret: null} would fail the module's own optionalString(input,
+				// "session_secret") check (undefined-or-string, not null), a real regression from
+				// sessionSecretField()'s own {} (key omitted) return for the same case.
+				const claims: Record<string, string> = sessionSecret ? { sessionId, sessionSecret } : { sessionId };
+				return { principal: { id: "pi-papyrus", claims } };
+			},
+			// papyrus.task-focus.v1 is a same-process Pi extension event bus broadcast (e.g. a
+			// token-cost router correlating its own telemetry with the currently focused task)
+			// -- has no Vehicle-transport equivalent, so it's emitted here, client-side, rather
+			// than from the operation's own output.
+			onInvoked: ({ descriptor }, output) => {
+				if (descriptor.name === "tasks.focus") {
+					const artifact = output as { id: string } | undefined;
+					if (artifact?.id) emitTaskFocusEvent({ taskId: artifact.id, status: "focused" });
+					return;
+				}
+				if (descriptor.name === "tasks.pause" || descriptor.name === "tasks.unpause") {
+					const focus = output as { artifact: { id: string } } | undefined;
+					if (focus?.artifact?.id) emitTaskFocusEvent({ taskId: focus.artifact.id, status: descriptor.name === "tasks.pause" ? "paused" : "unpaused" });
+					return;
+				}
+				if (descriptor.name === "tasks.clear_focus") {
+					const result = output as { cleared: boolean } | undefined;
+					if (result?.cleared) emitTaskFocusEvent({ taskId: null, status: "cleared" });
+				}
+			},
 		});
 	} catch {
 		// Daemon state is stale/unreachable -- degrade silently, matching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],
@@ -18,11 +18,11 @@
   },
   "dependencies": {
     "@danypops/jittor": "^0.14.0",
-    "@danypops/papyrus": "^0.39.0",
+    "@danypops/papyrus": "^0.41.0",
     "@danypops/vehicle-core": "^0.2.0",
     "@danypops/vehicle-server": "^0.1.1",
     "@danypops/vehicle-client": "^0.1.1",
-    "@danypops/vehicle-client-pi": "^0.2.0",
+    "@danypops/vehicle-client-pi": "^0.3.0",
     "beautiful-mermaid": "1.1.3",
     "malevich-tui-components": "^0.5.0"
   },