refactor(prompts): reorganize extensions and add protected tools extension

Author: Tarquinen

lib/commands/manual.ts

@@ -12,7 +12,7 @@ import type { SessionState, WithParts } from "../state"
 import type { PluginConfig } from "../config"
 import { sendIgnoredMessage } from "../ui/notification"
 import { getCurrentParams } from "../token-utils"
-import { buildCompressedBlockGuidance } from "../messages/inject/utils"
+import { buildCompressedBlockGuidance } from "../prompts/extensions/nudge"
 import { isIgnoredUserMessage } from "../messages/query"
 
 const MANUAL_MODE_ON = "Manual mode is now ON. Use /dcp compress to trigger context tools manually."

lib/compress/message.ts

@@ -1,7 +1,7 @@
 import { tool } from "@opencode-ai/plugin"
 import type { ToolContext } from "./types"
 import { countTokens } from "../token-utils"
-import { MESSAGE_FORMAT_OVERLAY } from "../prompts/internal-overlays"
+import { MESSAGE_FORMAT_EXTENSION } from "../prompts/extensions/tool"
 import { formatIssues, formatResult, resolveMessages, validateArgs } from "./message-utils"
 import { finalizeSession, prepareSession, type NotificationEntry } from "./pipeline"
 import { appendProtectedTools } from "./protected-content"
