tewip-ai 0.73.1 → 0.74.0

package/README.md

@@ -1216,6 +1216,47 @@ With `--act` it carries the decision out, and this is where the refusals matter
 - Everything it did or refused goes to `.tewip/actions.jsonl`, with the run that justified it.
 - It **will not repeat itself**: the same attempt is refused until a new run gives it new evidence.
 
+## What is your AI agent allowed to do? (Phase 139)
+
+```bash
+tewip agent                 # this project
+tewip agent ~/work/bot      # another one
+tewip agent --gate          # non-zero when nothing stands in the way
+```
+
+Every tool in this market evaluates an agent by **running** it - Langfuse, Phoenix, RAGAS, TruLens,
+DeepEval, Promptfoo, Giskard, garak. They need a runtime, a token budget and usually an account, and
+most judge with another model, so the same agent scores differently on Tuesday. They answer *is this
+agent any good*.
+
+Nobody answers the question an IT department has to sign off on: **what is this agent allowed to do,
+and what stands between it and the real world?** That one is decidable by reading, for free,
+offline, in CI, before anything runs.
+
+- **Every tool it can call**, with the file and line. Reads LangChain and LangGraph, the MCP SDKs in
+  Python and TypeScript, CrewAI, the OpenAI Agents SDK, the Vercel AI SDK and Anthropic's tool
+  shape. A framework it does not read is reported as silence, never as approval.
+- **Which of them cannot be undone.** When a tool declares `destructiveHint` or `readOnlyHint`, that
+  is believed over any guess - the author said it. Otherwise the name decides, then the opening
+  clause of the description, and a tool that says neither is printed as **undecided**, never folded
+  into "reads".
+- **The lethal trifecta.** Untrusted input, private data and a way to send data out, in one loop:
+  text the agent did not write can tell it to read the private thing and post it somewhere, and
+  every step is a tool it was given on purpose. A system prompt is not a defence, because whoever
+  writes the untrusted text writes the other half of the prompt. Tewip names the tools in each leg.
+- **What stands in the way**: a human approval gate, a dry run, a step budget, a tool allow-list -
+  and says plainly when nothing anywhere in the project has one. A ceiling written as
+  `max_iterations=None` is reported apart from no ceiling at all, because it reads as deliberate.
+
+It will not tell you that a gate which exists stands in front of these particular tools - that is a
+question about the running graph - and it says so in those words rather than letting you assume it.
+
+**Measured on real agents.** The official MCP servers: 27 tools, 6 that cannot be undone, every one
+of those confirmed by its own `destructiveHint: true`. The OpenAI Agents SDK and CrewAI: no tools,
+correctly - they are frameworks, and every candidate in them was a test fixture or a docstring
+example. Each of those three repositories broke an earlier version of this check, in the same two
+ways every time: prose read as code, or code read as prose.
+
 ## What an IT department has to answer (Phases 133-137)
 
 Five commands that produce evidence rather than a judgement. All five are rules-only: no model is

package/dist/cli/help.js

@@ -95,6 +95,14 @@ Usage:
                                     Compare a Figma frame against the running page: the words the
                                     design specifies and the controls its layer names imply. Says
                                     "the design says X, the page says Y". No model, no cost.
+  tewip agent [<folder>] [--out agent.md] [--gate]
+                                    What an AI agent in this project is allowed to do, read from
+                                    its source before it runs: every tool it can call, which of
+                                    them cannot be undone, and whether anything asks a person
+                                    first. Names the lethal trifecta when it is there - untrusted
+                                    input, private data and a way to send data out, in one loop.
+                                    Reads LangChain, LangGraph, the MCP SDKs, CrewAI, the OpenAI
+                                    Agents SDK and the Vercel AI SDK. No model, no cost.
   tewip audit [--all] [--gate]
                                     Who ran Tewip here, when, and with what. Each entry carries
                                     the hash of the one before it, so an entry changed or removed

package/dist/cli/verbs-assure.js

@@ -23,6 +23,11 @@ export async function assureVerb(verb, args) {
             runAttest({ root: process.cwd(), name: flag(args, 'name'), runId: flag(args, 'run'), out: flag(args, 'out'), json: flag(args, 'json') });
             return true;
         }
