docs: add BUILD_PR tool host state handoff bundle

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,16 +2,16 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_TOOL_HOST_MULTI_SWITCH
+Create BUILD_PR_TOOL_HOST_STATE_HANDOFF
 
 Scope:
-- add multi-tool switching to host
-- enforce lifecycle correctness
-- minimal UI
+- add shared context for tools
+- allow optional state passing
+- minimal changes
 
 Validation:
 - npm run test:launch-smoke -- --tools
-- verify switching works
+- verify state handoff works
 
 Output:
-<project>/tmp/BUILD_PR_TOOL_HOST_MULTI_SWITCH_delta.zip
+<project>/tmp/BUILD_PR_TOOL_HOST_STATE_HANDOFF_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: add BUILD_PR tool host multi-switch bundle
+docs: add BUILD_PR tool host state handoff bundle

docs/dev/reports/BUILD_PR_TOOL_HOST_STATE_HANDOFF_report.md

@@ -0,0 +1,40 @@
+# BUILD_PR_TOOL_HOST_STATE_HANDOFF Report
+
+## Scope Outcome
+- Added shared host context infrastructure for hosted tools.
+- Added optional JSON state passing from Tool Host UI to mounted tools.
+- Kept changes minimal and host-focused.
+
+## Implementation Summary
+- New shared context helper:
+  - `tools/shared/toolHostSharedContext.js`
+  - Writes/reads/removes per-mount host context records.
+  - Supports resolving context from `hostContextId` in URL.
+- Host runtime updates:
+  - `tools/shared/toolHostRuntime.js`
+  - Writes host context on mount and passes `hostContextId` in hosted tool URL.
+  - Excludes object payloads from query-string expansion.
+  - Cleans host context on unmount.
+- Tool Host UI updates:
+  - `tools/Tool Host/index.html`
+  - Added optional state JSON textarea.
+  - `tools/Tool Host/main.js`
+  - Parses optional JSON state and passes it with shared context during mount.
+
+## Validation
+- `npm run test:launch-smoke -- --tools`
+  - PASS (`9/9` tools)
+- Host state handoff verification (CDP):
+  - Mounted `asset-browser` with optional JSON state payload.
+  - Verified hosted iframe URL included `hostContextId`.
+  - Verified stored context record matched tool id, shared context, and optional state payload.
+  - Verified context key cleanup after unmount.
+  - Console/runtime errors: none.
+
+## Files Changed
+- `tools/shared/toolHostSharedContext.js`
+- `tools/shared/toolHostRuntime.js`
+- `tools/Tool Host/index.html`
+- `tools/Tool Host/main.js`
+- `docs/dev/reports/launch_smoke_report.md`
+- `docs/dev/reports/BUILD_PR_TOOL_HOST_STATE_HANDOFF_report.md`

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-11T23:48:31.310Z
+Generated: 2026-04-11T23:53:57.877Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 

docs/dev/reports/tool_host_state_handoff_targets.txt

@@ -0,0 +1,5 @@
+STATE HANDOFF TARGETS
+
+- shared context object
+- getState()/setState()
+- optional tool participation

docs/pr/BUILD_PR_TOOL_HOST_STATE_HANDOFF.md

@@ -0,0 +1,29 @@
+# BUILD_PR_TOOL_HOST_STATE_HANDOFF
+
+## Purpose
+Enable optional state handoff between tools within the Tool Host so workflows can span multiple tools without reload.
+
+## Goals
+- shared project context
+- controlled state passing between tools
+- no tight coupling between tools
+
+## Scope
+- shared state container
+- handoff interface (getState / setState)
+- minimal adapter layer
+
+## Out of Scope
+- persistent storage redesign
+- editor state rewrites
+- UI changes
+
+## Strategy
+- introduce shared context object
+- pass into init(container, config, context)
+- tools opt-in only
+
+## Validation
+- npm run test:launch-smoke -- --tools
+- switch tools and pass simple state
+- no console errors

tools/Tool Host/index.html

@@ -19,6 +19,12 @@ <h2>Tool Host Foundation</h2>
           <select data-tool-host-select></select>
         </label>
       </div>
