zenox 1.4.2 → 1.5.0

package/README.md

@@ -25,6 +25,7 @@ Zenox supercharges [OpenCode](https://opencode.ai) with specialized AI agents th
 - **Keyword Triggers** — `ultrawork`, `deep research`, `explore codebase`
 - **Session History** — Query past sessions to learn from previous work
 - **Code Intelligence** — Search symbols via LSP
+- **Project Guidelines Auto-Update** — Automatically keeps AGENTS.md and CLAUDE.md up-to-date
 - **Todo Continuation** — Auto-reminds when tasks are incomplete
 - **Auto-Updates** — Toast notification when new version available
 
@@ -165,6 +166,43 @@ Zenox automatically reminds you to continue working when:
 
 This keeps you on track without manual intervention. The agent will be prompted to continue until all todos are complete or blocked.
 
+## Project Guidelines Auto-Update
+
+Zenox automatically keeps your `AGENTS.md` and `CLAUDE.md` files up-to-date with important decisions, patterns, and conventions.
+
+### The Problem
+
+Developers forget to update documentation. Important decisions get lost. Team members repeat the same questions. Next session, the agent has no context.
+
+### The Solution
+
+Zenox detects important decisions and automatically documents them:
+
+```
+You: "In this project, always use Zustand for state management"
+→ Agent checks AGENTS.md — not documented yet
+→ Agent saves: "- State Management: Use Zustand, not Redux"
+→ Future sessions automatically know this
+```
+
+### What Gets Documented
+
+| Trigger | Example |
+|---------|---------|
+| User decision | "Always use Tailwind", "We use this API pattern" |
+| Architecture choice | Agent decides between approaches after analysis |
+| Reusable code | Agent creates a utility worth reusing |
+| Convention discovered | Agent notices consistent patterns in codebase |
+
+### How It Works
+
+1. Agent recognizes something important
+2. Reads `AGENTS.md` / `CLAUDE.md` to check if already documented
+3. If not there → calls `save_project_guideline` to add it
+4. Both files get updated (or `AGENTS.md` created if neither exists)
+
+**Zero manual work** — your project documentation stays current automatically.
+
 ## Configuration
 
 ### Custom Models

package/dist/background/index.d.ts

@@ -5,4 +5,4 @@
  */
 export { BackgroundManager } from "./manager";
 export { createBackgroundTools, type BackgroundTools } from "./tools";
-export type { BackgroundTask, TaskStatus, LaunchInput, CompletionNotification, } from "./types";
+export type { BackgroundTask, TaskStatus, LaunchInput, CompletionNotification, ParentModel, } from "./types";

package/dist/background/types.d.ts

@@ -3,6 +3,10 @@
  * Minimal interfaces for fire-and-forget parallel agent execution
  */
 export type TaskStatus = "running" | "completed" | "failed" | "cancelled";
+export interface ParentModel {
+    providerID: string;
+    modelID: string;
+}
 export interface BackgroundTask {
     id: string;
     sessionID: string;
@@ -14,6 +18,7 @@ export interface BackgroundTask {
     completedAt?: Date;
     error?: string;
     parentAgent?: string;
+    parentModel?: ParentModel;
 }
 export interface LaunchInput {
     agent: string;
@@ -21,6 +26,7 @@ export interface LaunchInput {
     description: string;
     parentSessionID: string;
     parentAgent?: string;
+    parentModel?: ParentModel;
 }
 export interface CompletionNotification {
     allComplete: boolean;
@@ -28,4 +34,5 @@ export interface CompletionNotification {
     completedTasks: BackgroundTask[];
     runningCount: number;
     parentAgent?: string;
+    parentModel?: ParentModel;
 }

package/dist/index.js

@@ -822,6 +822,51 @@ The system automatically reminds you if you go idle with incomplete tasks.
 - You have pending or in-progress todos
 - The session goes idle
 - There's been sufficient time since the last reminder
+
+---
+
+## Project Guidelines Auto-Documentation
+
+You have \`save_project_guideline\` to keep AGENTS.md and CLAUDE.md automatically updated.
+
+### When to Use
+
+| Trigger | Example |
+|---------|---------|
+| User states a decision | "Always use Zustand", "We use Tailwind here" |
+| You create reusable code | A utility function, hook, or pattern worth reusing |
+| Architecture decision made | After analyzing options and choosing an approach |
+| User corrects your approach | "No, do it this way instead" |
+| Convention discovered | You notice a consistent pattern in the codebase |
+
+### How to Use
+
+1. **Read first**: Check AGENTS.md and CLAUDE.md to see if the info already exists
+2. **If not there**: Call \`save_project_guideline({ content: "..." })\`
+3. **The tool**: Appends to both files (or creates AGENTS.md if neither exists)
+
+### Example
+
+\`\`\`
+// User says: "In this project, always use Zustand for state"
+// 1. Read AGENTS.md - check if Zustand is mentioned
+// 2. If not mentioned:
+save_project_guideline({ content: "- State Management: Use Zustand, not Redux" })
+\`\`\`
+
+### What to Document
+
+- Technology choices (frameworks, libraries, tools)
+- Code patterns (how to structure components, API calls, etc.)
+- Reusable utilities you create (hooks, helpers, formatters)
+- Conventions (naming, folder structure, coding style)
+- Important decisions that affect future work
+
+### What NOT to Document
+
+- One-off decisions ("use blue for this button")
+- Things obvious from the code itself
+- Temporary workarounds
 `;
 function getOrchestrationPrompt(agent) {
   switch (agent) {
@@ -835,18 +880,26 @@ function getOrchestrationPrompt(agent) {
 }
 
 // src/orchestration/session-agent-tracker.ts
-var sessionAgentMap = new Map;
-function setSessionAgent(sessionID, agent) {
-  if (agent) {
-    sessionAgentMap.set(sessionID, agent);
-  }
+var sessionContextMap = new Map;
+function setSessionContext(sessionID, context) {
+  const existing = sessionContextMap.get(sessionID) ?? {};
+  sessionContextMap.set(sessionID, {
+    agent: context.agent ?? existing.agent,
+    model: context.model ?? existing.model
+  });
+}
+function getSessionContext(sessionID) {
+  return sessionContextMap.get(sessionID);
 }
 function getSessionAgent(sessionID) {
-  return sessionAgentMap.get(sessionID);
+  return sessionContextMap.get(sessionID)?.agent;
+}
+function getSessionModel(sessionID) {
+  return sessionContextMap.get(sessionID)?.model;
 }
 function clearSessionAgent(sessionID) {
   if (sessionID) {
-    sessionAgentMap.delete(sessionID);
+    sessionContextMap.delete(sessionID);
   }
 }
 function getOrchestrationAgentType(agent) {
@@ -4995,7 +5048,8 @@ class BackgroundManager {
       prompt: input.prompt,
       status: "running",
       startedAt: new Date,
-      parentAgent: input.parentAgent
+      parentAgent: input.parentAgent,
+      parentModel: input.parentModel
     };
     this.tasks.set(task.id, task);
     if (this.toastManager) {
@@ -5134,12 +5188,14 @@ ${runningTasks.length} task(s) still running. Continue working.
 </system-reminder>`;
     }
     const parentAgent = completedTasks[0]?.parentAgent;
+    const parentModel = completedTasks[0]?.parentModel;
     return {
       allComplete,
       message,
       completedTasks,
       runningCount: runningTasks.length,
-      parentAgent
+      parentAgent,
+      parentModel
     };
   }
   listActiveTasks() {
@@ -17490,12 +17546,14 @@ Use for independent research tasks that benefit from parallelism.`,
     },
     async execute(args, context) {
       try {
+        const parentModel = getSessionModel(context.sessionID);
         const task = await manager.launch(client, {
           agent: args.agent,
           description: args.description,
           prompt: args.prompt,
           parentSessionID: context.sessionID,
-          parentAgent: context.agent
+          parentAgent: context.agent,
+          parentModel
         });
         const activeTasks = manager.listActiveTasks();
         return `Background task launched successfully.
@@ -17930,12 +17988,15 @@ Current incomplete tasks:
 ${todoList}
 
 ${statusLine}`;
-      const sendPrompt = async (omitAgent = false) => {
+      const sessionContext = getSessionContext(sessionID);
+      const model = sessionContext?.model;
+      const sendPrompt = async (omitContext = false) => {
         await ctx.client.session.prompt({
           path: { id: sessionID },
           body: {
             noReply: false,
-            ...omitAgent || !agent ? {} : { agent },
+            ...omitContext || !agent ? {} : { agent },
+            ...omitContext || !model ? {} : { model },
             parts: [{ type: "text", text: prompt }]
           }
         });
@@ -17944,7 +18005,7 @@ ${statusLine}`;
         await sendPrompt();
       } catch (err) {
         const errorMsg = err instanceof Error ? err.message : String(err);
-        if (errorMsg.includes("agent") || errorMsg.includes("undefined")) {
+        if (errorMsg.includes("agent") || errorMsg.includes("model") || errorMsg.includes("undefined")) {
           try {
             await sendPrompt(true);
           } catch {
@@ -18281,6 +18342,87 @@ Shows which LSP servers are running and their status.`,
     lsp_status: lspStatus
   };
 }
+// src/tools/project-guidelines/tools.ts
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+var GUIDELINE_FILES = ["AGENTS.md", "CLAUDE.md"];
+async function fileExists(filePath) {
+  try {
+    await fs2.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function appendToFile(filePath, content) {
+  const exists = await fileExists(filePath);
+  if (exists) {
+    const existing = await fs2.readFile(filePath, "utf-8");
+    const separator = existing.endsWith(`
+`) ? "" : `
+`;
+    await fs2.writeFile(filePath, existing + separator + content + `
+`);
+  } else {
+    await fs2.writeFile(filePath, content + `
+`);
+  }
+}
+function createProjectGuidelinesTools(projectDir) {
+  const saveProjectGuideline = tool({
+    description: `Save important project decisions, patterns, or conventions to AGENTS.md and CLAUDE.md.
+Use this to document:
+- Important decisions (technology choices, architecture decisions)
+- Reusable code patterns or utilities you created
+- Conventions discovered or agreed upon
+- Guidelines that should persist across sessions
+
+IMPORTANT: Before calling this tool, read AGENTS.md and CLAUDE.md first to check if the information already exists. Only call this tool if the guideline is NOT already documented.
+
+The tool appends to both files if they exist, or creates AGENTS.md if neither exists.`,
+    args: {
+      content: tool.schema.string().describe("The guideline, decision, or pattern to document")
+    },
+    async execute(args) {
+      try {
+        const content = args.content.trim();
+        if (!content) {
+          return "Error: Content cannot be empty";
+        }
+        const updatedFiles = [];
+        let createdFile = false;
+        const existingFiles = [];
+        for (const fileName of GUIDELINE_FILES) {
+          const filePath = path2.join(projectDir, fileName);
+          if (await fileExists(filePath)) {
+            existingFiles.push(fileName);
+          }
+        }
+        if (existingFiles.length === 0) {
+          const agentsPath = path2.join(projectDir, "AGENTS.md");
+          await appendToFile(agentsPath, content);
+          updatedFiles.push("AGENTS.md");
+          createdFile = true;
+        } else {
+          for (const fileName of existingFiles) {
+            const filePath = path2.join(projectDir, fileName);
+            await appendToFile(filePath, content);
+            updatedFiles.push(fileName);
+          }
+        }
+        const fileList = updatedFiles.join(" and ");
+        const action = createdFile ? "Created" : "Updated";
+        return `${action} ${fileList} with: "${content.substring(0, 100)}${content.length > 100 ? "..." : ""}"`;
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : "Unknown error";
+        return `Failed to save guideline: ${errorMsg}`;
+      }
+    }
+  });
+  return {
+    save_project_guideline: saveProjectGuideline
+  };
+}
 // src/shared/agent-variant.ts
 function resolveAgentVariant(config2, agentName) {
   if (!agentName)
@@ -18334,6 +18476,7 @@ var ZenoxPlugin = async (ctx) => {
   const todoEnforcerHook = createTodoEnforcerHook(ctx);
   const sessionTools = createSessionTools(ctx.client);
   const codeIntelligenceTools = createCodeIntelligenceTools(ctx.client);
+  const projectGuidelinesTools = createProjectGuidelinesTools(ctx.directory);
   const firstMessageVariantGate = createFirstMessageVariantGate();
   const applyModelOverride = (agentName, baseAgent) => {
     const override = pluginConfig.agents?.[agentName];
@@ -18346,10 +18489,11 @@ var ZenoxPlugin = async (ctx) => {
     tool: {
       ...backgroundTools,
       ...sessionTools,
-      ...codeIntelligenceTools
+      ...codeIntelligenceTools,
+      ...projectGuidelinesTools
     },
     "chat.message": async (input, output) => {
-      setSessionAgent(input.sessionID, input.agent);
+      setSessionContext(input.sessionID, { agent: input.agent, model: input.model });
       const message = output.message;
       if (firstMessageVariantGate.shouldOverride(input.sessionID)) {
         const variant = resolveAgentVariant(pluginConfig, input.agent);
@@ -18402,19 +18546,20 @@ var ZenoxPlugin = async (ctx) => {
         if (notification) {
           const mainSessionID = backgroundManager.getMainSession();
           if (mainSessionID) {
-            const sendNotification = async (omitAgent = false) => {
+            const sendNotification = async (omitContext = false) => {
               try {
                 await ctx.client.session.prompt({
                   path: { id: mainSessionID },
                   body: {
                     noReply: !notification.allComplete,
-                    ...omitAgent ? {} : { agent: notification.parentAgent },
+                    ...omitContext ? {} : { agent: notification.parentAgent },
+                    ...omitContext ? {} : { model: notification.parentModel },
                     parts: [{ type: "text", text: notification.message }]
                   }
                 });
               } catch (err) {
                 const errorMsg = err instanceof Error ? err.message : String(err);
-                if (!omitAgent && (errorMsg.includes("agent.name") || errorMsg.includes("undefined"))) {
+                if (!omitContext && (errorMsg.includes("agent") || errorMsg.includes("model") || errorMsg.includes("undefined"))) {
                   return sendNotification(true);
                 }
               }

package/dist/orchestration/prompt.d.ts

@@ -2,5 +2,5 @@
  * Orchestration prompt to inject into Build and Plan agents.
  * This teaches the primary agents how to delegate to specialized subagents using the Task tool.
  */
-export declare const ORCHESTRATION_PROMPT = "\n\n---\n\n## Sub-Agent Delegation\n\nYou have specialized subagents. Use the **Task tool** to delegate work proactively.\n\n### Available Agents\n\n| Agent | Use For | subagent_type |\n|-------|---------|---------------|\n| **Explorer** | Codebase grep - fast pattern matching, \"Where is X?\" | `explorer` |\n| **Librarian** | External grep - docs, GitHub, OSS examples | `librarian` |\n| **Oracle** | Strategic advisor - architecture, debugging, decisions | `oracle` |\n| **UI Planner** | Designer-developer - visual design, CSS, animations | `ui-planner` |\n\n### Quick Rule: Background vs Synchronous\n\n| Agent | Default Execution | Why |\n|-------|-------------------|-----|\n| Explorer | `background_task` | It's codebase grep - fire and continue |\n| Librarian | `background_task` | It's external grep - fire and continue |\n| Oracle | `Task` (sync) | Need strategic answer before proceeding |\n| UI Planner | `Task` (sync) | Implements changes, needs write access |\n\n**Mental Model**: Explorer & Librarian = **grep commands**. You don't wait for grep, you fire it and continue thinking.\n\n### When to Delegate (Fire Immediately)\n\n| Trigger | subagent_type | Why |\n|---------|---------------|-----|\n| \"Where is X?\", \"Find Y\", locate code | `explorer` | Fast codebase search |\n| External library, \"how does X library work?\" | `librarian` | Searches docs, GitHub, OSS |\n| 2+ modules involved, cross-cutting concerns | `explorer` | Multi-file pattern discovery |\n| Architecture decision, \"should I use X or Y?\" | `oracle` | Deep reasoning advisor |\n| Visual/styling, CSS, animations, UI/UX | `ui-planner` | Designer-developer hybrid |\n| After 2+ failed fix attempts | `oracle` | Debugging escalation |\n\n### How to Delegate\n\nUse the Task tool with these parameters:\n\n```\nTask(\n  subagent_type: \"explorer\" | \"librarian\" | \"oracle\" | \"ui-planner\",\n  description: \"Short 3-5 word task description\",\n  prompt: \"Detailed instructions for the agent\"\n)\n```\n\n**Example delegations:**\n\n```\n// Find code in codebase\nTask(\n  subagent_type: \"explorer\",\n  description: \"Find auth middleware\",\n  prompt: \"Find all authentication middleware implementations in this codebase. Return file paths and explain the auth flow.\"\n)\n\n// Research external library\nTask(\n  subagent_type: \"librarian\",\n  description: \"React Query caching docs\",\n  prompt: \"How does React Query handle caching? Find official documentation and real-world examples with GitHub permalinks.\"\n)\n\n// Architecture decision\nTask(\n  subagent_type: \"oracle\",\n  description: \"Redux vs Zustand analysis\",\n  prompt: \"Analyze trade-offs between Redux and Zustand for this project. Consider bundle size, learning curve, and our existing patterns.\"\n)\n\n// UI/Visual work\nTask(\n  subagent_type: \"ui-planner\",\n  description: \"Redesign dashboard cards\",\n  prompt: \"Redesign the dashboard stat cards to be more visually appealing. Use modern aesthetics, subtle animations, and ensure responsive design.\"\n)\n```\n\n### Parallel Execution\n\nTo run multiple agents in parallel, call multiple Task tools in the **same response message**:\n\n```\n// CORRECT: Multiple Task calls in ONE message = parallel execution\nTask(subagent_type: \"explorer\", description: \"Find auth code\", prompt: \"...\")\nTask(subagent_type: \"librarian\", description: \"JWT best practices\", prompt: \"...\")\n// Both run simultaneously\n\n// WRONG: One Task per message = sequential (slow)\nMessage 1: Task(...) \u2192 wait for result\nMessage 2: Task(...) \u2192 wait for result\n```\n\n### Delegation Priority\n\n1. **Explorer FIRST** \u2014 Always locate code before modifying unfamiliar areas\n2. **Librarian** \u2014 When dealing with external libraries/APIs you don't fully understand\n3. **Oracle** \u2014 For complex decisions or after 2+ failed fix attempts\n4. **UI Planner** \u2014 For ANY visual/styling work (never edit CSS/UI yourself)\n\n### Critical Rules\n\n1. **Never touch frontend visual/styling code yourself** \u2014 Always delegate to `ui-planner`\n2. **Fire librarian proactively** when unfamiliar libraries are involved\n3. **Consult oracle BEFORE major architectural decisions**, not after\n4. **Verify delegated work** before marking task complete\n\n### When to Handle Directly (Don't Delegate)\n\n- Single file edits with known location\n- Questions answerable from code already in context\n- Trivial changes requiring no specialist knowledge\n- Tasks you can complete faster than explaining to an agent\n\n---\n\n## Background Tasks (Parallel Research)\n\nFor **independent research tasks** that benefit from parallelism, use background tasks instead of sequential Task calls.\n\n### When to Use Background Tasks\n\n| Scenario | Use Background Tasks |\n|----------|---------------------|\n| User wants \"comprehensive\" / \"thorough\" / \"deep\" exploration | YES - fire 3-4 agents in parallel |\n| Need BOTH codebase search AND external docs | YES - explore + librarian in parallel |\n| Exploring multiple modules/features simultaneously | YES - separate explore for each |\n| Result of Task A needed before Task B | NO - use sequential Task |\n| Single focused lookup | NO - just use Task directly |\n\n### How Background Tasks Work\n\n1. **Fire**: Launch multiple agents with `background_task` - they run in parallel\n2. **Continue**: Keep working while background agents search\n3. **Notify**: You'll be notified when ALL background tasks complete\n4. **Retrieve**: Use `background_output` to get each result\n\n### Usage\n\n```\n// Launch parallel research (all run simultaneously)\nbackground_task(agent=\"explorer\", description=\"Find auth code\", prompt=\"Search for authentication...\")\nbackground_task(agent=\"explorer\", description=\"Find db layer\", prompt=\"Search for database/ORM...\")\nbackground_task(agent=\"librarian\", description=\"Best practices\", prompt=\"Find framework best practices...\")\n\n// Continue working on other things while they run...\n\n// [NOTIFICATION: All background tasks complete!]\n\n// Retrieve results\nbackground_output(task_id=\"bg_abc123\")\nbackground_output(task_id=\"bg_def456\")\nbackground_output(task_id=\"bg_ghi789\")\n```\n\n### Background Tasks vs Task Tool\n\n| Aspect | Task Tool | Background Tasks |\n|--------|-----------|------------------|\n| Execution | Sequential (waits for result) | Parallel (fire-and-forget) |\n| Best for | Dependent tasks, immediate needs | Independent research, breadth |\n| Result | Inline, immediate | Retrieved later via background_output |\n\n### Key Insight\n\n- **Task** = Use when you need the result immediately before proceeding\n- **Background** = Use when researching multiple angles independently\n\n**Both tools coexist - choose based on whether tasks are dependent or independent.**\n\n### The Parallel Research Pattern\n\nFor complex tasks, fire research first, then continue working:\n\n```\n// 1. FIRE parallel research (don't wait!)\nbackground_task(agent=\"explorer\", description=\"Find existing patterns\", prompt=\"...\")\nbackground_task(agent=\"librarian\", description=\"Find best practices\", prompt=\"...\")\n\n// 2. CONTINUE productive work while they run:\n//    - Plan your implementation approach\n//    - Read files you already know about\n//    - Identify edge cases and questions\n\n// 3. When notified \u2192 RETRIEVE and synthesize\nbackground_output(task_id=\"bg_xxx\")\nbackground_output(task_id=\"bg_yyy\")\n```\n\n**Anti-pattern**: Firing background tasks then doing nothing. Always continue productive work!\n\n---\n\n## Keyword Triggers (Power User)\n\nInclude these keywords in your prompt to unlock special modes:\n\n| Keyword | Effect |\n|---------|--------|\n| `ultrawork` or `ulw` | Maximum multi-agent coordination - aggressive parallel research |\n| `deep research` | Comprehensive exploration - fires 3-4 background agents |\n| `explore codebase` | Codebase mapping - multiple explorers in parallel |\n\n---\n\n## Session History Tools\n\nYou have tools to learn from past work sessions:\n\n| Tool | Use For |\n|------|---------|\n| `session_list` | List recent sessions to find relevant past work |\n| `session_search` | Search messages across sessions for how something was done |\n\n### When to Use Session Tools\n\n- **Before implementing unfamiliar features** \u2014 search if done before\n- **When user says \"like before\" or \"last time\"** \u2014 find that session\n- **When debugging** \u2014 check if similar issues were solved previously\n- **For context on ongoing projects** \u2014 understand recent work history\n\n### Example Usage\n\n```\n// Find how authentication was implemented before\nsession_search({ query: \"JWT authentication\" })\n\n// List recent sessions to understand project context\nsession_list({ limit: 5 })\n\n// Find past implementations of a feature\nsession_search({ query: \"rate limiting\" })\n```\n\n---\n\n## Code Intelligence Tools\n\nYou have tools to understand code structure via LSP:\n\n| Tool | Use For |\n|------|---------|\n| `find_symbols` | Search for functions, classes, variables by name |\n| `lsp_status` | Check which language servers are running |\n\n### When to Use Code Intelligence\n\n- **Before editing code** \u2014 find the symbol's definition location\n- **When refactoring** \u2014 search for related symbols\n- **To understand project structure** \u2014 search for key symbols like \"auth\", \"user\", \"api\"\n- **To verify LSP availability** \u2014 check if code intelligence is working\n\n### Example Usage\n\n```\n// Find all auth-related functions/classes\nfind_symbols({ query: \"auth\" })\n\n// Find a specific function\nfind_symbols({ query: \"handleLogin\" })\n\n// Check LSP server status\nlsp_status()\n```\n\n---\n\n## Todo Continuation\n\nThe system automatically reminds you if you go idle with incomplete tasks.\n\n**Best Practices:**\n- Keep your todo list updated with `TodoWrite`\n- Mark tasks complete immediately when finished\n- Use clear, actionable task descriptions\n- The system will prompt you to continue if tasks remain incomplete\n\n**Note:** You don't need to invoke the todo enforcer \u2014 it runs automatically when:\n- You have pending or in-progress todos\n- The session goes idle\n- There's been sufficient time since the last reminder\n";
+export declare const ORCHESTRATION_PROMPT = "\n\n---\n\n## Sub-Agent Delegation\n\nYou have specialized subagents. Use the **Task tool** to delegate work proactively.\n\n### Available Agents\n\n| Agent | Use For | subagent_type |\n|-------|---------|---------------|\n| **Explorer** | Codebase grep - fast pattern matching, \"Where is X?\" | `explorer` |\n| **Librarian** | External grep - docs, GitHub, OSS examples | `librarian` |\n| **Oracle** | Strategic advisor - architecture, debugging, decisions | `oracle` |\n| **UI Planner** | Designer-developer - visual design, CSS, animations | `ui-planner` |\n\n### Quick Rule: Background vs Synchronous\n\n| Agent | Default Execution | Why |\n|-------|-------------------|-----|\n| Explorer | `background_task` | It's codebase grep - fire and continue |\n| Librarian | `background_task` | It's external grep - fire and continue |\n| Oracle | `Task` (sync) | Need strategic answer before proceeding |\n| UI Planner | `Task` (sync) | Implements changes, needs write access |\n\n**Mental Model**: Explorer & Librarian = **grep commands**. You don't wait for grep, you fire it and continue thinking.\n\n### When to Delegate (Fire Immediately)\n\n| Trigger | subagent_type | Why |\n|---------|---------------|-----|\n| \"Where is X?\", \"Find Y\", locate code | `explorer` | Fast codebase search |\n| External library, \"how does X library work?\" | `librarian` | Searches docs, GitHub, OSS |\n| 2+ modules involved, cross-cutting concerns | `explorer` | Multi-file pattern discovery |\n| Architecture decision, \"should I use X or Y?\" | `oracle` | Deep reasoning advisor |\n| Visual/styling, CSS, animations, UI/UX | `ui-planner` | Designer-developer hybrid |\n| After 2+ failed fix attempts | `oracle` | Debugging escalation |\n\n### How to Delegate\n\nUse the Task tool with these parameters:\n\n```\nTask(\n  subagent_type: \"explorer\" | \"librarian\" | \"oracle\" | \"ui-planner\",\n  description: \"Short 3-5 word task description\",\n  prompt: \"Detailed instructions for the agent\"\n)\n```\n\n**Example delegations:**\n\n```\n// Find code in codebase\nTask(\n  subagent_type: \"explorer\",\n  description: \"Find auth middleware\",\n  prompt: \"Find all authentication middleware implementations in this codebase. Return file paths and explain the auth flow.\"\n)\n\n// Research external library\nTask(\n  subagent_type: \"librarian\",\n  description: \"React Query caching docs\",\n  prompt: \"How does React Query handle caching? Find official documentation and real-world examples with GitHub permalinks.\"\n)\n\n// Architecture decision\nTask(\n  subagent_type: \"oracle\",\n  description: \"Redux vs Zustand analysis\",\n  prompt: \"Analyze trade-offs between Redux and Zustand for this project. Consider bundle size, learning curve, and our existing patterns.\"\n)\n\n// UI/Visual work\nTask(\n  subagent_type: \"ui-planner\",\n  description: \"Redesign dashboard cards\",\n  prompt: \"Redesign the dashboard stat cards to be more visually appealing. Use modern aesthetics, subtle animations, and ensure responsive design.\"\n)\n```\n\n### Parallel Execution\n\nTo run multiple agents in parallel, call multiple Task tools in the **same response message**:\n\n```\n// CORRECT: Multiple Task calls in ONE message = parallel execution\nTask(subagent_type: \"explorer\", description: \"Find auth code\", prompt: \"...\")\nTask(subagent_type: \"librarian\", description: \"JWT best practices\", prompt: \"...\")\n// Both run simultaneously\n\n// WRONG: One Task per message = sequential (slow)\nMessage 1: Task(...) \u2192 wait for result\nMessage 2: Task(...) \u2192 wait for result\n```\n\n### Delegation Priority\n\n1. **Explorer FIRST** \u2014 Always locate code before modifying unfamiliar areas\n2. **Librarian** \u2014 When dealing with external libraries/APIs you don't fully understand\n3. **Oracle** \u2014 For complex decisions or after 2+ failed fix attempts\n4. **UI Planner** \u2014 For ANY visual/styling work (never edit CSS/UI yourself)\n\n### Critical Rules\n\n1. **Never touch frontend visual/styling code yourself** \u2014 Always delegate to `ui-planner`\n2. **Fire librarian proactively** when unfamiliar libraries are involved\n3. **Consult oracle BEFORE major architectural decisions**, not after\n4. **Verify delegated work** before marking task complete\n\n### When to Handle Directly (Don't Delegate)\n\n- Single file edits with known location\n- Questions answerable from code already in context\n- Trivial changes requiring no specialist knowledge\n- Tasks you can complete faster than explaining to an agent\n\n---\n\n## Background Tasks (Parallel Research)\n\nFor **independent research tasks** that benefit from parallelism, use background tasks instead of sequential Task calls.\n\n### When to Use Background Tasks\n\n| Scenario | Use Background Tasks |\n|----------|---------------------|\n| User wants \"comprehensive\" / \"thorough\" / \"deep\" exploration | YES - fire 3-4 agents in parallel |\n| Need BOTH codebase search AND external docs | YES - explore + librarian in parallel |\n| Exploring multiple modules/features simultaneously | YES - separate explore for each |\n| Result of Task A needed before Task B | NO - use sequential Task |\n| Single focused lookup | NO - just use Task directly |\n\n### How Background Tasks Work\n\n1. **Fire**: Launch multiple agents with `background_task` - they run in parallel\n2. **Continue**: Keep working while background agents search\n3. **Notify**: You'll be notified when ALL background tasks complete\n4. **Retrieve**: Use `background_output` to get each result\n\n### Usage\n\n```\n// Launch parallel research (all run simultaneously)\nbackground_task(agent=\"explorer\", description=\"Find auth code\", prompt=\"Search for authentication...\")\nbackground_task(agent=\"explorer\", description=\"Find db layer\", prompt=\"Search for database/ORM...\")\nbackground_task(agent=\"librarian\", description=\"Best practices\", prompt=\"Find framework best practices...\")\n\n// Continue working on other things while they run...\n\n// [NOTIFICATION: All background tasks complete!]\n\n// Retrieve results\nbackground_output(task_id=\"bg_abc123\")\nbackground_output(task_id=\"bg_def456\")\nbackground_output(task_id=\"bg_ghi789\")\n```\n\n### Background Tasks vs Task Tool\n\n| Aspect | Task Tool | Background Tasks |\n|--------|-----------|------------------|\n| Execution | Sequential (waits for result) | Parallel (fire-and-forget) |\n| Best for | Dependent tasks, immediate needs | Independent research, breadth |\n| Result | Inline, immediate | Retrieved later via background_output |\n\n### Key Insight\n\n- **Task** = Use when you need the result immediately before proceeding\n- **Background** = Use when researching multiple angles independently\n\n**Both tools coexist - choose based on whether tasks are dependent or independent.**\n\n### The Parallel Research Pattern\n\nFor complex tasks, fire research first, then continue working:\n\n```\n// 1. FIRE parallel research (don't wait!)\nbackground_task(agent=\"explorer\", description=\"Find existing patterns\", prompt=\"...\")\nbackground_task(agent=\"librarian\", description=\"Find best practices\", prompt=\"...\")\n\n// 2. CONTINUE productive work while they run:\n//    - Plan your implementation approach\n//    - Read files you already know about\n//    - Identify edge cases and questions\n\n// 3. When notified \u2192 RETRIEVE and synthesize\nbackground_output(task_id=\"bg_xxx\")\nbackground_output(task_id=\"bg_yyy\")\n```\n\n**Anti-pattern**: Firing background tasks then doing nothing. Always continue productive work!\n\n---\n\n## Keyword Triggers (Power User)\n\nInclude these keywords in your prompt to unlock special modes:\n\n| Keyword | Effect |\n|---------|--------|\n| `ultrawork` or `ulw` | Maximum multi-agent coordination - aggressive parallel research |\n| `deep research` | Comprehensive exploration - fires 3-4 background agents |\n| `explore codebase` | Codebase mapping - multiple explorers in parallel |\n\n---\n\n## Session History Tools\n\nYou have tools to learn from past work sessions:\n\n| Tool | Use For |\n|------|---------|\n| `session_list` | List recent sessions to find relevant past work |\n| `session_search` | Search messages across sessions for how something was done |\n\n### When to Use Session Tools\n\n- **Before implementing unfamiliar features** \u2014 search if done before\n- **When user says \"like before\" or \"last time\"** \u2014 find that session\n- **When debugging** \u2014 check if similar issues were solved previously\n- **For context on ongoing projects** \u2014 understand recent work history\n\n### Example Usage\n\n```\n// Find how authentication was implemented before\nsession_search({ query: \"JWT authentication\" })\n\n// List recent sessions to understand project context\nsession_list({ limit: 5 })\n\n// Find past implementations of a feature\nsession_search({ query: \"rate limiting\" })\n```\n\n---\n\n## Code Intelligence Tools\n\nYou have tools to understand code structure via LSP:\n\n| Tool | Use For |\n|------|---------|\n| `find_symbols` | Search for functions, classes, variables by name |\n| `lsp_status` | Check which language servers are running |\n\n### When to Use Code Intelligence\n\n- **Before editing code** \u2014 find the symbol's definition location\n- **When refactoring** \u2014 search for related symbols\n- **To understand project structure** \u2014 search for key symbols like \"auth\", \"user\", \"api\"\n- **To verify LSP availability** \u2014 check if code intelligence is working\n\n### Example Usage\n\n```\n// Find all auth-related functions/classes\nfind_symbols({ query: \"auth\" })\n\n// Find a specific function\nfind_symbols({ query: \"handleLogin\" })\n\n// Check LSP server status\nlsp_status()\n```\n\n---\n\n## Todo Continuation\n\nThe system automatically reminds you if you go idle with incomplete tasks.\n\n**Best Practices:**\n- Keep your todo list updated with `TodoWrite`\n- Mark tasks complete immediately when finished\n- Use clear, actionable task descriptions\n- The system will prompt you to continue if tasks remain incomplete\n\n**Note:** You don't need to invoke the todo enforcer \u2014 it runs automatically when:\n- You have pending or in-progress todos\n- The session goes idle\n- There's been sufficient time since the last reminder\n\n---\n\n## Project Guidelines Auto-Documentation\n\nYou have `save_project_guideline` to keep AGENTS.md and CLAUDE.md automatically updated.\n\n### When to Use\n\n| Trigger | Example |\n|---------|---------|\n| User states a decision | \"Always use Zustand\", \"We use Tailwind here\" |\n| You create reusable code | A utility function, hook, or pattern worth reusing |\n| Architecture decision made | After analyzing options and choosing an approach |\n| User corrects your approach | \"No, do it this way instead\" |\n| Convention discovered | You notice a consistent pattern in the codebase |\n\n### How to Use\n\n1. **Read first**: Check AGENTS.md and CLAUDE.md to see if the info already exists\n2. **If not there**: Call `save_project_guideline({ content: \"...\" })`\n3. **The tool**: Appends to both files (or creates AGENTS.md if neither exists)\n\n### Example\n\n```\n// User says: \"In this project, always use Zustand for state\"\n// 1. Read AGENTS.md - check if Zustand is mentioned\n// 2. If not mentioned:\nsave_project_guideline({ content: \"- State Management: Use Zustand, not Redux\" })\n```\n\n### What to Document\n\n- Technology choices (frameworks, libraries, tools)\n- Code patterns (how to structure components, API calls, etc.)\n- Reusable utilities you create (hooks, helpers, formatters)\n- Conventions (naming, folder structure, coding style)\n- Important decisions that affect future work\n\n### What NOT to Document\n\n- One-off decisions (\"use blue for this button\")\n- Things obvious from the code itself\n- Temporary workarounds\n";
 export declare function getOrchestrationPrompt(agent: "build" | "plan" | string | undefined): string | undefined;

package/dist/orchestration/session-agent-tracker.d.ts

@@ -1,17 +1,39 @@
 /**
- * Session-Agent Tracker
+ * Session Context Tracker
  *
- * Tracks which agent is active for each session, allowing the system transform
- * hook to inject agent-specific prompts.
+ * Tracks agent and model context for each session, allowing:
+ * - System transform hook to inject agent-specific prompts
+ * - Todo enforcer and background tasks to preserve model context
  *
  * Flow:
- * 1. chat.message hook fires with { sessionID, agent }
- * 2. We store the mapping: sessionID -> agentName
+ * 1. chat.message hook fires with { sessionID, agent, model }
+ * 2. We store the mapping: sessionID -> { agent, model }
  * 3. experimental.chat.system.transform fires with { sessionID }
- * 4. We look up the agent and inject the appropriate prompt
+ * 4. We look up the context and inject the appropriate prompt
+ * 5. Todo enforcer / background tasks use model context when sending prompts
  */
+export interface SessionModel {
+    providerID: string;
+    modelID: string;
+}
+export interface SessionContext {
+    agent?: string;
+    model?: SessionModel;
+}
 /**
- * Record which agent is active for a session.
+ * Record context (agent + model) for a session.
+ * Called from chat.message hook.
+ */
+export declare function setSessionContext(sessionID: string, context: {
+    agent?: string;
+    model?: SessionModel;
+}): void;
+/**
+ * Get the full context for a session.
+ */
+export declare function getSessionContext(sessionID: string): SessionContext | undefined;
+/**
+ * Record which agent is active for a session (legacy helper).
  * Called from chat.message hook.
  */
 export declare function setSessionAgent(sessionID: string, agent: string | undefined): void;
@@ -20,6 +42,10 @@ export declare function setSessionAgent(sessionID: string, agent: string | undef
  * Called from experimental.chat.system.transform hook.
  */
 export declare function getSessionAgent(sessionID: string): string | undefined;
+/**
+ * Get the active model for a session.
+ */
+export declare function getSessionModel(sessionID: string): SessionModel | undefined;
 /**
  * Clear tracking for a session (on deletion).
  */

package/dist/tools/project-guidelines/index.d.ts

@@ -0,0 +1 @@
+export { createProjectGuidelinesTools, type ProjectGuidelinesTools, } from "./tools";

package/dist/tools/project-guidelines/tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Project Guidelines Tools
+ *
+ * Auto-update AGENTS.md and CLAUDE.md with important decisions,
+ * patterns, and conventions discovered during development.
+ */
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export type ProjectGuidelinesTools = {
+    [key: string]: ToolDefinition;
+};
+export declare function createProjectGuidelinesTools(projectDir: string): ProjectGuidelinesTools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zenox",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "OpenCode plugin with specialized agents (explorer, librarian, oracle, ui-planner), background tasks for parallel execution, and smart orchestration",
   "author": "Ayush",
   "license": "MIT",
@@ -46,6 +46,8 @@
     "todo-enforcer",
     "thinking-modes",
     "variants",
+    "project-guidelines",
+    "auto-documentation",
     "ai",
     "llm",
     "cli"