agent-nuvira 3.3.13 → 3.3.14

package/dist/tools/registry.js

@@ -27,7 +27,16 @@ import { envBuff } from '../config/paths.js';
 import { z, toJSONSchema } from 'zod';
 import { ACTION_BY_INTENT } from '../nlu/actions.js';
 import { detectPermissionSeeking, IRREVERSIBLE_ACTION_RE } from '../learning/autonomy-policy.js';
+// The explicit, session-scoped "allow all <category> for this session" grant —
+// offered at the confirmation a state-changing tool demanded (see the
+// `ask_user` runner) and consulted by the write/terminal gates.
+import { grantSession, sessionGrantLabel, sessionGrantNotice, } from '../learning/session-grant.js';
+// Cluster G — a folder the user names in an ask_user reply IS the workspace
+// (see the adoption block in the `ask_user` runner). The rule is the same,
+// conservative one the dashboard server applies to a message.
+import { directoryFromMessage } from '../utils/workspace-path.js';
 import { createFindingTool } from './finding-tool.js';
+import { declareToolCapability } from './capability-registry.js';
 import { recordArtifact } from './artifact-append.js';
 import { checkStepArtifacts } from './step-artifact.js';
 // ─── Tool definitions ───────────────────────────────────────────────────────
@@ -94,6 +103,19 @@ const askUserSchema = z.object({
         .describe('2–4 answer choices the user can pick from'),
     multi_select: z.boolean().default(false).describe('Allow multiple selections (checkbox)'),
 });