+      <div class="meta">
+        <label class="field" style="width:100%;">
+          Optional State JSON
+          <textarea data-tool-host-state-input rows="5" style="width:100%;" placeholder='{"example":"value"}'></textarea>
+        </label>
+      </div>
       <div class="meta">
         <button type="button" data-tool-host-mount>Load Selected Tool</button>
         <button type="button" data-tool-host-prev>Previous Tool</button>

tools/Tool Host/main.js

@@ -3,6 +3,7 @@ import { createToolHostRuntime } from "../shared/toolHostRuntime.js";
 
 const refs = {
   toolSelect: document.querySelector("[data-tool-host-select]"),
+  stateInput: document.querySelector("[data-tool-host-state-input]"),
   mountButton: document.querySelector("[data-tool-host-mount]"),
   prevButton: document.querySelector("[data-tool-host-prev]"),
   nextButton: document.querySelector("[data-tool-host-next]"),
@@ -126,12 +127,31 @@ function mountSelectedTool(source = "manual") {
     writeStatus("Select a tool to mount.");
     return;
   }
+  let optionalState = null;
+  if (refs.stateInput instanceof HTMLTextAreaElement) {
+    const rawState = refs.stateInput.value.trim();
+    if (rawState) {
+      try {
+        optionalState = JSON.parse(rawState);
+      } catch {
+        writeStatus("State JSON is invalid. Fix JSON or clear the state field.");
+        return;
+      }
+    }
+  }
   updateSwitchMeta();
   updateStandaloneHref(toolId);
   writeQueryToolId(toolId, source === "init");
+  const previousMount = runtime.getCurrentMount();
   runtime.mountTool(toolId, {
     source,
-    requestedAt: new Date().toISOString()
+    requestedAt: new Date().toISOString(),
+    sharedContext: {
+      requestedToolId: toolId,
+      previousToolId: previousMount?.tool?.id || "",
+      switchPosition: `${Math.max(1, getSelectedToolIndex() + 1)}/${Math.max(1, toolIds.length)}`
+    },
+    state: optionalState
   });
 }
 

tools/shared/toolHostRuntime.js

@@ -1,17 +1,27 @@
 import { getToolHostEntryById } from "./toolHostManifest.js";
+import {
+  removeToolHostSharedContextById,
+  writeToolHostSharedContext
+} from "./toolHostSharedContext.js";
 
 function normalizeToolId(toolId) {
   return typeof toolId === "string" ? toolId.trim() : "";
 }
 