+        case 'agent': {
+            const { runAgent } = await import('../engine/agent/agent-command.js');
+            runAgent({ root: args.find((a) => !a.startsWith('--')) ?? process.cwd(), out: flag(args, 'out'), gate: args.includes('--gate') });
+            return true;
+        }
         case 'audit': {
             const { runAudit } = await import('../engine/audit/audit-command.js');
             runAudit({ root: process.cwd(), all: args.includes('--all'), gate: args.includes('--gate') });

package/dist/engine/agent/agent-command.js

@@ -0,0 +1,154 @@
+// `tewip agent`: what this agent is allowed to do, and what stands between it and the real world.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { scanSourceFiles } from '../walk.js';
+import { CAPABILITY_MEANS, FRAMEWORKS_READ, IRREVERSIBLE, toolsIn, trifectaIn } from './tools.js';
+import { budgetSetToNothing, guardsIn, GUARD_MEANS, GUARD_PREVENTS } from './guards.js';
+const NL = String.fromCharCode(10);
+const AGENT_FILE = /\.(?:py|[cm]?[jt]sx?)$/i;
+/**
+ * What is not the shipped agent.
+ *
+ * The first version of this named the directory `tests` and the file `*.test.ts`, which is what the
+ * documentation of every project says and not what projects do. Run against the OpenAI Agents SDK,
+ * all 24 "tools" it reported were fixtures in `integration_tests/` and `test_*.py` - a directory
+ * whose name ends in `tests` rather than being `tests`, and a Python convention that puts the word
+ * at the front of the file. A list of an agent's tools that is actually a list of test doubles is
+ * worse than no list.
+ *
+ * `[\w-]+[_-]tests?` and not `[\w-]*tests?`, because the second one also excludes `latest/`.
+ */
+const NOT_SHIPPED = /(?:^|[\\/])(?:tests?|[\w-]+[_-]tests?|__tests__|spec|e2e|examples?|samples?|docs?|fixtures?|node_modules|\.venv|venv)[\\/]|\.(?:test|spec)\.[cm]?[jt]sx?$|_test\.py$|(?:^|[\\/])test_[^\\/]*\.py$/i;
+export function scanAgent(root) {
+    const scan = scanSourceFiles(root, 20_000, (f) => AGENT_FILE.test(f));
+    const tools = [];
+    const guards = [];
+    let emptyBudget = null;
+    let filesRead = 0;
+    for (const path of scan.files) {
+        const where = relative(root, path).replace(/\\/g, '/');
+        if (NOT_SHIPPED.test(where))
+            continue;
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        filesRead += 1;
+        tools.push(...toolsIn(where, text));
+        guards.push(...guardsIn(where, text));
+        if (!emptyBudget) {
+            const empty = budgetSetToNothing(text);
+            if (empty)
+                emptyBudget = { file: where, text: empty };
+        }
+    }
+    return { tools, guards, filesRead, emptyBudget };
+}
+const REACH_READS = {
+    destructive: 'cannot be undone',
+    deletes: 'deletes something',
+    pays: 'moves money',
+    sends: 'sends something out of the building',
+    'runs-code': 'runs code or a shell command',
+    writes: 'changes stored data',
+    reads: 'reads only',
+    'not-sure': '**not decided**',
+};
+export function renderAgent(scan, root) {
+    const { tools, guards, filesRead, emptyBudget } = scan;
+    const lines = ['# What this agent is allowed to do', ''];
+    if (tools.length === 0) {
+        return [
+            '# What this agent is allowed to do',
+            '',
+            `No tool definitions were found in ${filesRead} file(s).`,
+            '',
+            'That is a fact about what was looked for, not a finding that this agent has no tools. These',
+            'are the shapes read here:',
+            '',
+            ...FRAMEWORKS_READ.map((f) => `- ${f}`),
+            '',
+            'An agent built another way, or one whose tools are assembled at run time from a registry, is',
+            'invisible to this and is not reported as safe. Nothing here was sent anywhere; no model was',
+            'called.',
+        ].join(NL);
+    }
+    const kinds = new Set(guards.map((g) => g.kind));
+    const risky = tools.filter((t) => IRREVERSIBLE.includes(t.reach));
+    const undecided = tools.filter((t) => t.reach === 'not-sure');
+    lines.push(`${tools.length} tool(s) in ${filesRead} file(s) read locally. No model was called and nothing left this machine.`, '');
+    // The lethal trifecta leads when it is present, because it outranks everything else here: the
+    // other findings are about what the agent may do by mistake, and this one is about what somebody
+    // else can make it do on purpose.
+    const trifecta = trifectaIn(tools);
+    if (trifecta.complete) {
+        lines.push('> **This agent has all three legs of the lethal trifecta.**', '>', '> It can pull in text an outsider writes, it can read data that is not meant to leave, and it', '> can send data out - in one loop. Text the agent did not write can tell it to read the', '> private thing and post it somewhere, and every step of that is a tool it was given on', '> purpose. A system prompt is not a defence here: whoever writes the untrusted text writes the', '> other half of the prompt.', '');
+    }
+    // The headline, because it is the sentence somebody has to act on.
+    if (risky.length > 0 && !kinds.has('asks-a-person')) {
+        lines.push(`**${risky.length} of them do something that cannot be undone, and nothing in this project stops to ask a person.**`, '');
+    }
+    else if (risky.length > 0) {
+        lines.push(`${risky.length} of them do something that cannot be undone. Something here does ask a person - whether it stands in front of these tools is below.`, '');
+    }
+    lines.push('## The tools', '', '| tool | reaches | where |', '| --- | --- | --- |');
+    for (const t of [...tools].sort((a, b) => rank(a.reach) - rank(b.reach) || a.name.localeCompare(b.name))) {
+        lines.push(`| \`${t.name}\` | ${REACH_READS[t.reach]} | ${t.file}:${t.line} |`);
+    }
+    lines.push('');
+    if (risky.length > 0) {
+        lines.push('## The ones that cannot be taken back', '');
+        for (const t of risky) {
+            lines.push(`- \`${t.name}\` — ${REACH_READS[t.reach]}, because ${t.why}. ${t.file}:${t.line}`);
+        }
+        lines.push('');
+    }
+    if (undecided.length > 0) {
+        lines.push('## The ones this could not decide about', '', 'Read these yourself. They are listed here rather than counted as harmless, which is the only', 'honest thing to do with a tool whose name does not say what it touches.', '', ...undecided.map((t) => `- \`${t.name}\`${t.description ? ` — "${t.description.slice(0, 90)}"` : ''} — ${t.file}:${t.line}`), '');
+    }
+    lines.push('## The lethal trifecta', '');
+    if (trifecta.complete) {
+        lines.push('All three legs are present. Breaking any one of them breaks the attack:', '');
+    }
+    else {
+        const missing = Object.keys(trifecta.legs).filter((c) => trifecta.legs[c].length === 0);
+        lines.push(`Not all three legs are here - nothing was found that ${missing.map((m) => CAPABILITY_MEANS[m]).join(', nor that ')}.`, '', 'That is worth keeping true. Adding one tool is all it takes, and the tool that completes it is', 'usually the harmless-looking one.', '');
+    }
+    for (const capability of Object.keys(trifecta.legs)) {
+        const legTools = trifecta.legs[capability];
+        lines.push(`- **${capability}** (${CAPABILITY_MEANS[capability]}): ${legTools.length === 0 ? 'nothing found' : legTools.slice(0, 6).map((t) => `\`${t.name}\``).join(', ') + (legTools.length > 6 ? `, and ${legTools.length - 6} more` : '')}`);
+    }
+    lines.push('');
+    lines.push('## What stands between them and the real world', '');
+    for (const kind of ['asks-a-person', 'dry-run', 'step-budget', 'tool-allow-list']) {
+        const found = guards.find((g) => g.kind === kind);
+        lines.push(found
+            ? `- **${kind}** — found at ${found.file}:${found.line}. ${GUARD_MEANS[kind]}.`
+            : `- **${kind}** — nothing found anywhere in this project. Without it: ${GUARD_PREVENTS[kind]}.`);
+    }
+    lines.push('');
+    if (emptyBudget) {
+        lines.push('### A ceiling that is written down and set to nothing', '', `\`${emptyBudget.text}\` in ${emptyBudget.file}. A budget removed this way reads as deliberate, and a check`, 'that only looked for the word would have called it a budget.', '');
+    }
+    lines.push('## What this does not check', '', '- **Whether a gate that exists stands in front of these tools.** Finding `interrupt()` in a', '  project means somebody wrote one, not that the refund tool is behind it. That is a question', '  about the graph at run time, and reading the source does not answer it.', '- **Whether the agent is ever given these tools.** A tool can be defined and never passed to a', '  model. This lists what exists, not what is wired up.', '- **What the model will actually do with them.** No prompt was judged and nothing was run.', '- **Tools assembled at run time**, from a registry, a plugin folder or a config file.', '- **Frameworks not in the list above.** Silence about a framework is silence, not approval.', '', 'Every line here is re-derivable: run `tewip agent` in this directory and you get it back.', '');
+    return lines.join(NL);
+}
+const rank = (r) => (IRREVERSIBLE.includes(r) ? 0 : r === 'not-sure' ? 1 : r === 'writes' ? 2 : 3);
+export function runAgent(cmd) {
+    const scan = scanAgent(cmd.root);
+    const report = renderAgent(scan, cmd.root);
+    if (cmd.out)
+        writeFileSync(cmd.out, report, 'utf8');
+    else
+        console.log(report);
+    const asksAPerson = scan.guards.some((g) => g.kind === 'asks-a-person');
+    const ungated = asksAPerson ? 0 : scan.tools.filter((t) => IRREVERSIBLE.includes(t.reach)).length;
+    // The gate fails on the trifecta whether or not a person is asked: an approval step in front of
+    // one tool does not close a path that runs through three.
+    if (cmd.gate && (ungated > 0 || trifectaIn(scan.tools).complete))
+        process.exitCode = 1;
+    return { report, ungated };
+}

