@danypops/pi-papyrus 0.40.0 → 0.41.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:
+Agent-facing domain tools own lifecycle invariants and sit above this store API. `tasks` and `discuss` are still single tools with an `action` parameter; `notes`, `docs`, `rules`, `skills`, and `playbooks` are projected from Papyrus's own Vehicle as one real tool per operation (`notes_capture`, `rules_create`, `skills_run`, `playbooks_invoke`, and so on) -- no `action` dispatch, each with its own schema:
 
 - **`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
+- **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

@@ -8,9 +8,6 @@ import {
 	type DiscussionRound,
 	type GateResult,
 	type OperationName,
-	type PlaybookInvocationResult,
-	type PlaybookMissingArguments,
-	type WorkflowRunResult,
 	type TaskCompletion,
 	type TaskExecutionPlan,
 	type TaskGraph,
@@ -185,23 +182,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
@@ -540,200 +520,9 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 	});
 }
 
-// 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.*, 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 +627,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, and playbooks 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.
 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.*, 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,12 @@ 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";
 
-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", "artifact:read", "artifact:write",
+];
 
 export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
 	const target = currentVehicleClientTarget();
@@ -25,6 +30,25 @@ 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 authorizes an internal Task Focus write via
+			// sessionIdentity.assertAuthorized(session_id, session_secret) -- see
+			// @danypops/papyrus's src/vehicle/playbooks-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 this
+			// operation moved onto Vehicle.
+			resolveInvocation: ({ descriptor, context }) => {
+				if (descriptor.name !== "playbooks.invoke") return {};
+				const sessionId = 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 } };
+			},
 		});
 	} 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.41.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,7 +18,7 @@
   },
   "dependencies": {
     "@danypops/jittor": "^0.14.0",
-    "@danypops/papyrus": "^0.39.0",
+    "@danypops/papyrus": "^0.40.0",
     "@danypops/vehicle-core": "^0.2.0",
     "@danypops/vehicle-server": "^0.1.1",
     "@danypops/vehicle-client": "^0.1.1",