gsd-pi 2.80.0-dev.2be7caf18 → 2.80.0-dev.3065f7bfa

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Registers GSD extension runtime hooks and token-saving tool policies.
 import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
@@ -19,10 +21,149 @@ import { initNotificationWidget } from "../notification-widget.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
+import { resolveSkillManifest } from "../skill-manifest.js";
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
 let approvalQuestionAbortInFlight = false;
+let deferredApprovalGate = null;
+export const MINIMAL_GSD_TOOL_NAMES = [
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_checkpoint_db",
+    "memory_query",
+    "capture_thought",
+];
+export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
+    "ask_user_questions",
+    "bash",
+    "bg_shell",
+    "edit",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+    "write",
+];
+const AUTO_UNIT_SCOPED_TOOLS = {
+    "research-milestone": ["gsd_summary_save", "gsd_decision_save"],
+    "plan-milestone": ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
+    "discuss-milestone": ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+    "validate-milestone": ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+    "complete-milestone": ["gsd_complete_milestone", "subagent"],
+    "research-slice": ["gsd_summary_save", "gsd_decision_save"],
+    "plan-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+    "refine-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+    "replan-slice": ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
+    "complete-slice": ["gsd_slice_complete", "gsd_decision_save", "gsd_requirement_update", "subagent"],
+    "reassess-roadmap": ["gsd_reassess_roadmap"],
+    "execute-task": ["gsd_task_complete", "gsd_decision_save"],
+    "execute-task-simple": ["gsd_task_complete", "gsd_decision_save"],
+    "reactive-execute": ["gsd_task_complete", "gsd_decision_save"],
+    "run-uat": ["gsd_summary_save"],
+    "gate-evaluate": ["gsd_save_gate_result"],
+    "rewrite-docs": ["gsd_summary_save", "gsd_decision_save"],
+    "workflow-preferences": ["gsd_summary_save"],
+    "discuss-project": ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+    "discuss-requirements": ["gsd_requirement_save", "gsd_summary_save"],
+    "research-decision": ["gsd_summary_save"],
+    "research-project": ["gsd_summary_save", "gsd_decision_save"],
+};
+const WORKFLOW_GSD_TOOL_NAMES = [
+    ...MINIMAL_GSD_TOOL_NAMES,
+    ...Object.values(AUTO_UNIT_SCOPED_TOOLS).flat(),
+].filter(isGsdManagedTool);
+function isGsdManagedTool(name) {
+    return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
+}
+export function buildMinimalGsdToolSet(activeToolNames) {
+    const active = new Set(activeToolNames);
+    const preserved = activeToolNames.filter((name) => !isGsdManagedTool(name));
+    const minimal = MINIMAL_GSD_TOOL_NAMES.filter((name) => active.has(name));
+    return [...new Set([...preserved, ...minimal])];
+}
+export function buildMinimalAutoGsdToolSet(activeToolNames, unitType) {
+    const active = new Set(activeToolNames);
+    const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
+    const autoBaseTools = new Set(MINIMAL_AUTO_BASE_TOOL_NAMES);
+    const preserved = activeToolNames.filter((name) => autoBaseTools.has(name));
+    const scoped = [...MINIMAL_GSD_TOOL_NAMES, ...unitTools].filter((name) => active.has(name));
+    return [...new Set([...preserved, ...scoped])];
+}
+export function buildMinimalGsdWorkflowToolSet(activeToolNames) {
+    const active = new Set(activeToolNames);
+    const autoBaseTools = new Set(MINIMAL_AUTO_BASE_TOOL_NAMES);
+    const preserved = activeToolNames.filter((name) => autoBaseTools.has(name));
+    const scoped = WORKFLOW_GSD_TOOL_NAMES.filter((name) => active.has(name));
+    return [...new Set([...preserved, ...scoped])];
+}
+export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages) {
+    for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
+        const currentCustomType = requestCustomMessages?.[index]?.customType;
+        if (currentCustomType === "gsd-run" ||
+            currentCustomType === "gsd-discuss" ||
+            currentCustomType === "gsd-doctor-heal" ||
+            currentCustomType === "gsd-triage") {
+            return buildMinimalGsdWorkflowToolSet(activeToolNames);
+        }
+    }
+    return undefined;
+}
+export function isFullGsdToolSurfaceRequested() {
+    return process.env.PI_GSD_FULL_TOOLS === "1";
+}
+function isGeneralGsdToolScopingRequested() {
+    return process.env.PI_GSD_MINIMAL_TOOLS === "1";
+}
+function applyMinimalGsdToolSurface(pi) {
+    if (isFullGsdToolSurfaceRequested())
+        return;
+    const dash = getAutoRuntimeSnapshot();
+    if (dash.active && dash.currentUnit) {
+        pi.setActiveTools(buildMinimalAutoGsdToolSet(pi.getActiveTools(), dash.currentUnit.type));
+        return;
+    }
+    if (!isGeneralGsdToolScopingRequested())
+        return;
+    pi.setActiveTools(buildMinimalGsdToolSet(pi.getActiveTools()));
+}
+export function scopeGsdWorkflowToolsForDispatch(pi, unitType) {
+    if (isFullGsdToolSurfaceRequested())
+        return null;
+    const current = pi.getActiveTools();
+    const scoped = unitType
+        ? buildMinimalAutoGsdToolSet(current, unitType)
+        : buildMinimalGsdWorkflowToolSet(current);
+    const toolsChanged = !(scoped.length === current.length && scoped.every((name, index) => name === current[index]));
+    const skillManifest = resolveSkillManifest(unitType);
+    const canScopeSkills = skillManifest !== null && pi.getVisibleSkills && pi.setVisibleSkills;
+    if (!toolsChanged && !canScopeSkills) {
+        return null;
+    }
+    if (toolsChanged) {
+        pi.setActiveTools(scoped);
+    }
+    const visibleSkills = canScopeSkills ? pi.getVisibleSkills() : undefined;
+    if (canScopeSkills) {
+        pi.setVisibleSkills(skillManifest);
+    }
+    return {
+        tools: toolsChanged ? current : null,
+        visibleSkills,
+        restoreVisibleSkills: Boolean(canScopeSkills),
+    };
+}
+export function restoreGsdWorkflowTools(pi, savedState) {
+    if (!savedState)
+        return;
+    if (savedState.tools)
+        pi.setActiveTools(savedState.tools);
+    if (savedState.restoreVisibleSkills && pi.setVisibleSkills) {
+        pi.setVisibleSkills(savedState.visibleSkills);
+    }
+}
 async function deriveGsdState(basePath) {
     const { deriveState } = await import("../state.js");
     return deriveState(basePath);
@@ -71,11 +212,51 @@ async function applyCompactionThresholdOverride(ctx) {
         // Non-fatal: leave any existing override in place.
     }
 }
