@ouro.bot/cli 0.1.0-alpha.175 → 0.1.0-alpha.176

package/dist/nerves/coverage/audit.js

@@ -92,7 +92,7 @@ function scanSourceFiles(sourceRoot) {
                     continue;
                 walkDir(full);
             }
-            else if (entry.name.endsWith(".ts")) {
+            else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts")) {
                 const content = (0, fs_1.readFileSync)(full, "utf8");
                 const relPath = full.slice(root.length - "src".length);
                 fileContents.set(relPath, content);

package/dist/repertoire/ado-semantic.js

@@ -221,7 +221,7 @@ exports.adoSemanticToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_backlog_list",
-                description: "Query the backlog and return enriched work items with hierarchy, type, parent, assignee, area path, and iteration. Supports filtering. Use this instead of raw WIQL queries.",
+                description: "Query the backlog and return enriched work items with hierarchy, type, parent, assignee, area path, and iteration. Supports filtering. Use this instead of raw WIQL queries. Provides enriched results with hierarchy.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -287,7 +287,7 @@ exports.adoSemanticToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_create_epic",
-                description: "Create an epic in Azure DevOps with title, description, area path, and optional parent.",
+                description: "Create an epic in Azure DevOps with title, description, area path, and optional parent. Use ado_preview_changes first to dry-run the operation.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -327,7 +327,7 @@ exports.adoSemanticToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_create_issue",
-                description: "Create an issue or user story in Azure DevOps with title, description, area path, and parent epic.",
+                description: "Create an issue or user story in Azure DevOps with title, description, area path, and parent epic. Use ado_preview_changes first to dry-run the operation.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -369,7 +369,7 @@ exports.adoSemanticToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_move_items",
-                description: "Reparent work items -- move them to a new parent epic or feature.",
+                description: "Reparent work items -- move them to a new parent epic or feature. Use ado_preview_changes first. These mutations affect real work items.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -424,7 +424,7 @@ exports.adoSemanticToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_restructure_backlog",
-                description: "Bulk restructure: reparent multiple work items in a single logical operation.",
+                description: "Bulk restructure: reparent multiple work items in a single logical operation. Use ado_preview_changes first. These mutations affect real work items.",
                 parameters: {
                     type: "object",
                     properties: {

package/dist/repertoire/coding/tools.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codingToolDefinitions = void 0;
+exports.countFilesInSessionOutput = countFilesInSessionOutput;
 const index_1 = require("./index");
 const context_pack_1 = require("./context-pack");
 const identity_1 = require("../../heart/identity");
 const obligations_1 = require("../../heart/obligations");
 const runtime_1 = require("../../nerves/runtime");
+const scrutiny_1 = require("../../mind/scrutiny");
 const RUNNERS = ["claude", "codex"];
 function requireArg(args, key) {
     const value = args[key];
@@ -32,6 +34,34 @@ function emitCodingToolEvent(toolName) {
         meta: { toolName },
     });
 }
+/**
+ * Count distinct file paths mentioned in a coding session's stdout output.
+ * Looks for path-like tokens (containing / and a file extension).
+ * Returns the count of unique paths found.
+ */
+function countFilesInSessionOutput(session) {
+    const text = `${session.stdoutTail}\n${session.stderrTail}`;
+    // Match path-like tokens: contain at least one / and a file extension
+    const pathPattern = /(?:^|\s)((?:\/|\.\/|\.\.\/)?(?:[\w.@-]+\/)+[\w.-]+\.[\w]+)/gm;
+    const paths = new Set();
+    let match;
+    while ((match = pathPattern.exec(text)) !== null) {
+        paths.add(match[1]);
+    }
+    return paths.size;
+}
+/**
+ * If a coding session is completed, append scrutiny to the result.
+ * Returns the original result with scrutiny appended, or unchanged if
+ * the session is not completed or has no file changes.
+ */
+function appendCompletionScrutiny(result, session) {
+    if (session.status !== "completed")
+        return result;
+    const fileCount = countFilesInSessionOutput(session);
+    const scrutiny = (0, scrutiny_1.getCodingCompletionScrutiny)(fileCount);
+    return scrutiny ? `${result}\n\n${scrutiny}` : result;
+}
 function sameOriginSession(left, right) {
     if (!left && !right)
         return true;
@@ -109,7 +139,7 @@ const codingSpawnTool = {
     type: "function",
     function: {
         name: "coding_spawn",
-        description: "spawn a coding session using claude/codex and explicit task-threaded guidance",
+        description: "Spawn a coding session using claude or codex with task-threaded guidance. The coding session runs as a separate process with its own context. Give it a COMPLETE, SELF-CONTAINED task description -- it cannot see this conversation, doesn't know what you've tried, doesn't understand the broader context. Include: what to do, why, what files are involved, what 'done' looks like. Never delegate understanding -- don't write 'based on the conversation, fix the bug.' Write the specific file paths, line numbers, and what to change. Include any required verification steps or tests in the task description so the coding session knows how to prove the work is done.",
         parameters: {
             type: "object",
             properties: {
@@ -128,7 +158,7 @@ const codingStatusTool = {
     type: "function",
     function: {
         name: "coding_status",
-        description: "inspect coding sessions; omit sessionId to list all active/known sessions",
+        description: "Inspect coding sessions. Omit sessionId to list all active/known sessions with their status. Use this to check progress before asking the human for a status update.",
         parameters: {
             type: "object",
             properties: {
@@ -141,7 +171,7 @@ const codingTailTool = {
     type: "function",
     function: {
         name: "coding_tail",
-        description: "show recent stdout/stderr tail for a coding session in a readable format",
+        description: "Show recent stdout/stderr output from a coding session. Use this to understand what the session is doing or why it might be stuck. Read the actual output before reporting status -- don't guess.",
         parameters: {
             type: "object",
             properties: {
@@ -293,7 +323,7 @@ exports.codingToolDefinitions = [
             const session = manager.getSession(sessionId);
             if (!session)
                 return `session not found: ${sessionId}`;
-            return JSON.stringify(session);
+            return appendCompletionScrutiny(JSON.stringify(session), session);
         },
         summaryKeys: ["sessionId"],
     },
@@ -307,7 +337,7 @@ exports.codingToolDefinitions = [
             const session = (0, index_1.getCodingSessionManager)().getSession(sessionId);
             if (!session)
                 return `session not found: ${sessionId}`;
-            return (0, index_1.formatCodingTail)(session);
+            return appendCompletionScrutiny((0, index_1.formatCodingTail)(session), session);
         },
         summaryKeys: ["sessionId"],
     },

package/dist/repertoire/shell-sessions.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnBackgroundShell = spawnBackgroundShell;
+exports.getShellSession = getShellSession;
+exports.listShellSessions = listShellSessions;
+exports.tailShellSession = tailShellSession;
+exports.resetShellSessions = resetShellSessions;
+exports.detectDestructivePatterns = detectDestructivePatterns;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const runtime_1 = require("../nerves/runtime");
+const sessions = new Map();
+const MAX_OUTPUT_LINES = 200;
+function spawnBackgroundShell(command) {
+    const id = (0, crypto_1.randomUUID)();
+    const proc = (0, child_process_1.spawn)("sh", ["-c", command], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const session = {
+        process: proc,
+        info: {
+            id,
+            command,
+            status: "running",
+            exitCode: null,
+            pid: proc.pid,
+            startedAt: Date.now(),
+            output: [],
+        },
+    };
+    const appendOutput = (data) => {
+        const lines = data.toString().split("\n");
+        for (const line of lines) {
+            if (line.length > 0 || session.info.output.length > 0) {
+                session.info.output.push(line);
+            }
+        }
+        // Keep only the last MAX_OUTPUT_LINES
+        if (session.info.output.length > MAX_OUTPUT_LINES) {
+            session.info.output = session.info.output.slice(-MAX_OUTPUT_LINES);
+        }
+    };
+    proc.stdout?.on("data", appendOutput);
+    proc.stderr?.on("data", appendOutput);
+    proc.on("close", (code) => {
+        session.info.status = "exited";
+        session.info.exitCode = code;
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.shell.process_exit",
+            message: "background shell process exited",
+            meta: { id, command, exitCode: code, pid: proc.pid },
+        });
+    });
+    sessions.set(id, session);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.shell.spawn",
+        message: "spawned background shell session",
+        meta: { id, command, pid: proc.pid },
+    });
+    return { ...session.info };
+}
+function getShellSession(id) {
+    const session = sessions.get(id);
+    if (!session)
+        return undefined;
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.shell.status_check",
+        message: "checked shell session status",
+        meta: { id, status: session.info.status, exitCode: session.info.exitCode },
+    });
+    return { ...session.info };
+}
+function listShellSessions() {
+    return Array.from(sessions.values()).map((s) => ({
+        id: s.info.id,
+        command: s.info.command,
+        status: s.info.status,
+        exitCode: s.info.exitCode,
+        pid: s.info.pid,
+        startedAt: s.info.startedAt,
+        output: [], // Don't include full output in listing
+    }));
+}
+function tailShellSession(id, lines = 50) {
+    const session = sessions.get(id);
+    if (!session)
+        return undefined;
+    const tail = session.info.output.slice(-lines);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.shell.tail",
+        message: "tailed shell session output",
+        meta: { id, requestedLines: lines, returnedLines: tail.length },
+    });
+    return tail.join("\n");
+}
+/** Reset all sessions (for testing) */
+function resetShellSessions() {
+    for (const session of sessions.values()) {
+        if (session.info.status === "running") {
+            session.process.kill();
+        }
+    }
+    sessions.clear();
+}
+const DESTRUCTIVE_PATTERNS = [
+    { name: "rm -rf root/home", regex: /rm\s+-rf\s+[/~]/ },
+    { name: "git push --force", regex: /git\s+push\s+--force/ },
+    { name: "git reset --hard", regex: /git\s+reset\s+--hard/ },
+    { name: "git clean -f", regex: /git\s+clean\s+-f/ },
+    { name: "git branch -D", regex: /git\s+branch\s+-D/ },
+    { name: "fork bomb", regex: /:\(\)\s*\{/ },
+    { name: "write to raw device", regex: />\s*\/dev\/sd/ },
+    { name: "git checkout .", regex: /git\s+checkout\s+\./ },
+    { name: "git stash drop", regex: /git\s+stash\s+drop/ },
+];
+/**
+ * Detect destructive patterns in a shell command.
+ * Returns list of matched pattern names. Empty array = safe.
+ * This is a friction layer, not a hard block.
+ */
+function detectDestructivePatterns(command) {
+    const matched = [];
+    for (const pattern of DESTRUCTIVE_PATTERNS) {
+        if (pattern.regex.test(command)) {
+            matched.push(pattern.name);
+        }
+    }
+    return matched;
+}

package/dist/repertoire/tools-base.js

@@ -40,8 +40,11 @@ const fg = __importStar(require("fast-glob"));
 const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
 const skills_1 = require("./skills");
+const shell_sessions_1 = require("./shell-sessions");
 const config_1 = require("../heart/config");
 const runtime_1 = require("../nerves/runtime");
+const file_state_1 = require("../mind/file-state");
+const scrutiny_1 = require("../mind/scrutiny");
 const identity_1 = require("../heart/identity");
 const identity_2 = require("../heart/identity");
 const socket_client_1 = require("../heart/daemon/socket-client");
@@ -337,7 +340,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "read_file",
-                description: "read file contents",
+                description: "Read file contents. Results include line numbers. Use offset/limit for large files -- don't read the whole thing if you only need a section. Use this tool before editing any file. When reading code, read enough context to understand the surrounding logic, not just the target line.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -355,6 +358,17 @@ exports.baseToolDefinitions = [
             exports.editFileReadTracker.add(resolvedPath);
             const offset = a.offset ? parseInt(a.offset, 10) : undefined;
             const limit = a.limit ? parseInt(a.limit, 10) : undefined;
+            // Record in file state cache for staleness detection
+            try {
+                const mtime = fs.statSync(resolvedPath).mtimeMs;
+                const readContent = (offset === undefined && limit === undefined)
+                    ? content
+                    : content.split("\n").slice(offset ? offset - 1 : 0, limit !== undefined ? (offset ? offset - 1 : 0) + limit : undefined).join("\n");
+                file_state_1.fileStateCache.record(resolvedPath, readContent, mtime, offset, limit);
+            }
+            catch {
+                // stat failed -- skip cache recording
+            }
             if (offset === undefined && limit === undefined)
                 return content;
             const lines = content.split("\n");
@@ -369,7 +383,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "write_file",
-                description: "write content to file",
+                description: "Prefer this tool for creating new files or fully replacing existing ones. You MUST read an existing file with read_file before overwriting it. Prefer edit_file for modifying existing files -- it only sends the diff. Do not create documentation files (*.md, README) by default; only do so when explicitly asked or when documentation is clearly part of the requested change.",
                 parameters: {
                     type: "object",
                     properties: { path: { type: "string" }, content: { type: "string" } },
@@ -381,7 +395,10 @@ exports.baseToolDefinitions = [
             const resolvedPath = resolveLocalToolPath(a.path);
             fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
             fs.writeFileSync(resolvedPath, a.content, "utf-8");
-            return "ok";
+            (0, scrutiny_1.trackModifiedFile)(resolvedPath);
+            const scrutiny = (0, scrutiny_1.getPostImplementationScrutiny)((0, scrutiny_1.getModifiedFileCount)());
+            /* v8 ignore next -- scrutiny appendix branch depends on session-level file count @preserve */
+            return scrutiny ? `ok\n\n${scrutiny}` : "ok";
         },
         summaryKeys: ["path"],
     },
@@ -390,7 +407,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "edit_file",
-                description: "surgically edit a file by replacing an exact string. the file must have been read via read_file first. old_string must match exactly one location in the file.",
+                description: "Surgically edit a file by replacing an exact string. The file MUST have been read via read_file first -- this tool will reject the call otherwise. old_string must match EXACTLY ONE location in the file -- if it matches zero or multiple, the edit fails. To fix: provide more surrounding context to make the match unique. Preserve exact indentation (tabs/spaces) from the file. Prefer this over write_file for modifications -- it only sends the diff.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -407,6 +424,8 @@ exports.baseToolDefinitions = [
             if (!exports.editFileReadTracker.has(resolvedPath)) {
                 return `error: you must read the file with read_file before editing it. call read_file on ${a.path} first.`;
             }
+            // Check staleness before editing
+            const stalenessCheck = file_state_1.fileStateCache.isStale(resolvedPath);
             let content;
             try {
                 content = fs.readFileSync(resolvedPath, "utf-8");
@@ -434,13 +453,33 @@ exports.baseToolDefinitions = [
             const idx = occurrences[0];
             const updated = content.slice(0, idx) + a.new_string + content.slice(idx + a.old_string.length);
             fs.writeFileSync(resolvedPath, updated, "utf-8");
+            // Update file state cache with new content
+            try {
+                const newMtime = fs.statSync(resolvedPath).mtimeMs;
+                file_state_1.fileStateCache.record(resolvedPath, updated, newMtime);
+            }
+            catch {
+                // stat failed -- skip cache update
+            }
             // Build contextual diff
             const lines = updated.split("\n");
             const prefixLines = content.slice(0, idx).split("\n");
             const changeStartLine = prefixLines.length - 1;
             const newStringLines = a.new_string.split("\n");
             const changeEndLine = changeStartLine + newStringLines.length;
-            return buildContextDiff(lines, changeStartLine, changeEndLine);
+            const diffResult = buildContextDiff(lines, changeStartLine, changeEndLine);
+            // Track modified file and compute scrutiny appendix
+            (0, scrutiny_1.trackModifiedFile)(resolvedPath);
+            const scrutiny = (0, scrutiny_1.getPostImplementationScrutiny)((0, scrutiny_1.getModifiedFileCount)());
+            // Append staleness warning if detected (do not block -- TTFA)
+            /* v8 ignore start -- staleness+diff+scrutiny combo not exercised in integration tests @preserve */
+            if (stalenessCheck.stale) {
+                const base = `${diffResult}\n\n⚠️ warning: file changed externally since last read -- re-read recommended`;
+                return scrutiny ? `${base}\n\n${scrutiny}` : base;
+            }
+            /* v8 ignore stop */
+            /* v8 ignore next -- scrutiny appendix branch depends on session-level file count @preserve */
+            return scrutiny ? `${diffResult}\n\n${scrutiny}` : diffResult;
         },
         summaryKeys: ["path"],
     },
@@ -449,7 +488,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "glob",
-                description: "find files matching a glob pattern. returns matching paths sorted alphabetically, one per line.",
+                description: "Find files matching a glob pattern, sorted alphabetically. Use this instead of shell commands like `find` or `ls`. For broad exploratory searches that would require multiple rounds of globbing and grepping, consider using claude or coding_spawn.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -472,7 +511,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "grep",
-                description: "search file contents for lines matching a regex pattern. searches recursively when given a directory. returns matching lines with file path and line numbers.",
+                description: "Search file contents for lines matching a regex pattern. Searches recursively in directories. Use this instead of shell commands like `grep` or `rg`. Returns matching lines with file path and line numbers. Use context_lines for surrounding context. Use include to filter file types (e.g., '*.ts').",
                 parameters: {
                     type: "object",
                     properties: {
@@ -581,22 +620,112 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "shell",
-                description: "run shell command",
+                description: "Run a shell command and return stdout/stderr. Working directory persists between calls. Use dedicated tools instead of shell when available: read_file instead of cat, edit_file instead of sed, glob instead of find, grep instead of grep/rg. Reserve shell for operations that genuinely need the shell: installing packages, running builds/tests, git operations, process management. Be careful with destructive commands -- consider reversibility before running. If a command fails, read the error output before retrying with a different approach.",
                 parameters: {
                     type: "object",
-                    properties: { command: { type: "string" } },
+                    properties: {
+                        command: { type: "string" },
+                        timeout_ms: {
+                            type: "number",
+                            description: "Timeout in milliseconds. Default: 30000. Max: 600000.",
+                        },
+                        background: {
+                            type: "boolean",
+                            description: "Run in background. Returns immediately with a process ID. Use shell_status/shell_tail to monitor.",
+                        },
+                    },
                     required: ["command"],
                 },
             },
         },
         handler: (a) => {
-            return (0, child_process_1.execSync)(a.command, {
+            // Destructive pattern detection (friction, not a block)
+            const destructivePatterns = (0, shell_sessions_1.detectDestructivePatterns)(a.command);
+            if (destructivePatterns.length > 0) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    event: "tool.shell.destructive_detected",
+                    component: "tools",
+                    message: `destructive pattern detected: ${destructivePatterns.join(", ")}`,
+                    meta: { command: a.command, patterns: destructivePatterns },
+                });
+            }
+            // Background mode: spawn and return immediately
+            if (a.background === "true") {
+                const session = (0, shell_sessions_1.spawnBackgroundShell)(a.command);
+                return JSON.stringify({ id: session.id, command: session.command, status: session.status });
+            }
+            const MAX_TIMEOUT = 600000;
+            const requestedTimeout = Number(a.timeout_ms) || 0;
+            let configDefault = 30000;
+            try {
+                configDefault = (0, identity_1.loadAgentConfig)().shell?.defaultTimeout ?? 30000;
+            }
+            catch { /* test env: no --agent flag */ }
+            const baseTimeout = requestedTimeout > 0 ? requestedTimeout : configDefault;
+            const timeout = Math.min(baseTimeout, MAX_TIMEOUT);
+            const output = (0, child_process_1.execSync)(a.command, {
                 encoding: "utf-8",
-                timeout: 30000,
+                timeout,
             });
+            if (destructivePatterns.length > 0) {
+                return `${output}\n\n--- destructive pattern detected: ${destructivePatterns.join(", ")} ---`;
+            }
+            return output;
         },
         summaryKeys: ["command"],
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "shell_status",
+                description: "Check status of background shell processes. Omit id to list all.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Background shell process ID" },
+                    },
+                },
+            },
+        },
+        handler: (a) => {
+            if (!a.id) {
+                return JSON.stringify((0, shell_sessions_1.listShellSessions)());
+            }
+            const session = (0, shell_sessions_1.getShellSession)(a.id);
+            if (!session)
+                return `process not found: ${a.id}`;
+            return JSON.stringify(session);
+        },
+        summaryKeys: ["id"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "shell_tail",
+                description: "Show recent output from a background shell process.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Background shell process ID" },
+                    },
+                    required: ["id"],
+                },
+            },
+        },
+        handler: (a) => {
+            /* v8 ignore next -- schema requires id, defensive guard @preserve */
+            if (!a.id)
+                return "id is required";
+            const output = (0, shell_sessions_1.tailShellSession)(a.id);
+            if (output === undefined)
+                return `process not found: ${a.id}`;
+            return output || "(no output yet)";
+        },
+        summaryKeys: ["id"],
+    },
     {
         tool: {
             type: "function",
@@ -636,7 +765,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "claude",
-                description: "use claude code to query this codebase or get an outside perspective. useful for code review, second opinions, and asking questions about your own source.",
+                description: "use claude code to query this codebase or get an outside perspective. Use for code review, second opinions, or questions that benefit from a fresh perspective outside this conversation's context.",
                 parameters: {
                     type: "object",
                     properties: { prompt: { type: "string" } },
@@ -709,7 +838,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "recall",
-                description: "recall what i know — search my diary and journal for facts, thoughts, and working notes that match a query",
+                description: "Search my diary and journal for facts, thoughts, and working notes matching a query. Uses semantic similarity -- phrasing matters. Try different angles if the first query doesn't find what you're looking for. Check recall before asking the human something you might already know.",
                 parameters: {
                     type: "object",
                     properties: { query: { type: "string" } },
@@ -762,7 +891,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "diary_write",
-                description: "write an entry in my diary — something i learned, noticed, or concluded that i want to recall later. optional 'about' tags the entry to a person, topic, or context.",
+                description: "Write an entry in my diary -- something I learned, noticed, or concluded that I want to recall later. Use 'about' to tag the entry to a person, topic, or context. Write for my future self: include enough context that the entry makes sense without the surrounding conversation. Prefer durable conclusions over passing noise. Don't duplicate what already belongs in friend notes.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -1376,7 +1505,7 @@ exports.ponderTool = {
     type: "function",
     function: {
         name: "ponder",
-        description: "i need to sit with this. from a conversation, takes the thread inward with a thought and a parting word. from inner dialog, keeps the wheel turning for another pass. must be the only tool call in the turn.",
+        description: "i need to sit with this. from a conversation, takes the thread inward with a thought and a parting word. from inner dialog, keeps the wheel turning for another pass. must be the only tool call in the turn. Use when a question deserves more thought than this turn allows. Don't ponder trivial questions.",
         parameters: {
             type: "object",
             properties: {
@@ -1409,7 +1538,7 @@ exports.settleTool = {
     type: "function",
     function: {
         name: "settle",
-        description: "respond to the user with your message. call this tool when you are ready to deliver your response.",
+        description: "respond to the user with your message. call this tool when you are ready to deliver your response. Only call when you have a substantive response. If you're settling with 'I'll look into that,' you probably should be using a tool instead.",
         parameters: {
             type: "object",
             properties: {

package/dist/repertoire/tools.js

@@ -38,6 +38,7 @@ exports.getToolsForChannel = getToolsForChannel;
 exports.isConfirmationRequired = isConfirmationRequired;
 exports.execTool = execTool;
 exports.summarizeArgs = summarizeArgs;
+exports.buildToolResultSummary = buildToolResultSummary;
 const tools_base_1 = require("./tools-base");
 const tools_teams_1 = require("./tools-teams");
 const tools_bluebubbles_1 = require("./tools-bluebubbles");
@@ -387,3 +388,39 @@ function summarizeArgs(name, args) {
     }
     return summarizeUnknownArgs(args);
 }
+/**
+ * Build an enriched tool result summary for display on remote channels.
+ * For recognized tools, includes result-derived info (diff stats, exit codes, etc.).
+ * Falls back to arg-based summary for unrecognized tools.
+ */
+function buildToolResultSummary(name, args, _result, success) {
+    switch (name) {
+        case "edit_file": {
+            if (!success)
+                return summarizeArgs(name, args);
+            const addedLines = (args.new_string ?? "").split("\n").length;
+            const removedLines = (args.old_string ?? "").split("\n").length;
+            return `+${addedLines} -${removedLines} lines in ${args.path ?? "unknown"}`;
+        }
+        case "shell": {
+            const cmd = args.command ?? "?";
+            const exitCode = success ? 0 : 1;
+            return `$ ${cmd} (exit ${exitCode})`;
+        }
+        case "read_file":
+            return `path=${args.path ?? "unknown"}`;
+        case "write_file":
+            return `path=${args.path ?? "unknown"}`;
+        case "glob":
+            return `pattern=${args.pattern ?? "?"} ${args.cwd ? `cwd=${args.cwd}` : ""}`.trim();
+        case "grep":
+            return `pattern=${args.pattern ?? "?"} ${args.path ? `path=${args.path}` : ""}`.trim();
+        case "coding_spawn": {
+            const taskRef = args.taskRef ?? "unknown";
+            const status = success ? "spawned" : "failed";
+            return `${taskRef} -> ${status}`;
+        }
+        default:
+            return summarizeArgs(name, args);
+    }
+}