@mcoda/codali 0.1.108 → 0.1.109

package/dist/tools/ToolTypes.d.ts

@@ -57,10 +57,45 @@ export interface ToolExecutionResult extends ToolHandlerResult {
     error?: ToolError;
 }
 export type ToolHandler = (args: unknown, context: ToolContext) => Promise<ToolHandlerResult>;
+/**
+ * Capability group a tool belongs to. The orchestrator selects capabilities
+ * first and only then sees the full schemas of the tools inside them, so this
+ * value is what keeps the planner prompt bounded as the registry grows.
+ */
+export type ToolCapability = string;
 export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema?: ToolInputSchema;
+    /** Shape of `ToolHandlerResult.data`, when the tool returns structured data. */
+    outputSchema?: ToolSchemaDefinition;
+    /**
+     * Whether the tool can mutate anything. Decided by Codali policy, never by a
+     * connector's self-description: an MCP server advertising `readOnlyHint` is a
+     * hint, not a security boundary.
+     */
+    readOnly?: boolean;
+    capability?: ToolCapability;
     handler: ToolHandler;
 }
+/**
+ * The model-facing view of a tool. Derived from {@link ToolDefinition} on
+ * demand — never stored separately, so the planner and the executor cannot
+ * drift onto different schemas.
+ */
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema?: ToolInputSchema;
+    outputSchema?: ToolSchemaDefinition;
+    readOnly: boolean;
+    capability: ToolCapability;
+}
+export declare const DEFAULT_TOOL_CAPABILITY = "general";
+/**
+ * Capability inferred from a tool name when the definition does not declare
+ * one. Names are conventionally `<capability>_<action>` (`docdex_search`) or
+ * `<source>:<server>:<tool>` for connector-backed tools.
+ */
+export declare const toolCapabilityForName: (name: string) => ToolCapability;
 //# sourceMappingURL=ToolTypes.d.ts.map

package/dist/tools/ToolTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolTypes.d.ts","sourceRoot":"","sources":["../../src/tools/ToolTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ToolTypes.d.ts","sourceRoot":"","sources":["../../src/tools/ToolTypes.ts"],"names":[],"mappings":"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"}

package/dist/tools/ToolTypes.js

@@ -42,3 +42,24 @@ export const toolErrorCategoryForCode = (code) => {
     }
     return "execution";
 };
+export const DEFAULT_TOOL_CAPABILITY = "general";
+/**
+ * Capability inferred from a tool name when the definition does not declare
+ * one. Names are conventionally `<capability>_<action>` (`docdex_search`) or
+ * `<source>:<server>:<tool>` for connector-backed tools.
+ */
+export const toolCapabilityForName = (name) => {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return DEFAULT_TOOL_CAPABILITY;
+    const namespaced = trimmed.split(":");
+    if (namespaced.length >= 3) {
+        // "mcp:github:list_issues" -> "github"
+        return namespaced[1] || DEFAULT_TOOL_CAPABILITY;
+    }
+    const underscored = trimmed.split("_");
+    if (underscored.length >= 2 && underscored[0]) {
+        return underscored[0];
+    }
+    return DEFAULT_TOOL_CAPABILITY;
+};

package/dist/tools/TruncateResult.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fitting a tool result into a budget without destroying it.
+ *
+ * Cutting a serialized payload at a character count leaves the model invalid
+ * JSON ending mid-token. Observed with `list_commits`: 12,063 characters cut at
+ * 12,000, so the model received a broken document and reported "I can only see
+ * one commit" — accurate about what survived, useless as an answer.
+ *
+ * Most oversized results are a list of similar things. Keeping whole items and
+ * saying how many were dropped preserves both validity and the fact that more
+ * exists, which is what the model needs to be honest about coverage.
+ */
+export interface TruncationResult {
+    text: string;
+    truncated: boolean;
+    /** Items kept, when the payload was a list. */
+    keptItems?: number;
+    /** Items dropped, when the payload was a list. */
+    droppedItems?: number;
+}
+/**
+ * Trims a tool result to `limit` characters.
+ *
+ * When the payload holds a list, drops whole items from the end until it fits,
+ * so the result stays parseable. Otherwise falls back to a character cut, which
+ * is still better than silence for prose.
+ */
+export declare const truncateToolResult: (raw: unknown, serialized: string, limit: number) => TruncationResult;
+//# sourceMappingURL=TruncateResult.d.ts.map