+/**
+ * The extra choice a TOOL-DEMANDED confirmation ask offers: allow this whole
+ * category of state-changing action for the rest of the session. Deliberately
+ * one fixed label, so the grant is a choice the user picks — never a phrase
+ * the harness tries to recognise in free text.
+ */
+const SESSION_GRANT_CHOICE_LABEL = 'Allow this for the whole session';
+/** Did the user's answer (single-select or multi-select) name the grant choice? */
+function answerIsSessionGrant(answer) {
+    return Array.isArray(answer)
+        ? answer.includes(SESSION_GRANT_CHOICE_LABEL)
+        : answer === SESSION_GRANT_CHOICE_LABEL;
+}
 /** E3c — publish tool args: bump type + safety flags (irreversible action). */
 export const publishToolSchema = z.object({
     goal: z.string().optional().describe('Optional release goal (e.g. "Release v1.2.0")'),
@@ -307,8 +329,12 @@ const editFileSchema = z.object({
 });
 /** P0.3 — write_file tool args: create/overwrite a file (confirmed). */
 const writeFileSchema = z.object({
-    path: z.string().describe('Path to write, relative to the workspace root (parent directories are created as needed). Overwrites existing content.'),
-    content: z.string().describe('The FULL new file content (replaces any existing content).'),
+    path: z.string().describe('Path to write, relative to the workspace root (parent directories are created as needed). Overwrites existing content unless mode is "append".'),
+    content: z.string().describe('The new file content. With mode "overwrite" (default) this REPLACES the file; with mode "append" it is added to the end. Keep any SINGLE call small enough to emit (well under ~150 lines): a payload too large for one model output arrives empty and cannot be sent at all.'),
+    mode: z
+        .enum(['overwrite', 'append'])
+        .default('overwrite')
+        .describe('Use "append" to build a large document or file in SECTIONS across several calls: the first call creates it (mode "overwrite" or "append" — same thing when the file does not exist yet), then every further section appends. This is the supported way to deliver something bigger than one model output; a single oversized call cannot be delivered.'),
     confirm: z.boolean().default(false).describe('Set true ONLY after the user explicitly confirmed this write via ask_user. CREATING a new file the request asked for needs no confirmation — it is applied directly. Refused without it only when it would REPLACE content that already exists.'),
 });
 /** P0.4 — run_terminal tool args: verify commands + gated shell execution. */
@@ -316,6 +342,7 @@ const runTerminalSchema = z.object({
     command: z.string().min(1).describe('The shell command to run in the workspace — e.g. "npx vitest run tests/foo.test.ts", "npx tsc --noEmit", "npm run build", "git diff --stat". Read-only verify commands run directly. Recoverable workspace commands (dependency installs, mkdir/touch/cp/mv, git add, npm init) also run directly when the request authorized the work; every other state-changing command needs confirm:true after the user approves via ask_user. Destructive/system commands are denied outright.'),
     confirm: z.boolean().default(false).describe('Set true ONLY after the user explicitly confirmed a command you initiated. Required for state-changing commands outside the recoverable workspace set (network fetches, arbitrary code, global installs, anything that leaves the machine).'),
     timeout_ms: z.number().int().min(1000).max(300000).optional().describe('Timeout in ms (default 120000).'),
+    verb: z.string().optional().describe('What this command is FOR (e.g. "install java"). When it SUCCEEDS, it is remembered for this verb on this machine, so the next tool_search resolve can offer it instead of re-deriving it. Optional.'),
 });
 /** The C2 requirementState check as a reusable tool. */
 const verifyRequirementSchema = z.object({
@@ -348,6 +375,11 @@ const registry = new Map();
  */
 export function registerTool(tool) {
     registry.set(tool.name, tool);
+    // Record the tool's OWN capability declaration so the name-only lookups
+    // (`effectClassOfTool`, `grantCategoryOfTool`) and the descriptor answer from
+    // it instead of a hand-maintained map. A tool that declares nothing is left
+    // out — absence IS the conservative default.
+    declareToolCapability(tool.name, tool.capability);
 }
 /** Look up a tool by name. */
 export function getTool(name) {
@@ -435,6 +467,7 @@ registerTool({
 // same pipeline core + the publish workflow, so any ask auto-runs.
 registerTool({
     name: 'document',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a git revert" },
     description: 'Write documentation for the project (README, API docs, guides) through the agent pipeline',
     category: 'pipeline',
     inputSchema: taskGoalArgs,
@@ -443,6 +476,7 @@ registerTool({
 });
 registerTool({
     name: 'website',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a git revert" },
     description: 'Create or build a website / web app end-to-end through the agent pipeline',
     category: 'pipeline',
     inputSchema: taskGoalArgs,
@@ -451,6 +485,7 @@ registerTool({
 });
 registerTool({
     name: 'analyze',
+    capability: { effectClass: 'read' },
     description: 'Analyze the project (state, architecture, comparison against another project) and produce findings',
     category: 'pipeline',
     inputSchema: taskGoalArgs,
@@ -467,6 +502,7 @@ registerTool({
 });
 registerTool({
     name: 'publish',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external', requires: { credentials: [{ anyOf: ['NPM_TOKEN', 'GITHUB_TOKEN'], note: 'an npm automation token, or a GitHub token for a GitHub release' }] } },
     description: 'Publish a release to npm/GitHub (version bump, changelog, build, publish). IRREVERSIBLE — confirm bump type and target with ask_user first.',
     category: 'workflow',
     inputSchema: publishToolSchema,
@@ -485,6 +521,7 @@ registerTool({
 });
 registerTool({
     name: 'ask_user',
+    capability: { effectClass: 'read' },
     description: 'Ask the user a clarifying question with 2–4 choices (multi-select optional). Every surface also offers the user a free-text "Other" answer, so a reply may be their own words instead of one of your choices. Use when a request is ambiguous or missing information.',
     category: 'experience',
     inputSchema: askUserSchema,
@@ -538,6 +575,14 @@ registerTool({
         // question reaches the user once.
         const pending = ctx.pendingConfirmation;
         if (!pending &&
+            // Cluster G — an UNSCOPED turn is asking for a required INPUT, not for
+            // permission, and the two can look identical to this heuristic ("which
+            // folder should I create the app in?" reads as permission-seeking).
+            // Suppressing it deadlocks the turn: the user is never asked, so no
+            // folder is ever named, so every retry fails for the same reason — the
+            // "keeps refusing" loop. A missing workspace is not a decision the model
+            // may take on the user's behalf.
+            !ctx.workspaceUnscoped &&
             (ctx.writesAuthorized?.authorized === true || Boolean(ctx.envelope)) &&
             detectPermissionSeeking(question) &&
             !IRREVERSIBLE_ACTION_RE.test(question)) {
@@ -565,18 +610,131 @@ registerTool({
         // One confirmation refusal buys exactly ONE ask — clear it before rendering.
         if (pending)
             ctx.pendingConfirmation = undefined;
+        // ── Session-grant offer (Copilot-style "allow all for this session") ─────
+        // Only when the ask is the CONFIRMATION a state-changing tool demanded
+        // (`pending` is set) is there a category to offer. It is ONE extra choice,
+        // so the user's explicit go-ahead is RECEIVED, never inferred — an answer
+        // that does not name it leaves the ask-every-time default untouched, and an
+        // unattended default (returned below) is an assumption, not a grant.
+        const grantCategory = pending
+            ? (pending.category ??
+                (pending.tool === 'run_terminal'
+                    ? 'terminal'
+                    : pending.tool === 'run_cli'
+                        ? null // run_cli states its own category; absent = a grant cannot help
+                        : 'write'))
+            : null;
+        const offeredChoices = grantCategory && choices.length < 4
+            ? [
+                ...choices,
+                {
+                    label: SESSION_GRANT_CHOICE_LABEL,
+                    description: `Allow all ${sessionGrantLabel(grantCategory)} for this session — no more asks until the conversation ends.`,
+                },
+            ]
+            : choices;
+        // Deferred so the registry stays import-light — the writing half of the
+        // decision log is only needed when an ask actually reaches a person.
+        const { recordDecision, decisionsRecordingEnabled } = await import('../learning/decision-log.js');
         const render = ctx.askUser || (await import('./ask-user.js')).renderAskUser;
-        const answer = await render(question, choices, multi_select);
+        const answer = await render(question, offeredChoices, multi_select);
         const picked = Array.isArray(answer.answer) ? answer.answer.join(', ') : answer.answer;
+        // E1 — an UNATTENDED answer is an ASSUMPTION, not the user's word. Recorded
+        // as one (never as a shown ask with an answer, which is what made a silent
+        // default indistinguishable from a real reply), emitted so the turn can
+        // disclose it, and worded to the model as an assumption so its answer cannot
+        // claim the user chose it.
+        if (answer.unattended) {
+            ctx.runTrace?.recordAssumption(question, picked);
+            ctx.emit?.('autonomy:assumed-default', { question, assumed: picked }, 'tool-loop');
+            return (`No user was reachable to answer, so "${picked}" was ASSUMED — it is NOT their answer. ` +
+                (answer.custom ??
+                    `In your written answer, tell the user the question you would have asked and the assumption ` +
+                        `you made (e.g. "I assumed ${picked} — tell me if you would prefer something else"), then continue with it.`) +
+                ' Do not record it as a user decision or re-ask the same question.');
+        }
+        // ── Grant it, if the user picked the session choice ──────────────────────
+        // The grant is stored against the session (the same key the intent envelope
+        // uses), so it outlives this turn and dies with the conversation. The write
+        // happens HERE; the RETURN that tells the model to finish the refused call
+        // is issued after the decision is recorded, so the grant itself is a
+        // recorded, revisable decision like any other must-ask.
+        const granted = Boolean(grantCategory) && answerIsSessionGrant(answer.answer);
+        const grant = granted && grantCategory
+            ? grantSession(ctx.planStore, [grantCategory], 'the user allowed it for the session')
+            : null;
+        if (granted && grantCategory) {
+            ctx.emit?.('autonomy:session-grant', { category: grantCategory, question }, 'tool-loop');
+        }
         // Recorded SHOWN and with the answer, so the trace can hand both back when
         // the agent tries to ask it a second time (and so a self-report can say what
         // the user actually replied, instead of "asked 4×, no answer recorded").
         ctx.runTrace?.recordAsk(question, true, picked);
+        // Bundle 36 — a MUST-ASK decision is also a PROJECT artifact: recorded so the
+        // user can go back through it later and revise it (see
+        // `learning/decision-log.ts`). Only a genuine, SHOWN ask reaches here (an
+        // unattended default is an assumption and returned above), and the write is
+        // best-effort — recording a decision must never break the turn. Deferred
+        // import to keep the registry import-light.
+        if (decisionsRecordingEnabled() && ctx.cwd) {
+            try {
+                const answerText = answer.custom
+                    ? picked
+                        ? `${picked} (${answer.custom})`
+                        : answer.custom
+                    : picked;
+                recordDecision({
+                    question,
+                    answer: answerText,
+                    choices: offeredChoices.map((c) => c.label),
+                    source: 'ask_user',
+                    dir: ctx.cwd,
+                });
+            }
+            catch {
+                // Best-effort — never break a turn on a decision-log write.
+            }
+        }
+        // The grant was a real decision — recorded above — so now hand the model the
+        // instruction that turns it into work: finish the ONE refused call, then stop
+        // asking about this category.
+        if (granted && grantCategory) {
+            return (`User allowed all ${sessionGrantLabel(grantCategory)} for this session. ` +
+                `Retry the refused ${grantCategory === 'terminal' ? 'run_terminal command' : 'write'} ONCE with confirm:true to complete it. ` +
+                'Every later action in this category proceeds without asking — do not ask about it again. ' +
+                (grant ? sessionGrantNotice(grant) : '') +
+                'Irreversible and off-machine actions still ask, and the permission ends with the conversation.');
+        }
+        // ── Cluster G: the reply may be the FOLDER, and then it is the workspace ──
+        // An unscoped turn asks "which folder should I use?". The user answers by
+        // typing one (the free-text "Other" field, or a label they edited) — and
+        // until now that answer went no further than the model's context: the write
+        // tool would refuse again for the same reason and the user would be asked
+        // the same question a second time. That repeat is the reported "agent keep
+        // refusing even after i attach the folder".
+        //
+        // So a directory in the answer IS adopted: `ctx.cwd` moves to it and the
+        // unscoped flag clears, exactly as `clone_repo` moves `ctx.cwd` after it
+        // clones. `directoryFromMessage` is the same conservative rule the server
+        // applies to a message (absolute, existing, a DIRECTORY), so a reply that
+        // merely mentions a file path cannot relocate the turn.
+        const namedFolder = ctx.workspaceUnscoped
+            ? directoryFromMessage(`${picked}\n${answer.custom ?? ''}`)
+            : undefined;
+        if (namedFolder) {
+            ctx.cwd = namedFolder;
+            ctx.workspaceUnscoped = false;
+            ctx.emit?.('workspace:adopted', { path: namedFolder, source: 'ask_user' }, 'tool-loop');
+            return (`User answered: ${picked}${answer.custom ? ` (custom: ${answer.custom})` : ''}\n` +
+                `Workspace adopted: '${namedFolder}'. This chat now works INSIDE that folder — retry the ` +
+                'write with a path inside it (the previous refusal no longer applies).');
+        }
         return `User answered: ${picked}${answer.custom ? ` (custom: ${answer.custom})` : ''}`;
     },
 });
 registerTool({
     name: 'suggest_followups',
+    capability: { effectClass: 'read' },
     description: 'Suggest clickable followup prompts the user can click to send. Use this tool AFTER completing the task — call it last, after your written answer (never before or instead of it). Aim for ~3 suggestions; skip only when there is no sensible next step (e.g. the user said goodbye).',
     category: 'experience',
     inputSchema: suggestFollowupsSchema,
@@ -595,6 +753,7 @@ registerTool({
 // LLM needed — runs entirely on file system access.
 registerTool({
     name: 'code_search',
+    capability: { effectClass: 'read' },
     description: 'Search the project for a regex/literal pattern (ripgrep-fast), returning matching file:line:column entries. Use for context gathering: finding definitions, usages, and where things live.',
     category: 'workflow',
     inputSchema: codeSearchSchema,
@@ -627,6 +786,7 @@ registerTool({
 // Backed by `src/tools/coding-tools.ts` (pure fs — no new dependencies).
 registerTool({
     name: 'read_file',
+    capability: { effectClass: 'read' },
     description: 'Read files with line numbers. Pass `path` for one file (offset/limit for large files) OR `paths` to read several in one call — batching is one step instead of many. Each file gets its own line count and a continuation offset when truncated. Use to open the actual contents of files code_search or glob located — never guess what a file contains.',
     category: 'workflow',
     inputSchema: readFileSchema,
@@ -635,6 +795,7 @@ registerTool({
 });
 registerTool({
     name: 'list_dir',
+    capability: { effectClass: 'read' },
     description: 'List a directory in the workspace (subdirectories first, sorted). Use to explore project structure — what is in this folder, where does this component live.',
     category: 'workflow',
     inputSchema: listDirSchema,
@@ -643,6 +804,7 @@ registerTool({
 });
 registerTool({
     name: 'glob',
+    capability: { effectClass: 'read' },
     description: 'Find files by glob pattern relative to the workspace (e.g. "src/**\/*.ts", "tests/*.test.ts"). Use to locate files by shape when code_search content search does not fit.',
     category: 'workflow',
     inputSchema: globSchema,
@@ -651,6 +813,7 @@ registerTool({
 });
 registerTool({
     name: 'edit_file',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a git revert" },
     description: 'Surgical exact-text edit to a file (find old_string, replace with new_string — like str_replace). Make ONE call for ALL edits to a file via `replacements[]` (they apply atomically — all-or-nothing, never a partial edit). Optionally `dry_run` to preview a unified diff without writing. State-changing: confirm with the user via ask_user first, then retry with confirm:true. Use after read_file so the match is exact.',
     category: 'workflow',
     inputSchema: editFileSchema,
@@ -659,7 +822,8 @@ registerTool({
 });
 registerTool({
     name: 'write_file',
-    description: 'Create a new file or overwrite one with full content (parent directories are created). State-changing: confirm with the user via ask_user first, then retry with confirm:true.',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a create is undone by deleting the file; an overwrite is a git revert" },
+    description: 'Create a new file, overwrite one, or APPEND a section to one (parent directories are created). Use mode "append" to deliver a large document or file in sections across several calls — a payload too large for one model output cannot be sent at all, so split it. State-changing: confirm with the user via ask_user first, then retry with confirm:true.',
     category: 'workflow',
     inputSchema: writeFileSchema,
     endsAgentStep: false,
@@ -667,6 +831,7 @@ registerTool({
 });
 registerTool({
     name: 'run_terminal',
+    capability: { effectClass: 'local-state', grantCategory: 'terminal' },
     description: 'Run a shell command in the workspace and see its REAL output — typecheck, a single test file, a build, git diff/status. Use to verify code by actual invocation: run, read the failure, edit, re-run. Verify-class commands (tests/typecheck/build/git-readonly) run directly; state-changing commands need confirm:true after the user approves via ask_user. Destructive/system commands (sudo, git push, rm -rf at dangerous targets, ...) are denied outright.',
     category: 'workflow',
     inputSchema: runTerminalSchema,
@@ -690,11 +855,25 @@ registerTool({
         const { action, goal, steps, id, status, note } = planTodoSchema.parse(args);
         const { defaultPlanStore } = await import('./plan-store.js');
         const store = ctx.planStore ?? defaultPlanStore();
+        // C4 — a re-declaration of the SAME goal carries the progress of the steps it
+        // re-declares (see PlanStore.create). Disclosed rather than silent: a model
+        // that re-declared the plan to RESET it must be told that the harness kept a
+        // step's status, or it will keep working around a step it believes is pending.
+        let carriedNote = '';
         if (action === 'create') {
             if (!goal || !steps || steps.length === 0) {
                 return 'Error: plan_todo create needs goal + steps (id + description each).';
             }
+            const before = store.snapshot?.() ?? null;
             store.create(goal, steps);
+            const after = store.snapshot?.() ?? null;
+            const carried = (after?.steps ?? []).filter((s) => s.status !== 'pending');
+            if (before?.goal === after?.goal && carried.length > 0) {
+                carriedNote =
+                    `\n♻️ Carried ${carried.length} step(s) already progressed from this goal's previous plan: ` +
+                        `${carried.map((s) => `${s.id} (${s.status})`).join(', ')}. ` +
+                        `Leave them as they are, or call update with status "pending" if you really mean to redo them.`;
+            }
         }
         else if (id && status) {
             // A1 — never accept an update that matched nothing. Silently returning
@@ -733,7 +912,7 @@ registerTool({
                 ctx.emit?.('plan:changed', snapshot);
             }
         }
-        return store.toText ? store.toText() : `Plan updated (${action}).`;
+        return (store.toText ? store.toText() : `Plan updated (${action}).`) + carriedNote;
     },
 });
 // ─── WS1 (#23) finding tool — a claim, and the verdict the gate computed ────
@@ -753,6 +932,7 @@ registerTool(createFindingTool());
 // `src/tools/web-research.ts` (mocked-fetch tests, no network).
 registerTool({
     name: 'web_search',
+    capability: { effectClass: 'read' },
     description: 'Search the web for a query, returning title/url/snippet hits. Uses the first available backend: a configured Brave/Serper/Tavily/Google-CSE key, a self-hosted SearXNG, or the keyless DuckDuckGo fallback. Set the backend with `tools.toolsets.web.provider` or an API-key env var. Use to ground answers in current information.',
     category: 'workflow',
     inputSchema: webSearchSchema,
@@ -775,6 +955,7 @@ registerTool({
 });
 registerTool({
     name: 'read_page',
+    capability: { effectClass: 'read' },
     description: 'Fetch a URL and return its readable text (Jina Reader free tier when JINA_API_KEY is set, else a plain fetch). Use to read a full page found by web_search.',
     category: 'workflow',
     inputSchema: readPageSchema,
@@ -792,6 +973,7 @@ registerTool({
 // ─── I2–I5 modality packs (browser / image / voice / vision) ────────────────
 registerTool({
     name: 'browser',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Automate a real browser (open/click/type/extract/screenshot). Requires the optional playwright package (npm i playwright && npx playwright install chromium). Use for tasks that need a live page (login flows, scraping dynamic sites).',
     category: 'workflow',
     inputSchema: browserSchema,
@@ -809,6 +991,7 @@ registerTool({
 });
 registerTool({
     name: 'generate_image',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Generate an image from a text prompt using a bring-your-own-key backend: Google Gemini/Imagen (GEMINI_API_KEY), OpenAI DALL-E/gpt-image (OPENAI_API_KEY), Stability AI (STABILITY_API_KEY), a local ComfyUI/Stable Diffusion (BUFF_IMAGE_API_URL), or the free keyless Pollinations.ai fallback. The first backend whose key is configured wins (override with `modality.image.provider`), and a failing backend falls back to Pollinations. The image is saved to the sandbox images/ dir and the path is returned. When running in a gateway context (WhatsApp/Telegram/etc.), the image is automatically sent back to the originating channel.',
     category: 'workflow',
     inputSchema: imageGenSchema,
@@ -845,6 +1028,7 @@ registerTool({
 });
 registerTool({
     name: 'speak',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Synthesize speech for text to an audio file (edge-tts or Piper, both free and local). Requires edge-tts or piper on PATH. Returns the audio file path. When running in a gateway context, the audio is automatically sent back to the originating channel.',
     category: 'workflow',
     inputSchema: speakSchema,
@@ -868,6 +1052,7 @@ registerTool({
 });
 registerTool({
     name: 'transcribe',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Transcribe an audio file to text (whisper.cpp or faster-whisper, local and free). Requires whisper on PATH. Returns the transcript.',
     category: 'workflow',
     inputSchema: transcribeSchema,
@@ -881,6 +1066,7 @@ registerTool({
 });
 registerTool({
     name: 'describe_image',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Describe an image (local Ollama llava/llama3.2-vision, or free Gemini vision when BUFF_GEMINI_API_KEY is set). Use for screenshots, diagrams, or any image the user references.',
     category: 'workflow',
     inputSchema: describeImageSchema,
@@ -897,6 +1083,7 @@ registerTool({
 });
 registerTool({
     name: 'gateway_send',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Send a message (text or image) to a DIFFERENT channel or contact through the gateway (WhatsApp by contact name or number, Telegram, Slack, Discord, email, or any registered alias). Do NOT use this tool to reply to the CURRENT conversation — your text response is automatically sent back to the originating channel. Only call this when the user asks you to deliver a result to SOMEONE ELSE — e.g. "send the poem to Alex on whatsapp" (while you are chatting with Divya). For images, set image_path to the file path (e.g. from generate_image output) — the image is sent with text as caption. AUTHORIZATION: on a gateway turn the sender must hold outbound send authority for that platform (dashboard → Agent Hub → Permissions → Send authority); the result string tells you plainly when a send was refused and why — report that to the user honestly and NEVER claim a message was delivered unless this tool returned its \'✅ sent\' result.',
     category: 'workflow',
     inputSchema: gatewaySendSchema,
@@ -905,6 +1092,7 @@ registerTool({
 });
 registerTool({
     name: 'run_cli',
+    capability: { effectClass: 'local-state', grantCategory: 'terminal' },
     description: 'Resolve a plain-English request into the exact nuvira CLI command and execute it (start/stop the dashboard or gateway, check status, add a verified sender or send-by-name contact, configure a platform like telegram/whatsapp, run evals, show stats, manage memory/cache, etc.). Use when the user describes a system/tooling task in plain English instead of typing the command — e.g. "stop the dashboard", "add Rahul to whatsapp", "enable telegram support", "run the eval suite". Ambiguous asks and destructive actions are gated: the tool returns what to confirm, then call ask_user and retry with confirm:true when the user agreed.',
     category: 'workflow',
     inputSchema: runCliSchema,
@@ -913,6 +1101,7 @@ registerTool({
 });
 registerTool({
     name: 'verify_requirement',
+    capability: { effectClass: 'read' },
     description: 'Verify whether a user request is complete enough to act on (requirementState: complete vs needs-clarification), returning the missing information.',
     category: 'experience',
     inputSchema: verifyRequirementSchema,
@@ -945,6 +1134,7 @@ registerTool({
 // exec (no shell) make injection structurally impossible.
 registerTool({
     name: 'clone_repo',
+    capability: { effectClass: 'external', grantCategory: 'external', reversibleHow: 'delete the cloned directory' },
     description: 'Clone a git repository (depth-1 shallow) into an ephemeral cache and scope the conversation to it — read_file / list_dir / glob / code_search / run_terminal then operate on the CLONE, so you can assess another project without touching the user\'s workspace. Use when the ask is about a repo that is not the attached project.',
     category: 'workflow',
     inputSchema: cloneRepoSchema,
@@ -960,6 +1150,7 @@ registerTool({
 // while reset --hard/clean remain structurally unexpressible AND deny-guarded.
 registerTool({
     name: 'git',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external', reversibleHow: 'a local commit is reversible; a push is only as reversible as the remote' },
     description: 'Structured git operations: status/log (read-only), diff (unified output + a diff card in the GUI), commit (GATED — confirm:true only after the user approved via ask_user; optional files = the accepted subset to stage+commit), and push (GATED — sends a branch to a remote; runs when the user’s own request named the push, otherwise ask via ask_user first). Use for the whole flow: diff → ask_user (accept/reject files) → commit → push.',
     category: 'workflow',
     inputSchema: gitToolSchema,
@@ -1131,6 +1322,7 @@ registerTool({
 // Browser Supervisor tool
 registerTool({
     name: 'browser_supervisor',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Browser CDP supervisor: monitor health, detect dialogs, track frames.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1152,6 +1344,7 @@ registerTool({
 // Browser Dialog tool
 registerTool({
     name: 'browser_dialog',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Handle native browser dialogs: accept, dismiss, or enter values.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1179,6 +1372,7 @@ registerTool({
 // Camofox tool
 registerTool({
     name: 'camofox',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Camofox anti-detection browser: open pages, screenshots, interact via a11y refs.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1206,6 +1400,7 @@ registerTool({
 // Docker tool
 registerTool({
     name: 'docker',
+    capability: { effectClass: 'local-state', grantCategory: 'terminal' },
     description: 'Docker management: containers, images, compose, volumes, networks.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1320,6 +1515,7 @@ registerTool({
 // Kanban tool
 registerTool({
     name: 'kanban',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a git revert" },
     description: 'Kanban board: create boards, manage cards, track priorities.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1438,6 +1634,7 @@ registerTool({
 // Blueprint tool
 registerTool({
     name: 'blueprint',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a git revert" },
     description: 'Project blueprints: create project templates with file structure.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1459,6 +1656,7 @@ registerTool({
 // File ops tool
 registerTool({
     name: 'file_ops',
+    capability: { effectClass: 'local-write', grantCategory: 'write', reversibleHow: "a git revert" },
     description: 'Advanced file operations: state tracking, safe writes, extraction, preview.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1669,6 +1867,7 @@ registerTool({
 // tool-loop.ts trusts). See TOOL_TRUTHFULNESS_TRACKER.md findings #3 and #9.
 registerTool({
     name: 'messaging',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'NOT CONNECTED — this tool has no delivery adapter and every send/react refuses with code "not_configured". '
         + 'Do NOT use it to deliver anything and never report a delivery from it. Use gateway_send instead: it sends '
         + 'through the configured gateway (WhatsApp by contact name or number, Telegram, Slack, Discord, email) and '
@@ -1700,6 +1899,7 @@ registerTool({
 // Vision tool — comprehensive image analysis, OCR, UI element detection
 registerTool({
     name: 'vision',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Analyze an image and transcribe its text (OCR) through the configured vision backend (a local Ollama '
         + 'vision model or a Gemini key); `analyze` also reports real pixel dimensions. detect-elements, '
         + 'find-element and compare have NO backend and return ok:false with code "not_configured" — an empty '
@@ -1781,6 +1981,7 @@ registerTool({
 // Process registry tool
 registerTool({
     name: 'process_registry',
+    capability: { effectClass: 'read' },
     description: 'Track all running processes with metadata and cleanup.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1806,6 +2007,7 @@ registerTool({
 // Code execution tool
 registerTool({
     name: 'code_execution',
+    capability: { effectClass: 'local-state', grantCategory: 'terminal' },
     description: 'Execute code in sandboxed environment with timeout and resource limits.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1863,6 +2065,7 @@ registerTool({
 // Threat patterns tool
 registerTool({
     name: 'threat_patterns',
+    capability: { effectClass: 'read' },
     description: 'Detect threat patterns: shell execution, external HTTP, obfuscation.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1877,6 +2080,7 @@ registerTool({
 // URL safety tool
 registerTool({
     name: 'url_safety',
+    capability: { effectClass: 'read' },
     description: 'Check URL safety: suspicious TLDs, patterns, length.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1891,6 +2095,7 @@ registerTool({
 // Path security tool
 registerTool({
     name: 'path_security',
+    capability: { effectClass: 'read' },
     description: 'Check path security: traversal, null bytes, directory escape.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1906,6 +2111,7 @@ registerTool({
 // Security score tool
 registerTool({
     name: 'security_score',
+    capability: { effectClass: 'read' },
     description: 'Calculate security score for a file: code injection, secrets, threats.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1926,6 +2132,7 @@ registerTool({
 // and no network, and reports masked values only — see src/security/secret-scan.ts.
 registerTool({
     name: 'secret_scan',
+    capability: { effectClass: 'read' },
     description: 'Scan the workspace for secret-shaped strings (API keys, tokens, private keys, credentials in URLs) before committing or publishing. Fully local — no network and no external scanner binary — and every reported value is masked. Returns findings with path:line and severity, plus a summary. Set history:true to scan git HISTORY as well (every committed version of every file) — a key deleted in a later commit is STILL committed and must be rotated. A clean result means "nothing matched a known shape", NOT "no secrets": report it as a lint, never as a guarantee.',
     category: 'workflow',
     inputSchema: z.object({
@@ -1975,21 +2182,28 @@ registerTool({
 //   ~85% of per-turn schema tokens saved, zero capability lost.
 registerTool({
     name: 'tool_search',
-    description: 'Discover and load tools. Actions: "search" fuzzy-finds tools by query; ' +
+    capability: { effectClass: 'read' },
+    description: 'Discover and load capabilities. Actions: "search" finds what the agent can DO by query and returns each hit as a CAPABILITY — its effect (read / local-write / local-state / external / destructive), whether it is reversible and how, any credentials or binaries it needs, whether a session grant can cover it, and a `check` saying whether those needs are actually MET on this machine (run this FIRST for an install / publish / deploy / push task, so a missing executable is known before the work starts rather than halfway through); ' +
+        '"readiness" is the same probe without a search — call it with a query to pre-flight a described task, or with no query to see what the curated install / publish / deploy / push verbs are missing here; ' +
+        'Tools on any MCP server connected this session are included as capabilities too (kind "mcp", with an `invoke` saying how to call them). Installed SKILLS are capabilities too (kind "skill") — call this to find the skill that fits a task, then load it with the skill tool; ' +
         '"load" activates a whole toolset (media, browser, channels, docker, ' +
         'productivity, publish, core-pipeline, …) for THIS turn — call it before ' +
         'using any tool outside the always-available core set. "load" returns ' +
-        'the toolset\'s tool names, which become callable immediately.',
+        'the toolset\'s tool names, which become callable immediately; ' +
+        '"resolve" checks a command or a verb against THIS machine (is the executable present, which package managers exist here, and any command already learned for it) — run it BEFORE an OS-specific command instead of guessing the platform; "record" stores a command you derived so it is known next time (the table grows by use); "list-commands" and "forget" manage that store.',
     category: 'workflow',
     inputSchema: z.object({
-        action: z.enum(['search', 'load']).optional().describe('Defaults to "search".'),
-        query: z.string().optional().describe('Search query (action=search)'),
+        action: z.enum(['search', 'load', 'readiness', 'resolve', 'record', 'forget', 'list-commands']).optional().describe('Defaults to "search".'),
+        query: z.string().optional().describe('Search query (action=search|readiness; omit for readiness to check the install/publish/deploy/push verbs)'),
         limit: z.number().optional().describe('Max results (action=search)'),
         toolset: z.string().optional().describe('Toolset name to load (action=load) — e.g. "media", "browser", "channels"'),
+        command: z.string().optional().describe('A command to check against this machine (action=resolve) or to store (action=record)'),
+        verb: z.string().optional().describe('What the command is FOR (action=resolve|record|forget) — e.g. "install java", or a capability ref'),
+        note: z.string().optional().describe('Optional caveat to store beside a learned command (action=record)'),
     }),
     endsAgentStep: false,
     run: async (args, ctx) => {
-        const { action = 'search', query, limit, toolset } = args;
+        const { action = 'search', query, limit, toolset, command, verb, note } = args;
         // ── load: activate a toolset for this turn (tiered exposure) ──
         if (action === 'load') {
             if (!toolset) {
@@ -2032,13 +2246,181 @@ registerTool({
                     : 'Toolset recorded, but this context has no live schema loader (loop not in tiered mode) — tools remain governed by the standard enablement gate.',
             });
         }
-        // ── search: the pre-existing fuzzy find (unchanged behavior) ──
+        // ── resolve / record / forget / list-commands: the long-tail OS command
+        //    loop. The MODEL derives a command; the harness checks it against the
+        //    machine and remembers it. No enumeration, no phrase list — presence is
+        //    probed (binaryOnPath) and the learned store is keyed by (verb, os).
+        if (action === 'resolve' || action === 'record' || action === 'forget' || action === 'list-commands') {
+            const { detectMachineFacts } = await import('../learning/machine-facts.js');
+            const facts = detectMachineFacts();
+            const learnedMod = await import('../learning/learned-commands.js');
+            const { leadingBinary, suggestInstallCommand } = await import('../learning/command-adaptation.js');
+            const { binaryOnPath } = await import('../utils/binary-probe.js');
+            if (action === 'list-commands') {
+                return JSON.stringify({ os: facts.os, commands: learnedMod.listLearnedCommands() });
+            }
+            if (action === 'forget') {
+                return JSON.stringify({ os: facts.os, verb: verb ?? '', forgotten: learnedMod.forgetLearnedCommand(verb ?? '') });
+            }
+            if (action === 'record') {
+                const bin = command ? leadingBinary(command) : null;
+                const entry = learnedMod.recordLearnedCommand({
+                    verb: verb ?? '',
+                    command: command ?? '',
+                    ...(bin ? { binary: bin } : {}),
+                    ...(note ? { note } : {}),
+                });
+                return JSON.stringify({
+                    os: facts.os,
+                    recorded: entry,
+                    ...(entry
+                        ? { note: 'Recorded. It will be offered the next time this verb is resolved on this OS.' }
+                        : { error: 'record needs a verb and a command.' }),
+                });
+            }
+            // resolve
+            const bin = command ? leadingBinary(command) : null;
+            const binPresent = bin ? binaryOnPath(bin) : null;
+            const learned = verb ? learnedMod.learnedCommandFor(verb) : null;
+            // When the executable is missing, prefer a manager that is ACTUALLY PRESENT
+            // here — the suggestion is buildable, not a manager the machine lacks.
+            const suggestedInstall = bin && binPresent === false ? suggestInstallCommand(facts, bin) : null;
+            return JSON.stringify({
+                os: facts.os,
+                osName: facts.osName,
+                arch: facts.arch,
+                shell: facts.shellName,
+                packageManagers: facts.packageManagers,
+                ...(command ? { proposed: { command, binary: bin, present: binPresent } } : {}),
+                ...(suggestedInstall
+                    ? {
+                        suggestedInstall: {
+                            manager: suggestedInstall.manager,
+                            command: suggestedInstall.command,
+                            note: 'The package name can differ from the executable name — adjust if the install fails.',
+                        },
+                    }
+                    : {}),
+                ...(learned
+                    ? { learned: { command: learned.command, binary: learned.binary, source: learned.source, learnedAt: learned.learnedAt } }
+                    : {}),
+                advice: command
+                    ? binPresent
+                        ? `\`${bin}\` is on this machine — the command can run.`
+                        : bin
+                            ? `\`${bin}\` is NOT on this machine.` +
+                                (suggestedInstall
+                                    ? ` Install it with \`${suggestedInstall.command}\` (${suggestedInstall.manager} is present here), or choose another present manager: ${facts.packageManagers.join(', ')}.`
+                                    : ` No package manager that can install it is present; use what is on the machine.`)
+                            : 'Could not identify an executable in this command; check it with a small probe run.'
+                    : learned
+                        ? `A command for "${verb}" on this OS was already derived — use it, or record a better one.`
+                        : `No command is known for "${verb}" on this OS yet. Derive one from the machine facts, run it, then record it.`,
+            });
+        }
+        // ── search: fuzzy find, ENRICHED with capability descriptors ──
+        // The tools returned are the same as before; each is also returned as a
+        // CAPABILITY (effect class + reversibility + requirements + grant), and the
+        // curated high-level ACTIONS (install / publish / deploy / push …) ride
+        // alongside, so the model can discover what it can do — not just which tool
+        // names exist. Discovery only: nothing here decides what runs.
         const m = await import('./infra-tools.js');
         const engine = m.getToolSearchEngine();
-        // Index from registry
         const { listTools } = await import('./registry.js');
-        engine.index(listTools().map((t) => ({ name: t.name, description: t.description })));
-        return JSON.stringify(engine.search(query || '', limit || 10));
+        const tools = listTools();
+        engine.index(tools.map((t) => ({ name: t.name, description: t.description })));
+        const { capabilityIndex, searchCapabilities } = await import('./capability-registry.js');
+        const index = await capabilityIndex(tools.map((t) => ({ name: t.name, description: t.description, category: t.category })));
+        const { describeGap, probeRequirements } = await import('../learning/requirement-probe.js');
+        // A command the MODEL derived for THIS OS (learned) rides on the hit, so the
+        // per-OS table grows by use rather than by hand.
+        const { detectMachineFacts: detectFacts } = await import('../learning/machine-facts.js');
+        const { learnedCommandFor } = await import('../learning/learned-commands.js');
+        const currentOs = detectFacts().os;
+        const hits = searchCapabilities(index, query || '', limit || 10);
+        // PRE-FLIGHT. Each hit's declared requirements are probed HERE, at discovery
+        // time, so a missing executable is known BEFORE the run starts rather than
+        // after it has written half the work. A binary gap is a hard blocker; a
+        // credential gap is advisory and never blocks — see requirement-probe.ts.
+        const toCapability = (h) => {
+            const requires = h.capability.requires;
+            const hasRequires = Object.keys(requires).length > 0;
+            const readiness = hasRequires ? probeRequirements(requires) : undefined;
+            const learnedOnThisOs = learnedCommandFor(h.capability.ref, currentOs);
+            return {
+                id: h.capability.id,
+                kind: h.capability.kind,
+                ref: h.capability.ref,
+                name: h.capability.name,
+                does: h.capability.oneLiner,
+                effect: h.capability.effectClass,
+                reversible: h.capability.reversible,
+                ...(h.capability.reversibleHow ? { undo: h.capability.reversibleHow } : {}),
+                ...(h.capability.grantCategory ? { grantable: h.capability.grantCategory } : {}),
+                ...(hasRequires ? { requires } : {}),
+                // A foreign (MCP) hit is not called by its own name — say how to reach it.
+                ...(h.capability.invoke ? { invoke: h.capability.invoke } : {}),
+                // HOW TO DO IT HERE vs. EVERYWHERE. `onThisMachine` is the entry for the
+                // OS the agent is actually running on, resolved from the same per-OS map the
+                // rest is declared in, so the model never has to infer which package manager
+                // exists from the platform name. `platforms` carries the others, present only
+                // where the OS genuinely determines the command.
+                ...(h.capability.platforms
+                    ? {
+                        onThisMachine: h.capability.platforms[process.platform],
+                        platforms: h.capability.platforms,
+                    }
+                    : {}),
+                // A command the MODEL derived for this OS rides ALONGSIDE the declared
+                // one: the table grows by use, and the model can see both and choose.
+                ...(learnedOnThisOs
+                    ? {
+                        learnedOnThisMachine: {
+                            command: learnedOnThisOs.command,
+                            ...(learnedOnThisOs.binary ? { binary: learnedOnThisOs.binary } : {}),
+                            source: learnedOnThisOs.source,
+                        },
+                    }
+                    : {}),
+                ...(readiness
+                    ? {
+                        check: {
+                            ready: readiness.ready,
+                            ...(readiness.gaps.length > 0 ? { gaps: readiness.gaps.map(describeGap) } : {}),
+                            ...(readiness.ask.length > 0 ? { ask: readiness.ask } : {}),
+                        },
+                    }
+                    : {}),
+                matched: h.matched,
+            };
+        };
+        // ── readiness: the same hits, reported as a PRE-FLIGHT rather than a find ──
+        if (action === 'readiness') {
+            // With no query, check the curated ACTION verbs — the capabilities that
+            // declare requirements (install / publish / deploy / push / credentials).
+            // With no query, check the curated verbs that declare needs. A read-only
+            // action with no requirements (this-machine facts) is not a pre-flight
+            // subject, so it is excluded rather than reported with an empty check.
+            const selected = query
+                ? hits
+                : index
+                    .filter((c) => c.kind === 'action' && Object.keys(c.requires).length > 0)
+                    .map((c) => ({ capability: c, matched: [] }));
+            const caps = selected.map(toCapability);
+            const blocked = caps.filter((c) => c.check && !c.check.ready);
+            return JSON.stringify({
+                checked: caps.length,
+                blocked: blocked.length,
+                summary: blocked.length === 0
+                    ? 'No missing executables among these capabilities. Any credential notes are advisory — a credential may live in the vault rather than the environment.'
+                    : `${blocked.length} of ${caps.length} need an executable that is not on PATH; see each check.gaps.`,
+                capabilities: caps,
+            });
+        }
+        return JSON.stringify({
+            tools: engine.search(query || '', limit || 10),
+            capabilities: hits.map(toCapability),
+        });
     },
 });
 // Budget config tool
@@ -2067,6 +2449,7 @@ registerTool({
 // Fuzzy match tool
 registerTool({
     name: 'fuzzy_match',
+    capability: { effectClass: 'read' },
     description: 'Fuzzy string matching with Levenshtein distance.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2100,6 +2483,7 @@ registerTool({
 // OSV check tool
 registerTool({
     name: 'osv_check',
+    capability: { effectClass: 'read' },
     description: 'Check for known vulnerabilities in npm packages via OSV API.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2129,6 +2513,7 @@ registerTool({
 // Image source tool
 registerTool({
     name: 'image_source',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Detect image source: format, size, is screenshot.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2144,6 +2529,7 @@ registerTool({
 // Discord tool
 registerTool({
     name: 'discord',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Discord server management: list servers, channels, members, messages, roles. Send messages.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2171,6 +2557,7 @@ registerTool({
 // Home Assistant tool
 registerTool({
     name: 'homeassistant',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Home Assistant smart home: list entities, get state, call services (turn_on/off, set_temperature).',
     category: 'workflow',
     inputSchema: z.object({
@@ -2199,6 +2586,7 @@ registerTool({
 // Microsoft Graph tool
 registerTool({
     name: 'microsoft_graph',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Microsoft Graph API: email, calendar, OneDrive, contacts.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2249,6 +2637,7 @@ registerTool({
 // Feishu document tool
 registerTool({
     name: 'feishu_doc',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Feishu document management: create, read, update, delete documents.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2273,6 +2662,7 @@ registerTool({
 // Feishu drive tool
 registerTool({
     name: 'feishu_drive',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Feishu drive management: list files, create folders, move, copy, search.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2302,6 +2692,7 @@ registerTool({
 // Video generation tool
 registerTool({
     name: 'video_generate',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Generate videos from text prompts or images. Supports FAL/BFL providers. When running in a gateway context and a video URL is returned, the video is automatically downloaded and sent back to the originating channel.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2410,6 +2801,7 @@ registerTool({
 // NeuTTS synthesis tool
 registerTool({
     name: 'neutts_synth',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'High-quality text-to-speech synthesis via NeuTTS.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2433,6 +2825,7 @@ registerTool({
 // Terminal tool — multi-environment execution
 registerTool({
     name: 'terminal',
+    capability: { effectClass: 'local-state', grantCategory: 'terminal' },
     description: 'Execute commands in local, Docker, Modal, SSH environments with background support.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2487,6 +2880,7 @@ registerTool({
 // Send message tool — cross-channel messaging
 registerTool({
     name: 'send_message',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Send messages to Telegram, Discord, Slack, WhatsApp, Email. Supports media attachments (images, videos, audio, documents) on WhatsApp.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2748,6 +3142,7 @@ registerTool({
 // MCP Tool — Dynamic MCP server connection and tool invocation
 registerTool({
     name: 'mcp_tool',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Connect to external MCP servers and invoke their tools — stdio, HTTP, or SSE transport.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2775,6 +3170,7 @@ registerTool({
 // Computer Use — Desktop automation via cua-driver
 registerTool({
     name: 'computer_use',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Desktop control via cua-driver — screenshots, mouse, keyboard, scroll without stealing focus.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2863,6 +3259,7 @@ registerTool({
 // OpenRouter Client — Multi-LLM routing
 registerTool({
     name: 'openrouter_client',
+    capability: { effectClass: 'external', grantCategory: 'external' },
     description: 'Route LLM calls to multiple providers via OpenRouter — cost optimization and fallback.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2887,6 +3284,7 @@ registerTool({
 // TTS Streaming — Provider-agnostic streaming TTS
 registerTool({
     name: 'tts_streaming',
+    capability: { effectClass: 'external', reversible: false, grantCategory: 'external' },
     description: 'Convert text to speech using various providers — streaming and batch modes.',
     category: 'workflow',
     inputSchema: z.object({
@@ -2965,6 +3363,7 @@ registerTool({
 // that cannot, so the model can distinguish "read it" from "could not read it".
 registerTool({
     name: 'read_extract',
+    capability: { effectClass: 'read' },
     description: 'Extract text from a document. WORKS for PDF, DOCX, XLSX, PPTX, HTML, CSV/TSV, JSON, XML, YAML and '
         + 'plain text/Markdown; PDF and spreadsheet table rows are preserved so values stay paired with their '
         + 'columns. Returns success:false with a typed code when it cannot read the file — "no_data" means a '
@@ -2997,23 +3396,29 @@ registerTool({
 // knowledge / web-research.
 registerTool({
     name: 'knowledge',
-    description: 'Answer questions from the USER\'S OWN tagged documents. `add` ingests files/folders under a tag '
-        + '(extract → chunk → embed, done once); `query` retrieves the tag\'s most relevant passages, labeled '
-        + 'with their source file, so the data part of an answer comes from the user\'s data and the general '
-        + 'part from model knowledge or web-research. Use this instead of re-reading a large document on every '
-        + 'turn. Actions: add | query | list | forget | stats. Tags are normalized (spaces/capitals/underscores '
-        + 'become lowercase-hyphen), e.g. "Dheeraj health report" → "dheeraj-health-report".',
-    category: 'workflow',
-    inputSchema: z.object({
-        action: z.enum(['add', 'query', 'list', 'forget', 'stats']).describe('Action'),
+    description: 'Work with the USER\'S OWN tagged documents. `add` ingests files/folders under a tag (extract → '
+        + 'chunk → embed, done once); `query` retrieves the tag\'s most relevant passages, labeled with their '
+        + 'source file and section, so the data part of an answer comes from the user\'s data and the general '
+        + 'part from model knowledge or web-research. `toc` lists a tag\'s documents and their headings; `read` '
+        + 'returns a whole document or ONE named section VERBATIM — use it when you have to implement or quote '
+        + 'what a document says, rather than summarizing it from similar passages. `sync` brings a tag up to '
+        + 'date with its folders (unchanged files are not re-embedded; files that vanished stop being served). '
+        + 'Actions: add | query | toc | read | sync | list | forget | stats. Tags are normalized '
+        + '(spaces/capitals/underscores become lowercase-hyphen), e.g. "Dheeraj health report" → '
+        + '"dheeraj-health-report".',
+    category: 'workflow',
+    inputSchema: z.object({
+        action: z.enum(['add', 'query', 'toc', 'read', 'sync', 'list', 'forget', 'stats']).describe('Action'),
         tag: z.string().optional().describe('Tag/hashtag scoping the data (e.g. "dheeraj-health-report")'),
-        paths: z.array(z.string()).optional().describe('Files or folders to ingest (action: add)'),
+        paths: z.array(z.string()).optional().describe('Files or folders to ingest (action: add | sync)'),
         question: z.string().optional().describe('Question to answer from the tagged data (action: query)'),
+        doc: z.string().optional().describe('Document to read or list: doc id, full path, or basename (action: read | toc)'),
+        section: z.string().optional().describe('Section heading to read verbatim (action: read) — omit for the whole document'),
         topK: z.number().optional().describe('Chunks to retrieve (action: query, default 6)'),
     }),
     endsAgentStep: false,
     run: (args) => import('../learning/knowledge-base.js').then(async (m) => {
-        const { action, tag, paths, question, topK } = args;
+        const { action, tag, paths, question, doc, section, topK } = args;
         switch (action) {
             case 'add': {
                 if (!tag)
@@ -3024,7 +3429,11 @@ registerTool({
                 const skipped = result.skipped.length
                     ? `\nSkipped: ${result.skipped.map((s) => `${s.path} (${s.reason})`).join('; ')}`
                     : '';
-                return `✅ Ingested ${result.files} document(s) / ${result.chunks} chunk(s) under tag '${result.tag}'.`
+                // Unchanged documents are named rather than silently folded in: "0 chunks"
+                // and "nothing needed re-embedding" are different answers, and only one
+                // of them means the ingest did nothing.
+                const unchanged = result.unchanged > 0 ? `, ${result.unchanged} unchanged (not re-embedded)` : '';
+                return `✅ Ingested ${result.files} document(s) / ${result.chunks} chunk(s)${unchanged} under tag '${result.tag}'.`
                     + `\nQuery it with action: query, tag: '${result.tag}'.${skipped}`;
             }
             case 'query': {
@@ -3035,6 +3444,54 @@ registerTool({
                 const hits = await m.queryKnowledge(tag, question, { topK });
                 return m.formatKnowledgeContext(tag, hits);
             }
+            case 'toc': {
+                if (!tag)
+                    return 'tag is required for action: toc';
+                const docs = m.listKnowledgeSections(tag, doc);
+                if (docs.length === 0) {
+                    return doc
+                        ? `No document '${doc}' under tag '${tag}'.`
+                        : `No documents under tag '${tag}' — ingest some with action: add.`;
+                }
+                return docs
+                    .map((d) => {
+                    const head = `📄 ${d.title} (${d.chunks} chunk(s)) — ${d.path}`;
+                    const sections = d.sections.length
+                        ? d.sections
+                            .map((s) => `\n  ${'  '.repeat(Math.max(0, s.level - 1))}§ ${s.headingPath ? `${s.headingPath} > ` : ''}${s.title}`)
+                            .join('')
+                        : '\n  (no headings — read the whole document)';
+                    return head + sections;
+                })
+                    .join('\n');
+            }
+            case 'read': {
+                if (!tag)
+                    return 'tag is required for action: read';
+                if (!doc)
+                    return 'doc is required for action: read (a doc id, full path, or basename — see action: toc)';
+                const read = m.readKnowledgeDocument(tag, doc, section);
+                if (!read.ok)
+                    return read.reason;
+                const header = `📖 ${read.path}${read.headingPath ? ` — §${read.headingPath}` : ''}`;
+                const note = read.truncated ? `\n\n[... truncated at ${m.MAX_READ_CHARS} characters ...]` : '';
+                return `${header}\n\n${read.text}${note}`;
+            }
+            case 'sync': {
+                if (!tag)
+                    return 'tag is required for action: sync';
+                if (!paths || paths.length === 0)
+                    return 'paths is required for action: sync';
+                const synced = await m.syncKnowledgeTag(tag, paths, { onChunkSkipped: () => { } });
+                const removed = synced.removed.length
+                    ? `\nRemoved (no longer present): ${synced.removed.map((p) => `${p}`).join('; ')}`
+                    : '';
+                const skipped = synced.skipped.length
+                    ? `\nSkipped: ${synced.skipped.map((s) => `${s.path} (${s.reason})`).join('; ')}`
+                    : '';
+                return `🔄 Synced '${synced.tag}': ${synced.added} added, ${synced.changed} changed, `
+                    + `${synced.unchanged} unchanged, ${synced.chunks} chunk(s) written.${removed}${skipped}`;
+            }
             case 'list': {
                 const tags = m.listKnowledgeTags();
                 if (tags.length === 0)
@@ -3112,6 +3569,7 @@ registerTool({
 });
 registerTool({
     name: 'search_memory',
+    capability: { effectClass: 'read' },
     description: 'Search memories by content, type, or tags. Searches BOTH memory stores: entries added with add_memory (keyword/tag) and facts learned from earlier sessions (semantic), so a memory recorded by another path is still found.',
     category: 'workflow',
     inputSchema: z.object({
@@ -3173,6 +3631,7 @@ registerTool({
 });
 registerTool({
     name: 'list_memories',
+    capability: { effectClass: 'read' },
     description: 'List all memory entries with optional filters.',
     category: 'workflow',
     inputSchema: z.object({
@@ -3189,6 +3648,7 @@ registerTool({
 });
 registerTool({
     name: 'memory_stats',
+    capability: { effectClass: 'read' },
     description: 'Get memory statistics.',
     category: 'workflow',
     inputSchema: z.object({}),