-export function resolveNotificationStoreBasePath(cwd = process.cwd()) {
-    return resolveWorktreeProjectRoot(cwd);
+function clearDeferredApprovalGate(basePath) {
+    if (!basePath || deferredApprovalGate?.basePath === basePath) {
+        deferredApprovalGate = null;
+    }
+}
+function deferApprovalGate(gateId, basePath) {
+    deferredApprovalGate = { gateId, basePath };
+}
+function contextBasePath(ctx) {
+    return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
+}
+function activateDeferredApprovalGate(basePath) {
+    if (deferredApprovalGate?.basePath !== basePath)
+        return;
+    setPendingGate(deferredApprovalGate.gateId, basePath);
+    deferredApprovalGate = null;
+}
+function isContextDraftSummarySave(toolName, input) {
+    if (toolName !== "gsd_summary_save" && toolName !== "summary_save")
+        return false;
+    if (!input || typeof input !== "object")
+        return false;
+    return input.artifact_type === "CONTEXT-DRAFT";
+}
+function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
+    if (deferredApprovalGate?.basePath !== basePath)
+        return { block: false };
+    if (toolName === "ask_user_questions")
+        return { block: false };
+    if (isContextDraftSummarySave(toolName, input))
+        return { block: false };
+    return {
+        block: true,
+        reason: [
+            `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" has been shown to the user.`,
+            `Only CONTEXT-DRAFT persistence may finish in this same assistant turn.`,
+            `Wait for the user's answer before calling additional tools.`,
+        ].join(" "),
+    };
+}
+export function resolveNotificationStoreBasePath(basePath) {
+    return resolveWorktreeProjectRoot(basePath);
 }
 function initSessionNotifications(ctx) {
-    initNotificationStore(resolveNotificationStoreBasePath());
+    initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
     installNotifyInterceptor(ctx);
     initNotificationWidget(ctx);
 }
