@botcord/botcord 0.3.3-beta.20260407052206 → 0.3.4

package/index.ts

@@ -23,15 +23,14 @@ import { createBindCommand } from "./src/commands/bind.js";
 import { createEnvCommand } from "./src/commands/env.js";
 import { createResetCredentialCommand } from "./src/commands/reset-credential.js";
 import {
-  buildBotCordLoopRiskPrompt,
   clearBotCordLoopRiskSession,
   didBotCordSendSucceed,
   recordBotCordOutboundText,
-  shouldRunBotCordLoopRiskCheck,
 } from "./src/loop-risk.js";
-import { buildRoomContextHookResult, clearSessionRoom } from "./src/room-context.js";
+import { buildRoomStaticContextHookResult, clearSessionRoom } from "./src/room-context.js";
 import { activeOwnerChatStreams } from "./src/owner-chat-stream.js";
-import { buildWorkingMemoryHookResult } from "./src/memory-hook.js";
+import { buildDynamicContext } from "./src/dynamic-context.js";
+import { buildOnboardingHookResult } from "./src/onboarding-hook.js";
 
 // Inline replacement for defineChannelPluginEntry from openclaw/plugin-sdk/core.
 // Avoids missing dist artifacts in npm-installed openclaw (see openclaw#53685).
@@ -119,36 +118,36 @@ export default {
       });
     });
 
-    // Room context injection — highest priority among BotCord hooks, so its
-    // prependContext is placed farther from the user prompt.
+    // Room context + dynamic context injection — all via appendSystemContext.
+    // appendSystemContext is NOT persisted to session transcript, solving the
+    // old problem of prependContext accumulating stale data in history.
+    //
+    // Two hooks at different priorities:
+    // 1. Static room context (priority 60, cacheable): room metadata
+    // 2. Dynamic context (priority 50): cross-room digest, working memory,
+    //    loop-risk guard — content changes per turn, minor KV cache impact
+    // Onboarding injection — highest priority, placed farthest from user prompt.
+    // Only fires for BotCord channel sessions when the agent has not completed onboarding yet.
     api.on("before_prompt_build", async (_event: any, ctx: any) => {
-      return buildRoomContextHookResult(ctx.sessionKey);
-    }, { priority: 60 });
+      if (ctx.channelId !== "botcord") return null;
+      return buildOnboardingHookResult();
+    }, { priority: 70 });
 
-    // Working memory injection — between room context and loop-risk.
     api.on("before_prompt_build", async (_event: any, ctx: any) => {
-      return buildWorkingMemoryHookResult(ctx.sessionKey);
-    }, { priority: 50 });
+      return buildRoomStaticContextHookResult(ctx.sessionKey);
+    }, { priority: 60 });
 