@@ -43,7 +43,7 @@ export function createCompressMessageTool(ctx: ToolContext): ReturnType<typeof t
     const runtimePrompts = ctx.prompts.getRuntimePrompts()
 
     return tool({
-        description: runtimePrompts.compressMessage + MESSAGE_FORMAT_OVERLAY,
+        description: runtimePrompts.compressMessage + MESSAGE_FORMAT_EXTENSION,
         args: buildSchema(),
         async execute(args, toolCtx) {
             const input = args as CompressMessageToolArgs

lib/compress/range.ts

@@ -1,7 +1,7 @@
 import { tool } from "@opencode-ai/plugin"
 import type { ToolContext } from "./types"
 import { countTokens } from "../token-utils"
-import { RANGE_FORMAT_OVERLAY } from "../prompts/internal-overlays"
+import { RANGE_FORMAT_EXTENSION } from "../prompts/extensions/tool"
 import { finalizeSession, prepareSession, type NotificationEntry } from "./pipeline"
 import { appendProtectedTools, appendProtectedUserMessages } from "./protected-content"
 import {
@@ -54,7 +54,7 @@ export function createCompressRangeTool(ctx: ToolContext): ReturnType<typeof too
     const runtimePrompts = ctx.prompts.getRuntimePrompts()
 
     return tool({
-        description: runtimePrompts.compressRange + RANGE_FORMAT_OVERLAY,
+        description: runtimePrompts.compressRange + RANGE_FORMAT_EXTENSION,
         args: buildSchema(),
         async execute(args, toolCtx) {
             const input = args as CompressRangeToolArgs

lib/hooks.ts

@@ -15,6 +15,7 @@ import {
     syncCompressionBlocks,
 } from "./messages"
 import { renderSystemPrompt, type PromptStore } from "./prompts"
+import { buildProtectedToolsExtension } from "./prompts/extensions/system"
 import {
     applyPendingManualTrigger,
     handleContextCommand,
@@ -75,6 +76,7 @@ export function createSystemPromptHandler(
         const runtimePrompts = prompts.getRuntimePrompts()
         const newPrompt = renderSystemPrompt(
             runtimePrompts,
+            buildProtectedToolsExtension(config.compress.protectedTools),
             !!state.manualMode,
             state.isSubAgent && config.experimental.allowSubAgents,
         )

lib/messages/inject/utils.ts

@@ -1,6 +1,10 @@
 import type { SessionState, WithParts } from "../../state"
 import type { PluginConfig } from "../../config"
-import { renderMessagePriorityGuidance } from "../../prompts/message-priority-guidance"
+import {
+    appendGuidanceToDcpTag,
+    buildCompressedBlockGuidance,
+    renderMessagePriorityGuidance,
+} from "../../prompts/extensions/nudge"
 import type { RuntimePrompts } from "../../prompts/store"
 import type { UserMessage } from "@opencode-ai/sdk/v2"
 import {
@@ -188,38 +192,6 @@ export function addAnchor(
     return anchorMessageIds.size !== previousSize
 }
 
-export function buildCompressedBlockGuidance(state: SessionState): string {
-    const refs = Array.from(state.prune.messages.activeBlockIds)
-        .filter((id) => Number.isInteger(id) && id > 0)
-        .sort((a, b) => a - b)
-        .map((id) => `b${id}`)
-    const blockCount = refs.length
-    const blockList = blockCount > 0 ? refs.join(", ") : "none"
-
-    return [
-        "Compressed block context:",
-        `- Active compressed blocks in this session: ${blockCount} (${blockList})`,
-        "- If your selected compression range includes any listed block, include each required placeholder exactly once in the summary using \`(bN)\`.",
-    ].join("\n")
-}
-
-function appendGuidanceToDcpTag(nudgeText: string, guidance: string): string {
-    if (!guidance.trim()) {
-        return nudgeText
-    }
-
-    const closeTag = "</dcp-system-reminder>"
-    const closeTagIndex = nudgeText.lastIndexOf(closeTag)
-
-    if (closeTagIndex === -1) {
-        return nudgeText
-    }
-
-    const beforeClose = nudgeText.slice(0, closeTagIndex).trimEnd()
-    const afterClose = nudgeText.slice(closeTagIndex)
-    return `${beforeClose}\n\n${guidance}\n${afterClose}`
-}
-
 function buildMessagePriorityGuidance(
     messages: WithParts[],
     compressionPriorities: CompressionPriorityMap | undefined,

lib/prompts/extensions/nudge.ts

@@ -0,0 +1,43 @@
+import type { SessionState } from "../../state"
+
+export function buildCompressedBlockGuidance(state: SessionState): string {
+    const refs = Array.from(state.prune.messages.activeBlockIds)
+        .filter((id) => Number.isInteger(id) && id > 0)
+        .sort((a, b) => a - b)
+        .map((id) => `b${id}`)
+    const blockCount = refs.length
+    const blockList = blockCount > 0 ? refs.join(", ") : "none"
+
+    return [
+        "Compressed block context:",
+        `- Active compressed blocks in this session: ${blockCount} (${blockList})`,
+        "- If your selected compression range includes any listed block, include each required placeholder exactly once in the summary using `(bN)`.",
+    ].join("\n")
+}
+
+export function renderMessagePriorityGuidance(priorityLabel: string, refs: string[]): string {
+    const refList = refs.length > 0 ? refs.join(", ") : "none"
+
+    return [
+        "Message priority context:",
+        "- Higher-priority older messages consume more context and should be compressed right away if it is safe to do so.",
+        `- ${priorityLabel}-priority message IDs before this point: ${refList}`,
+    ].join("\n")
+}
+
+export function appendGuidanceToDcpTag(nudgeText: string, guidance: string): string {
+    if (!guidance.trim()) {
+        return nudgeText
+    }
+
+    const closeTag = "</dcp-system-reminder>"
+    const closeTagIndex = nudgeText.lastIndexOf(closeTag)
+
+    if (closeTagIndex === -1) {
+        return nudgeText
+    }
+
+    const beforeClose = nudgeText.slice(0, closeTagIndex).trimEnd()
+    const afterClose = nudgeText.slice(closeTagIndex)
+    return `${beforeClose}\n\n${guidance}\n${afterClose}`
+}

lib/prompts/extensions/system.ts

@@ -0,0 +1,32 @@
+export const MANUAL_MODE_SYSTEM_EXTENSION = `<dcp-system-reminder>
+Manual mode is enabled. Do NOT use compress unless the user has explicitly triggered it through a manual marker.
+
+Only use the compress tool after seeing \`<compress triggered manually>\` in the current user instruction context.
+
+Issue exactly ONE compress tool per manual trigger. Do NOT launch multiple compress tools in parallel. Each trigger grants a single compression; after it completes, wait for the next trigger.
+
+After completing a manually triggered context-management action, STOP IMMEDIATELY. Do NOT continue with any task execution. End your response right after the tool use completes and wait for the next user input.
+</dcp-system-reminder>
+`
+
+export const SUBAGENT_SYSTEM_EXTENSION = `<dcp-system-reminder>
+You are operating in a subagent environment.
+
+The initial subagent instruction is imperative and must be followed exactly.
+It is the only user message intentionally not assigned a message ID, and therefore is not eligible for compression.
+All subsequent messages in the session will have IDs.
+</dcp-system-reminder>
+`
+
+export function buildProtectedToolsExtension(protectedTools: string[]): string {
+    if (protectedTools.length === 0) {
+        return ""
+    }
+
+    const toolList = protectedTools.map((t) => `\`${t}\``).join(", ")
+    return `<dcp-system-reminder>
+The following tools are environment-managed: ${toolList}.
+Their outputs are automatically preserved during compression.
+Do not include their content in compress tool summaries — the environment retains it independently.
+</dcp-system-reminder>`
+}

lib/prompts/extensions/tool.ts

@@ -0,0 +1,35 @@
+// These format schemas are kept separate from the editable compress prompts
+// so they cannot be modified via custom prompt overrides. The schemas must
+// match the tool's input validation and are not safe to change independently.
+
+export const RANGE_FORMAT_EXTENSION = `
+THE FORMAT OF COMPRESS
+
+\`\`\`
+{
+  topic: string,           // Short label (3-5 words) - e.g., "Auth System Exploration"
+  content: [               // One or more ranges to compress
+    {
+      startId: string,     // Boundary ID at range start: mNNNN or bN
+      endId: string,       // Boundary ID at range end: mNNNN or bN
+      summary: string      // Complete technical summary replacing all content in range
+    }
+  ]
+}
+\`\`\``
+
+export const MESSAGE_FORMAT_EXTENSION = `
+THE FORMAT OF COMPRESS
+
+\`\`\`
+{
+  topic: string,           // Short label (3-5 words) for the overall batch
+  content: [               // One or more messages to compress independently
+    {
+      messageId: string,   // Raw message ID only: mNNNN (ignore metadata attributes like priority)
+      topic: string,       // Short label (3-5 words) for this one message summary
+      summary: string      // Complete technical summary replacing that one message
+    }
+  ]
+}
+\`\`\``

lib/prompts/index.ts

@@ -1,29 +1,29 @@
 import type { RuntimePrompts } from "./store"
 export type { PromptStore, RuntimePrompts } from "./store"
 
-function stripLegacyInlineComments(content: string): string {
-    return content.replace(/^[ \t]*\/\/.*?\/\/[ \t]*$/gm, "")
-}
-
-function appendSystemOverlays(systemPrompt: string, overlays: string[]): string {
-    return [systemPrompt, ...overlays].filter(Boolean).join("\n\n")
-}
-
 export function renderSystemPrompt(
     prompts: RuntimePrompts,
+    protectedToolsExtension?: string,
     manual?: boolean,
     subagent?: boolean,
 ): string {
-    const overlays: string[] = []
+    const extensions: string[] = []
+
+    if (protectedToolsExtension) {
+        extensions.push(protectedToolsExtension.trim())
+    }
+
     if (manual) {
-        overlays.push(prompts.manualOverlay.trim())
+        extensions.push(prompts.manualExtension.trim())
     }
 
     if (subagent) {
-        overlays.push(prompts.subagentOverlay.trim())
+        extensions.push(prompts.subagentExtension.trim())
     }
 
-    const strippedSystem = stripLegacyInlineComments(prompts.system).trim()
-    const withOverlays = appendSystemOverlays(strippedSystem, overlays)
-    return withOverlays.replace(/\n([ \t]*\n)+/g, "\n\n").trim()
+    return [prompts.system.trim(), ...extensions]
+        .filter(Boolean)
+        .join("\n\n")
+        .replace(/\n([ \t]*\n)+/g, "\n\n")
+        .trim()
 }