@defend-tech/opencode-optima 0.1.54 → 0.1.55

package/dist/index.js

@@ -9830,12 +9830,170 @@ function normalizeOpenCodeSessionMessages(result) {
   if (Array.isArray(data?.items)) return [...data.items];
   return [];
 }
+function clampOpenCodeMessageLimit(limit) {
+  const value = Number(limit);
+  if (!Number.isFinite(value)) return 20;
+  return Math.min(50, Math.max(1, Math.floor(value)));
+}
+function clampOpenCodeSessionText(text = "", maxLength = 12e3) {
+  const value = String(text ?? "");
+  return value.length > maxLength ? value.slice(0, maxLength) : value;
+}
+function hashOpenCodeSessionText(text = "") {
+  return crypto.createHash("sha256").update(String(text ?? "")).digest("hex");
+}
 async function readOpenCodeSessionMessages(client, { sessionId, directory, limit = 20 } = {}) {
   if (typeof client?.session?.messages !== "function") return null;
-  const query = { limit };
+  const query = { limit: clampOpenCodeMessageLimit(limit) };
   if (directory) query.directory = directory;
   return normalizeOpenCodeSessionMessages(await client.session.messages({ path: { id: sessionId }, query }));
 }
+function openCodeResultSummary(result) {
+  const data = result?.data ?? result;
+  return {
+    type: Array.isArray(data) ? "array" : typeof data,
+    id: data?.id || data?.sessionID || data?.sessionId || result?.id || result?.sessionID || result?.sessionId || null,
+    keys: data && typeof data === "object" && !Array.isArray(data) ? Object.keys(data).slice(0, 20) : [],
+    dataKeys: result?.data && typeof result.data === "object" && !Array.isArray(result.data) ? Object.keys(result.data).slice(0, 20) : [],
+    status: result?.status || result?.response?.status || null
+  };
+}
+function normalizeOpenCodeMessageRole(message = {}) {
+  return message.role || message.info?.role || message.author?.role || message.type || "";
+}
+function normalizeOpenCodeMessageAgent(message = {}) {
+  return message.agent || message.info?.agent || message.mode?.agent || message.author?.agent || "";
+}
+function normalizeOpenCodeMessageMode(message = {}) {
+  return message.mode || message.info?.mode || message.metadata?.mode || "";
+}
+function normalizeOpenCodeMessageId(message = {}) {
+  return message.id || message.messageID || message.messageId || message.info?.id || message.data?.id || null;
+}
+function summarizeOpenCodeMessages(messages = [], { snippetLength = 160, maxMessages = 50 } = {}) {
+  const list = Array.isArray(messages) ? messages.slice(0, maxMessages) : [];
+  const safeSnippetLength = Math.min(240, Math.max(20, Number(snippetLength) || 160));
+  return list.map((message, index) => {
+    const text = openCodeMessageText(message).replace(/\s+/g, " ").trim();
+    return {
+      index,
+      id: normalizeOpenCodeMessageId(message),
+      role: normalizeOpenCodeMessageRole(message),
+      agent: normalizeOpenCodeMessageAgent(message),
+      mode: normalizeOpenCodeMessageMode(message),
+      text_length: text.length,
+      text_hash: hashOpenCodeSessionText(text),
+      snippet: text.length > safeSnippetLength ? `${text.slice(0, safeSnippetLength)}...` : text
+    };
+  });
+}
+function promptResultAssistantReturned(result) {
+  const parts = normalizePromptResponseParts(result);
+  const text = extractTextParts(parts);
+  const data = result?.data ?? result;
+  return Boolean(text || data?.role === "assistant" || data?.info?.role === "assistant");
+}
+async function createOpenCodeSessionControl(client, { directory, title, agent } = {}) {
+  if (typeof client?.session?.create !== "function") throw new Error("OpenCode client does not expose session.create.");
+  const body = { title };
+  if (agent) body.agent = agent;
+  const result = await client.session.create({ query: { directory }, body });
+  const sessionId = extractOpenCodeSessionId(result);
+  if (!sessionId) throw new Error("OpenCode session create response did not include a session id.");
+  return {
+    ok: true,
+    session_id: sessionId,
+    title,
+    directory,
+    agent: agent || null,
+    result_summary: openCodeResultSummary(result)
+  };
+}
+async function promptOpenCodeSessionControl(client, { sessionId, directory, text, agent, omitAgent = false, requireReadable = true } = {}) {
+  if (typeof client?.session?.prompt !== "function") throw new Error("OpenCode client does not expose session.prompt.");
+  if (requireReadable) await assertOpenCodeSessionReadableForDirectory(client, { sessionId, directory });
+  const safeText = clampOpenCodeSessionText(text);
+  const body = { parts: [{ type: "text", text: safeText }] };
+  if (!omitAgent && agent) body.agent = agent;
+  const result = await client.session.prompt({ path: { id: sessionId }, query: { directory }, body });
+  return {
+    ok: true,
+    session_id: sessionId,
+    directory,
+    agent: omitAgent ? null : agent || null,
+    omit_agent: Boolean(omitAgent),
+    text_length: safeText.length,
+    text_truncated: String(text ?? "").length > safeText.length,
+    text_hash: hashOpenCodeSessionText(safeText),
+    assistant_returned: promptResultAssistantReturned(result),
+    returned_parts_count: normalizePromptResponseParts(result).length,
+    result_summary: openCodeResultSummary(result)
+  };
+}
+async function assertOpenCodeSessionReadableForDirectory(client, { sessionId, directory } = {}) {
+  try {
+    await readOpenCodeSessionMessages(client, { sessionId, directory, limit: 1 });
+    return true;
+  } catch (error) {
+    throw new Error(`OpenCode session '${sessionId}' is not readable for the requested safe directory.`);
+  }
+}
+async function readOpenCodeSessionControl(client, { sessionId, directory, limit = 20 } = {}) {
+  const boundedLimit = clampOpenCodeMessageLimit(limit);
+  const messages = await readOpenCodeSessionMessages(client, { sessionId, directory, limit: boundedLimit });
+  if (!messages) throw new Error("OpenCode client does not expose session.messages.");
+  return {
+    ok: true,
+    session_id: sessionId,
+    directory: directory || null,
+    limit: boundedLimit,
+    count: messages.length,
+    messages: summarizeOpenCodeMessages(messages)
+  };
+}
+async function probeOpenCodeSessionControl(client, { directory, agent, omitAgentOnPrompt = false, text = "" } = {}) {
+  const requestedMarker = text || `optima-session-probe-${crypto.randomUUID()}`;
+  const marker = clampOpenCodeSessionText(requestedMarker);
+  const create = await createOpenCodeSessionControl(client, {
+    directory,
+    title: `Optima session probe ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    agent
+  });
+  const prompt = await promptOpenCodeSessionControl(client, {
+    sessionId: create.session_id,
+    directory,
+    text: marker,
+    agent,
+    omitAgent: omitAgentOnPrompt,
+    requireReadable: false
+  });
+  const rawMessages = await readOpenCodeSessionMessages(client, { sessionId: create.session_id, directory, limit: 50 });
+  if (!rawMessages) throw new Error("OpenCode client does not expose session.messages.");
+  const fullMessageText = rawMessages.map(openCodeMessageText).join("\n");
+  const messages = {
+    ok: true,
+    session_id: create.session_id,
+    directory,
+    limit: 50,
+    count: rawMessages.length,
+    messages: summarizeOpenCodeMessages(rawMessages)
+  };
+  return {
+    ok: true,
+    session_id: create.session_id,
+    directory,
+    agent: agent || null,
+    omit_agent_on_prompt: Boolean(omitAgentOnPrompt),
+    marker_length: marker.length,
+    marker_truncated: requestedMarker.length > marker.length,
+    marker_hash: hashOpenCodeSessionText(marker),
+    marker_visible: fullMessageText.includes(marker),
+    assistant_visible: rawMessages.some((message) => normalizeLooseToken(normalizeOpenCodeMessageRole(message)) === "assistant" || Boolean(normalizeOpenCodeMessageAgent(message) && openCodeMessageText(message))),
+    create,
+    prompt,
+    messages
+  };
+}
 function openCodeMessageText(message) {
   const parts = [message?.text, message?.content, message?.message, message?.body?.text, message?.data?.text];
   const partList = Array.isArray(message?.parts) ? message.parts : Array.isArray(message?.body?.parts) ? message.body.parts : [];
@@ -11481,6 +11639,21 @@ function shouldRegisterWorkflowProductManager(options = {}, worktree = process.c
   const validation = options.clickUpWebhookValidation;
   return validation?.complete === true && validation?.ok !== false && isSameOrNestedPath(worktree, validation.config?.basePath);
 }
+function resolveSessionToolDirectory({ requestedDirectory, context, pluginWorktree, clickUpWebhookValidation } = {}) {
+  const safe = safeWorktreeOrFailure(context, pluginWorktree);
+  if (!safe.ok) return { ok: false, error: safe.message };
+  const requested = String(requestedDirectory || "").trim() ? path2.resolve(safe.worktree, String(requestedDirectory).trim()) : safe.worktree;
+  if (!isSafeWritableDirectory(requested)) return { ok: false, error: `Directory is not a safe writable directory: ${requested}` };
+  if (isSameOrNestedPath(requested, safe.worktree)) return { ok: true, directory: requested, safeWorktree: safe.worktree, scope: "context_worktree" };
+  const clickUpBasePath = clickUpWebhookValidation?.complete === true && clickUpWebhookValidation?.ok !== false ? clickUpWebhookValidation.config?.basePath : "";
+  if (clickUpBasePath && isSameOrNestedPath(requested, clickUpBasePath)) {
+    return { ok: true, directory: requested, safeWorktree: safe.worktree, scope: "clickup_base_path", clickupBasePath: path2.resolve(clickUpBasePath) };
+  }
+  return {
+    ok: false,
+    error: `Directory '${requested}' is outside the safe worktree '${safe.worktree}' and configured ClickUp base path.`
+  };
+}
 function buildOptimaAgents(repoCfg, operatingTeamMode, worktree, debugDir, options = {}) {
   const optimaActive = repoCfg && repoCfg.enabled === true;
   const clickUpWebhookActive = shouldRegisterWorkflowProductManager(options, worktree);
@@ -11767,6 +11940,100 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
 Restart or reload OpenCode manually if the newly scaffolded config or agents are not visible in this session. Optima did not dispose or reload the active OpenCode instance automatically to avoid aborting the current session.`;
       }
     }),