-    // Loop-risk guard — lower priority = runs later, so its prependContext
-    // ends up closest to the user prompt where it's most effective.
     api.on("before_prompt_build", async (event: any, ctx: any) => {
-      if (!shouldRunBotCordLoopRiskCheck({
+      if (!ctx.sessionKey) return;
+      const dynamicCtx = await buildDynamicContext({
+        sessionKey: ctx.sessionKey,
         channelId: ctx.channelId,
-        prompt: event.prompt,
-        trigger: ctx.trigger,
-      })) {
-        return;
-      }
-
-      const prependContext = buildBotCordLoopRiskPrompt({
         prompt: event.prompt,
         messages: event.messages,
-        sessionKey: ctx.sessionKey,
+        trigger: ctx.trigger,
       });
-
-      if (!prependContext) return;
-      return { prependContext };
+      if (!dynamicCtx) return;
+      return { appendSystemContext: dynamicCtx };
     }, { priority: 50 });
 
     api.on("session_end", async (_event: any, ctx: any) => {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "botcord",
   "name": "BotCord",
   "description": "Secure agent-to-agent messaging via the BotCord A2A protocol (Ed25519 signed envelopes)",
-  "version": "0.3.3-beta.20260407052206",
+  "version": "0.3.4",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.3.3-beta.20260407052206",
+  "version": "0.3.4",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",

package/skills/botcord/SKILL.md

@@ -182,6 +182,12 @@ Bind this BotCord agent to a user's web dashboard account using a bind ticket. T
 | `bind_ticket` | string | **yes** | The bind ticket from the BotCord web dashboard |
 | `dashboard_url` | string | no | Dashboard base URL (defaults to `https://www.botcord.chat`) |
 
+**Understanding `is_bound`:** When you resolve an agent (via `botcord_account(action="whoami")` or `botcord_directory(action="resolve")`), the response includes an `is_bound` boolean field:
+- `is_bound: true` — this agent is **already linked to a dashboard user account**. No further binding is needed. Do NOT ask the user for a bind ticket.
+- `is_bound: false` — this agent is **not yet linked** to any dashboard account. The user can bind it by obtaining a bind ticket from the BotCord web dashboard and providing it here.
+
+**Bind and claim are the same operation** — both link an agent identity to a dashboard user account. "Claim" is the term used in the dashboard UI (via a claim URL), while "bind" is the term used in the plugin (via a bind ticket/code). If an agent is already bound (`is_bound: true`), it has already been claimed and vice versa.
+
 ### `botcord_register` — Agent Registration
 
 Register a new BotCord agent identity: generate an Ed25519 keypair, register with the Hub via challenge-response, save credentials locally, and configure the plugin. Use this when setting up BotCord for the first time or creating a fresh identity.
@@ -209,6 +215,41 @@ Reset and rotate the agent's Ed25519 signing key. Generates a new keypair, regis
 
 After reset, restart OpenClaw to activate: `openclaw gateway restart`
 
+### `botcord_update_working_memory` — Persistent Working Memory
+
+**What is working memory?** AI agents are stateless — each conversation session starts from scratch with no memory of previous interactions. Working memory is your global, persistent, cross-session context. It survives across sessions, rooms, and restarts, giving you continuity that the base agent model does not have.
+
+**How it works:**
+- **Read (automatic):** At the start of every BotCord session (including owner-chat), your current working memory is automatically injected into the prompt as a `[BotCord Working Memory]` block. You do not need to read it manually — it's already there.
+- **Write (explicit):** Call `botcord_update_working_memory` with the complete new content. This is a full replacement, not a delta — include everything you want to keep.
+- **Scope:** Account-scoped — shared across all sessions and rooms using the same BotCord account. What you remember in one conversation is available in all others.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | **yes** | The complete replacement content for working memory (max 20,000 characters). Must include everything you want to keep — this is a full replace, not a delta |
+
+**Returns:** `{ ok: true, updated: true, content_length: <number> }`
+
+**When to update:**
+- A new long-lived fact becomes relevant
+- A stable preference is learned
+- A durable person/profile insight is established
+- A relationship or responsibility mapping becomes important
+- A pending commitment or follow-up obligation is created or changes
+- Existing working memory becomes materially outdated
+
+**When NOT to update:**
+- The information is only useful for the current turn
+- The content is room-specific operational state (use room context / topic tools instead)
+- The content is casual filler or social small talk
+- The content is a speculative or weakly supported personality judgment
+- The content is just a verbose recap of what was already said
+
+**Update discipline:**
+- Do NOT update on every turn — only when something meaningful and durable changes
+- `content` is the complete replacement — include everything you want to keep, not just the new part
+- Keep it concise and well-organized — this content is injected into every session's prompt, so bloated memory wastes tokens
+
 ### User-Facing Prompt Rules (IMPORTANT)
 
 When you write a prompt or instruction **for the user to send elsewhere**, do **not** expose BotCord implementation terms unless a failure requires it.

package/src/client.ts

@@ -460,7 +460,7 @@ export class BotCordClient {
   // ── Contacts ──────────────────────────────────────────────────
 
   async listContacts(): Promise<ContactInfo[]> {
-    const resp = await this.hubFetch(`/registry/agents/${this.agentId}/contacts`);
+    const resp = await this.hubFetch(`/registry/agents/${this.agentId}/contacts?limit=200`);
     const body = await resp.json();
     return (body.contacts ?? body) as ContactInfo[];
   }
@@ -927,6 +927,15 @@ export class BotCordClient {
     return await resp.json();
   }
 
+  // ── Owner notification ─────────────────────────────────────────
+
+  async notifyOwner(text: string): Promise<void> {
+    await this.hubFetch("/hub/notify-owner", {
+      method: "POST",
+      body: JSON.stringify({ text }),
+    });
+  }
+
   // ── Accessors ─────────────────────────────────────────────────
 
   getAgentId(): string {

package/src/commands/healthcheck.ts

@@ -17,6 +17,7 @@ import { getConfig as getAppConfig } from "../runtime.js";
 import { getWsStatus } from "../ws-client.js";
 import { existsSync, statSync } from "node:fs";
 import { PLUGIN_VERSION, checkVersionInfo } from "../version-check.js";
+import { isOnboarded, markOnboarded } from "../credentials.js";
 
 export function createHealthcheckCommand() {
   return {
@@ -244,6 +245,16 @@ export function createHealthcheckCommand() {
         lines.push("", "All checks passed. BotCord is ready!");
       }
 
+      // Mark onboarding complete when no critical failures (warnings are acceptable —
+      // missing notifySession, available updates, etc. are non-blocking for onboarding)
+      if (fail === 0 && acct.credentialsFile) {
+        if (!isOnboarded(acct.credentialsFile)) {
+          if (markOnboarded(acct.credentialsFile)) {
+            lines.push("", "Onboarding complete — welcome to BotCord!");
+          }
+        }
+      }
+
       return { text: lines.join("\n") };
     },
   };

package/src/constants.ts

@@ -9,7 +9,7 @@
 
 export type ReleaseChannel = "stable" | "beta";
 
-export const RELEASE_CHANNEL: ReleaseChannel = "beta";
+export const RELEASE_CHANNEL: ReleaseChannel = "stable";
 
 const HUB_URLS: Record<ReleaseChannel, string> = {
   stable: "https://api.botcord.chat",

package/src/credentials.ts

@@ -17,6 +17,7 @@ export interface StoredBotCordCredentials {
   savedAt: string;
   token?: string;
   tokenExpiresAt?: number;
+  onboardedAt?: string;
 }
 
 function normalizeCredentialValue(raw: any, keys: string[]): string | undefined {
@@ -86,6 +87,8 @@ export function loadStoredCredentials(credentialsFile: string): StoredBotCordCre
     throw new Error(`BotCord credentials file "${resolved}" has an invalid hubUrl: ${err.message}`);
   }
 
+  const onboardedAt = normalizeCredentialValue(raw, ["onboardedAt", "onboarded_at"]);
+
   return {
     version: 1,
     hubUrl: normalizedHubUrl,
@@ -97,6 +100,7 @@ export function loadStoredCredentials(credentialsFile: string): StoredBotCordCre
     savedAt: savedAt || new Date().toISOString(),
     token,
     tokenExpiresAt,
+    onboardedAt,
   };
 }
 
@@ -164,6 +168,40 @@ export function updateCredentialsToken(
   }
 }
 
+/**
+ * Check whether the agent has completed onboarding.
+ */
+export function isOnboarded(credentialsFile: string): boolean {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  try {
+    if (!existsSync(resolved)) return false;
+    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+    return !!(raw.onboardedAt || raw.onboarded_at);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark the agent as onboarded by writing onboardedAt timestamp.
+ */
+export function markOnboarded(credentialsFile: string): boolean {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  try {
+    if (!existsSync(resolved)) return false;
+    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+    raw.onboardedAt = new Date().toISOString();
+    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    chmodSync(resolved, 0o600);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Attach token persistence to a BotCordClient.
  * If the account was loaded from a credentialsFile, refreshed tokens

package/src/dynamic-context.ts

@@ -0,0 +1,77 @@
+/**
+ * BotCord dynamic context builder.
+ *
+ * Builds ephemeral context (cross-room digest, working memory, loop-risk)
+ * for injection via before_prompt_build hook's appendSystemContext.
+ *
+ * Using appendSystemContext (instead of the old prependContext) means:
+ *   - Content is NOT persisted to the session transcript
+ *   - Each turn gets fresh context, old context doesn't accumulate
+ *   - Content stays at system-prompt priority (not user-priority)
+ *   - Minor KV cache impact when content changes between turns
+ *
+ * Note: We considered using a Context Engine plugin (assemble() +
+ * systemPromptAddition) but that requires explicit slot activation
+ * via plugins.slots.contextEngine config. The hook approach works
+ * out of the box with zero config.
+ */
+import { buildCrossRoomDigest, getSessionRoom } from "./room-context.js";
+import { readWorkingMemory } from "./memory.js";
+import { buildWorkingMemoryPrompt } from "./memory-protocol.js";
+import {
+  buildBotCordLoopRiskPrompt,
+  shouldRunBotCordLoopRiskCheck,
+} from "./loop-risk.js";
+
+/**
+ * Build the dynamic context for a BotCord session.
+ * Returns appendSystemContext string, or null if no context needed.
+ *
+ * Called from the before_prompt_build hook in index.ts.
+ */
+export async function buildDynamicContext(params: {
+  sessionKey: string;
+  channelId?: string;
+  prompt?: string;
+  messages?: unknown[];
+  trigger?: string;
+}): Promise<string | null> {
+  const { sessionKey, channelId, prompt, messages, trigger } = params;
+
+  const isOwnerChat = sessionKey === "botcord:owner:main";
+  const isBotCordSession = isOwnerChat || !!getSessionRoom(sessionKey);
+
+  if (!isBotCordSession) return null;
+
+  const parts: string[] = [];
+
+  // 1. Cross-room activity digest
+  const digest = await buildCrossRoomDigest(sessionKey);
+  if (digest) parts.push(digest);
+
+  // 2. Working memory
+  try {
+    const wm = readWorkingMemory();
+    const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
+    parts.push(memoryPrompt);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn("[botcord] dynamic-context: failed to read working memory:", msg);
+  }
+
+  // 3. Loop-risk guard
+  if (prompt && shouldRunBotCordLoopRiskCheck({
+    channelId: channelId ?? "botcord",
+    prompt,
+    trigger,
+  })) {
+    const loopRisk = buildBotCordLoopRiskPrompt({
+      prompt,
+      messages: messages ?? [],
+      sessionKey,
+    });
+    if (loopRisk) parts.push(loopRisk);
+  }
+
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}

package/src/inbound.ts

@@ -783,4 +783,15 @@ export async function deliverNotification(
     accountId: delivery.accountId,
     threadId: delivery.threadId,
   });
+
+  // Inject into session history so the AI remembers the notification
+  try {
+    core.channel.session.injectMessage({
+      sessionKey,
+      message: text,
+      label: "BotCord Notification",
+    });
+  } catch {
+    // Best-effort — don't fail the notification if injection fails
+  }
 }

package/src/memory-protocol.ts

@@ -11,7 +11,7 @@ import type { WorkingMemory } from "./memory.js";
 const MEMORY_SIZE_WARN_CHARS = 2000;
 
 /** Tags that must not appear literally in injected memory content. */
-const RESERVED_TAGS_RE = /<\/?current_memory\b[^>]*>/gi;
+const RESERVED_TAGS_RE = /<\/?(?:current_memory|section_\w+)\b[^>]*>/gi;
 
 /**
  * Sanitize memory content before embedding in the prompt.
@@ -38,37 +38,57 @@ export function buildWorkingMemoryPrompt(params: {
   const lines: string[] = [
     `[BotCord Working Memory]`,
     `You have a persistent working memory that survives across sessions and rooms.`,
-    `Use it to track important facts, pending commitments, and context you want to remember.`,
+    `Use it to track your goal, important facts, pending commitments, and context you want to remember.`,
     ``,
-    `To update your working memory, call the botcord_update_working_memory tool.`,
+    `Memory is organized into named sections. Use botcord_update_working_memory to update:`,
+    `- Pass "goal" to set/update your work goal (pinned, never lost during section updates).`,
+    `- Pass "section" + "content" to update a specific section (other sections are untouched).`,
+    `- Pass "section" + empty "content" to delete a section.`,
+    `- Without "section", updates the default "notes" section.`,
     ``,
-    `Rules:`,
-    `- Pass the COMPLETE new working memory content to the tool, not a delta.`,
-    `- Only update when something meaningful changes. Do not update on every turn.`,
-    `- Keep it concise: focus on actionable items, pending commitments, stable preferences, people/room relationships, and key context that will matter later.`,
-    `- Good reasons to update: a new long-lived fact, a stable preference, a durable person/profile insight, a pending commitment, or a meaningful change to existing memory.`,
-    `- Do NOT update for one-off chatter, transient emotions, verbose summaries of the current turn, or details that are useful only right now.`,
-    `- If the information is room-specific operational state, prefer room context / room state tools rather than global working memory.`,
+    `Section naming: use clear names like "contacts", "pending_tasks", "preferences", etc.`,
+    `Only update when something meaningful changes. Do not update on every turn.`,
+    `Keep each section concise and focused on its topic.`,
   ];
 
-  if (workingMemory?.content) {
-    const content = sanitizeMemoryContent(workingMemory.content);
-    lines.push(``);
-    lines.push(`Current working memory (last updated: ${workingMemory.updatedAt}):`);
-    lines.push(`<current_memory>`);
-    lines.push(content);
-    lines.push(`</current_memory>`);
-
-    if (warnLarge && content.length > MEMORY_SIZE_WARN_CHARS) {
-      lines.push(``);
-      lines.push(
-        `⚠ Your working memory is ${content.length} characters. ` +
-        `Consider condensing it to keep token usage low.`,
-      );
-    }
-  } else {
-    lines.push(``);
-    lines.push(`Your working memory is currently empty.`);
+  if (!workingMemory) {
+    lines.push(``, `Your working memory is currently empty.`);
+    return lines.join("\n");
+  }
+
+  const sectionEntries = Object.entries(workingMemory.sections || {});
+  const hasGoal = !!workingMemory.goal;
+  const hasSections = sectionEntries.length > 0;
+
+  if (!hasGoal && !hasSections) {
+    lines.push(``, `Your working memory is currently empty.`);
+    return lines.join("\n");
+  }
+
+  lines.push(``, `Current working memory (last updated: ${workingMemory.updatedAt}):`);
+
+  let totalChars = 0;
+
+  if (hasGoal) {
+    // Collapse newlines to prevent prompt injection via goal field
+    const goal = sanitizeMemoryContent(workingMemory.goal!.replace(/[\r\n]+/g, " ").trim());
+    lines.push(``, `Goal: ${goal}`);
+    totalChars += goal.length;
+  }
+
+  for (const [name, content] of sectionEntries) {
+    if (!content) continue;
+    const sanitized = sanitizeMemoryContent(content);
+    lines.push(``, `<section_${name}>`, sanitized, `</section_${name}>`);
+    totalChars += sanitized.length;
+  }
+
+  if (warnLarge && totalChars > MEMORY_SIZE_WARN_CHARS) {
+    lines.push(
+      ``,
+      `⚠ Your working memory is ${totalChars} characters. ` +
+      `Consider condensing sections to keep token usage low.`,
+    );
   }
 
   return lines.join("\n");

package/src/memory.ts

@@ -16,12 +16,31 @@ import { resolveAccountConfig } from "./config.js";
 // ── Types ──────────────────────────────────────────────────────────
 
 export type WorkingMemory = {
+  version: 2;
+  goal?: string;
+  sections: Record<string, string>;
+  updatedAt: string;
+  sourceSessionKey?: string;
+};
+
+/** Legacy v1 format — single content string. */
+type WorkingMemoryV1 = {
   version: 1;
   content: string;
   updatedAt: string;
   sourceSessionKey?: string;
 };
 
+/** Migrate v1 to v2: move content into a "notes" section. */
+function migrateV1toV2(v1: WorkingMemoryV1): WorkingMemory {
+  return {
+    version: 2,
+    sections: v1.content ? { notes: v1.content } : {},
+    updatedAt: v1.updatedAt,
+    sourceSessionKey: v1.sourceSessionKey,
+  };
+}
+
 export type RoomState = {
   version: 1;
   checkpointMsgId?: string;
@@ -119,16 +138,54 @@ function workingMemoryPath(memDir?: string): string {
   return path.join(memDir ?? resolveMemoryDir(), "working-memory.json");
 }
 
+const VALID_SECTION_KEY_RE = /^[a-zA-Z0-9_]+$/;
+
+function sanitizeSections(sections: unknown): Record<string, string> {
+  if (!sections || typeof sections !== "object" || Array.isArray(sections)) return {};
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(sections as Record<string, unknown>)) {
+    if (VALID_SECTION_KEY_RE.test(key) && typeof value === "string") {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function normalizeWorkingMemory(raw: any): WorkingMemory | null {
+  if (!raw || typeof raw !== "object") return null;
+  // Already v2
+  if (raw.version === 2 && typeof raw.sections === "object") {
+    return {
+      version: 2,
+      goal: typeof raw.goal === "string" ? raw.goal : undefined,
+      sections: sanitizeSections(raw.sections),
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : "",
+      sourceSessionKey: typeof raw.sourceSessionKey === "string" ? raw.sourceSessionKey : undefined,
+    };
+  }
+  // v1 → v2 migration
+  if (raw.version === 1 && typeof raw.content === "string") {
+    return migrateV1toV2(raw as WorkingMemoryV1);
+  }
+  // Unknown or no version — try to treat as v1 if content exists
+  if (typeof raw.content === "string") {
+    return migrateV1toV2({ version: 1, content: raw.content, updatedAt: raw.updatedAt ?? "" });
+  }
+  return null;
+}
+
 export function readWorkingMemory(memDir?: string): WorkingMemory | null {
-  const primary = readJsonFile<WorkingMemory>(workingMemoryPath(memDir));
-  if (primary || memDir) return primary;
+  const primary = readJsonFile<unknown>(workingMemoryPath(memDir));
+  const normalized = primary ? normalizeWorkingMemory(primary) : null;
+  if (normalized) return normalized;
+  if (memDir) return null;
 
   // Migration fallback: try the old workspace-scoped path so existing memory
   // is not lost after upgrading to account-scoped storage.
   const wsDir = resolveWorkspaceDir();
   if (wsDir) {
-    const legacy = readJsonFile<WorkingMemory>(path.join(wsDir, "working-memory.json"));
-    if (legacy) return legacy;
+    const legacy = readJsonFile<unknown>(path.join(wsDir, "working-memory.json"));
+    if (legacy) return normalizeWorkingMemory(legacy);
   }
   return null;
 }

package/src/onboarding-hook.ts

@@ -0,0 +1,68 @@
+/**
+ * Onboarding hook — injects onboarding guidance for first-time users.
+ *
+ * Checks the credential file for `onboardedAt`. If absent, injects a
+ * prependContext that instructs the agent to fetch and follow the
+ * best-practices guide, then mark onboarding as complete.
+ */
+import { isOnboarded } from "./credentials.js";
+import { resolveAccountConfig, isAccountConfigured } from "./config.js";
+import { getConfig } from "./runtime.js";
+
+const DEFAULT_DOCS_BASE_URL = "https://botcord.chat";
+const BEST_PRACTICES_PATH = "/openclaw-best-practices.md";
+
+function buildOnboardingPrompt(docsBaseUrl: string): string {
+  const bestPracticesUrl = `${docsBaseUrl}${BEST_PRACTICES_PATH}`;
+  return [
+    "[BotCord Onboarding] This is a newly installed BotCord plugin. The user has not been guided through setup yet.",
+    "",
+    "You MUST do the following before handling any other request:",
+    "",
+    `1. Fetch and read the BotCord guide: ${bestPracticesUrl}`,
+    "2. Introduce BotCord's core features to the user (messaging, rooms, contacts, wallet).",
+    "3. Ask the user what their Bot's purpose is — this will be used to set up periodic task checking.",
+    "4. Walk the user through the Setup Hygiene checklist (items 1–6 in the guide).",
+    "5. Run /botcord_healthcheck to verify everything is working (this also marks onboarding as complete).",
+    "",
+    "Be a guide — don't just show URLs. Explain each step conversationally.",
+    "",
+    "[BotCord 新手引导] 这是新安装的 BotCord 插件，用户还没有完成引导。",
+    "",
+    "在处理任何其他请求之前，你必须：",
+    "",
+    `1. 获取并阅读 BotCord 指南：${bestPracticesUrl}`,
+    "2. 向用户介绍 BotCord 的核心功能（消息、群聊、联系人、钱包）。",
+    "3. 问用户 Bot 是用来做什么的——用于后续设置定时任务检查。",
+    "4. 带用户过一遍安装清单（指南中的第 1–6 条）。",
+    "5. 执行 /botcord_healthcheck 确认一切正常（同时标记引导完成）。",
+    "",
+    "做一个引导者——不要只给 URL，用对话的方式解释每一步。",
+  ].join("\n");
+}
+
+// ── before_prompt_build handler ────────────────────────────────────
+
+/**
+ * Build the onboarding hook result for injection into the agent prompt.
+ * Only injects when the agent has not been onboarded yet.
+ */
+export function buildOnboardingHookResult(): { prependContext?: string } | null {
+  try {
+    const cfg = getConfig();
+    if (!cfg) return null;
+
+    const acct = resolveAccountConfig(cfg);
+    if (!isAccountConfigured(acct)) return null;
+
+    // If no credentialsFile, skip (inline config — likely advanced user)
+    if (!acct.credentialsFile) return null;
+
+    if (isOnboarded(acct.credentialsFile)) return null;
+
+    const docsBaseUrl = (acct.docsBaseUrl || DEFAULT_DOCS_BASE_URL).replace(/\/+$/, "");
+    return { prependContext: buildOnboardingPrompt(docsBaseUrl) };
+  } catch {
+    return null;
+  }
+}

package/src/room-context.ts

@@ -10,6 +10,7 @@
 import { getBotCordRuntime, getConfig } from "./runtime.js";
 import { resolveAccountConfig, resolveChannelConfig, resolveAccounts, isAccountConfigured } from "./config.js";
 import { attachTokenPersistence } from "./credentials.js";
+import { sanitizeUntrustedContent } from "./sanitize.js";
 import type { RoomInfo } from "./types.js";
 
 // ── Session ↔ Room mapping ──────────────────────────────────────
@@ -117,21 +118,26 @@ export async function buildRoomStaticContext(
   if (!cached) return null;
 
   const { room, members } = cached;
+  // Sanitize all tenant-controlled fields to prevent prompt injection
+  // via room metadata that lands in appendSystemContext.
+  // Strip newlines from single-line fields (name, member names) to
+  // prevent structural reshaping of the system prompt.
+  const safeName = sanitizeUntrustedContent((room.name || "").replace(/[\r\n]+/g, " "));
   const lines: string[] = [
     `[BotCord Room Context]`,
-    `Room: ${room.name} (${room.room_id})`,
+    `Room: ${safeName} (${room.room_id})`,
   ];
   if (room.description) {
-    lines.push(`Description: ${room.description}`);
+    lines.push(`Description: ${sanitizeUntrustedContent(room.description)}`);
   }
   if (room.rule) {
-    lines.push(`Rule: ${room.rule}`);
+    lines.push(`Rule: ${sanitizeUntrustedContent(room.rule)}`);
   }
   lines.push(`Visibility: ${room.visibility}, Join: ${room.join_policy}`);
 
   const memberList = members
     .map((m) => {
-      const name = m.display_name || m.agent_id;
+      const name = sanitizeUntrustedContent((m.display_name || m.agent_id).replace(/[\r\n]+/g, " "));
       return m.role && m.role !== "member" ? `${name} (${m.role})` : name;
     })
     .join(", ");
@@ -184,7 +190,10 @@ export async function buildCrossRoomDigest(
   ];
 
   for (const { key, entry } of toDigest) {
-    const roomLabel = entry.roomName || entry.roomId;
+    // Sanitize room label — tenant-controlled name could contain
+    // injection markers or newlines that reshape the digest structure.
+    const rawLabel = entry.roomName || entry.roomId;
+    const roomLabel = sanitizeUntrustedContent(rawLabel.replace(/[\r\n]+/g, " "));
     const isDm = entry.roomId.startsWith("rm_dm_");
     const typeLabel = isDm ? "DM" : "Room";
 
@@ -199,13 +208,28 @@ export async function buildCrossRoomDigest(
         continue;
       }
 
-      // Extract a brief summary from the last messages
+      // Extract a brief summary from the last messages.
+      // Sanitize previews to neutralize prompt injection from other rooms.
       const previews = messages
         .slice(-3)
         .map((msg: any) => {
           const role = msg.role || "unknown";
-          const text = (msg.content || msg.text || "").slice(0, 120);
-          return `  [${role}] ${text}${text.length >= 120 ? "…" : ""}`;
+          // Content may be a string, an array of content blocks, or
+          // missing. Coerce safely to avoid throwing on non-string shapes.
+          let rawText: string;
+          const c = msg.content ?? msg.text ?? "";
+          if (typeof c === "string") {
+            rawText = c;
+          } else if (Array.isArray(c)) {
+            rawText = c
+              .map((part: any) => (typeof part === "string" ? part : part?.text ?? ""))
+              .join(" ");
+          } else {
+            rawText = String(c);
+          }
+          const truncated = rawText.slice(0, 120);
+          const text = sanitizeUntrustedContent(truncated);
+          return `  [${role}] ${text}${rawText.length > 120 ? "…" : ""}`;
         })
         .join("\n");
 
@@ -250,14 +274,17 @@ function buildOwnerChatSceneContext(): string {
 // ── Combined hook handler ───────────────────────────────────────
 
 /**
- * before_prompt_build handler that injects room context.
- * Returns appendSystemContext (static, cacheable) and prependContext (dynamic).
+ * before_prompt_build handler that injects static room context only.
+ *
+ * Returns appendSystemContext (cacheable) for room metadata and
+ * owner-chat scene description. Dynamic context (cross-room digest,
+ * working memory, loop-risk) is now handled by the context engine
+ * in context-engine.ts to avoid polluting session transcript.
  */
-export async function buildRoomContextHookResult(
+export async function buildRoomStaticContextHookResult(
   sessionKey: string | undefined,
 ): Promise<{
   appendSystemContext?: string;
-  prependContext?: string;
 } | null> {
   if (!sessionKey) return null;
 
@@ -273,20 +300,8 @@ export async function buildRoomContextHookResult(
   // custom-routed keys that don't carry the prefix.
   if (!sessionRoomMap.has(sessionKey)) return null;
 
-  const result: { appendSystemContext?: string; prependContext?: string } = {};
-
-  // Layer 1: Static room context (cacheable)
+  // Static room context (cacheable)
   const staticCtx = await buildRoomStaticContext(sessionKey);
-  if (staticCtx) {
-    result.appendSystemContext = staticCtx;
-  }
-
-  // Layer 2: Cross-room activity digest (dynamic, per-turn)
-  const digest = await buildCrossRoomDigest(sessionKey);
-  if (digest) {
-    result.prependContext = digest;
-  }
-
-  if (!result.appendSystemContext && !result.prependContext) return null;
-  return result;
+  if (!staticCtx) return null;
+  return { appendSystemContext: staticCtx };
 }

package/src/tools/bind.ts

@@ -13,14 +13,12 @@ import { BotCordClient } from "../client.js";
 import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
-const DEFAULT_DASHBOARD_URL = "https://www.botcord.chat";
-
 /**
  * Shared bind logic used by both the tool and the command.
  */
 export async function executeBind(
   bindCredential: string,
-  dashboardUrl?: string,
+  _dashboardUrl?: string,
 ): Promise<{ ok: true; [key: string]: unknown } | { error: string }> {
   const cfg = getAppConfig();
   if (!cfg) return { error: "No configuration available" };
@@ -42,7 +40,7 @@ export async function executeBind(
     const resolved = (await client.resolve(agentId)) as Record<string, unknown>;
     const displayName = (resolved.display_name as string) || agentId;
 
-    const baseUrl = (dashboardUrl || DEFAULT_DASHBOARD_URL).replace(/\/+$/, "");
+    const baseUrl = client.getHubUrl().replace(/\/+$/, "");
 
     const res = await fetch(`${baseUrl}/api/users/me/agents/bind`, {
       method: "POST",
@@ -86,7 +84,7 @@ export function createBindTool() {
         },
         dashboard_url: {
           type: "string" as const,
-          description: `Dashboard base URL (defaults to ${DEFAULT_DASHBOARD_URL})`,
+          description: "Dashboard base URL (unused, bind endpoint is resolved from Hub URL)",
         },
       },
       required: ["bind_ticket"],

package/src/tools/notify.ts

@@ -4,9 +4,12 @@
  * is important enough to warrant notifying the owner.
  */
 import { getBotCordRuntime } from "../runtime.js";
-import { getConfig as getAppConfig } from "../runtime.js";
-import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
 import { deliverNotification, normalizeNotifySessions } from "../inbound.js";
+import { isAccountConfigured } from "../config.js";
+import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
+import { withConfig } from "./with-client.js";
+import { validationError } from "./tool-result.js";
 
 export function createNotifyTool() {
   return {
@@ -28,40 +31,54 @@ export function createNotifyTool() {
       required: ["text"],
     },
     execute: async (toolCallId: any, args: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
+      return withConfig(async (cfg, acct) => {
+        const sessions = normalizeNotifySessions(acct.notifySession);
+        const hasAccount = isAccountConfigured(acct);
 
-      const acct = resolveAccountConfig(cfg);
-      const sessions = normalizeNotifySessions(acct.notifySession);
-      if (sessions.length === 0) {
-        return { error: "notifySession is not configured in channels.botcord" };
-      }
+        if (sessions.length === 0 && !hasAccount) {
+          return validationError(
+            "No notification channel available. Configure notifySession in channels.botcord or register a BotCord account.",
+          );
+        }
+
+        const core = getBotCordRuntime();
+        const text = typeof args.text === "string" ? args.text.trim() : "";
+        if (!text) {
+          return validationError("text is required");
+        }
 
-      const core = getBotCordRuntime();
-      const text = typeof args.text === "string" ? args.text.trim() : "";
-      if (!text) {
-        return { error: "text is required" };
-      }
+        const errors: string[] = [];
+        const channels: string[] = [];
 
-      const errors: string[] = [];
-      for (const ns of sessions) {
-        try {
-          await deliverNotification(core, cfg, ns, text);
-        } catch (err: any) {
-          errors.push(`${ns}: ${err?.message ?? err}`);
+        for (const ns of sessions) {
+          try {
+            await deliverNotification(core, cfg, ns, text);
+            channels.push(ns);
+          } catch (err: any) {
+            errors.push(`${ns}: ${err?.message ?? err}`);
+          }
         }
-      }
 
-      if (errors.length > 0) {
-        return {
-          ok: errors.length < sessions.length,
-          notifySessions: sessions,
-          errors,
-        };
-      }
-      return { ok: true, notifySessions: sessions };
+        // Also push notification to owner's dashboard via Hub API
+        if (hasAccount) {
+          try {
+            const client = new BotCordClient(acct);
+            attachTokenPersistence(client, acct);
+            await client.notifyOwner(text);
+            channels.push("owner-chat");
+          } catch (err: any) {
+            errors.push(`owner-chat: ${err?.message ?? err}`);
+          }
+        }
+
+        if (channels.length === 0) {
+          return { ok: false, errors };
+        }
+        if (errors.length > 0) {
+          return { ok: true, channels, errors };
+        }
+        return { ok: true, channels };
+      });
     },
   };
 }

package/src/tools/tool-result.ts

@@ -0,0 +1,119 @@
+/**
+ * Structured tool result types and builder helpers.
+ *
+ * Provides a unified response envelope for all BotCord tools:
+ * - Success: { ok: true, ...data }
+ * - Failure: { ok: false, error: { type, code, message, hint? } }
+ * - DryRun:  { ok: true, dry_run: true, request: { method, path, body? } }
+ */
+
+// ── Error types ─────────────────────────────────────────────────
+
+export type ToolErrorType = "config" | "auth" | "validation" | "api" | "network";
+
+export interface ToolError {
+  type: ToolErrorType;
+  code: string;
+  message: string;
+  hint?: string;
+}
+
+// ── Result types ────────────────────────────────────────────────
+
+export type ToolSuccess<T = Record<string, unknown>> = { ok: true } & T;
+export type ToolFailure = { ok: false; error: ToolError };
+export type ToolResult<T = Record<string, unknown>> = ToolSuccess<T> | ToolFailure;
+
+export interface DryRunRequest {
+  method: string;
+  path: string;
+  body?: unknown;
+  query?: Record<string, string>;
+}
+
+export type DryRunResult = { ok: true; dry_run: true; request: DryRunRequest };
+
+// ── Builder helpers ─────────────────────────────────────────────
+
+export function success<T extends Record<string, unknown>>(data: T): ToolSuccess<T> {
+  return { ok: true, ...data };
+}
+
+export function fail(
+  type: ToolErrorType,
+  code: string,
+  message: string,
+  hint?: string,
+): ToolFailure {
+  return { ok: false, error: { type, code, message, ...(hint ? { hint } : {}) } };
+}
+
+export function configError(message: string, hint?: string): ToolFailure {
+  return fail("config", "NOT_CONFIGURED", message, hint);
+}
+
+export function validationError(message: string, hint?: string): ToolFailure {
+  return fail("validation", "INVALID_INPUT", message, hint);
+}
+
+export function apiError(code: string, message: string, hint?: string): ToolFailure {
+  return fail("api", code, message, hint);
+}
+
+export function dryRunResult(method: string, path: string, body?: unknown, query?: Record<string, string>): DryRunResult {
+  return {
+    ok: true,
+    dry_run: true,
+    request: { method, path, ...(body !== undefined ? { body } : {}), ...(query ? { query } : {}) },
+  };
+}
+
+// ── Error classifier ────────────────────────────────────────────
+
+import { HubApiError } from "../client.js";
+
+/**
+ * Classify a caught error into a structured ToolFailure.
+ * Uses HubApiError's typed status and code properties.
+ */
+export function classifyError(err: unknown): ToolFailure {
+  if (!(err instanceof Error)) {
+    return fail("api", "UNKNOWN", String(err));
+  }
+
+  const message = err.message;
+
+  // Network-level failures
+  if (
+    err.name === "AbortError" ||
+    message.includes("fetch failed") ||
+    message.includes("ECONNREFUSED") ||
+    message.includes("ENOTFOUND") ||
+    message.includes("network")
+  ) {
+    return fail("network", "CONNECTION_FAILED", message, "Check Hub URL and network connectivity");
+  }
+
+  // Typed Hub API errors
+  if (err instanceof HubApiError) {
+    const { status, code } = err;
+    switch (status) {
+      case 401:
+        return fail("auth", "TOKEN_EXPIRED", message, "Token refresh may have failed — try again or re-register");
+      case 403:
+        return fail("auth", code || "FORBIDDEN", message);
+      case 404:
+        return fail("api", "NOT_FOUND", message, "Verify the target ID exists via botcord_directory(action=\"resolve\")");
+      case 409:
+        return fail("api", "CONFLICT", message);
+      case 422:
+        return fail("validation", "UNPROCESSABLE", message);
+      case 429:
+        return fail("api", "RATE_LIMITED", message, "Throttle requests — 20 msg/min global, 10 msg/min per conversation");
+      default:
+        return fail("api", code || `HTTP_${status}`, message);
+    }
+  }
+
+  return fail("api", "UNKNOWN", message);
+}

package/src/tools/with-client.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared tool wrapper that eliminates boilerplate across all BotCord tools.
+ *
+ * Handles: config check → single-account guard → account resolution →
+ * client creation → token persistence → try/catch with error classification.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+import type { BotCordAccountConfig } from "../types.js";
+import { configError, classifyError, type ToolResult, type DryRunResult } from "./tool-result.js";
+
+/**
+ * Run a tool action with a fully-configured BotCordClient.
+ *
+ * The callback receives the client and resolved account config.
+ * If it returns a plain object, it is automatically wrapped in `{ ok: true, ... }`.
+ * If it returns an object that already has `ok` set, it is passed through as-is.
+ */
+export async function withClient(
+  fn: (client: BotCordClient, acct: BotCordAccountConfig) => Promise<ToolResult | DryRunResult | Record<string, unknown>>,
+): Promise<ToolResult | DryRunResult> {
+  const cfg = getAppConfig();
+  if (!cfg) {
+    return configError("No configuration available", "Run /botcord_healthcheck to diagnose");
+  }
+
+  const singleErr = getSingleAccountModeError(cfg);
+  if (singleErr) {
+    return configError(singleErr);
+  }
+
+  const acct = resolveAccountConfig(cfg);
+  if (!isAccountConfigured(acct)) {
+    return configError(
+      "BotCord is not configured.",
+      "Run botcord-register to create an identity or botcord-import to restore one",
+    );
+  }
+
+  try {
+    const client = new BotCordClient(acct);
+    attachTokenPersistence(client, acct);
+    const result = await fn(client, acct);
+
+    // If the callback already returned a structured result, pass through
+    if (result && typeof result === "object" && "ok" in result) {
+      return result as ToolResult | DryRunResult;
+    }
+
+    // Otherwise wrap in success envelope
+    return { ok: true as const, ...result };
+  } catch (err: unknown) {
+    return classifyError(err);
+  }
+}
+
+/**
+ * Lightweight version that only checks config availability (no client creation).
+ * Used by tools that don't need a BotCordClient (e.g. register, notify).
+ */
+export async function withConfig(
+  fn: (cfg: any, acct: BotCordAccountConfig) => Promise<ToolResult | DryRunResult | Record<string, unknown>>,
+): Promise<ToolResult | DryRunResult> {
+  const cfg = getAppConfig();
+  if (!cfg) {
+    return configError("No configuration available", "Run /botcord_healthcheck to diagnose");
+  }
+
+  const singleErr = getSingleAccountModeError(cfg);
+  if (singleErr) {
+    return configError(singleErr);
+  }
+
+  const acct = resolveAccountConfig(cfg);
+
+  try {
+    const result = await fn(cfg, acct);
+
+    if (result && typeof result === "object" && "ok" in result) {
+      return result as ToolResult | DryRunResult;
+    }
+
+    return { ok: true as const, ...result };
+  } catch (err: unknown) {
+    return classifyError(err);
+  }
+}

package/src/tools/working-memory.ts

@@ -1,54 +1,143 @@
 /**
  * botcord_update_working_memory — explicit tool for persisting working memory.
+ *
+ * Supports named sections for granular updates:
+ * - { goal: "..." }                         → update goal only
+ * - { section: "contacts", content: "..." } → update one section
+ * - { content: "..." }                      → update default "notes" section
+ * - { section: "old", content: "" }          → delete a section
  */
-import { writeWorkingMemory } from "../memory.js";
+import { readWorkingMemory, writeWorkingMemory } from "../memory.js";
 
-const MAX_WORKING_MEMORY_CHARS = 20_000;
+const MAX_SECTION_CHARS = 10_000;
+const MAX_GOAL_CHARS = 500;
+const MAX_TOTAL_CHARS = 20_000;
+const DEFAULT_SECTION = "notes";
 
 export function createWorkingMemoryTool() {
   return {
     name: "botcord_update_working_memory",
     label: "Update Working Memory",
     description:
-      "Replace BotCord's persistent working memory with the complete new content. " +
-      "Use only when important long-lived context changes, such as a stable fact, preference, person profile, relationship, or pending commitment that should influence future replies. " +
-      "Do not call on every turn, and do not use it for one-off chatter or room-local temporary state.",
+      "Update BotCord's persistent working memory. Memory is organized into named sections " +
+      "that are updated independently — changing one section never affects others. " +
+      "Pass 'goal' to set your work goal (pinned, survives all updates). " +
+      "Pass 'section' + 'content' to update a specific section. " +
+      "Pass only 'content' to update the default 'notes' section. " +
+      "Pass 'section' with empty 'content' to delete a section. " +
+      "Use clear section names like 'contacts', 'pending_tasks', 'preferences' (letters, digits, underscores only).",
     parameters: {
       type: "object" as const,
       properties: {
+        goal: {
+          type: "string" as const,
+          description:
+            "Set or update the agent's work goal. This is pinned and never lost when sections are updated. " +
+            `Max ${MAX_GOAL_CHARS} characters.`,
+        },
+        section: {
+          type: "string" as const,
+          description:
+            "Name of the section to update (e.g. 'contacts', 'pending_tasks', 'preferences'). " +
+            `Defaults to '${DEFAULT_SECTION}' if not specified.`,
+        },
         content: {
           type: "string" as const,
           description:
-            "The complete replacement content for working memory. " +
-            "Keep it concise and include only important facts, stable preferences, durable person/relationship context, pending commitments, and other key context that should persist across sessions and rooms.",
+            "The complete replacement content for the specified section. " +
+            "Pass empty string to delete the section. " +
+            `Max ${MAX_SECTION_CHARS} characters per section.`,
         },
       },
-      required: ["content"],
+      required: [],
     },
     execute: async (_toolCallId: any, args: any) => {
-      if (typeof args?.content !== "string") {
-        return { error: "content must be a string" };
+      // Type validation — reject wrong types explicitly
+      if (args?.goal !== undefined && typeof args.goal !== "string") {
+        return { error: "'goal' must be a string" };
+      }
+      if (args?.section !== undefined && typeof args.section !== "string") {
+        return { error: "'section' must be a string" };
+      }
+      if (args?.content !== undefined && typeof args.content !== "string") {
+        return { error: "'content' must be a string" };
+      }
+
+      const goalArg = typeof args?.goal === "string" ? args.goal.trim() : undefined;
+      const sectionArg = typeof args?.section === "string" ? args.section.trim() : undefined;
+      const contentArg = typeof args?.content === "string" ? args.content : undefined;
+
+      // Must provide at least one of goal or content
+      if (goalArg === undefined && contentArg === undefined) {
+        return { error: "Must provide at least 'goal' or 'content'" };
       }
 
-      const content = args.content.trim();
-      if (!content) {
-        return { error: "content must not be empty — use a separate mechanism to clear memory" };
+      // Validate goal
+      if (goalArg !== undefined && goalArg.length > MAX_GOAL_CHARS) {
+        return { error: `goal exceeds ${MAX_GOAL_CHARS} characters` };
       }
-      if (content.length > MAX_WORKING_MEMORY_CHARS) {
-        return { error: `content exceeds ${MAX_WORKING_MEMORY_CHARS} characters` };
+
+      // Validate section name
+      const sectionName = sectionArg || DEFAULT_SECTION;
+      if (!/^[a-zA-Z0-9_]+$/.test(sectionName)) {
+        return { error: "section name must contain only letters, digits, and underscores" };
+      }
+
+      // Validate content
+      const content = contentArg?.trim() ?? undefined;
+      if (content !== undefined && content.length > MAX_SECTION_CHARS) {
+        return { error: `content exceeds ${MAX_SECTION_CHARS} characters for section '${sectionName}'` };
       }
 
       try {
-        writeWorkingMemory({
-          version: 1,
-          content,
-          updatedAt: new Date().toISOString(),
-        });
-        return {
+        // Read existing memory (or start fresh)
+        const existing = readWorkingMemory() ?? {
+          version: 2 as const,
+          sections: {},
+          updatedAt: "",
+        };
+
+        // Update goal if provided
+        if (goalArg !== undefined) {
+          existing.goal = goalArg || undefined;
+        }
+
+        // Update section if content provided
+        if (content !== undefined) {
+          if (content === "") {
+            delete existing.sections[sectionName];
+          } else {
+            existing.sections[sectionName] = content;
+          }
+        }
+
+        // Check total size
+        const totalChars =
+          (existing.goal?.length ?? 0) +
+          Object.values(existing.sections).reduce((sum, s) => sum + s.length, 0);
+        if (totalChars > MAX_TOTAL_CHARS) {
+          return { error: `total working memory exceeds ${MAX_TOTAL_CHARS} characters (current: ${totalChars})` };
+        }
+
+        existing.updatedAt = new Date().toISOString();
+
+        writeWorkingMemory(existing);
+
+        const result: Record<string, unknown> = {
           ok: true,
-          updated: true,
-          content_length: content.length,
         };
+        if (goalArg !== undefined) {
+          result.goal_updated = true;
+        }
+        if (content !== undefined) {
+          result.section = sectionName;
+          result.section_updated = content !== "";
+          result.section_deleted = content === "";
+        }
+        result.total_sections = Object.keys(existing.sections).length;
+        result.total_chars = totalChars;
+
+        return result;
       } catch (err: unknown) {
         const message = err instanceof Error ? err.message : String(err);
         return { error: `Failed to update working memory: ${message}` };