package/dist/tools/TruncateResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TruncateResult.d.ts","sourceRoot":"","sources":["../../src/tools/TruncateResult.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAkCD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,KAAK,OAAO,EACZ,YAAY,MAAM,EAClB,OAAO,MAAM,KACZ,gBA8CF,CAAC"}

package/dist/tools/TruncateResult.js

@@ -0,0 +1,91 @@
+/**
+ * Fitting a tool result into a budget without destroying it.
+ *
+ * Cutting a serialized payload at a character count leaves the model invalid
+ * JSON ending mid-token. Observed with `list_commits`: 12,063 characters cut at
+ * 12,000, so the model received a broken document and reported "I can only see
+ * one commit" — accurate about what survived, useless as an answer.
+ *
+ * Most oversized results are a list of similar things. Keeping whole items and
+ * saying how many were dropped preserves both validity and the fact that more
+ * exists, which is what the model needs to be honest about coverage.
+ */
+const NOTICE = (detail) => `\n\n[TRUNCATED: ${detail}. This result is INCOMPLETE — say so explicitly and do not present it as the full set.]`;
+/**
+ * Finds the largest array in a payload — the part worth trimming. A connector
+ * usually wraps its list in an envelope (`{ value: [...] }`, `{ issues: [...] }`),
+ * so the array is rarely at the root.
+ */
+const findLargestArray = (value, depth = 0) => {
+    if (depth > 4)
+        return undefined;
+    if (Array.isArray(value))
+        return { parent: undefined, items: value };
+    if (!value || typeof value !== "object")
+        return undefined;
+    let best;
+    for (const [key, entry] of Object.entries(value)) {
+        if (Array.isArray(entry)) {
+            if (!best || entry.length > best.items.length) {
+                best = { parent: value, key, items: entry };
+            }
+            continue;
+        }
+        const nested = findLargestArray(entry, depth + 1);
+        if (nested?.parent && (!best || nested.items.length > best.items.length)) {
+            best = { parent: nested.parent, key: nested.key, items: nested.items };
+        }
+    }
+    return best;
+};
+/**
+ * Trims a tool result to `limit` characters.
+ *
+ * When the payload holds a list, drops whole items from the end until it fits,
+ * so the result stays parseable. Otherwise falls back to a character cut, which
+ * is still better than silence for prose.
+ */
+export const truncateToolResult = (raw, serialized, limit) => {
+    if (serialized.length <= limit) {
+        return { text: serialized, truncated: false };
+    }
+    const found = findLargestArray(raw);
+    if (found && found.items.length > 1) {
+        const total = found.items.length;
+        // Binary search the largest prefix that fits, rather than dropping one at a
+        // time — a 500-item result would otherwise re-serialize 500 times.
+        let low = 1;
+        let high = total;
+        let bestFit = 1;
+        let bestText = "";
+        while (low <= high) {
+            const mid = Math.floor((low + high) / 2);
+            const kept = found.items.slice(0, mid);
+            const candidate = found.parent
+                ? { ...found.parent, [found.key]: kept }
+                : kept;
+            const text = JSON.stringify(candidate, null, 2);
+            if (text.length <= limit) {
+                bestFit = mid;
+                bestText = text;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        if (bestText) {
+            const dropped = total - bestFit;
+            return {
+                text: `${bestText}${NOTICE(`showing ${bestFit} of ${total} items; ${dropped} omitted`)}`,
+                truncated: true,
+                keptItems: bestFit,
+                droppedItems: dropped,
+            };
+        }
+    }
+    return {
+        text: `${serialized.slice(0, limit)}${NOTICE(`${serialized.length - limit} more characters were cut`)}`,
+        truncated: true,
+    };
+};

package/dist/tools/diff/DiffTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DiffTool.d.ts","sourceRoot":"","sources":["../../../src/tools/diff/DiffTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAanE,eAAO,MAAM,cAAc,QAAO,cAsBhC,CAAC"}
+{"version":3,"file":"DiffTool.d.ts","sourceRoot":"","sources":["../../../src/tools/diff/DiffTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAanE,eAAO,MAAM,cAAc,QAAO,cAwBhC,CAAC"}

package/dist/tools/diff/DiffTool.js

@@ -12,6 +12,8 @@ const runGitStatus = (cwd) => {
 export const createDiffTool = () => ({
     name: "diff_summary",
     description: "Show a git status summary of workspace changes.",
+    readOnly: true,
+    capability: "workspace",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/docdex/DocdexTools.d.ts

@@ -1,4 +1,24 @@
 import type { ToolDefinition } from "../ToolTypes.js";
 import type { DocdexClient } from "../../docdex/DocdexClient.js";
-export declare const createDocdexTools: (client: DocdexClient) => ToolDefinition[];
+/**
+ * Judges whether search results actually answer the question.
+ *
+ * Needed because presence is not relevance. The local index returns *something*
+ * for almost any query — "GDP of France 2025" scores 29.07 against this
+ * repository, higher than "gateway planner class" at 14.35, because a test
+ * fixture happens to contain the phrase. A score threshold would therefore be
+ * both arbitrary and wrong, and keyword rules ("if the query mentions GDP, go
+ * to the web") are exactly the hardcoding this project rules out.
+ *
+ * So the judgement is delegated to a model: cheap, generic, and it degrades to
+ * the old presence-based behaviour when no judge is supplied.
+ */
+export type RelevanceJudge = (input: {
+    query: string;
+    results: unknown;
+}) => Promise<boolean>;
+export interface DocdexToolOptions {
+    judgeRelevance?: RelevanceJudge;
+}
+export declare const createDocdexTools: (client: DocdexClient, options?: DocdexToolOptions) => ToolDefinition[];
 //# sourceMappingURL=DocdexTools.d.ts.map

package/dist/tools/docdex/DocdexTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAOjE,eAAO,MAAM,iBAAiB,GAAI,QAAQ,YAAY,KAAG,cAAc,EA8iBtE,CAAC"}
+{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAwEjE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,iBAAsB,KAC9B,cAAc,EAAgE,CAAC"}

package/dist/tools/docdex/DocdexTools.js

@@ -2,7 +2,70 @@ const toOutput = (payload) => ({
     output: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2),
     data: payload,
 });
-export const createDocdexTools = (client) => [
+/**
+ * Docdex tools that mutate state (index, memory, profile, repo binding). Every
+ * other docdex tool is read-only. Listed as the exception set so a newly added
+ * read tool is safe by default and a newly added write tool must be declared.
+ */
+const DOCDEX_WRITE_TOOLS = new Set([
+    "docdex_initialize",
+    "docdex_index_rebuild",
+    "docdex_index_ingest",
+    "docdex_memory_save",
+    "docdex_save_preference",
+    "docdex_delegate",
+]);
+/**
+ * Docdex is one capability from the orchestrator's point of view, except web
+ * research, which is a distinct capability ("current external information")
+ * even though docdex happens to serve it.
+ */
+const docdexCapabilityFor = (name) => name === "docdex_web_research" ? "web" : "docdex";
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Whether a docdex search payload actually returned anything usable. Docdex
+ * answers with `hits: []` rather than an error when the index has no match, so
+ * an empty result is a normal outcome that the waterfall must recognize.
+ */
+const hasSearchHits = (payload) => {
+    if (!isRecord(payload))
+        return false;
+    for (const key of ["hits", "results", "matches"]) {
+        const value = payload[key];
+        if (Array.isArray(value) && value.length > 0)
+            return true;
+    }
+    return false;
+};
+/**
+ * Whether a forced-web search actually discovered anything.
+ *
+ * Docdex reports web findings under `webDiscovery.discovery.results` and leaves
+ * `hits` empty until the fetched pages are indexed, so judging a web result by
+ * `hits` alone throws away everything it just found.
+ */
+const hasWebFindings = (payload) => {
+    if (hasSearchHits(payload))
+        return true;
+    if (!isRecord(payload))
+        return false;
+    const discovery = isRecord(payload.webDiscovery) ? payload.webDiscovery : undefined;
+    if (!discovery)
+        return false;
+    const inner = isRecord(discovery.discovery) ? discovery.discovery : undefined;
+    const results = inner?.results ?? discovery.results;
+    if (Array.isArray(results) && results.length > 0)
+        return true;
+    const fetches = discovery.fetches;
+    return Array.isArray(fetches) && fetches.length > 0;
+};
+const withDocdexMetadata = (tools) => tools.map((tool) => ({
+    ...tool,
+    readOnly: tool.readOnly ?? !DOCDEX_WRITE_TOOLS.has(tool.name),
+    capability: tool.capability ?? docdexCapabilityFor(tool.name),
+}));
+export const createDocdexTools = (client, options = {}) => withDocdexMetadata(docdexToolDefinitions(client, options));
+const docdexToolDefinitions = (client, options) => [
     {
         name: "docdex_health",
         description: "Check docdex healthz endpoint.",
@@ -30,7 +93,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_search",
-        description: "Search docdex index.",
+        description: "Search the indexed repository and organizational memory for code, docs, and prior decisions. Ranked snippets with file paths and doc ids. Searches locally first and falls back to the web when the local index has nothing relevant, so this is the default tool for both repo questions and general external questions.",
         inputSchema: {
             type: "object",
             required: ["query"],
@@ -41,13 +104,42 @@ export const createDocdexTools = (client) => [
         },
         handler: async (args) => {
             const { query, limit } = args;
-            const result = await client.search(query, { limit });
-            return toOutput(result);
+            const local = await client.search(query, { limit });
+            // The local-then-web waterfall lives here, inside the search tool, rather
+            // than in the orchestrator. The orchestrator should only have to know
+            // "search"; whether an answer comes from the repository index or the
+            // public web is an implementation detail of searching. Putting this
+            // decision in the router would make it special-case logic that every new
+            // question type has to be taught.
+            let localAnswers = hasSearchHits(local);
+            // Hits alone do not mean the question was answered. Ask a model whether
+            // they are actually relevant before settling for them.
+            if (localAnswers && options.judgeRelevance) {
+                try {
+                    localAnswers = await options.judgeRelevance({ query, results: local });
+                }
+                catch {
+                    // A judge that fails must not block a search that already succeeded.
+                }
+            }
+            if (!localAnswers) {
+                try {
+                    const web = await client.search(query, { limit, forceWeb: true });
+                    if (hasWebFindings(web)) {
+                        return toOutput(web);
+                    }
+                }
+                catch {
+                    // Web discovery being unavailable must not fail a local search that
+                    // simply found nothing. Return the local (empty) result instead.
+                }
+            }
+            return toOutput(local);
         },
     },
     {
         name: "docdex_open",
-        description: "Open a file by path or fetch a snippet by doc id.",
+        description: "Read an exact slice of a file, either by repo-relative path or by a doc id returned from a search. Use after a search has identified a target rather than guessing paths.",
         inputSchema: {
             type: "object",
             properties: {
@@ -76,7 +168,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_symbols",
-        description: "Fetch docdex symbols for a file.",
+        description: "List the definitions in a file with their exact signatures and line numbers - functions, classes, methods, exported constants. Use to confirm where something is defined before relying on it.",
         inputSchema: {
             type: "object",
             required: ["path"],
@@ -92,7 +184,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_ast",
-        description: "Fetch docdex AST nodes for a file.",
+        description: "Query a file's syntax tree for precise structure: class and function definitions, call sites, imports. More exact than text search when the question is structural.",
         inputSchema: {
             type: "object",
             required: ["path"],
@@ -109,7 +201,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_impact_graph",
-        description: "Fetch docdex impact graph for a file.",
+        description: "Show what depends on a file and what it depends on. Answers \"what breaks if this changes\" and identifies the blast radius of an edit.",
         inputSchema: {
             type: "object",
             required: ["file"],
@@ -128,7 +220,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_impact_diagnostics",
-        description: "Fetch docdex impact diagnostics (dynamic imports).",
+        description: "List unresolved or dynamic imports that the dependency graph could not follow, so gaps in impact analysis are visible rather than silent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -163,7 +255,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_tree",
-        description: "Render a folder tree from docdex.",
+        description: "Render the repository folder tree with build output and vendor directories excluded. Use to orient in an unfamiliar repo instead of listing directories manually.",
         inputSchema: {
             type: "object",
             properties: {
@@ -218,7 +310,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_get_profile",
-        description: "Fetch docdex profile preferences.",
+        description: "Read stored global preferences and constraints that should shape the answer, such as style rules or disallowed libraries.",
         inputSchema: {
             type: "object",
             properties: {
@@ -251,7 +343,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_memory_recall",
-        description: "Recall repo memory from docdex.",
+        description: "Recall durable facts previously recorded about this repository - architectural decisions, gotchas, where things live.",
         inputSchema: {
             type: "object",
             required: ["query"],
@@ -268,7 +360,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_web_research",
-        description: "Run docdex web research (requires DOCDEX_WEB_ENABLED=1).",
+        description: "Search the public web for current external information: facts, news, third-party documentation, anything not in this repository. Returns sourced results with URLs.",
         inputSchema: {
             type: "object",
             required: ["query"],
@@ -343,7 +435,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_batch_search",
-        description: "Run batched docdex search queries via optional batch endpoint/tool.",
+        description: "Run several related search queries in one call. Use when a question decomposes into multiple independent lookups, to save round trips.",
         inputSchema: {
             type: "object",
             required: ["queries"],
@@ -376,7 +468,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_stats",
-        description: "Fetch docdex index stats.",
+        description: "Report index size and when it was last updated. Use to detect a stale index before trusting a negative search result.",
         inputSchema: { type: "object", properties: {} },
         handler: async () => {
             const result = await client.stats();
@@ -385,7 +477,7 @@ export const createDocdexTools = (client) => [
     },
     {
         name: "docdex_files",
-        description: "List docdex indexed files.",
+        description: "List the files currently present in the index, to confirm coverage before concluding that something does not exist.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/filesystem/FileTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../src/tools/filesystem/FileTools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgEnE,eAAO,MAAM,eAAe,QAAO,cAAc,EAwFhD,CAAC"}
+{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../src/tools/filesystem/FileTools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgEnE,eAAO,MAAM,eAAe,QAAO,cAAc,EAgGhD,CAAC"}

package/dist/tools/filesystem/FileTools.js

@@ -55,6 +55,8 @@ export const createFileTools = () => {
         {
             name: "read_file",
             description: "Read a text file from the workspace.",
+            readOnly: true,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 required: ["path"],
@@ -73,6 +75,8 @@ export const createFileTools = () => {
         {
             name: "write_file",
             description: "Write content to a file inside the workspace.",
+            readOnly: false,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 required: ["path", "content"],
@@ -96,6 +100,8 @@ export const createFileTools = () => {
         {
             name: "list_files",
             description: "List files under a directory within the workspace.",
+            readOnly: true,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -115,6 +121,8 @@ export const createFileTools = () => {
         {
             name: "stat_path",
             description: "Get stat info for a file or directory.",
+            readOnly: true,
+            capability: "workspace",
             inputSchema: {
                 type: "object",
                 required: ["path"],

package/dist/tools/search/SearchTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SearchTool.d.ts","sourceRoot":"","sources":["../../../src/tools/search/SearchTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA0BnE,eAAO,MAAM,gBAAgB,QAAO,cAwBlC,CAAC"}
+{"version":3,"file":"SearchTool.d.ts","sourceRoot":"","sources":["../../../src/tools/search/SearchTool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA0BnE,eAAO,MAAM,gBAAgB,QAAO,cA0BlC,CAAC"}

package/dist/tools/search/SearchTool.js

@@ -22,7 +22,9 @@ const runGrepFallback = (query, cwd) => {
 };
 export const createSearchTool = () => ({
     name: "search_repo",
-    description: "Search for text in the workspace using rg when available.",
+    description: "Search for literal text in the working tree. Use when an exact string is known; prefer docdex_search for conceptual questions.",
+    readOnly: true,
+    capability: "workspace",
     inputSchema: {
         type: "object",
         required: ["query"],

package/dist/tools/shell/ShellTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShellTool.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellTool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA2C5F,eAAO,MAAM,eAAe,QAAO,cAyEjC,CAAC"}
+{"version":3,"file":"ShellTool.d.ts","sourceRoot":"","sources":["../../../src/tools/shell/ShellTool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA2C5F,eAAO,MAAM,eAAe,QAAO,cA2EjC,CAAC"}

package/dist/tools/shell/ShellTool.js

@@ -41,6 +41,8 @@ const isDestructiveShellAction = (command, args) => {
 export const createShellTool = () => ({
     name: "run_shell",
     description: "Run a shell command from the workspace root (allowlist only).",
+    readOnly: false,
+    capability: "shell",
     inputSchema: {
         type: "object",
         required: ["command"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/codali",
-  "version": "0.1.108",
+  "version": "0.1.109",
   "description": "Standalone tool-runner adapter for mcoda.",
   "type": "module",
   "main": "dist/index.js",
@@ -34,8 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcoda/db": "0.1.108",
-    "@mcoda/shared": "0.1.108"
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@mcoda/db": "0.1.109",
+    "@mcoda/shared": "0.1.109"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",