+    optima_session_create: tool({
+      description: "Create an OpenCode session through the installed structured SDK shape",
+      args: {
+        directory: tool.schema.string().describe("Project directory for the OpenCode session"),
+        title: tool.schema.string().describe("Session title"),
+        agent: tool.schema.string().describe("Optional agent id for session creation")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await createOpenCodeSessionControl(input.client, {
+            directory: directory.directory,
+            title: args.title,
+            agent: args.agent
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
+    optima_session_prompt: tool({
+      description: "Prompt an existing OpenCode session through the installed structured SDK shape",
+      args: {
+        session_id: tool.schema.string().describe("OpenCode session id"),
+        directory: tool.schema.string().describe("Project directory for the OpenCode session"),
+        text: tool.schema.string().describe("Text prompt to send"),
+        agent: tool.schema.string().describe("Optional agent id for the prompt body"),
+        omit_agent: tool.schema.string().describe("Set to 'true' to omit agent from the prompt body")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await promptOpenCodeSessionControl(input.client, {
+            sessionId: args.session_id,
+            directory: directory.directory,
+            text: args.text,
+            agent: args.agent,
+            omitAgent: String(args.omit_agent || "").toLowerCase() === "true"
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
+    optima_session_messages: tool({
+      description: "Read and summarize OpenCode session messages through the installed structured SDK shape",
+      args: {
+        session_id: tool.schema.string().describe("OpenCode session id"),
+        directory: tool.schema.string().describe("Optional project directory for the OpenCode session"),
+        limit: tool.schema.number().describe("Optional message limit")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await readOpenCodeSessionControl(input.client, {
+            sessionId: args.session_id,
+            directory: directory.directory,
+            limit: args.limit
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
+    optima_session_probe: tool({
+      description: "Create, prompt, and read an OpenCode session without touching ClickUp state",
+      args: {
+        directory: tool.schema.string().describe("Project directory for the OpenCode session"),
+        agent: tool.schema.string().describe("Optional agent id to probe"),
+        omit_agent_on_prompt: tool.schema.string().describe("Set to 'true' to omit agent from the prompt body"),
+        text: tool.schema.string().describe("Optional marker text to send")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await probeOpenCodeSessionControl(input.client, {
+            directory: directory.directory,
+            agent: args.agent,
+            omitAgentOnPrompt: String(args.omit_agent_on_prompt || "").toLowerCase() === "true",
+            text: args.text
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
     optima_clickup_sync_summary: tool({
       description: "Generate a dry-run ClickUp summary/comment payload from Optima Markdown task and evidence artifacts",
       args: {
@@ -12235,7 +12502,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionMessages, reconcileClickUpStartup, scheduleClickUpStartupReconciliation, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, scheduleClickUpStartupReconciliation, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 export {
   OptimaPlugin as default
 };

package/dist/sanitize_cli.js

@@ -9837,12 +9837,170 @@ function normalizeOpenCodeSessionMessages(result) {
   if (Array.isArray(data?.items)) return [...data.items];
   return [];
 }
+function clampOpenCodeMessageLimit(limit) {
+  const value = Number(limit);
+  if (!Number.isFinite(value)) return 20;
+  return Math.min(50, Math.max(1, Math.floor(value)));
+}
+function clampOpenCodeSessionText(text = "", maxLength = 12e3) {
+  const value = String(text ?? "");
+  return value.length > maxLength ? value.slice(0, maxLength) : value;
+}
+function hashOpenCodeSessionText(text = "") {
+  return crypto.createHash("sha256").update(String(text ?? "")).digest("hex");
+}
 async function readOpenCodeSessionMessages(client, { sessionId, directory, limit = 20 } = {}) {
   if (typeof client?.session?.messages !== "function") return null;
-  const query = { limit };
+  const query = { limit: clampOpenCodeMessageLimit(limit) };
   if (directory) query.directory = directory;
   return normalizeOpenCodeSessionMessages(await client.session.messages({ path: { id: sessionId }, query }));
 }
+function openCodeResultSummary(result) {
+  const data = result?.data ?? result;
+  return {
+    type: Array.isArray(data) ? "array" : typeof data,
+    id: data?.id || data?.sessionID || data?.sessionId || result?.id || result?.sessionID || result?.sessionId || null,
+    keys: data && typeof data === "object" && !Array.isArray(data) ? Object.keys(data).slice(0, 20) : [],
+    dataKeys: result?.data && typeof result.data === "object" && !Array.isArray(result.data) ? Object.keys(result.data).slice(0, 20) : [],
+    status: result?.status || result?.response?.status || null
+  };
+}
+function normalizeOpenCodeMessageRole(message = {}) {
+  return message.role || message.info?.role || message.author?.role || message.type || "";
+}
+function normalizeOpenCodeMessageAgent(message = {}) {
+  return message.agent || message.info?.agent || message.mode?.agent || message.author?.agent || "";
+}
+function normalizeOpenCodeMessageMode(message = {}) {
+  return message.mode || message.info?.mode || message.metadata?.mode || "";
+}
+function normalizeOpenCodeMessageId(message = {}) {
+  return message.id || message.messageID || message.messageId || message.info?.id || message.data?.id || null;
+}
+function summarizeOpenCodeMessages(messages = [], { snippetLength = 160, maxMessages = 50 } = {}) {
+  const list = Array.isArray(messages) ? messages.slice(0, maxMessages) : [];
+  const safeSnippetLength = Math.min(240, Math.max(20, Number(snippetLength) || 160));
+  return list.map((message, index) => {
+    const text = openCodeMessageText(message).replace(/\s+/g, " ").trim();
+    return {
+      index,
+      id: normalizeOpenCodeMessageId(message),
+      role: normalizeOpenCodeMessageRole(message),
+      agent: normalizeOpenCodeMessageAgent(message),
+      mode: normalizeOpenCodeMessageMode(message),
+      text_length: text.length,
+      text_hash: hashOpenCodeSessionText(text),
+      snippet: text.length > safeSnippetLength ? `${text.slice(0, safeSnippetLength)}...` : text
+    };
+  });
+}
+function promptResultAssistantReturned(result) {
+  const parts = normalizePromptResponseParts(result);
+  const text = extractTextParts(parts);
+  const data = result?.data ?? result;
+  return Boolean(text || data?.role === "assistant" || data?.info?.role === "assistant");
+}
+async function createOpenCodeSessionControl(client, { directory, title, agent } = {}) {
+  if (typeof client?.session?.create !== "function") throw new Error("OpenCode client does not expose session.create.");
+  const body = { title };
+  if (agent) body.agent = agent;
+  const result = await client.session.create({ query: { directory }, body });
+  const sessionId = extractOpenCodeSessionId(result);
+  if (!sessionId) throw new Error("OpenCode session create response did not include a session id.");
+  return {
+    ok: true,
+    session_id: sessionId,
+    title,
+    directory,
+    agent: agent || null,
+    result_summary: openCodeResultSummary(result)
+  };
+}
+async function promptOpenCodeSessionControl(client, { sessionId, directory, text, agent, omitAgent = false, requireReadable = true } = {}) {
+  if (typeof client?.session?.prompt !== "function") throw new Error("OpenCode client does not expose session.prompt.");
+  if (requireReadable) await assertOpenCodeSessionReadableForDirectory(client, { sessionId, directory });
+  const safeText = clampOpenCodeSessionText(text);
+  const body = { parts: [{ type: "text", text: safeText }] };
+  if (!omitAgent && agent) body.agent = agent;
+  const result = await client.session.prompt({ path: { id: sessionId }, query: { directory }, body });
+  return {
+    ok: true,
+    session_id: sessionId,
+    directory,
+    agent: omitAgent ? null : agent || null,
+    omit_agent: Boolean(omitAgent),
+    text_length: safeText.length,
+    text_truncated: String(text ?? "").length > safeText.length,
+    text_hash: hashOpenCodeSessionText(safeText),
+    assistant_returned: promptResultAssistantReturned(result),
+    returned_parts_count: normalizePromptResponseParts(result).length,
+    result_summary: openCodeResultSummary(result)
+  };
+}
+async function assertOpenCodeSessionReadableForDirectory(client, { sessionId, directory } = {}) {
+  try {
+    await readOpenCodeSessionMessages(client, { sessionId, directory, limit: 1 });
+    return true;
+  } catch (error) {
+    throw new Error(`OpenCode session '${sessionId}' is not readable for the requested safe directory.`);
+  }
+}
+async function readOpenCodeSessionControl(client, { sessionId, directory, limit = 20 } = {}) {
+  const boundedLimit = clampOpenCodeMessageLimit(limit);
+  const messages = await readOpenCodeSessionMessages(client, { sessionId, directory, limit: boundedLimit });
+  if (!messages) throw new Error("OpenCode client does not expose session.messages.");
+  return {
+    ok: true,
+    session_id: sessionId,
+    directory: directory || null,
+    limit: boundedLimit,
+    count: messages.length,
+    messages: summarizeOpenCodeMessages(messages)
+  };
+}
+async function probeOpenCodeSessionControl(client, { directory, agent, omitAgentOnPrompt = false, text = "" } = {}) {
+  const requestedMarker = text || `optima-session-probe-${crypto.randomUUID()}`;
+  const marker = clampOpenCodeSessionText(requestedMarker);
+  const create = await createOpenCodeSessionControl(client, {
+    directory,
+    title: `Optima session probe ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    agent
+  });
+  const prompt = await promptOpenCodeSessionControl(client, {
+    sessionId: create.session_id,
+    directory,
+    text: marker,
+    agent,
+    omitAgent: omitAgentOnPrompt,
+    requireReadable: false
+  });
+  const rawMessages = await readOpenCodeSessionMessages(client, { sessionId: create.session_id, directory, limit: 50 });
+  if (!rawMessages) throw new Error("OpenCode client does not expose session.messages.");
+  const fullMessageText = rawMessages.map(openCodeMessageText).join("\n");
+  const messages = {
+    ok: true,
+    session_id: create.session_id,
+    directory,
+    limit: 50,
+    count: rawMessages.length,
+    messages: summarizeOpenCodeMessages(rawMessages)
+  };
+  return {
+    ok: true,
+    session_id: create.session_id,
+    directory,
+    agent: agent || null,
+    omit_agent_on_prompt: Boolean(omitAgentOnPrompt),
+    marker_length: marker.length,
+    marker_truncated: requestedMarker.length > marker.length,
+    marker_hash: hashOpenCodeSessionText(marker),
+    marker_visible: fullMessageText.includes(marker),
+    assistant_visible: rawMessages.some((message) => normalizeLooseToken(normalizeOpenCodeMessageRole(message)) === "assistant" || Boolean(normalizeOpenCodeMessageAgent(message) && openCodeMessageText(message))),
+    create,
+    prompt,
+    messages
+  };
+}
 function openCodeMessageText(message) {
   const parts = [message?.text, message?.content, message?.message, message?.body?.text, message?.data?.text];
   const partList = Array.isArray(message?.parts) ? message.parts : Array.isArray(message?.body?.parts) ? message.body.parts : [];
@@ -11488,6 +11646,21 @@ function shouldRegisterWorkflowProductManager(options = {}, worktree = process.c
   const validation = options.clickUpWebhookValidation;
   return validation?.complete === true && validation?.ok !== false && isSameOrNestedPath(worktree, validation.config?.basePath);
 }
+function resolveSessionToolDirectory({ requestedDirectory, context, pluginWorktree, clickUpWebhookValidation } = {}) {
+  const safe = safeWorktreeOrFailure(context, pluginWorktree);
+  if (!safe.ok) return { ok: false, error: safe.message };
+  const requested = String(requestedDirectory || "").trim() ? path2.resolve(safe.worktree, String(requestedDirectory).trim()) : safe.worktree;
+  if (!isSafeWritableDirectory(requested)) return { ok: false, error: `Directory is not a safe writable directory: ${requested}` };
+  if (isSameOrNestedPath(requested, safe.worktree)) return { ok: true, directory: requested, safeWorktree: safe.worktree, scope: "context_worktree" };
+  const clickUpBasePath = clickUpWebhookValidation?.complete === true && clickUpWebhookValidation?.ok !== false ? clickUpWebhookValidation.config?.basePath : "";
+  if (clickUpBasePath && isSameOrNestedPath(requested, clickUpBasePath)) {
+    return { ok: true, directory: requested, safeWorktree: safe.worktree, scope: "clickup_base_path", clickupBasePath: path2.resolve(clickUpBasePath) };
+  }
+  return {
+    ok: false,
+    error: `Directory '${requested}' is outside the safe worktree '${safe.worktree}' and configured ClickUp base path.`
+  };
+}
 function buildOptimaAgents(repoCfg, operatingTeamMode, worktree, debugDir, options = {}) {
   const optimaActive = repoCfg && repoCfg.enabled === true;
   const clickUpWebhookActive = shouldRegisterWorkflowProductManager(options, worktree);
@@ -11774,6 +11947,100 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
 Restart or reload OpenCode manually if the newly scaffolded config or agents are not visible in this session. Optima did not dispose or reload the active OpenCode instance automatically to avoid aborting the current session.`;
       }
     }),
+    optima_session_create: tool({
+      description: "Create an OpenCode session through the installed structured SDK shape",
+      args: {
+        directory: tool.schema.string().describe("Project directory for the OpenCode session"),
+        title: tool.schema.string().describe("Session title"),
+        agent: tool.schema.string().describe("Optional agent id for session creation")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await createOpenCodeSessionControl(input.client, {
+            directory: directory.directory,
+            title: args.title,
+            agent: args.agent
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
+    optima_session_prompt: tool({
+      description: "Prompt an existing OpenCode session through the installed structured SDK shape",
+      args: {
+        session_id: tool.schema.string().describe("OpenCode session id"),
+        directory: tool.schema.string().describe("Project directory for the OpenCode session"),
+        text: tool.schema.string().describe("Text prompt to send"),
+        agent: tool.schema.string().describe("Optional agent id for the prompt body"),
+        omit_agent: tool.schema.string().describe("Set to 'true' to omit agent from the prompt body")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await promptOpenCodeSessionControl(input.client, {
+            sessionId: args.session_id,
+            directory: directory.directory,
+            text: args.text,
+            agent: args.agent,
+            omitAgent: String(args.omit_agent || "").toLowerCase() === "true"
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
+    optima_session_messages: tool({
+      description: "Read and summarize OpenCode session messages through the installed structured SDK shape",
+      args: {
+        session_id: tool.schema.string().describe("OpenCode session id"),
+        directory: tool.schema.string().describe("Optional project directory for the OpenCode session"),
+        limit: tool.schema.number().describe("Optional message limit")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await readOpenCodeSessionControl(input.client, {
+            sessionId: args.session_id,
+            directory: directory.directory,
+            limit: args.limit
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
+    optima_session_probe: tool({
+      description: "Create, prompt, and read an OpenCode session without touching ClickUp state",
+      args: {
+        directory: tool.schema.string().describe("Project directory for the OpenCode session"),
+        agent: tool.schema.string().describe("Optional agent id to probe"),
+        omit_agent_on_prompt: tool.schema.string().describe("Set to 'true' to omit agent from the prompt body"),
+        text: tool.schema.string().describe("Optional marker text to send")
+      },
+      async execute(args, context) {
+        try {
+          const directory = resolveSessionToolDirectory({ requestedDirectory: args.directory, context, pluginWorktree: worktree, clickUpWebhookValidation });
+          if (!directory.ok) return JSON.stringify({ ok: false, error: directory.error }, null, 2);
+          const result = await probeOpenCodeSessionControl(input.client, {
+            directory: directory.directory,
+            agent: args.agent,
+            omitAgentOnPrompt: String(args.omit_agent_on_prompt || "").toLowerCase() === "true",
+            text: args.text
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
     optima_clickup_sync_summary: tool({
       description: "Generate a dry-run ClickUp summary/comment payload from Optima Markdown task and evidence artifacts",
       args: {
@@ -12242,7 +12509,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionMessages, reconcileClickUpStartup, scheduleClickUpStartupReconciliation, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, scheduleClickUpStartupReconciliation, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 
 // src/sanitize_cli.js
 var { migrateLegacyOptimaLayout: migrateLegacyOptimaLayout2 } = OptimaPlugin.__internals;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defend-tech/opencode-optima",
-  "version": "0.1.54",
+  "version": "0.1.55",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"