@@ -109,28 +290,30 @@ async function writeContextModeCompactionSnapshot(basePath) {
 }
 export function registerHooks(pi, ecosystemHandlers) {
     pi.on("session_start", async (_event, ctx) => {
+        const basePath = contextBasePath(ctx);
         initSessionNotifications(ctx);
         if (!isAutoActive()) {
             const { initHealthWidget } = await import("../health-widget.js");
             initHealthWidget(ctx);
         }
-        resetWriteGateState(process.cwd());
+        resetWriteGateState(basePath);
         resetToolCallLoopGuard();
         approvalQuestionAbortInFlight = false;
+        clearDeferredApprovalGate();
         await resetAskUserQuestionsTurnCache();
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);
         // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
         const { isInAutoWorktree } = await import("../auto-worktree.js");
-        if (!isInAutoWorktree(process.cwd())) {
+        if (!isInAutoWorktree(basePath)) {
             const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-            prepareWorkflowMcpForProject(ctx, process.cwd());
+            prepareWorkflowMcpForProject(ctx, basePath);
         }
         // Apply show_token_cost preference (#1515)
         try {
             const { loadEffectiveGSDPreferences } = await import("../preferences.js");
-            const prefs = loadEffectiveGSDPreferences();
+            const prefs = loadEffectiveGSDPreferences(basePath);
             process.env.GSD_SHOW_TOKEN_COST = prefs?.preferences.show_token_cost ? "1" : "";
         }
         catch { /* non-fatal */ }
@@ -162,11 +345,13 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("session_switch", async (_event, ctx) => {
+        const basePath = contextBasePath(ctx);
         initSessionNotifications(ctx);
-        resetWriteGateState(process.cwd());
+        resetWriteGateState(basePath);
         resetToolCallLoopGuard();
+        clearDeferredApprovalGate();
         await resetAskUserQuestionsTurnCache();
-        clearDiscussionFlowState(process.cwd());
+        clearDiscussionFlowState(basePath);
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);
@@ -175,9 +360,9 @@ export function registerHooks(pi, ecosystemHandlers) {
         // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
         // CLI path resolution), dirtying the tree and breaking the milestone merge.
         const { isInAutoWorktree } = await import("../auto-worktree.js");
-        if (!isInAutoWorktree(process.cwd())) {
+        if (!isInAutoWorktree(basePath)) {
             const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-            prepareWorkflowMcpForProject(ctx, process.cwd());
+            prepareWorkflowMcpForProject(ctx, basePath);
         }
         await loadToolApiKeysForSession();
         if (!isAutoActive()) {
@@ -189,10 +374,11 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
+        applyMinimalGsdToolSurface(pi);
         // Wait for ecosystem loader to finish (no-op after first turn).
         const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
         await getEcosystemReadyPromise();
-        const beforeAgentBasePath = process.cwd();
+        const beforeAgentBasePath = contextBasePath(ctx);
         const pendingApprovalGate = getPendingGate(beforeAgentBasePath);
         if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
             markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
@@ -201,13 +387,14 @@ export function registerHooks(pi, ecosystemHandlers) {
                 markDepthVerified(milestoneId, beforeAgentBasePath);
             clearPendingGate(beforeAgentBasePath);
         }
+        clearDeferredApprovalGate(beforeAgentBasePath);
         // GSD's own context injection (existing behavior — unchanged).
         const { buildBeforeAgentStartResult } = await import("./system-context.js");
         const gsdResult = await buildBeforeAgentStartResult(event, ctx);
         // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
         // deriveState has its own ~100ms cache so this is cheap on repeat calls.
         try {
-            const state = await deriveGsdState(process.cwd());
+            const state = await deriveGsdState(beforeAgentBasePath);
             updateSnapshot(state);
         }
         catch {
@@ -244,7 +431,12 @@ export function registerHooks(pi, ecosystemHandlers) {
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();
         const { handleAgentEnd } = await import("./agent-end-recovery.js");
-        await handleAgentEnd(pi, event, ctx);
+        try {
+            await handleAgentEnd(pi, event, ctx);
+        }
+        finally {
+            activateDeferredApprovalGate(contextBasePath(ctx));
+        }
     });
     // Squash-merge quick-task branch back to the original branch after the
     // agent turn completes (#2668). cleanupQuickBranch is a no-op when no
@@ -258,8 +450,8 @@ export function registerHooks(pi, ecosystemHandlers) {
             // Best-effort: don't break the turn lifecycle if cleanup fails.
         }
     });
-    pi.on("session_before_compact", async () => {
-        const basePath = process.cwd();
+    pi.on("session_before_compact", async (_event, ctx) => {
+        const basePath = contextBasePath(ctx);
         // Context Mode is default-on. Write the resumable snapshot before any
         // active-auto cancel return so auto sessions still leave re-entry context.
         await writeContextModeCompactionSnapshot(basePath);
@@ -323,7 +515,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (!unitType) {
             try {
                 const { getPendingDeepProjectSetupUnitForContext } = await import("../guided-flow.js");
-                const pending = getPendingDeepProjectSetupUnitForContext(ctx, process.cwd());
+                const pending = getPendingDeepProjectSetupUnitForContext(ctx, contextBasePath(ctx));
                 unitType = pending?.unitType;
                 unitId = pending?.unitId;
             }
@@ -332,7 +524,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         if (!unitType) {
-            const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+            const milestoneId = await getDiscussionMilestoneIdFor(contextBasePath(ctx));
             if (milestoneId) {
                 unitType = "discuss-milestone";
                 unitId = milestoneId;
@@ -342,11 +534,12 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         const gateId = approvalGateIdForUnit(unitType, unitId);
         if (gateId)
-            setPendingGate(gateId, process.cwd());
+            deferApprovalGate(gateId, contextBasePath(ctx));
         approvalQuestionAbortInFlight = true;
         ctx.ui.notify(`${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
-        // The pending gate set above blocks subsequent non-read-only tool calls
-        // via the tool_call hook below, so we do not abort the in-flight stream.
+        // The durable pending gate is activated at agent_end so same-turn
+        // CONTEXT-DRAFT persistence can finish after the text boundary streams.
+        // The tool_call hook below still blocks non-draft tools in this turn.
         // Aborting mid-stream eats the model's question text on external CLI
         // providers (Claude Code SDK) because lastTextContent isn't populated
         // from in-flight builder state — the user only ever sees "Claude Code
@@ -356,7 +549,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
         if (isParallelActive()) {
             try {
-                await shutdownParallel(process.cwd());
+                await shutdownParallel(contextBasePath(ctx));
             }
             catch {
                 // best-effort
@@ -369,14 +562,17 @@ export function registerHooks(pi, ecosystemHandlers) {
             saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
         }
     });
-    pi.on("tool_call", async (event) => {
-        const discussionBasePath = process.cwd();
+    pi.on("tool_call", async (event, ctx) => {
+        const discussionBasePath = contextBasePath(ctx);
         const toolName = canonicalToolName(event.toolName);
         // ── Loop guard: block repeated identical tool calls ──
         const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
             return { block: true, reason: loopCheck.reason };
         }
+        const deferredGateGuard = shouldBlockDeferredApprovalTool(toolName, event.input, discussionBasePath);
+        if (deferredGateGuard.block)
+            return deferredGateGuard;
         // ── Discussion gate enforcement: track pending gate questions ─────────
         // Only gate-shaped ask_user_questions calls should block execution.
         // The gate stays pending until the user selects the approval option.
@@ -515,7 +711,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
     });
-    pi.on("tool_result", async (event) => {
+    pi.on("tool_result", async (event, ctx) => {
         if (isAutoActive() && typeof event.toolCallId === "string") {
             markToolEnd(event.toolCallId);
         }
@@ -535,7 +731,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         const toolName = canonicalToolName(event.toolName);
         if (toolName !== "ask_user_questions")
             return;
-        const basePath = process.cwd();
+        const basePath = contextBasePath(ctx);
         const milestoneId = await getDiscussionMilestoneIdFor(basePath);
         const queueActive = isQueuePhaseActive(basePath);
         const details = event.details;
@@ -737,8 +933,22 @@ export function registerHooks(pi, ecosystemHandlers) {
     // Tool set adaptation hook (ADR-005 Phase 4)
     // Extensions can override tool set after model selection by returning { toolNames: [...] }
     // Return undefined to let the built-in provider compatibility filtering proceed.
-    pi.on("adjust_tool_set", async (_event) => {
-        // Default: no override — let provider capability filtering handle tool set
+    pi.on("adjust_tool_set", async (event) => {
+        if (isFullGsdToolSurfaceRequested())
+            return undefined;
+        const removed = new Set(event.filteredTools);
+        const providerCompatible = event.activeToolNames.filter((name) => !removed.has(name));
+        const requestScoped = buildRequestScopedGsdToolSet(providerCompatible, event.requestCustomMessages);
+        if (requestScoped) {
+            return { toolNames: requestScoped };
+        }
+        const dash = getAutoRuntimeSnapshot();
+        if (dash.active && dash.currentUnit) {
+            return { toolNames: buildMinimalAutoGsdToolSet(providerCompatible, dash.currentUnit.type) };
+        }
+        if (isGeneralGsdToolScopingRequested()) {
+            return { toolNames: buildMinimalGsdToolSet(providerCompatible) };
+        }
         return undefined;
     });
 }

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: System prompt and hidden context bootstrap for GSD sessions.
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { logWarning } from "../workflow-logger.js";
@@ -17,6 +19,11 @@ import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile,
 import { toPosixPath } from "../../shared/mod.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
 import { gsdHome } from "../gsd-home.js";
+const DEFAULT_CONTEXT_MESSAGE_MAX_CHARS = 4_000;
+const DEFAULT_KNOWLEDGE_MAX_CHARS = 12_000;
+const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
+const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
+const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -135,7 +142,6 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
-    const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -165,11 +171,10 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
-                const MAX_CODEBASE_CHARS = 8_000;
                 const generatedMatch = rawContent.match(/Generated: (\S+)/);
                 const generatedAt = generatedMatch?.[1] ?? "unknown";
-                const content = rawContent.length > MAX_CODEBASE_CHARS
-                    ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
+                const content = rawContent.length > DEFAULT_CODEBASE_MAX_CHARS
+                    ? rawContent.slice(0, DEFAULT_CODEBASE_MAX_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
                 codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
@@ -180,6 +185,9 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     }
     warnDeprecatedAgentInstructions();
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
+    const memoryBlock = await loadMemoryBlock(event.prompt ?? "", {
+        includePromptRelevant: !(injection && isLowEntropyResumePrompt(event.prompt ?? "")),
+    });
     // Re-inject forensics context on follow-up turns (#2941)
     const forensicsInjection = !injection ? buildForensicsContextInjection(process.cwd(), event.prompt) : null;
     const worktreeBlock = buildWorktreeContextBlock();
@@ -188,12 +196,9 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         ? `\n\n## Subagent Model\n\nWhen spawning subagents via the \`subagent\` tool, always pass \`model: "${subagentModelConfig.primary}"\` in the tool call parameters. Never omit this — always specify it explicitly.`
         : "";
     // memoryBlock is FTS-queried against the user prompt and changes per call.
-    // Removing it from `fullSystem` keeps the system-prompt cache breakpoint
-    // stable across calls — the only scoped goal of this fix. The pi-ai
-    // Anthropic adapter additionally cache-marks the last user turn, so the
-    // memoryBlock injected via the context message may itself be cached up to
-    // that boundary; that's orthogonal and unchanged from prior behavior. The
-    // load-bearing win here is preserving the system+tools cache hit. (#5019)
+    // Keeping it out of `fullSystem` preserves provider prompt-cache stability
+    // for the static system/tool prefix. The dynamic memory block rides the
+    // volatile context message instead. (#5019)
     const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
     stopContextTimer({
         systemPromptSize: fullSystem.length,
@@ -217,20 +222,49 @@ export async function buildBeforeAgentStartResult(event, ctx) {
  * filesystem and DB dependencies to exercise this routing logic in-place.
  */
 export function buildContextMessage(opts) {
-    const memoryContent = opts.memoryBlock.trim();
+    const contextCharLimit = getContextMessageCharLimit();
+    const memoryContent = markMemoryContextSupplied(opts.memoryBlock.trim());
     if (opts.injection) {
-        const content = memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection;
+        const content = limitContextMessageContent(memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection, contextCharLimit);
         return { customType: "gsd-guided-context", content, display: false };
     }
     if (opts.forensicsInjection) {
-        const content = memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection;
+        const content = limitContextMessageContent(memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection, contextCharLimit);
         return { customType: "gsd-forensics", content, display: false };
     }
     if (memoryContent) {
-        return { customType: "gsd-memory", content: memoryContent, display: false };
+        return {
+            customType: "gsd-memory",
+            content: limitContextMessageContent(memoryContent, contextCharLimit),
+            display: false,
+        };
     }
     return null;
 }
+function getContextMessageCharLimit() {
+    const raw = process.env.PI_GSD_CONTEXT_MAX_CHARS;
+    if (!raw)
+        return DEFAULT_CONTEXT_MESSAGE_MAX_CHARS;
+    if (raw === "0")
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < MIN_CONTEXT_MESSAGE_MAX_CHARS) {
+        return DEFAULT_CONTEXT_MESSAGE_MAX_CHARS;
+    }
+    return Math.floor(parsed);
+}
+function limitContextMessageContent(content, limit) {
+    if (!limit || content.length <= limit)
+        return content;
+    const suffix = "\n\n[GSD Context Truncated]\nFull context is available from the referenced .gsd files and tools; read on demand only if this excerpt lacks required evidence.";
+    const headBudget = Math.max(0, limit - suffix.length);
+    return `${content.slice(0, headBudget).trimEnd()}${suffix}`;
+}
+function markMemoryContextSupplied(memoryContent) {
+    if (!memoryContent)
+        return "";
+    return `[GSD Context Metadata]\n- Memory supplied: yes\n\n${memoryContent}`;
+}
 /**
  * ADR-013 step 4 — auto-injection parity for the memories table.
  *
@@ -249,7 +283,7 @@ export function buildContextMessage(opts) {
  * with a token-budget cap. Failures degrade gracefully — the function never
  * throws and returns "" so the system prompt construction continues.
  */
-export async function loadMemoryBlock(userPrompt) {
+export async function loadMemoryBlock(userPrompt, opts = {}) {
     try {
         const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
         // Categories that belong in every turn. Pre-ADR-013 this was just
@@ -268,7 +302,7 @@ export async function loadMemoryBlock(userPrompt) {
         const criticalIds = new Set(critical.map((m) => m.id));
         let relevant = [];
         const trimmed = userPrompt.trim();
-        if (trimmed) {
+        if (trimmed && opts.includePromptRelevant !== false) {
             const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
             relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
         }
@@ -319,15 +353,37 @@ export function loadKnowledgeBlock(gsdHomeDir, cwd) {
         return { block: "", globalSizeKb: 0 };
     }
     const parts = [];
-    if (globalKnowledge)
-        parts.push(`## Global Knowledge\n\n${globalKnowledge}`);
-    if (projectKnowledge)
-        parts.push(`## Project Knowledge\n\n${projectKnowledge}`);
+    if (globalKnowledge) {
+        parts.push(`## Global Knowledge\nSource: \`${globalKnowledgePath}\`\n\n${globalKnowledge}`);
+    }
+    if (projectKnowledge) {
+        parts.push(`## Project Knowledge\nSource: \`${knowledgePath}\`\n\n${projectKnowledge}`);
+    }
+    const body = limitKnowledgeBlock(parts.join("\n\n"), getKnowledgeCharLimit());
     return {
-        block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${parts.join("\n\n")}`,
+        block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${body}`,
         globalSizeKb,
     };
 }
+function getKnowledgeCharLimit() {
+    const raw = process.env.PI_GSD_KNOWLEDGE_MAX_CHARS;
+    if (!raw)
+        return DEFAULT_KNOWLEDGE_MAX_CHARS;
+    if (raw === "0")
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < MIN_KNOWLEDGE_MAX_CHARS) {
+        return DEFAULT_KNOWLEDGE_MAX_CHARS;
+    }
+    return Math.floor(parsed);
+}
+function limitKnowledgeBlock(content, limit) {
+    if (!limit || content.length <= limit)
+        return content;
+    const suffix = "\n\n[Knowledge Truncated]\nFull KNOWLEDGE.md content remains available at the source path(s) above; read on demand only if this excerpt lacks a required rule.";
+    const headBudget = Math.max(0, limit - suffix.length);
+    return `${content.slice(0, headBudget).trimEnd()}${suffix}`;
+}
 function buildWorktreeContextBlock() {
     const worktreeName = getActiveWorktreeName();
     const worktreeMainCwd = getWorktreeOriginalCwd();
@@ -376,6 +432,10 @@ function buildWorktreeContextBlock() {
  * Tested against the trimmed, lowercased prompt with trailing punctuation stripped.
  */
 const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/;
+export function isLowEntropyResumePrompt(prompt) {
+    const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+    return RESUME_INTENT_PATTERNS.test(trimmed);
+}
 async function buildGuidedExecuteContextInjection(prompt, basePath) {
     const ensureStateDbOpen = async () => {
         const { ensureDbOpen } = await import("./dynamic-tools.js");
@@ -402,8 +462,7 @@ async function buildGuidedExecuteContextInjection(prompt, basePath) {
     // control/help/diagnostic prompts with unrelated execution context.
     // Phase-gated: only fire during "executing" to avoid misrouting during
     // replanning, gate evaluation, or other non-execution phases.
-    const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
-    if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+    if (isLowEntropyResumePrompt(prompt)) {
         await ensureStateDbOpen();
         const state = await deriveState(basePath);
         if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {