From b26bbb02e9bc9cce171939ebc00c214f6b00c98b Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Sun, 21 Jun 2026 20:20:36 -0500
Subject: [PATCH] feat(pi): register model-callable mosaic_mission_status tool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a first-class registerTool (R14 'proper tool usage') so the Pi
agent can load its active Mosaic mission, milestone progress, task
counts, and latest scratchpad as a tool call before planning — instead
of shelling out or guessing. Reuses detectMission/buildMissionSummary;
returns AgentToolResult text + structured details. promptGuidelines
names the tool explicitly per the pi extension authoring contract.

Tool shape verified against @earendil-works/pi-coding-agent@0.79.9
ToolDefinition (name/label/description/promptSnippet/promptGuidelines/
parameters + execute(toolCallId,params,signal,onUpdate,ctx)).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
---
 .../framework/runtime/pi/mosaic-extension.ts  | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/packages/mosaic/framework/runtime/pi/mosaic-extension.ts b/packages/mosaic/framework/runtime/pi/mosaic-extension.ts
index d4749be..cbf783f 100644
--- a/packages/mosaic/framework/runtime/pi/mosaic-extension.ts
+++ b/packages/mosaic/framework/runtime/pi/mosaic-extension.ts
@@ -10,6 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
 import {
   existsSync,
   readFileSync,
@@ -342,4 +343,32 @@ export default function register(pi: ExtensionAPI) {
       }
     },
   });
+
+  // ── Register mosaic_mission_status tool (model-callable) ──────────────
+  // R14 "proper tool usage": give the agent a first-class tool to load its
+  // active Mosaic mission, milestone progress, task counts, and latest
+  // scratchpad — so it self-orients on in-flight work before planning,
+  // instead of shelling out or guessing. Mirrors the /mosaic-status command
+  // but returns the summary as tool output the LLM can read.
+  pi.registerTool({
+    name: 'mosaic_mission_status',
+    label: 'Mosaic Mission Status',
+    description:
+      'Return the active Mosaic mission, milestone progress, task counts, and latest scratchpad for the current project. Returns a note when no mission is active.',
+    promptSnippet: 'Read the active Mosaic mission + task state for the current project',
+    promptGuidelines: [
+      'Use mosaic_mission_status at the start of a session or task to load the active mission, milestone progress, and open tasks before planning work.',
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      const mission = detectMission(sessionCwd);
+      const text = mission
+        ? buildMissionSummary(sessionCwd, mission)
+        : 'No active Mosaic mission in this project.';
+      return {
+        content: [{ type: 'text', text }],
+        details: mission ? { ...mission } : { active: false },
+      };
+    },
+  });
 }