package/dist/engine/agent/guards.js

@@ -0,0 +1,74 @@
+// What stands between an agent's tools and the real world.
+//
+// The decision tree every serious write-up of agent safety draws is the same: is the tool on an
+// allow-list, is the input clean, is there a budget, is this a dry run, and for anything that pays,
+// deletes or sends - ask a human. Each of those is a thing somebody either wrote in this project or
+// did not, and a file can be read for it.
+//
+// What a reader must not take from this: that finding `interrupt()` somewhere means the dangerous
+// tools are gated. It means a gate exists in this project. Whether it stands in front of the tool
+// that issues refunds is a question about the running graph, and this does not answer it - the
+// report says so in those words. The useful half is the other direction: when nothing anywhere in
+// a project asks a person anything, and the agent can delete and pay, that is not a maybe.
+import { blank } from './source-text.js';
+const NL = String.fromCharCode(10);
+export const GUARD_MEANS = {
+    'asks-a-person': 'something here stops and waits for a person',
+    'dry-run': 'something here can run without touching anything',
+    'step-budget': 'the loop has a declared ceiling, so it cannot run forever',
+    'tool-allow-list': 'the tools are drawn from a named list rather than whatever is in scope',
+};
+/** Why each one matters, in the words of the failure it prevents. */
+export const GUARD_PREVENTS = {
+    'asks-a-person': 'a refund, a deletion or an email going out because a model decided it should',
+    'dry-run': 'having to find out what it would do by letting it do it',
+    'step-budget': 'loop divergence - the agent retrying the same failing tool until the bill arrives',
+    'tool-allow-list': 'a tool reaching the model because it was in scope, not because anyone chose it',
+};
+const PATTERNS = [
+    {
+        kind: 'asks-a-person',
+        // LangGraph's interrupt and interrupt_before, LangChain's human tools, and the plain words
+        // people use when they write the gate themselves.
+        re: /\b(?:interrupt(?:_before|_after)?\s*[(=]|human_in_the_loop|humanInTheLoop|HumanInputRun|requires?_approval|requiresApproval|needs_approval|await_approval|ask_human|askHuman|confirm_with_user|human_review)\b/g,
+    },
+    {
+        kind: 'dry-run',
+        re: /\b(?:dry_run|dryRun|DRY_RUN|--dry-run|preview_only|previewOnly|simulate_only|no_execute)\b/g,
+    },
+    {
+        kind: 'step-budget',
+        re: /\b(?:max_iterations|maxIterations|max_steps|maxSteps|recursion_limit|recursionLimit|max_turns|maxTurns|max_tool_calls|maxToolCalls|max_tool_roundtrips|stop_after_attempt)\b/g,
+    },
+    {
+        kind: 'tool-allow-list',
+        re: /\b(?:allowed_tools|allowedTools|tool_allow_?list|toolAllow_?[Ll]ist|permitted_tools|enabled_tools|ALLOWED_TOOLS)\b/g,
+    },
+];
+const lineOf = (text, index) => text.slice(0, index).split(NL).length;
+export function guardsIn(file, text) {
+    const out = [];
+    const code = blank(text, /\.py$/i.test(file)).calls;
+    for (const { kind, re } of PATTERNS) {
+        const m = re.exec(code);
+        re.lastIndex = 0;
+        if (!m)
+            continue;
+        const line = lineOf(text, m.index);
+        const evidence = (text.split(NL)[line - 1] ?? '').trim().slice(0, 120);
+        out.push({ kind, file, line, evidence });
+    }
+    return out;
+}
+/**
+ * A step budget that is written down but set to nothing.
+ *
+ * `max_iterations=None` and `recursion_limit = 0` are how a ceiling gets removed without anybody
+ * deleting the line, and a check that only looks for the word would call that a budget. Reported
+ * apart from "no budget at all" because it is worse: it reads as deliberate.
+ */
+export function budgetSetToNothing(raw) {
+    const text = blank(raw, false).calls;
+    const m = /\b(?:max_iterations|maxIterations|max_steps|maxSteps|recursion_limit|recursionLimit|max_turns|maxTurns)\s*[:=]\s*(None|null|0|-1|Infinity|float\(["']inf["']\))/.exec(text);
+    return m ? m[0].replace(/\s+/g, ' ') : null;
+}

package/dist/engine/agent/source-text.js

@@ -0,0 +1,96 @@
+// Reading source as source: one scanner that knows a comment from a string from a pattern.
+//
+// Both halves of this module needed it and both got it wrong in a different direction first, which
+// is the argument for having it once.
+//
+// `tools.ts` blanked comments with a plain regex and lost three real tools from the official MCP
+// filesystem server - `copy_file`, `move_file`, `search_files` - because a glob in a string holds
+// `/*`, so "blank from `/*` to the next `*/`" ate the code between two unrelated path patterns.
+//
+// `guards.ts` blanked strings without stripping comments first, and an apostrophe in an English
+// sentence - "Tewip's own server" - opened a string that stayed open for the rest of the file, so
+// every later line was one quote out of step and the checker found its own regex and reported it
+// as a human approval gate.
+//
+// Both are the same mistake: deciding what a character means without tracking what you are inside.
+const NL = String.fromCharCode(10);
+const blankOut = (s) => s.replace(/[^\n]/g, ' ');
+/**
+ * One pass, both answers, lengths and line breaks preserved throughout.
+ *
+ * Keeping the length means every index into either result still points at the same place in the
+ * original, which is what lets a tool's description be read back out of the untouched source after
+ * the docstring it lives in has been blanked for matching.
+ */
+export function blank(text, python) {
+    const code = [];
+    const calls = [];
+    const keep = (s) => {
+        code.push(s);
+        calls.push(s);
+    };
+    const drop = (s) => {
+        code.push(blankOut(s));
+        calls.push(blankOut(s));
+    };
+    let before = '';
+    let i = 0;
+    while (i < text.length) {
+        const two = text.slice(i, i + 2);
+        const three = text.slice(i, i + 3);
+        // A comment is blanked in both, because nothing in one is code.
+        if ((python && text[i] === '#') || (!python && two === '//')) {
+            const end = text.indexOf(NL, i);
+            const stop = end === -1 ? text.length : end;
+            drop(text.slice(i, stop));
+            i = stop;
+            continue;
+        }
+        if (!python && two === '/*') {
+            const end = text.indexOf('*/', i + 2);
+            const stop = end === -1 ? text.length : end + 2;
+            drop(text.slice(i, stop));
+            i = stop;
+            continue;
+        }
+        // A Python docstring is documentation, and a framework documents its own decorator by showing
+        // it being used. crewAI's `@tool` docstring contains `@tool` and `def greet(...)`.
+        if (python && (three === '"""' || three === "'''")) {
+            const end = text.indexOf(three, i + 3);
+            const stop = end === -1 ? text.length : end + 3;
+            drop(text.slice(i, stop));
+            i = stop;
+            continue;
+        }
+        const ch = text[i];
+        const quote = ch === '"' || ch === "'" || ch === '`';
+        // A regex literal, not a division: only where an expression cannot have just ended.
+        const regex = !python && ch === '/' && (before === '' || '(,=:[!&|?{};+*'.includes(before));
+        if (!quote && !regex) {
+            keep(ch);
+            if (!/\s/.test(ch))
+                before = ch;
+            i += 1;
+            continue;
+        }
+        const close = quote ? ch : '/';
+        let j = i + 1;
+        while (j < text.length && text[j] !== close) {
+            if (text[j] === '\\') {
+                j += 2;
+                continue;
+            }
+            // An unterminated quote must not swallow the file; only a backtick spans lines.
+            if (text[j] === NL && quote && ch !== '`')
+                break;
+            j += 1;
+        }
+        const inner = text.slice(i + 1, j);
+        const closer = text[j] ?? '';
+        code.push(ch, inner, closer);
+        calls.push(ch, blankOut(inner), closer);
+        before = closer || before;
+        i = j + 1;
+    }
+    return { code: code.join(''), calls: calls.join('') };
+}

package/dist/engine/agent/tools.js

@@ -0,0 +1,187 @@
+// What an AI agent is allowed to do, read from its source before it ever runs.
+//
+// Every tool in this market evaluates an agent by running it: Langfuse, Phoenix, RAGAS, TruLens,
+// DeepEval, Promptfoo, Giskard, garak. They need a runtime, a token budget and usually an account,
+// and most judge with another model, so the same agent scores differently on Tuesday. They answer
+// "is this agent any good".
+//
+// Nobody answers the question an IT department actually has to sign off on: **what is this agent
+// allowed to do, and what stands between it and the real world?** That one is decidable by
+// reading, for free, offline, in CI, before anything runs. It is also the question an auditor
+// asks, and the one a post-mortem starts from.
+//
+// The honesty rule is the same as everywhere else in Tewip. A tool whose reach cannot be decided
+// from its name and description is reported as undecided, never as safe. "No approval gate found"
+// is a fact about this source, not a verdict about the running system, and the report says which
+// it is.
+import { blank } from './source-text.js';
+const NL = String.fromCharCode(10);
+const PYTHON_SHAPES = [
+    // LangChain / LangGraph: @tool("name") or a bare @tool above the function that names it.
+    { framework: 'LangChain @tool', re: /@tool\s*\(\s*["']([\w.-]+)["']/g },
+    { framework: 'LangChain @tool', re: /@tool(?:\s*\(\s*\))?\s*\n\s*(?:async\s+)?def\s+(\w+)/g },
+    // MCP Python SDK, and FastMCP.
+    { framework: 'MCP @tool', re: /@(?:mcp|server|app)\.tool\s*\(\s*(?:\)\s*)?\n\s*(?:async\s+)?def\s+(\w+)/g },
+    { framework: 'MCP @tool', re: /@(?:mcp|server|app)\.tool\s*\(\s*name\s*=\s*["']([\w.-]+)["']/g },
+    // OpenAI Agents SDK.
+    { framework: 'OpenAI @function_tool', re: /@function_tool(?:\s*\([^)]*\))?\s*\n\s*(?:async\s+)?def\s+(\w+)/g },
+    // Explicit construction, LangChain and CrewAI alike.
+    { framework: 'Tool(name=...)', re: /\b(?:Structured)?Tool\s*\(\s*name\s*=\s*["']([\w.\s-]+)["']/g },
+];
+const JS_SHAPES = [
+    // MCP TypeScript SDK.
+    { framework: 'MCP server.tool()', re: /\b(?:server|mcp|app)\s*\.\s*(?:tool|registerTool)\s*\(\s*["']([\w.-]+)["']/g },
+    // Vercel AI SDK: tools: { theName: tool({ ... }) }
+    { framework: 'AI SDK tool()', re: /\b([\w.-]+)\s*:\s*tool\s*\(\s*\{/g },
+    // Anthropic's own tool shape, and anything else that writes a JSON schema by hand.
+    { framework: 'name + input_schema', re: /name\s*:\s*["']([\w.-]+)["'][^}]{0,400}?input_schema\s*:/g },
+    // OpenAI function calling.
+    { framework: 'OpenAI function', re: /type\s*:\s*["']function["'][^}]{0,200}?name\s*:\s*["']([\w.-]+)["']/g },
+    // LangChain JS.
+    { framework: 'DynamicStructuredTool', re: /new\s+Dynamic(?:Structured)?Tool\s*\(\s*\{[^}]{0,200}?name\s*:\s*["']([\w.-]+)["']/g },
+];
+/**
+ * What the tool does to the world, from its name and its description.
+ *
+ * Ordered most-serious first on purpose: `delete_and_notify` is a delete, not a send. A name that
+ * matches nothing is `not-sure`, which is printed as undecided - never folded into "reads", because
+ * the whole value of this report is that it does not quietly downgrade a risk it failed to parse.
+ */
+/**
+ * `ENDING` matters more than the word lists do.
+ *
+ * Without it these were written `\b(?:read|...)\b`, and `\bread\b` does not match "Reads" - the
+ * trailing s removes the word boundary. Tool names survive that, because `read_file` splits on the
+ * underscore, but descriptions do not: they are written in the third person. "Reads test files and
+ * says..." matched nothing, and all seventeen tools in Tewip's own MCP server came back undecided
+ * while the file sat there saying exactly what each one did.
+ */
+const ENDING = String.raw `(?:e?[sd]|ing)?\b`;
+const verbs = (words) => new RegExp(String.raw `\b(?:${words})${ENDING}`, 'i');
+const REACH = [
+    { reach: 'deletes', words: verbs('delete|destroy|drop|purge|wipe|remove|revoke|terminate|uninstall|erase|truncate') },
+    { reach: 'pays', words: verbs('pay|payment|refund|charge|transfer|invoice|payout|purchase|checkout|billing|subscribe|withdraw') },
+    { reach: 'runs-code', words: verbs('exec|execute|shell|bash|terminal|subprocess|run_code|runcode|eval|interpreter|command') },
+    { reach: 'sends', words: verbs('send|email|mail|post|publish|notify|notification|sms|slack|tweet|broadcast|message|dispatch|share|invite') },
+    { reach: 'writes', words: verbs('write|create|update|insert|upsert|upload|save|edit|modify|patch|rename|commit|merge|deploy|provision|grant') },
+    { reach: 'reads', words: verbs('get|list|read|search|fetch|find|query|lookup|show|describe|view|count|check|status|say|report|explain|answer|tell|trace|plan|prove|recall') },
+];
+/** Everything that cannot be taken back once the model has called it. */
+export const IRREVERSIBLE = ['destructive', 'deletes', 'pays', 'sends', 'runs-code'];
+export const CAPABILITY_MEANS = {
+    'untrusted-input': 'pulls in text somebody outside your company can write',
+    'private-data': 'reads data that is not meant to leave',
+    'can-send-out': 'can put data somewhere outside',
+};
+const CAPABILITIES = [
+    {
+        capability: 'untrusted-input',
+        words: /\b(?:fetch|browse|scrape|crawl|web|url|http|search|google|bing|read_email|readmail|inbox|gmail|ticket|issue|comment|review|pdf|document|attachment|rss|feed|webhook_in|transcri)\w*/i,
+    },
+    {
+        capability: 'private-data',
+        words: /\b(?:sql|query|database|db|select|table|record|customer|user|account|employee|salary|patient|secret|credential|token|key|env|vault|file|read_file|readfile|fs|s3|bucket|storage|internal|crm|ledger)\w*/i,
+    },
+    {
+        capability: 'can-send-out',
+        words: /\b(?:send|email|mail|smtp|post|publish|webhook|slack|discord|teams|sms|twilio|tweet|upload|push|notify|share|export|forward|broadcast|comment|reply)\w*/i,
+    },
+];
+export function capabilitiesOf(name, description) {
+    const text = `${name.replace(/[_-]/g, ' ')} ${description}`;
+    return CAPABILITIES.filter(({ words }) => words.test(text)).map(({ capability }) => capability);
+}
+export function trifectaIn(tools) {
+    const legs = { 'untrusted-input': [], 'private-data': [], 'can-send-out': [] };
+    for (const tool of tools)
+        for (const c of tool.capabilities)
+            legs[c].push(tool);
+    return { complete: Object.values(legs).every((l) => l.length > 0), legs };
+}
+/**
+ * What the author declared, which beats anything guessed from a name.
+ *
+ * MCP tools carry `readOnlyHint` and `destructiveHint`, and a tool that says of itself that it is
+ * read-only is better evidence than any verb list. Both shapes are read: written inline, and
+ * written once as a named constant and reused - `annotations: readOnly`, with
+ * `const readOnly = { readOnlyHint: true, ... }` further up the same file, which is how Tewip's own
+ * server does it and therefore the shape most likely to be missed by a check written against the
+ * documentation instead of against real code.
+ */
+function declaredHint(text, from) {
+    const window = text.slice(from, from + 1200);
+    const named = /annotations\s*:\s*([A-Za-z_$][\w$]*)/.exec(window);
+    const where = named
+        ? new RegExp(String.raw `\b(?:const|let|var)\s+${named[1]}\s*(?::[^=]{0,120})?=\s*\{([^}]{0,300})\}`).exec(text)?.[1] ?? ''
+        : window;
+    if (/destructiveHint\s*:\s*true/.test(where))
+        return { reach: 'destructive', why: 'its own annotation says destructiveHint: true' };
+    if (/readOnlyHint\s*:\s*true/.test(where))
+        return { reach: 'reads', why: 'it declares readOnlyHint: true' };
+    return null;
+}
+export function reachOf(name, description) {
+    // The name first. A description is marketing for the model and often says "safely" about a tool
+    // that drops a table; the name is what the person who wrote it called the thing.
+    for (const { reach, words } of REACH) {
+        const hit = words.exec(name.replace(/[_-]/g, ' '));
+        if (hit)
+            return { reach, why: `its name contains "${hit[0]}"` };
+    }
+    // Only the opening clause of the description, where a tool says what it does: "Reads test files
+    // and says...". Searching the whole of it matches verbs in prose that are about something else
+    // entirely - Tewip's own `explain_failure` describes "history on this commit versus others" and
+    // was classified as a tool that writes, on the strength of the word "commit" in a sentence about
+    // reading. A first clause is a claim about the tool; the rest is explanation.
+    const opening = description.split(/[.;:]/)[0]?.slice(0, 120) ?? '';
+    for (const { reach, words } of REACH) {
+        const hit = words.exec(opening);
+        if (hit)
+            return { reach, why: `its description opens with "${hit[0]}"` };
+    }
+    return { reach: 'not-sure', why: 'neither its name nor its description says what it does to the world' };
+}
+const lineOf = (text, index) => text.slice(0, index).split(NL).length;
+/** The description written beside a tool, when one is written at all. */
+function describedNear(text, from) {
+    const window = text.slice(from, from + 600);
+    const described = 
+    // Up to 800: a real tool description is a paragraph, not a label. Capped at 200 this matched
+    // none of the seventeen in Tewip's own MCP server, so every one of them came back undecided.
+    /description\s*[:=]\s*["'`]((?:[^"'`\\]|\\.){3,800})["'`]/.exec(window) ??
+        // A Python docstring on the line after the def is the description the framework sends.
+        /def\s+\w+[^\n]*\n\s*(?:"""|''')\s*([^\n"']{3,200})/.exec(window);
+    return (described?.[1] ?? '').trim().replace(/\s+/g, ' ');
+}
+export function toolsIn(file, text) {
+    const python = /\.py$/i.test(file);
+    const source = blank(text, python).code;
+    const found = new Map();
+    for (const { framework, re } of python ? PYTHON_SHAPES : JS_SHAPES) {
+        for (const m of source.matchAll(re)) {
+            const name = m[1]?.trim();
+            if (!name || name.length > 60)
+                continue;
+            const line = lineOf(source, m.index ?? 0);
+            // One entry per name per file: the same tool matched by two shapes is one tool.
+            const key = `${name}:${file}`;
+            if (found.has(key))
+                continue;
+            // The original text, not the blanked one: a Python docstring *is* the description, and it
+            // has just been blanked for matching. The indexes line up because blanking kept the lengths.
+            const description = describedNear(text, m.index ?? 0);
+            // Declared first, guessed second.
+            const { reach, why } = declaredHint(source, m.index ?? 0) ?? reachOf(name, description);
+            found.set(key, { name, file, line, shape: framework, description, reach, why, capabilities: capabilitiesOf(name, description) });
+        }
+    }
+    return [...found.values()];
+}
+/** The frameworks this knows how to read, named in the report so the silence is not mistaken. */
+export const FRAMEWORKS_READ = [
+    'LangChain and LangGraph (`@tool`, `Tool(name=...)`, `DynamicStructuredTool`)',
+    'the MCP SDKs, Python and TypeScript (`@mcp.tool`, `server.tool(...)`)',
+    'the OpenAI Agents SDK (`@function_tool`) and OpenAI function calling',
+    'the Vercel AI SDK (`tool({ ... })`)',
+    "Anthropic's tool shape (`name` beside `input_schema`)",
+];

package/dist/engine/portfolio/portfolio-command.js

@@ -17,6 +17,8 @@ import { NEEDS_A_LOOK } from '../sbom/licences.js';
 import { findBarriers } from '../access/access-command.js';
 import { migrationsUnder, readMigration } from '../schema/schema-command.js';
 import { vouchAll } from '../vouch/vouch-command.js';
+import { scanAgent } from '../agent/agent-command.js';
+import { IRREVERSIBLE } from '../agent/tools.js';
 import { CHECKS, renderPortfolio } from './portfolio.js';
 const ran = (count, detail) => ({ ran: true, count, detail });
 const JS = /\.(?:[cm]?[jt]sx?)$/;
@@ -65,6 +67,16 @@ export function examine(path, quick = false) {
         const risky = found.filter((f) => triageSecret(f, path, new Set()).verdict === 'real-risk');
         return ran(risky.length, `${found.length} shape(s) matched, ${risky.length} need action`);
     });
+    // An agent's irreversible tools belong on this page for the same reason the rest do: at forty
+    // repositories nobody opens each one, and "which of these can delete things on its own" is the
+    // question that now gets asked first.
+    cells['agent tools'] = attempt(() => {
+        const scan = scanAgent(path);
+        if (scan.tools.length === 0)
+            return { ran: false, why: 'no agent tool definitions found, in the frameworks this reads' };
+        const risky = scan.tools.filter((t) => IRREVERSIBLE.includes(t.reach));
+        return ran(risky.length, `${scan.tools.length} tool(s), ${risky.length} that cannot be undone`);
+    });
     cells.injection = attempt(() => {
         const files = scanSourceFiles(path, 20_000, (f) => JS.test(f) && !/\.(?:test|spec)\./.test(f)).files;
         let n = 0;

package/dist/engine/portfolio/portfolio.js

@@ -1,4 +1,4 @@
-export const CHECKS = ['secrets', 'injection', 'containers', 'licences', 'access', 'migrations', 'hollow tests'];
+export const CHECKS = ['secrets', 'injection', 'agent tools', 'containers', 'licences', 'access', 'migrations', 'hollow tests'];
 /** What each column counts, so the header is not seven words a reader has to guess at. */
 export const COUNTS = {
     secrets: 'credentials that need somebody to act now',
@@ -7,6 +7,7 @@ export const COUNTS = {
     licences: 'dependencies whose licence needs a decision',
     access: 'accessibility barriers, not warnings',
     migrations: 'migrations that destroy data or break the running version',
+    'agent tools': 'tools an AI agent can call that cannot be undone',
     'hollow tests': 'tests that cannot fail',
 };
 export function worstFirst(rows) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.73.1",
+  "version": "0.74.0",
   "mcpName": "io.github.hmamut39/tewip",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [