pi-context 1.1.0 → 1.1.2

package/dist/index.js

@@ -0,0 +1,370 @@
+import { Type } from "@sinclair/typebox";
+import { formatTokens } from "./utils.js";
+const InternalTools = ["context_tag", "context_log", "context_checkout"];
+let CommandCtx = null;
+let CheckoutParams = null;
+const isInternal = (name) => InternalTools.includes(name);
+const resolveTargetId = (sm, target) => {
+    if (target.toLowerCase() === "root") {
+        const tree = sm.getTree();
+        return tree.length > 0 ? tree[0].entry.id : target;
+    }
+    // If it already looks like an ID, keep it.
+    if (/^[0-9a-f]{8,}$/i.test(target))
+        return target;
+    // Iterative DFS to avoid call stack overflows on deep histories.
+    const stack = [...sm.getTree()];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (sm.getLabel(n.entry.id) === target)
+            return n.entry.id;
+        if (n.children?.length)
+            stack.push(...n.children);
+    }
+    // Fallback: let SessionManager deal with invalid targets downstream.
+    return target;
+};
+const ContextLogParams = Type.Object({
+    limit: Type.Optional(Type.Number({ description: "History limit for visible entries (default: 50)." })),
+    verbose: Type.Optional(Type.Boolean({ description: "If true, show ALL messages. If false (default), collapses intermediate AI steps and only shows 'milestones': User messages, Tags, Branch Points, and Summaries." })),
+});
+const ContextCheckoutParams = Type.Object({
+    target: Type.String({ description: "Where to jump/squash to. Can be a tag name (e.g., 'task-start'), a commit ID, or 'root'. This is the base for your new branch." }),
+    message: Type.String({ description: "The 'Carryover Message' for the new branch. A summary of your *current* progress/lessons that you want to bring with you to the new state. This ensures you don't lose key information when switching contexts. Good summary message: '[Status] + [Reason] + [Important Changes] + [Carryover Data]'" }),
+    backupTag: Type.Optional(Type.String({ description: "Optional tag name to apply to the CURRENT state before checking out. Use this to create an automatic backup of the history you are about to leave/squash." })),
+});
+const ContextTagParams = Type.Object({
+    name: Type.String({ description: "The tag/milestone name. Use meaningful names." }),
+    target: Type.Optional(Type.String({ description: "The commit ID to tag. Defaults to HEAD (current state)." })),
+});
+export default function (pi) {
+    pi.registerCommand("acm", {
+        description: "Enable agentic context management for the current session",
+        handler: async (args, ctx) => {
+            CommandCtx = ctx;
+            ctx.ui.notify("Agentic Context Management enabled.", "info");
+            pi.sendMessage({
+                customType: "pi-context",
+                content: "use context-management skill",
+                display: false,
+            }, {
+                deliverAs: "followUp"
+            });
+            if (args) {
+                pi.sendUserMessage(args);
+            }
+        }
+    });
+    // Helper: Check if a tag name already exists in the tree
+    const findTagInTree = (sm, nodes, tagName) => {
+        for (const n of nodes) {
+            if (sm.getLabel(n.entry.id) === tagName)
+                return n.entry.id;
+            const r = findTagInTree(sm, n.children, tagName);
+            if (r)
+                return r;
+        }
+        return null;
+    };
+    pi.registerTool({
+        name: "context_tag",
+        label: "Context Tag",
+        description: "Creates a 'Save Point' (Bookmark) in the history. Use this before trying risky changes or when a feature is stable. 'Untagged progress is risky'.",
+        parameters: ContextTagParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const sm = ctx.sessionManager;
+            // Deduplication check: ensure tag name is unique
+            const existingTagId = findTagInTree(sm, sm.getTree(), params.name);
+            if (existingTagId) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: Tag '${params.name}' already exists at ${existingTagId}. Tag names must be unique. Use a different name or delete the existing tag first.`
+                        }],
+                    details: {}
+                };
+            }
+            let id = params.target ? resolveTargetId(sm, params.target) : undefined;
+            if (!id) {
+                // Auto-resolve: Find the last "interesting" node to tag.
+                // We skip ToolResults (which look ugly tagged) and internal-only Assistant messages (which look empty).
+                const branch = sm.getBranch();
+                for (let i = branch.length - 1; i >= 0; i--) {
+                    const entry = branch[i];
+                    // 1. Check ToolResults
+                    if (entry.type === 'message' && entry.message.role === 'toolResult') {
+                        const tr = entry.message;
+                        if (isInternal(tr.toolName))
+                            continue;
+                        // Public tool result is a valid target
+                        id = entry.id;
+                        break;
+                    }
+                    // 2. Check Assistant messages for visibility
+                    if (entry.type === 'message' && entry.message.role === 'assistant') {
+                        const m = entry.message;
+                        const hasInternalTool = m.content.some(c => c.type === 'toolCall' && isInternal(c.name));
+                        if (!hasInternalTool) {
+                            id = entry.id;
+                            break;
+                        }
+                    }
+                    id = entry.id;
+                    break;
+                }
+                // Fallback to leaf if search failed
+                if (!id)
+                    id = sm.getLeafId() ?? "";
+            }
+            pi.setLabel(id, params.name);
+            return { content: [{ type: "text", text: `Created tag '${params.name}' at ${id}` }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "context_log",
+        label: "Context Log",
+        description: "Show the entire history structure (status, message, tags, milestones). Analogous to 'git log --graph --oneline --decorate'",
+        parameters: ContextLogParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const sm = ctx.sessionManager;
+            const branch = sm.getBranch();
+            const currentLeafId = sm.getLeafId();
+            const verbose = params.verbose ?? false;
+            const limit = params.limit ?? 50;
+            const backboneIds = new Set(branch.map((e) => e.id));
+            const sequence = [];
+            branch.forEach((entry) => {
+                sequence.push(entry);
+                // Preserve side-summary logic: Show branch summaries/compactions that are off-path
+                const children = sm.getChildren(entry.id);
+                children.forEach((child) => {
+                    if ((child.type === "branch_summary" || child.type === "compaction") && !backboneIds.has(child.id)) {
+                        sequence.push(child);
+                    }
+                });
+            });
+            const getMsgContent = (entry) => {
+                if (entry.type === "branch_summary" || entry.type === "compaction") {
+                    const e = entry;
+                    return e.summary || "[No summary provided]";
+                }
+                if (entry.type === "label") {
+                    return `tag: ${entry.label}`;
+                }
+                if (entry.type === "message") {
+                    const msg = entry.message;
+                    if (msg.role === "toolResult") {
+                        const tr = msg;
+                        if (!verbose && isInternal(tr.toolName))
+                            return "";
+                        const extractText = (content) => {
+                            return content
+                                .map((p) => (p.type === "text" ? p.text : ""))
+                                .join(" ")
+                                .trim();
+                        };
+                        let resText = extractText(tr.content);
+                        const details = tr.details;
+                        if ((tr.toolName === "read" || tr.toolName === "edit") && details && "path" in details && typeof details.path === "string") {
+                            resText = `${details.path}: ${resText}`;
+                        }
+                        return `(${tr.toolName}) ${resText}`;
+                    }
+                    if (msg.role === "bashExecution") {
+                        return `[Bash] ${msg.command}`;
+                    }
+                    if (msg.role === "user" || msg.role === "assistant") {
+                        let text = "";
+                        if (typeof msg.content === "string") {
+                            text = msg.content;
+                        }
+                        else if (Array.isArray(msg.content)) {
+                            text = msg.content
+                                .map((p) => {
+                                if (typeof p === "object" && p !== null && "text" in p)
+                                    return p.text;
+                                return "";
+                            })
+                                .join(" ")
+                                .trim();
+                        }
+                        let toolCallsText = "";
+                        if (msg.role === "assistant") {
+                            const toolCalls = msg.content.filter((c) => c.type === "toolCall");
+                            toolCallsText = toolCalls
+                                .filter((tc) => verbose || !isInternal(tc.name))
+                                .map((tc) => `call: ${tc.name}(${JSON.stringify(tc.arguments)})`)
+                                .join("; ");
+                        }
+                        return [text, toolCallsText].filter(Boolean).join(" ");
+                    }
+                }
+                return "";
+            };
+            const isInteresting = (entry) => {
+                // 1. HEAD and Root
+                if (entry.id === currentLeafId)
+                    return true;
+                if (branch.length > 0 && entry.id === branch[0].id)
+                    return true;
+                // 2. Explicit Tags (Labels) - Only show the TAGGED node, not the label node itself
+                if (sm.getLabel(entry.id))
+                    return true;
+                if (entry.type === 'label')
+                    return false; // Hide label nodes, they are redundant
+                // 3. Structural Milestones (Summaries)
+                if (entry.type === 'branch_summary' || entry.type === 'compaction')
+                    return true;
+                // 4. Branch Points (Forks)
+                if (sm.getChildren(entry.id).length > 1)
+                    return true;
+                // 5. Natural Milestones (User Messages) - This is the key auto-tagging mechanism
+                if (entry.type === 'message' && entry.message.role === 'user')
+                    return true;
+                return false;
+            };
+            const visibleSequenceIds = new Set();
+            sequence.forEach(e => {
+                if (verbose || isInteresting(e)) {
+                    visibleSequenceIds.add(e.id);
+                }
+            });
+            let visibleEntries = sequence.filter(e => visibleSequenceIds.has(e.id));
+            if (visibleEntries.length > limit) {
+                const allowedIds = new Set(visibleEntries.slice(-limit).map(e => e.id));
+                visibleSequenceIds.clear();
+                allowedIds.forEach(id => visibleSequenceIds.add(id));
+            }
+            const lines = [];
+            let hiddenCount = 0;
+            sequence.forEach((entry) => {
+                if (!visibleSequenceIds.has(entry.id)) {
+                    hiddenCount++;
+                    return;
+                }
+                if (hiddenCount > 0) {
+                    lines.push(`  :  ... (${hiddenCount} hidden messages) ...`);
+                    hiddenCount = 0;
+                }
+                const isHead = entry.id === currentLeafId;
+                const label = sm.getLabel(entry.id);
+                const content = getMsgContent(entry).replace(/\s+/g, " ");
+                let role = entry.type.toUpperCase();
+                if (entry.type === "message") {
+                    const m = entry.message;
+                    role =
+                        m.role === "assistant"
+                            ? "AI"
+                            : m.role === "user"
+                                ? "USER"
+                                : m.role === "bashExecution"
+                                    ? "BASH"
+                                    : "TOOL";
+                }
+                else if (entry.type === "branch_summary" || entry.type === "compaction") {
+                    role = "SUMMARY";
+                }
+                // hide custom messages
+                if (role === "CUSTOM_MESSAGE") {
+                    return;
+                }
+                const id = entry.id;
+                const isRoot = branch.length > 0 && entry.id === branch[0].id;
+                const meta = [isRoot ? "ROOT" : null, isHead ? "HEAD" : null, label ? `tag: ${label}` : null].filter(Boolean).join(", ");
+                const body = content.length > 100 ? content.slice(0, 100) + "..." : content;
+                const marker = isHead ? "*" : (role === "USER" ? "•" : "|");
+                lines.push(`${marker} ${id}${meta ? ` (${meta})` : ""} [${role}] ${body}`);
+            });
+            if (hiddenCount > 0) {
+                lines.push(`  :  ... (${hiddenCount} hidden messages) ...`);
+            }
+            // --- Context Dashboard (HUD) ---
+            const usage = await ctx.getContextUsage();
+            let usageStr = "Unknown";
+            if (usage) {
+                usageStr = `${usage.percent.toFixed(1)}% (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
+            }
+            // Find the distance to the nearest tag
+            let stepsSinceTag = 0;
+            let nearestTagName = "None";
+            for (let i = branch.length - 1; i >= 0; i--) {
+                const id = branch[i].id;
+                const label = sm.getLabel(id);
+                if (label) {
+                    nearestTagName = label;
+                    break;
+                }
+                stepsSinceTag++;
+            }
+            const hud = [
+                `[Context Dashboard]`,
+                `• Context Usage:    ${usageStr}`,
+                `• Segment Size:     ${stepsSinceTag} steps since last tag '${nearestTagName}'`,
+                `---------------------------------------------------`
+            ].join("\n");
+            return { content: [{ type: "text", text: hud + "\n" + (lines.join("\n") || "(Root Path Only)") }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "context_checkout",
+        label: "Context Checkout",
+        description: "Navigate to ANY point in the conversation history. This checkout only resets *conversation history*, NOT disk files. ALWAYS provide a detailed 'message' to bridge context.",
+        parameters: ContextCheckoutParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            if (!CommandCtx) {
+                ctx.ui.setEditorText(`/acm ${ctx.ui.getEditorText() || "continue"}`);
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Agentic context management is not enabled. Ask the user to run `/acm` in the pi to enable it, then retry."
+                        }],
+                    details: {}
+                };
+            }
+            const sm = ctx.sessionManager;
+            const tid = resolveTargetId(sm, params.target);
+            const currentLeaf = sm.getLeafId();
+            if (currentLeaf === tid) {
+                return { content: [{ type: "text", text: `Already at target ${tid}` }], details: {} };
+            }
+            if (params.backupTag && currentLeaf) {
+                pi.setLabel(currentLeaf, params.backupTag);
+            }
+            const currentLabel = currentLeaf ? sm.getLabel(currentLeaf) : undefined;
+            const origin = currentLabel ? `tag: ${currentLabel}` : (currentLeaf || "unknown");
+            const enrichedMessage = `(summary from ${origin})\n${params.message}`;
+            const nid = await sm.branchWithSummary(tid, enrichedMessage);
+            CheckoutParams = params;
+            CheckoutParams.nid = nid;
+            CheckoutParams.tid = tid;
+            CheckoutParams.enrichedMessage = enrichedMessage;
+            return { content: [{ type: "text", text: "checkout start" }], details: {} };
+        },
+    });
+    pi.on("turn_end", async (event, ctx) => {
+        if (!CheckoutParams) {
+            return;
+        }
+        ctx.abort();
+    });
+    pi.on("agent_end", async (_event, ctx) => {
+        if (!CheckoutParams) {
+            return;
+        }
+        if (!CommandCtx) {
+            return;
+        }
+        await CommandCtx.navigateTree(CheckoutParams.nid, {
+            summarize: false,
+        });
+        ctx.ui.notify(`Checked out ${CheckoutParams.target}${CheckoutParams.target === CheckoutParams.tid ? "" : `(${CheckoutParams.tid})`}\nBackup tag created: ${CheckoutParams.backupTag || "none"}\nmessage: ${CheckoutParams.enrichedMessage}`, "info");
+        CheckoutParams = null;
+        pi.sendMessage({
+            customType: "pi-context",
+            content: "context_checkout complete. A summary of your previous branch was injected above. Read it to understand your new state. Execute the 'Next Step' from the summary",
+            display: false,
+        }, {
+            triggerTurn: true,
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Agentic Context Management for the Pi",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/context-management/SKILL.md

@@ -111,6 +111,13 @@ If you fail 3 times:
 3.  Summarize the failure in the checkout message ("Tried X, failed because Y").
 4.  Try a new approach from the clean state.
 
+### After Checkout: Execute Next Step
+
+When `context_checkout` completes and injects a summary, you are in a **new context**.
+
+1. **READ** the injected summary carefully
+2. **EXECUTE** the `Next Step` from the summary - this is your new task.
+
 ## Decision Matrix: When to Act
 
 | Situation | Action | Reason |
@@ -132,24 +139,24 @@ If you cannot answer these, run `context_log`:
 | **Is this history useful?** | If "No" -> **SQUASH IT.** |
 | **Am I in a loop?** | Repeated entries in the graph. |
 
-
 ## Good Checkout Messages
 
 The `message` is your lifeline to your past self.
 A good message preserves critical context that would otherwise be lost.
 
-Structure: `[Key Finding/Status] + [Reason] + [Important Changes]`
+Structure: `[Key Finding/Status] + [Reason] + [Important Changes] + [Next Step]`
 
 *   **Key Finding/Status**: What did you discover or complete? Include specific numbers, errors, or outcomes.
 *   **Reason**: Why are you branching/moving? (e.g., "Task complete", "Approach failed", "Need raw logs")
 *   **Important Changes**: What files or logic have been modified? (This checkout only resets *conversation history*, NOT disk files, so you must remember what changed.)
+*   **Next Step**: What should you do immediately after this squash? Be specific. (e.g., "Wait for user feedback", "Implement the recommended fix", "Revert file X and try approach Y")
 
 Examples:
 
-*   *Good (Resetting after failure)*: "Recursive parser hit stack overflow at depth 8000. Switching to iterative. **Reason**: Stack limit reached. **Important Changes**: Modified `utils/recursion.ts`."
-*   *Good (Cleaning up)*: "Auth module complete: JWT + OAuth2 + RBAC. 23 tests passing. **Reason**: Task done, cleaning context. **Important Changes**: Created `auth/`, modified `routes.ts` and `middleware.ts`."
+*   *Good (Resetting after failure)*: "Recursive parser hit stack overflow at depth 8000. Switching to iterative. **Reason**: Stack limit reached. **Important Changes**: Modified `utils/recursion.ts`. **Next Step**: Inform user of the failure and propose iterative approach."
+*   *Good (Cleaning up)*: "Auth module complete: JWT + OAuth2 + RBAC. 23 tests passing. **Reason**: Task done, cleaning context. **Important Changes**: Created `auth/`, modified `routes.ts` and `middleware.ts`. **Next Step**: Report completion to user, ask if they want to review or test."
 *   *Bad*: "Switching context." (Too vague - you will forget why)
-*   *Bad*: "Done." (What is done? What did we learn?)
+*   *Bad*: "Done." (What is done? What should you do next?)
 
 ## Anti-Patterns
 
@@ -162,6 +169,7 @@ Examples:
 | **Blind Checkout** (Guessing IDs) | **Look** (`context_log`) first to get valid IDs. |
 | **Vague Summaries** ("Done", "Fixed") | **Detailed Summaries** ("Found bug in line 40. Fixed with patch X.") |
 | **Generic Tag Names** (`task-start`, `phase-1`) | **Semantic Names** (`auth-jwt-start`, `db-schema-plan`) |
+| **Missing Next Step** in checkout message | **Always specify** what to do after squash (e.g., "Wait for user", "Implement fix X") |
 
 ## Recipes (Copy-Paste)
 
@@ -180,7 +188,7 @@ context_tag({ name: "timeout-analysis-start" });
 // 2. Squash IMMEDIATELY. Do not wait for user.
 context_checkout({
   target: "timeout-analysis-start",
-  message: "Found DB connection pool exhaustion as root cause (pool size: 10, peak load: 1000 req/s). Recommended fix: increase to 50. **Reason**: Context cleanup after research. **Important Changes**: None (read-only).",
+  message: "Found DB connection pool exhaustion as root cause (pool size: 10, peak load: 1000 req/s). Recommended fix: increase to 50. **Reason**: Context cleanup after research. **Important Changes**: None (read-only). **Next Step**: Report findings to user and await approval to implement fix.",
   backupTag: "timeout-analysis-raw-history" // Safety backup
 });
 context_tag({ name: "timeout-analysis-done" });
@@ -197,7 +205,7 @@ context_tag({ name: "timeout-analysis-done" });
 // Squash to Summary (Optimistic Cleanup)
 context_checkout({
   target: "oauth-impl-start", // Squash range: Start -> Now
-  message: "OAuth2 flow implemented with PKCE, Google + GitHub providers. All 12 tests passing. **Reason**: Task complete, cleaning up. **Important Changes**: Created `auth/oauth.ts`, modified `routes.ts`, `config.ts`. Backup at 'oauth-impl-raw-history'.",
+  message: "OAuth2 flow implemented with PKCE, Google + GitHub providers. All 12 tests passing. **Reason**: Task complete, cleaning up. **Important Changes**: Created `auth/oauth.ts`, modified `routes.ts`, `config.ts`. **Next Step**: Report completion to user, summarize what was implemented.",
   backupTag: "oauth-impl-raw-history"
 });
 context_tag({ name: "oauth-impl-candidate" });
@@ -213,7 +221,7 @@ context_tag({ name: "oauth-impl-candidate" });
 // Jump back to the raw history
 context_checkout({
   target: "oauth-impl-raw-history",
-  message: "Reviewing token refresh logic - user reports 401 after 15 min idle. Suspect refresh token not firing. **Reason**: Need raw logs to trace the bug. **Important Changes**: None."
+  message: "Reviewing token refresh logic - user reports 401 after 15 min idle. Suspect refresh token not firing. **Reason**: Need raw logs to trace the bug. **Important Changes**: None. **Next Step**: Re-read token refresh implementation and identify the bug."
 });
 context_tag({ name: "oauth-review-start" });
 ```
@@ -228,7 +236,7 @@ context_tag({ name: "oauth-review-start" });
 // Method A (weak references) failed, trying Method B (object pooling)
 context_checkout({
   target: "memory-leak-fix-start", 
-  message: "WeakRef approach failed: objects GC'd within 30s (expected: 5min). Cache hit rate dropped from 95% to 12%. **Reason**: Switching to object pooling approach. **Important Changes**: `CacheManager.ts` modified (will revert)."
+  message: "WeakRef approach failed: objects GC'd within 30s (expected: 5min). Cache hit rate dropped from 95% to 12%. **Reason**: Switching to object pooling approach. **Important Changes**: `CacheManager.ts` modified (will revert). **Next Step**: Revert `CacheManager.ts` changes and implement object pooling strategy."
 });
 context_tag({ name: "memory-leak-pool-approach-start" });
 ```
@@ -243,7 +251,7 @@ You tried to fix a bug but broke everything.
 // Attempted mutex-based fix, but introduced deadlock
 context_checkout({
   target: "race-condition-fix-start",
-  message: "Mutex caused deadlock: Thread A holds mutex, awaits callback; callback needs mutex held by B; B waits for A. Circular wait detected. **Reason**: Trying lock-free CAS approach next. **Important Changes**: `AsyncQueue.ts` lines 70-90 modified (backup saved).",
+  message: "Mutex caused deadlock: Thread A holds mutex, awaits callback; callback needs mutex held by B; B waits for A. Circular wait detected. **Reason**: Trying lock-free CAS approach next. **Important Changes**: `AsyncQueue.ts` lines 70-90 modified (backup saved). **Next Step**: Revert `AsyncQueue.ts` and implement lock-free compare-and-swap approach.",
   backupTag: "race-condition-mutex-fail" // Save the failure for reference
 });
 context_tag({ name: "race-condition-lockfree-start" });

package/src/index.ts

@@ -30,17 +30,20 @@ const resolveTargetId = (sm: SessionManager, target: string): string => {
         const tree = sm.getTree();
         return tree.length > 0 ? tree[0].entry.id : target;
     }
+
+    // If it already looks like an ID, keep it.
     if (/^[0-9a-f]{8,}$/i.test(target)) return target;
-    const find = (nodes: SessionTreeNode[]): string | null => {
-        for (const n of nodes) {
-            if (sm.getLabel(n.entry.id) === target) return n.entry.id;
-            const r = find(n.children);
-            if (r) return r;
-        }
-        return null;
-    };
-    // sm.getTree() returns the SDK's SessionTreeNode[], which is structurally compatible
-    return find(sm.getTree()) || target;
+
+    // Iterative DFS to avoid call stack overflows on deep histories.
+    const stack: SessionTreeNode[] = [...(sm.getTree() as unknown as SessionTreeNode[])];
+    while (stack.length > 0) {
+        const n = stack.pop()!;
+        if (sm.getLabel(n.entry.id) === target) return n.entry.id;
+        if (n.children?.length) stack.push(...n.children);
+    }
+
+    // Fallback: let SessionManager deal with invalid targets downstream.
+    return target;
 };
 
 const ContextLogParams = Type.Object({
@@ -64,18 +67,30 @@ export default function (pi: ExtensionAPI) {
         description: "Enable agentic context management for the current session",
         handler: async (args, ctx) => {
             CommandCtx = ctx;
-            pi.setActiveTools(pi.getActiveTools().concat(InternalTools));
             ctx.ui.notify("Agentic Context Management enabled.", "info");
             pi.sendMessage({
                 customType: "pi-context",
-                content: "read context-management skill",
+                content: "use context-management skill",
                 display: false,
             }, {
                 deliverAs: "followUp"
             });
+            if (args) {
+                pi.sendUserMessage(args)
+            }
         }
     });
 
+    // Helper: Check if a tag name already exists in the tree
+    const findTagInTree = (sm: SessionManager, nodes: SessionTreeNode[], tagName: string): string | null => {
+        for (const n of nodes) {
+            if (sm.getLabel(n.entry.id) === tagName) return n.entry.id;
+            const r = findTagInTree(sm, n.children, tagName);
+            if (r) return r;
+        }
+        return null;
+    };
+
     pi.registerTool({
         name: "context_tag",
         label: "Context Tag",
@@ -83,6 +98,19 @@ export default function (pi: ExtensionAPI) {
         parameters: ContextTagParams,
         async execute(_id, params: Static<typeof ContextTagParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
+
+            // Deduplication check: ensure tag name is unique
+            const existingTagId = findTagInTree(sm, sm.getTree(), params.name);
+            if (existingTagId) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: `Error: Tag '${params.name}' already exists at ${existingTagId}. Tag names must be unique. Use a different name or delete the existing tag first.`
+                    }],
+                    details: {}
+                };
+            }
+
             let id = params.target ? resolveTargetId(sm, params.target) : undefined;
 
             if (!id) {
@@ -343,7 +371,14 @@ export default function (pi: ExtensionAPI) {
         parameters: ContextCheckoutParams,
         async execute(_id, params: Static<typeof ContextCheckoutParams>, _signal, _onUpdate, ctx) {
             if (!CommandCtx) {
-                return { content: [{ type: "text", text: "Command context not available, require /acm command first." }], details: {} };
+                ctx.ui.setEditorText(`/acm ${ctx.ui.getEditorText() || "continue"}`)
+                return {
+                    content: [{
+                        type: "text",
+                        text: "Agentic context management is not enabled. Ask the user to run `/acm` in the pi to enable it, then retry."
+                    }],
+                    details: {}
+                };
             }
             const sm = ctx.sessionManager as SessionManager;
 
@@ -395,15 +430,10 @@ export default function (pi: ExtensionAPI) {
 
         pi.sendMessage({
             customType: "pi-context",
-            content: "context_checkout done, continue",
+            content: "context_checkout complete. A summary of your previous branch was injected above. Read it to understand your new state. Execute the 'Next Step' from the summary",
             display: false,
         }, {
             triggerTurn: true,
         });
     });
-
-    pi.on("session_start", () => {
-        // hide tools by default
-        pi.setActiveTools(pi.getActiveTools().filter(n => !InternalTools.includes(n)));
-    });
 }