-function buildHostLaunchUrl(toolEntry, config = {}) {
+function buildHostLaunchUrl(toolEntry, config = {}, hostContextId = "") {
   const url = new URL(toolEntry.launchPath, window.location.href);
   url.searchParams.set("hosted", "1");
   url.searchParams.set("hostToolId", toolEntry.id);
+  if (hostContextId) {
+    url.searchParams.set("hostContextId", hostContextId);
+  }
 
   if (config && typeof config === "object") {
     Object.entries(config).forEach(([key, value]) => {
-      if (value === undefined || value === null) {
+      if (key === "state" || key === "sharedContext") {
+        return;
+      }
+      if (value === undefined || value === null || typeof value === "object") {
         return;
       }
       url.searchParams.set(`hostConfig_${key}`, String(value));
@@ -92,6 +102,9 @@ export function createToolHostRuntime(options = {}) {
       previous.frame.removeAttribute("src");
       mountContainer.removeChild(previous.frame);
     }
+    if (previous.hostContextId) {
+      removeToolHostSharedContextById(previous.hostContextId);
+    }
     onStatus(`Unmounted ${previous.tool.displayName} (${reason}, destroy=${destroyStatus}).`);
     onUnmounted(previous.tool, reason, destroyStatus);
     return true;
@@ -118,7 +131,16 @@ export function createToolHostRuntime(options = {}) {
 
     mountSequence += 1;
     const sequenceId = mountSequence;
-    const sourceUrl = buildHostLaunchUrl(toolEntry, config);
+    const sharedContext = config.sharedContext && typeof config.sharedContext === "object" ? config.sharedContext : {};
+    const hostContext = writeToolHostSharedContext({
+      toolId: toolEntry.id,
+      source: typeof config.source === "string" ? config.source : "",
+      requestedAt: typeof config.requestedAt === "string" ? config.requestedAt : new Date().toISOString(),
+      sharedContext,
+      state: Object.prototype.hasOwnProperty.call(config, "state") ? config.state : null
+    });
+    const hostContextId = hostContext?.contextId || "";
+    const sourceUrl = buildHostLaunchUrl(toolEntry, config, hostContextId);
     const frame = createHostFrame(toolEntry, sourceUrl);
     frame.addEventListener("load", () => {
       if (!currentMount || currentMount.mountSequence !== sequenceId) {
@@ -141,7 +163,8 @@ export function createToolHostRuntime(options = {}) {
       frame,
       sourceUrl,
       mountedAt: new Date().toISOString(),
-      mountSequence: sequenceId
+      mountSequence: sequenceId,
+      hostContextId
     };
 
     onStatus(`Mounting ${toolEntry.displayName}...`);

tools/shared/toolHostSharedContext.js

@@ -0,0 +1,125 @@
+const TOOL_HOST_CONTEXT_KEY_PREFIX = "toolboxaid.toolHost.context.";
+
+function getHostStorage() {
+  try {
+    if (globalThis.sessionStorage) {
+      return globalThis.sessionStorage;
+    }
+  } catch {}
+
+  try {
+    if (globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {}
+
+  return null;
+}
+
+function safeParseJson(rawValue) {
+  if (typeof rawValue !== "string" || !rawValue.trim()) {
+    return null;
+  }
+  try {
+    return JSON.parse(rawValue);
+  } catch {
+    return null;
+  }
+}
+
+function buildContextStorageKey(contextId) {
+  return `${TOOL_HOST_CONTEXT_KEY_PREFIX}${contextId}`;
+}
+
+function createContextId(toolId = "") {
+  const suffix = Math.random().toString(36).slice(2, 10);
+  return `${toolId || "tool"}-${Date.now().toString(36)}-${suffix}`;
+}
+
+function sanitizeToolId(toolId) {
+  return typeof toolId === "string" ? toolId.trim() : "";
+}
+
+export function createToolHostSharedContext(payload = {}) {
+  const toolId = sanitizeToolId(payload.toolId);
+  const source = typeof payload.source === "string" ? payload.source : "";
+  const sharedContext = payload.sharedContext && typeof payload.sharedContext === "object" ? payload.sharedContext : {};
+  const contextId = typeof payload.contextId === "string" && payload.contextId.trim()
+    ? payload.contextId.trim()
+    : createContextId(toolId);
+
+  return {
+    schema: "tools.tool-host-context/1",
+    contextId,
+    toolId,
+    source,
+    hosted: true,
+    requestedAt: typeof payload.requestedAt === "string" ? payload.requestedAt : new Date().toISOString(),
+    sharedContext: { ...sharedContext },
+    state: payload.state === undefined ? null : payload.state
+  };
+}
+
+export function writeToolHostSharedContext(payload = {}) {
+  const storage = getHostStorage();
+  if (!storage) {
+    return null;
+  }
+
+  const context = createToolHostSharedContext(payload);
+  storage.setItem(buildContextStorageKey(context.contextId), JSON.stringify(context));
+  return context;
+}
+
+export function readToolHostSharedContextById(contextId) {
+  const normalized = typeof contextId === "string" ? contextId.trim() : "";
+  if (!normalized) {
+    return null;
+  }
+
+  const storage = getHostStorage();
+  if (!storage) {
+    return null;
+  }
+
+  return safeParseJson(storage.getItem(buildContextStorageKey(normalized)));
+}
+
+export function removeToolHostSharedContextById(contextId) {
+  const normalized = typeof contextId === "string" ? contextId.trim() : "";
+  if (!normalized) {
+    return false;
+  }
+
+  const storage = getHostStorage();
+  if (!storage) {
+    return false;
+  }
+
+  storage.removeItem(buildContextStorageKey(normalized));
+  return true;
+}
+
+export function readToolHostSharedContextFromLocation(locationLike = null) {
+  const rawHref = typeof locationLike === "string"
+    ? locationLike
+    : (locationLike && typeof locationLike.href === "string" ? locationLike.href : (typeof window !== "undefined" ? window.location.href : ""));
+
+  if (!rawHref) {
+    return null;
+  }
+
+  let params = null;
+  try {
+    params = new URL(rawHref).searchParams;
+  } catch {
+    return null;
+  }
+
+  const contextId = params.get("hostContextId") || "";
+  if (!contextId) {
+    return null;
+  }
+
+  return readToolHostSharedContextById(contextId);
+}