@agentpro/scroll 0.0.0-stage → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +55 -0
  2. package/LICENSE +21 -0
  3. package/README.md +293 -2
  4. package/SPEC.md +1079 -0
  5. package/bin/scroll.js +8 -0
  6. package/docs/prompt-caching.md +128 -0
  7. package/index.js +33 -0
  8. package/lib/audit.js +358 -0
  9. package/lib/auth.js +849 -0
  10. package/lib/chat-sdk/admin-controller.js +289 -0
  11. package/lib/chat-sdk/debouncer.js +94 -0
  12. package/lib/chat-sdk/group-grants.js +150 -0
  13. package/lib/chat-sdk/index.js +222 -0
  14. package/lib/chat-sdk/long-task-runner.js +413 -0
  15. package/lib/chat-session.js +1788 -0
  16. package/lib/chat-telemetry.js +557 -0
  17. package/lib/codex-app-server.js +851 -0
  18. package/lib/digest.js +112 -0
  19. package/lib/effects.js +157 -0
  20. package/lib/eval.js +408 -0
  21. package/lib/grounding.js +356 -0
  22. package/lib/installers.js +176 -0
  23. package/lib/knowledge.js +335 -0
  24. package/lib/ledger.js +38 -0
  25. package/lib/loop.js +197 -0
  26. package/lib/mcp-client.js +926 -0
  27. package/lib/memory-cli.js +66 -0
  28. package/lib/memory-tracker.js +1472 -0
  29. package/lib/memory.js +1279 -0
  30. package/lib/people-cli.js +81 -0
  31. package/lib/people.js +534 -0
  32. package/lib/permissions.js +272 -0
  33. package/lib/providers.js +1572 -0
  34. package/lib/runtime.js +928 -0
  35. package/lib/sandbox.js +744 -0
  36. package/lib/scheduler.js +402 -0
  37. package/lib/scroll.js +1225 -0
  38. package/lib/skill-cli.js +120 -0
  39. package/lib/skill-eval.js +156 -0
  40. package/lib/skills.js +860 -0
  41. package/lib/style.js +126 -0
  42. package/lib/tool-retriever.js +489 -0
  43. package/lib/tools.js +1833 -0
  44. package/lib/user.js +711 -0
  45. package/lib/vault.js +151 -0
  46. package/package.json +88 -4
  47. package/templates/agent/IDENTITY.md +56 -0
  48. package/templates/agent/SOUL.md +23 -0
  49. package/templates/agent/TOOLS.md +25 -0
  50. package/templates/agent/evals/case-02-citation-discipline.md +29 -0
  51. package/templates/agent/evals/case-03-boundary.md +27 -0
  52. package/templates/agent/evals/case-example.md +43 -0
  53. package/templates/agent/hard-rules.md +11 -0
  54. package/templates/agent/memory/lessons.md +5 -0
  55. package/templates/agent/memory/log/.gitkeep +0 -0
  56. package/templates/external-safety-contract.md +5 -0
  57. package/templates/long-task-planner.md +17 -0
  58. package/templates/work/LOOP.md +37 -0
  59. package/templates/work/WORK.md +50 -0
  60. package/types/chat.d.ts +61 -0
  61. package/types/index.d.ts +112 -0
package/lib/tools.js ADDED
@@ -0,0 +1,1833 @@
1
+ // SCROLL 2.5 -- §47 Live Multi-Round Tool Executor, Built-in Registry,
2
+ // Security Boundary Wall (§20-§22, §28, §42), OS Sandbox, & §47.2 Portable Tool Retriever.
3
+ //
4
+ // Every tool call -- direct, MCP, or unwrapped from `tool_invoke` -- passes through ONE
5
+ // deterministic safety gate:
6
+ // 0. Transparent unwrap for `tool_invoke` (anti-recursion, hydrated check, schemaHash pin,
7
+ // host JSON Schema arg validation) so ALL downstream gates inspect the REAL target tool.
8
+ // 1. Unified allow-list (`IDENTITY.security.tools_allow` intersected with per-turn `toolsAllow`).
9
+ // 2. §42 boundary enforcement (external/mixed-group turns cannot invoke write/exec/admin tools).
10
+ // 3. §21 risk tier + floor + policy matrix (`resolveTier` + `policyForTier` + `evaluateAction`).
11
+ // 4. §22 provenance-aware action grounding for financial/destructive tiers (`checkGrounding`).
12
+ // 5. §21 per-call persistent HITL approval token (`approvalStore` + `userDoc.canApprove`).
13
+ // 6. §28 fail-closed post-write effect confirmation (`confirmEffect`, read-only probe only).
14
+ // 7. Tamper-evident hash-chained audit trail (`auditChain` + ring buffer).
15
+ //
16
+ // Zero runtime dependencies. Node >= 20 built-ins only.
17
+ import fs from 'node:fs';
18
+ import dns from 'node:dns';
19
+ import http from 'node:http';
20
+ import https from 'node:https';
21
+ import net from 'node:net';
22
+ import path from 'node:path';
23
+ import crypto from 'node:crypto';
24
+ import {
25
+ resolveTier,
26
+ maxTier,
27
+ policyForTier,
28
+ needsGrounding,
29
+ evaluateAction,
30
+ loadMcpRisk,
31
+ loadAgentSecurity,
32
+ matchesToolAllow,
33
+ } from './permissions.js';
34
+ import { checkGrounding } from './grounding.js';
35
+ import { confirmEffect } from './effects.js';
36
+ import { runSandboxedExec, evaluateExecPolicy } from './sandbox.js';
37
+ import { hashArgs } from './chat-telemetry.js';
38
+ import {
39
+ buildToolRetriever,
40
+ buildAvailableToolsIndex,
41
+ validateToolArgs,
42
+ computeSchemaHash,
43
+ } from './tool-retriever.js';
44
+ import { scanText } from './skills.js';
45
+
46
+ const EXTERNAL_SENSITIVE_FILES = new Set([
47
+ 'identity.md',
48
+ 'soul.md',
49
+ 'hard-rules.md',
50
+ 'tools.md',
51
+ 'lessons.md',
52
+ 'user.md',
53
+ 'work.md',
54
+ 'loop.md',
55
+ ]);
56
+
57
+ function hexPairToIpv4(hiHex, loHex) {
58
+ const hi = parseInt(hiHex, 16);
59
+ const lo = parseInt(loHex, 16);
60
+ if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
61
+ return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
62
+ }
63
+
64
+ function isPrivateIpv4Octets(o0, o1, o2, o3) {
65
+ if ([o0, o1, o2, o3].some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
66
+ if (o0 === 0) return true; // 0.0.0.0/8
67
+ if (o0 === 10) return true; // 10.0.0.0/8
68
+ if (o0 === 100 && o1 >= 64 && o1 <= 127) return true; // 100.64.0.0/10 CGNAT / Tailscale
69
+ if (o0 === 127) return true; // 127.0.0.0/8 loopback
70
+ if (o0 === 169 && o1 === 254) return true; // 169.254.0.0/16 link-local / cloud metadata
71
+ if (o0 === 172 && o1 >= 16 && o1 <= 31) return true; // 172.16.0.0/12
72
+ if (o0 === 192 && o1 === 0 && (o2 === 0 || o2 === 2)) return true; // 192.0.0.0/24, 192.0.2.0/24
73
+ if (o0 === 192 && o1 === 168) return true; // 192.168.0.0/16
74
+ if (o0 === 198 && (o1 === 18 || o1 === 19)) return true; // 198.18.0.0/15 benchmark
75
+ if (o0 === 198 && o1 === 51 && o2 === 100) return true; // 198.51.100.0/24 TEST-NET-2
76
+ if (o0 === 203 && o1 === 0 && o2 === 113) return true; // 203.0.113.0/24 TEST-NET-3
77
+ if (o0 >= 224) return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + broadcast
78
+ return false;
79
+ }
80
+
81
+ function expandIpv6ToWords(rawIp) {
82
+ let ip = String(rawIp || '').trim().toLowerCase();
83
+ if (!ip) return null;
84
+ // Convert trailing embedded IPv4 (e.g. `::ffff:127.0.0.1` or `0:0:0:0:0:ffff:127.0.0.1`) to two 16-bit hex words
85
+ const lastColon = ip.lastIndexOf(':');
86
+ if (lastColon >= 0 && ip.slice(lastColon + 1).includes('.')) {
87
+ const v4Part = ip.slice(lastColon + 1);
88
+ if (!net.isIPv4(v4Part)) return null;
89
+ const o = v4Part.split('.').map(Number);
90
+ const wHi = ((o[0] << 8) | o[1]).toString(16);
91
+ const wLo = ((o[2] << 8) | o[3]).toString(16);
92
+ ip = `${ip.slice(0, lastColon + 1)}${wHi}:${wLo}`;
93
+ }
94
+ const halves = ip.split('::');
95
+ if (halves.length > 2) return null;
96
+ const left = halves[0] ? halves[0].split(':') : [];
97
+ const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
98
+ const missing = halves.length === 2 ? 8 - (left.length + right.length) : 0;
99
+ if (halves.length === 2 ? missing < 0 : left.length !== 8) return null;
100
+ const full = [...left, ...Array(missing).fill('0'), ...right];
101
+ if (full.length !== 8) return null;
102
+ const words = [];
103
+ for (const part of full) {
104
+ if (!/^[0-9a-f]{1,4}$/.test(part)) return null;
105
+ words.push(parseInt(part, 16));
106
+ }
107
+ return words;
108
+ }
109
+
110
+ export function isPrivateIp(rawIp) {
111
+ let ip = String(rawIp || '').trim().toLowerCase().replace(/^\[|\]$/g, '');
112
+ const zoneIdx = ip.indexOf('%');
113
+ if (zoneIdx >= 0) ip = ip.slice(0, zoneIdx);
114
+ if (!ip) return true;
115
+
116
+ if (net.isIPv4(ip)) {
117
+ const parts = ip.split('.').map(Number);
118
+ return isPrivateIpv4Octets(parts[0], parts[1], parts[2], parts[3]);
119
+ }
120
+ if (net.isIPv6(ip)) {
121
+ const w = expandIpv6ToWords(ip);
122
+ if (!w) return true;
123
+ const allZero6 = w[0] === 0 && w[1] === 0 && w[2] === 0 && w[3] === 0 && w[4] === 0;
124
+ // Unspecified `::` & Loopback `::1`
125
+ if (allZero6 && w[5] === 0 && w[6] === 0 && (w[7] === 0 || w[7] === 1)) return true;
126
+ // IPv4-mapped IPv6 `::ffff:a.b.c.d` (including expanded `0:0:0:0:0:ffff:7f00:1`)
127
+ if (allZero6 && w[5] === 0xffff) {
128
+ return isPrivateIpv4Octets((w[6] >> 8) & 0xff, w[6] & 0xff, (w[7] >> 8) & 0xff, w[7] & 0xff);
129
+ }
130
+ // IPv4-translated `::ffff:0:a.b.c.d` (RFC 2765)
131
+ if (w[0] === 0 && w[1] === 0 && w[2] === 0 && w[3] === 0 && w[4] === 0xffff && w[5] === 0) {
132
+ return isPrivateIpv4Octets((w[6] >> 8) & 0xff, w[6] & 0xff, (w[7] >> 8) & 0xff, w[7] & 0xff);
133
+ }
134
+ // Deprecated IPv4-compatible IPv6 `::a.b.c.d`
135
+ if (allZero6 && w[5] === 0 && (w[6] !== 0 || w[7] > 1)) {
136
+ return isPrivateIpv4Octets((w[6] >> 8) & 0xff, w[6] & 0xff, (w[7] >> 8) & 0xff, w[7] & 0xff);
137
+ }
138
+ // NAT64 well-known (`64:ff9b::/96`) & local-use (`64:ff9b:1::/48`)
139
+ if (w[0] === 0x0064 && w[1] === 0xff9b && ((w[2] === 0 && w[3] === 0 && w[4] === 0 && w[5] === 0) || w[2] === 1)) return true;
140
+ // Discard-Only Prefix (`100::/64`, RFC 6666)
141
+ if (w[0] === 0x0100 && w[1] === 0 && w[2] === 0 && w[3] === 0) return true;
142
+ // 6to4 (`2002::/16`)
143
+ if (w[0] === 0x2002) return true;
144
+ // Teredo (`2001:0000::/32`), Benchmarking (`2001:2::/48`), Documentation (`2001:db8::/32`)
145
+ if (w[0] === 0x2001 && (w[1] === 0x0000 || w[1] === 0x0db8 || (w[1] === 0x0002 && w[2] === 0))) return true;
146
+ // ULA `fc00::/7`
147
+ if ((w[0] & 0xfe00) === 0xfc00) return true;
148
+ // Link-local `fe80::/10`
149
+ if ((w[0] & 0xffc0) === 0xfe80) return true;
150
+ // Deprecated site-local `fec0::/10`
151
+ if ((w[0] & 0xffc0) === 0xfec0) return true;
152
+ // Multicast `ff00::/8`
153
+ if ((w[0] & 0xff00) === 0xff00) return true;
154
+ return false;
155
+ }
156
+ return false;
157
+ }
158
+
159
+ function hostMatchesEgressAllow(host, egressAllow) {
160
+ if (!Array.isArray(egressAllow)) return true;
161
+ if (!egressAllow.length) return false;
162
+ const h = String(host || '').toLowerCase();
163
+ for (const rule of egressAllow) {
164
+ const r = String(rule || '').trim().toLowerCase();
165
+ if (!r) continue;
166
+ if (r === '*') return true;
167
+ if (r === h) return true;
168
+ if (r.startsWith('*.') && (h === r.slice(2) || h.endsWith(r.slice(1)))) return true;
169
+ }
170
+ return false;
171
+ }
172
+
173
+ export function isSafePublicUrl(rawUrl, { egressAllow = null } = {}) {
174
+ let u;
175
+ try { u = new URL(String(rawUrl || '')); } catch { return { ok: false, reason: 'invalid_url' }; }
176
+ if (u.protocol !== 'http:' && u.protocol !== 'https:') {
177
+ return { ok: false, reason: `disallowed_protocol:${u.protocol}` };
178
+ }
179
+ const host = (u.hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
180
+ if (!host || host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || host.endsWith('.internal')) {
181
+ return { ok: false, reason: `ssrf_blocked_host:${host}` };
182
+ }
183
+ if (host === 'metadata.google.internal' || host === '169.254.169.254') {
184
+ return { ok: false, reason: 'ssrf_blocked_metadata' };
185
+ }
186
+ if (isPrivateIp(host)) {
187
+ return { ok: false, reason: `ssrf_blocked_private_ip:${host}` };
188
+ }
189
+ if (egressAllow !== null && !hostMatchesEgressAllow(host, egressAllow)) {
190
+ return { ok: false, reason: `egress_host_not_allowed:${host}` };
191
+ }
192
+ return { ok: true, url: u.toString(), host };
193
+ }
194
+
195
+ export async function resolveAndValidatePublicUrl(rawUrl, {
196
+ egressAllow = null,
197
+ contentAudience = 'internal',
198
+ dnsLookup = null,
199
+ } = {}) {
200
+ // Egress axis on external audience: block outbound web_fetch unless egressAllow explicitly permits host
201
+ if (contentAudience === 'external' && (!Array.isArray(egressAllow) || !egressAllow.length)) {
202
+ return { ok: false, reason: 'egress_blocked_on_external_audience' };
203
+ }
204
+ const base = isSafePublicUrl(rawUrl, { egressAllow });
205
+ if (!base.ok) return base;
206
+
207
+ const ipVer = net.isIP(base.host);
208
+ if (ipVer) {
209
+ return { ...base, resolvedIp: base.host, resolvedFamily: ipVer };
210
+ }
211
+
212
+ // DNS resolution check (fail CLOSED on every DNS error; validates ALL A/AAAA records and pins first public IP)
213
+ const lookupFn = typeof dnsLookup === 'function'
214
+ ? dnsLookup
215
+ : (h) => dns.promises.lookup(h, { all: true, verbatim: true });
216
+
217
+ let records;
218
+ try {
219
+ records = await lookupFn(base.host);
220
+ } catch (err) {
221
+ return { ok: false, reason: `ssrf_dns_lookup_failed:${base.host}:${err?.message || err}` };
222
+ }
223
+ const list = Array.isArray(records) ? records : (records ? [records] : []);
224
+ if (!list.length) {
225
+ return { ok: false, reason: `ssrf_dns_no_records:${base.host}` };
226
+ }
227
+
228
+ let firstIp = null;
229
+ let firstFamily = 4;
230
+ for (const rec of list) {
231
+ const ip = typeof rec === 'string' ? rec : rec?.address;
232
+ if (!ip) continue;
233
+ if (isPrivateIp(ip)) {
234
+ return { ok: false, reason: `ssrf_dns_resolved_private_ip:${base.host}->${ip}` };
235
+ }
236
+ if (!firstIp) {
237
+ firstIp = ip;
238
+ firstFamily = (typeof rec === 'object' && rec?.family) || net.isIP(ip) || 4;
239
+ }
240
+ }
241
+ if (!firstIp) {
242
+ return { ok: false, reason: `ssrf_dns_no_valid_ip:${base.host}` };
243
+ }
244
+ return { ...base, resolvedIp: firstIp, resolvedFamily: firstFamily };
245
+ }
246
+
247
+ async function readBoundedStreamText(res, maxBytes = 2 * 1024 * 1024) {
248
+ const cap = Math.max(4096, Number(maxBytes || 2 * 1024 * 1024));
249
+ if (res.body && typeof res.body.getReader === 'function') {
250
+ const reader = res.body.getReader();
251
+ const chunks = [];
252
+ let total = 0;
253
+ let truncated = false;
254
+ try {
255
+ while (true) {
256
+ const { done, value } = await reader.read();
257
+ if (done) break;
258
+ const buf = Buffer.from(value);
259
+ if (total + buf.length > cap) {
260
+ const take = Math.max(0, cap - total);
261
+ if (take > 0) chunks.push(buf.subarray(0, take));
262
+ total += take;
263
+ truncated = true;
264
+ try { await reader.cancel(); } catch { /* ignore */ }
265
+ break;
266
+ }
267
+ chunks.push(buf);
268
+ total += buf.length;
269
+ }
270
+ } finally {
271
+ try { reader.releaseLock(); } catch { /* ignore */ }
272
+ }
273
+ return { text: Buffer.concat(chunks).toString('utf8'), bytesRead: total, truncated };
274
+ }
275
+ const raw = await res.text();
276
+ const buf = Buffer.from(String(raw || ''), 'utf8');
277
+ if (buf.length > cap) {
278
+ return { text: buf.subarray(0, cap).toString('utf8'), bytesRead: cap, truncated: true };
279
+ }
280
+ return { text: String(raw || ''), bytesRead: buf.length, truncated: false };
281
+ }
282
+
283
+ // Socket-pinned HTTP(S) GET preventing DNS rebinding TOCTOU (pins lookup to validated IP while
284
+ // preserving original hostname for TLS SNI, certificate verification, and Host header).
285
+ function pinnedHttpGet(urlStr, { resolvedIp, resolvedFamily = 4, signal = null, maxBytes = 2 * 1024 * 1024, timeoutMs = 20_000 } = {}) {
286
+ return new Promise((resolve, reject) => {
287
+ let u;
288
+ try { u = new URL(urlStr); } catch { reject(new Error('invalid_url')); return; }
289
+ const isHttps = u.protocol === 'https:';
290
+ const mod = isHttps ? https : http;
291
+ const cap = Math.max(4096, Number(maxBytes || 2 * 1024 * 1024));
292
+
293
+ const opts = {
294
+ protocol: u.protocol,
295
+ hostname: u.hostname,
296
+ port: u.port || (isHttps ? 443 : 80),
297
+ path: `${u.pathname}${u.search}`,
298
+ method: 'GET',
299
+ agent: false, // Never reuse pooled keep-alive sockets across DNS-pinned fetches
300
+ family: resolvedFamily,
301
+ autoSelectFamily: false,
302
+ headers: {
303
+ Host: u.host,
304
+ 'User-Agent': 'scroll-agent/2.5',
305
+ Accept: '*/*',
306
+ },
307
+ timeout: timeoutMs,
308
+ ...(isHttps ? { servername: u.hostname } : {}),
309
+ lookup: (_host, lookupOpts, cb) => {
310
+ const callback = typeof lookupOpts === 'function' ? lookupOpts : cb;
311
+ if (lookupOpts && typeof lookupOpts === 'object' && lookupOpts.all) {
312
+ callback(null, [{ address: resolvedIp, family: resolvedFamily }]);
313
+ } else {
314
+ callback(null, resolvedIp, resolvedFamily);
315
+ }
316
+ },
317
+ };
318
+
319
+ const req = mod.request(opts, (res) => {
320
+ const peerAddr = res.socket?.remoteAddress;
321
+ if (peerAddr && isPrivateIp(peerAddr)) {
322
+ res.destroy();
323
+ reject(new Error(`ssrf_peer_ip_private:${peerAddr}`));
324
+ return;
325
+ }
326
+ const status = Number(res.statusCode || 0);
327
+ const hdrs = res.headers || {};
328
+ const headers = {
329
+ get(k) {
330
+ const v = hdrs[String(k || '').toLowerCase()];
331
+ return Array.isArray(v) ? v.join(', ') : (v ?? null);
332
+ },
333
+ };
334
+ if (status >= 300 && status < 400) {
335
+ // Immediately destroy socket instead of res.resume() so a hostile 3xx body cannot cause unbounded drain
336
+ res.destroy();
337
+ resolve({ status, url: urlStr, headers, bodyText: '', truncated: false });
338
+ return;
339
+ }
340
+ const chunks = [];
341
+ let total = 0;
342
+ let truncated = false;
343
+ res.on('data', (chunk) => {
344
+ const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
345
+ if (total + buf.length > cap) {
346
+ const take = Math.max(0, cap - total);
347
+ if (take > 0) chunks.push(buf.subarray(0, take));
348
+ total += take;
349
+ truncated = true;
350
+ res.destroy();
351
+ resolve({ status, url: urlStr, headers, bodyText: Buffer.concat(chunks).toString('utf8'), truncated });
352
+ return;
353
+ }
354
+ chunks.push(buf);
355
+ total += buf.length;
356
+ });
357
+ res.once('end', () => {
358
+ resolve({ status, url: urlStr, headers, bodyText: Buffer.concat(chunks).toString('utf8'), truncated });
359
+ });
360
+ res.once('error', (err) => {
361
+ if (truncated) {
362
+ resolve({ status, url: urlStr, headers, bodyText: Buffer.concat(chunks).toString('utf8'), truncated: true });
363
+ } else {
364
+ reject(err);
365
+ }
366
+ });
367
+ });
368
+
369
+ req.once('timeout', () => {
370
+ req.destroy(new Error(`web_fetch_timeout:${timeoutMs}ms`));
371
+ });
372
+ req.once('error', reject);
373
+ if (signal) {
374
+ if (signal.aborted) {
375
+ req.destroy(new Error('web_fetch_aborted'));
376
+ return;
377
+ }
378
+ const onAbort = () => req.destroy(new Error('web_fetch_aborted'));
379
+ signal.addEventListener('abort', onAbort, { once: true });
380
+ req.once('close', () => signal.removeEventListener('abort', onAbort));
381
+ }
382
+ req.end();
383
+ });
384
+ }
385
+
386
+ function realpathNativeSafe(p) {
387
+ const abs = path.resolve(p);
388
+ try { return fs.realpathSync.native(abs); } catch {
389
+ try { return fs.realpathSync(abs); } catch {
390
+ try {
391
+ const parent = fs.realpathSync.native(path.dirname(abs));
392
+ return path.join(parent, path.basename(abs));
393
+ } catch {
394
+ return abs;
395
+ }
396
+ }
397
+ }
398
+ }
399
+
400
+ function resolveInsideRoot(rootDir, relPath) {
401
+ const root = realpathNativeSafe(rootDir);
402
+ const candidate = path.resolve(root, String(relPath || '.'));
403
+ const target = realpathNativeSafe(candidate);
404
+ const rootCmp = process.platform === 'darwin' || process.platform === 'win32' ? root.toLowerCase() : root;
405
+ const targetCmp = process.platform === 'darwin' || process.platform === 'win32' ? target.toLowerCase() : target;
406
+ if (targetCmp !== rootCmp && !targetCmp.startsWith(rootCmp + path.sep)) {
407
+ throw new Error(`path_traversal_denied:${relPath}`);
408
+ }
409
+ return { root, target, rel: path.relative(root, target) || '.' };
410
+ }
411
+
412
+ function assertFileReadable({ root, target, rel, userDoc, memoryStore, turnClassification }) {
413
+ // Block hidden dotfiles / directories (`.env`, `.scroll/**`, `.mcp.json`, `.git/**`)
414
+ if (rel !== '.') {
415
+ const segments = rel.split(path.sep).filter(Boolean);
416
+ for (const seg of segments) {
417
+ if (seg.startsWith('.')) {
418
+ throw new Error(`sensitive_dotfile_denied:${rel}`);
419
+ }
420
+ }
421
+ }
422
+ // Block USER.md (symlink & case-insensitive protected)
423
+ if (userDoc && typeof userDoc.guard === 'function') {
424
+ const g = userDoc.guard(target);
425
+ if (!g.allowed) throw new Error(g.reason || 'user_md_denied');
426
+ }
427
+ const baseLower = path.basename(target).toLowerCase();
428
+ if (baseLower === 'user.md' && path.dirname(target).toLowerCase() === root.toLowerCase()) {
429
+ throw new Error('user_md_denied');
430
+ }
431
+ if (memoryStore && typeof memoryStore.assertToolPathAllowed === 'function') {
432
+ const chk = memoryStore.assertToolPathAllowed(target);
433
+ if (!chk.allowed) throw new Error(chk.reason);
434
+ }
435
+ // External/mixed-group turns cannot read agent prompt files (`SOUL.md`, `IDENTITY.md`, `hard-rules.md`, etc.)
436
+ if (turnClassification?.contentAudience === 'external' && EXTERNAL_SENSITIVE_FILES.has(baseLower)) {
437
+ throw new Error(`external_audience_file_denied:${baseLower}`);
438
+ }
439
+ }
440
+
441
+ function readBoundedFile(absPath, maxBytes, rootDir = null) {
442
+ // Use O_NOFOLLOW when available to eliminate symlink-swap TOCTOU races between realpath and open
443
+ const openFlags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
444
+ const fd = fs.openSync(absPath, openFlags);
445
+ try {
446
+ const stat = fs.fstatSync(fd);
447
+ if (!stat.isFile()) throw new Error(`not_a_file:${path.basename(absPath)}`);
448
+ if (rootDir) {
449
+ const recheck = realpathNativeSafe(absPath);
450
+ const rootReal = realpathNativeSafe(rootDir);
451
+ const rootCmp = process.platform === 'darwin' || process.platform === 'win32' ? rootReal.toLowerCase() : rootReal;
452
+ const reCmp = process.platform === 'darwin' || process.platform === 'win32' ? recheck.toLowerCase() : recheck;
453
+ if (reCmp !== rootCmp && !reCmp.startsWith(rootCmp + path.sep)) {
454
+ throw new Error(`path_traversal_denied:${path.basename(absPath)}`);
455
+ }
456
+ // Verify the opened fd's dev/ino matches the post-open realpath (defeats intermediate directory symlink swaps!)
457
+ const recheckStat = fs.statSync(recheck);
458
+ if (recheckStat.dev !== stat.dev || recheckStat.ino !== stat.ino) {
459
+ throw new Error(`path_symlink_race_denied:${path.basename(absPath)}`);
460
+ }
461
+ }
462
+ const toRead = Math.min(stat.size, maxBytes);
463
+ const buf = Buffer.alloc(toRead);
464
+ let offset = 0;
465
+ while (offset < toRead) {
466
+ const n = fs.readSync(fd, buf, offset, toRead - offset, offset);
467
+ if (n <= 0) break;
468
+ offset += n;
469
+ }
470
+ return {
471
+ bytes: stat.size,
472
+ truncated: stat.size > toRead,
473
+ content: buf.subarray(0, offset).toString('utf8'),
474
+ };
475
+ } finally {
476
+ fs.closeSync(fd);
477
+ }
478
+ }
479
+
480
+ // DeepSeek-Harness-inspired Spill-to-File Output Limiter: keeps bounded head + tail in prompt
481
+ // context while persisting full raw output to `.scroll/scratch/` so the agent can slice on demand.
482
+ export function applySpillToFileLimit(output, {
483
+ toolName = 'tool',
484
+ maxChars = 24_000,
485
+ spillDir = null,
486
+ } = {}) {
487
+ const cap = Math.max(2000, Number(maxChars || 24_000));
488
+ if (output == null) return output;
489
+ const serialized = typeof output === 'string' ? output : JSON.stringify(output);
490
+ if (serialized.length <= cap) return output;
491
+
492
+ const headLen = Math.floor(cap * 0.65);
493
+ const tailLen = Math.floor(cap * 0.25);
494
+ const head = serialized.slice(0, headLen);
495
+ const tail = serialized.slice(serialized.length - tailLen);
496
+ const omitted = serialized.length - headLen - tailLen;
497
+
498
+ let spilledPath = null;
499
+ if (spillDir) {
500
+ try {
501
+ fs.mkdirSync(spillDir, { recursive: true, mode: 0o700 });
502
+ const safeTool = String(toolName).replace(/[^A-Za-z0-9_.-]/g, '_');
503
+ const file = path.join(spillDir, `${Date.now()}-${safeTool}-${crypto.randomBytes(4).toString('hex')}.log`);
504
+ fs.writeFileSync(file, serialized + '\n', { mode: 0o600 });
505
+ spilledPath = file;
506
+ } catch { /* isolate scratch spill error */ }
507
+ }
508
+
509
+ return {
510
+ truncated: true,
511
+ totalChars: serialized.length,
512
+ omittedChars: omitted,
513
+ ...(spilledPath ? { spilledPath } : {}),
514
+ preview: `${head}\n\n... [${omitted} chars omitted${spilledPath ? `; full output saved to ${spilledPath}` : ''}] ...\n\n${tail}`,
515
+ };
516
+ }
517
+
518
+ const DEFAULT_BUILTIN_RISK = {
519
+ read_file: 'read_only',
520
+ list_dir: 'read_only',
521
+ web_search: 'read_only',
522
+ web_fetch: 'read_only',
523
+ memory_search: 'read_only',
524
+ knowledge_search: 'read_only',
525
+ skill_list: 'read_only',
526
+ skill_view: 'read_only',
527
+ tool_search: 'read_only',
528
+ memory_remember: 'reversible_write',
529
+ memory_forget: 'destructive',
530
+ automations: 'reversible_write',
531
+ spawn_worker: 'reversible_write',
532
+ exec: 'destructive',
533
+ };
534
+
535
+ const CORE_ALWAYS_LOAD_DEFAULTS = [
536
+ 'read_file',
537
+ 'list_dir',
538
+ 'knowledge_search',
539
+ 'memory_search',
540
+ 'skill_list',
541
+ 'skill_view',
542
+ ];
543
+
544
+ export function createToolRegistry({
545
+ cwd = process.cwd(),
546
+ agentDir = null,
547
+ userDoc = null,
548
+ memoryStore = null,
549
+ knowledgeIndex = null,
550
+ skills = null,
551
+ scheduler = null,
552
+ workerPool = null,
553
+ mcpManager = null,
554
+ approvalStore = null,
555
+ auditChain = null,
556
+ requestApproval = null,
557
+ webSearchFn = null,
558
+ fetchImpl = globalThis.fetch,
559
+ dnsLookup = null,
560
+ enableExec = null, // null = auto (disabled if strictExec or agentDir disallows; enabled if bare registry or explicitly true)
561
+ strictExec = false,
562
+ allowedExecBinaries = null,
563
+ deniedExecBinaries = null,
564
+ execRunner = null,
565
+ execSandbox = 'os',
566
+ requireSandbox = true,
567
+ egressAllow = null,
568
+ toolsAllow = null,
569
+ toolsRetrieval = null,
570
+ riskDefaults = null,
571
+ approvalOverrides = null,
572
+ maxToolOutputChars = 24_000,
573
+ maxWebFetchBytes = 2 * 1024 * 1024,
574
+ spillDir = null,
575
+ onAudit = null,
576
+ embedFn = null,
577
+ } = {}) {
578
+ const tools = new Map();
579
+ const shortAliasMap = new Map(); // optional non-colliding short name -> canonical mcp.<server>.<tool>
580
+ const quarantinedMcp = new Map();
581
+ const auditLog = [];
582
+
583
+ const sec = agentDir ? loadAgentSecurity(agentDir) : {
584
+ riskDefaults: {},
585
+ approvalOverrides: {},
586
+ toolsAllow: null,
587
+ egressAllow: null,
588
+ execAllow: null,
589
+ execDeny: null,
590
+ capabilities: null,
591
+ budget: null,
592
+ toolsRetrieval: null,
593
+ };
594
+ const mcpRisk = loadMcpRisk(cwd, agentDir);
595
+ const mergedRiskDefaults = {
596
+ ...DEFAULT_BUILTIN_RISK,
597
+ ...(sec.riskDefaults || {}),
598
+ ...(riskDefaults || {}),
599
+ };
600
+ const mergedApprovalOverrides = {
601
+ ...(sec.approvalOverrides || {}),
602
+ ...(approvalOverrides || {}),
603
+ };
604
+ const effectiveIdentityToolsAllow = toolsAllow !== null ? toolsAllow : sec.toolsAllow;
605
+ const effectiveEgressAllow = egressAllow !== null ? egressAllow : sec.egressAllow;
606
+ const effectiveExecAllow = allowedExecBinaries !== null ? allowedExecBinaries : sec.execAllow;
607
+ const effectiveExecDeny = deniedExecBinaries !== null ? deniedExecBinaries : sec.execDeny;
608
+ const effectiveSpillDir = spillDir || null;
609
+ const retrievalCfg = {
610
+ mode: 'auto', // auto | portable | off
611
+ deferThreshold: 15,
612
+ maxSchemaBytes: 8192,
613
+ maxIndexTokens: 1500,
614
+ maxSearchResults: 5,
615
+ requireSearchBeforeInvoke: true,
616
+ alwaysLoad: CORE_ALWAYS_LOAD_DEFAULTS,
617
+ ...(sec.toolsRetrieval || {}),
618
+ ...(toolsRetrieval || {}),
619
+ };
620
+
621
+ let retrieverCache = null;
622
+ let registryVersion = 0;
623
+
624
+ function invalidateRetriever() {
625
+ retrieverCache = null;
626
+ registryVersion++;
627
+ }
628
+
629
+ function recordAudit(entry) {
630
+ const full = { ts: new Date().toISOString(), ...entry };
631
+ auditLog.push(full);
632
+ if (auditLog.length > 500) auditLog.shift();
633
+ if (auditChain && typeof auditChain.append === 'function') {
634
+ try { auditChain.append(entry); } catch { /* isolate disk error */ }
635
+ }
636
+ if (typeof onAudit === 'function') {
637
+ try { onAudit(full); } catch { /* ignore */ }
638
+ }
639
+ return full;
640
+ }
641
+
642
+ function register(def) {
643
+ if (!def || !def.name || typeof def.execute !== 'function') {
644
+ throw new Error('tool register: name and execute(args, ctx) are required');
645
+ }
646
+ const name = String(def.name);
647
+ const params = def.parameters || { type: 'object', properties: {} };
648
+ const description = String(def.description || '');
649
+ tools.set(name, {
650
+ name,
651
+ description,
652
+ shortDescription: def.shortDescription || null,
653
+ namespace: def.namespace || (def.server ? `mcp.${def.server}` : 'builtin'),
654
+ server: def.server || null,
655
+ serverDescription: def.serverDescription || '',
656
+ parameters: params,
657
+ risk: def.risk || null,
658
+ ground: Array.isArray(def.ground) ? def.ground : [],
659
+ confirm: def.confirm || null,
660
+ deferLoading: def.deferLoading !== undefined ? def.deferLoading : null,
661
+ tags: Array.isArray(def.tags) ? def.tags : [],
662
+ examples: Array.isArray(def.examples) ? def.examples : [],
663
+ schemaHash: def.schemaHash || computeSchemaHash({ name, description, parameters: params }),
664
+ trustedOutput: def.trustedOutput !== undefined ? Boolean(def.trustedOutput) : (name !== 'web_fetch' && name !== 'web_search'),
665
+ execute: def.execute,
666
+ });
667
+ invalidateRetriever();
668
+ }
669
+
670
+ function unregister(name) {
671
+ const ok = tools.delete(name);
672
+ if (ok) invalidateRetriever();
673
+ return ok;
674
+ }
675
+
676
+ // ── Built-in tools ──
677
+ register({
678
+ name: 'read_file',
679
+ description: 'Read a UTF-8 file inside the workspace directory.',
680
+ risk: 'read_only',
681
+ parameters: {
682
+ type: 'object',
683
+ properties: {
684
+ path: { type: 'string', description: 'Relative path inside workspace' },
685
+ maxBytes: { type: 'number', description: 'Max bytes to return (default 16000)' },
686
+ },
687
+ required: ['path'],
688
+ },
689
+ async execute(args, ctx) {
690
+ const resolved = resolveInsideRoot(cwd, args.path);
691
+ assertFileReadable({ ...resolved, userDoc: ctx?.userDoc || userDoc, memoryStore, turnClassification: ctx?.turnClassification });
692
+ const cap = Math.min(64_000, Math.max(256, Number(args.maxBytes || 16_000)));
693
+ const data = readBoundedFile(resolved.target, cap, resolved.root);
694
+ return {
695
+ path: resolved.rel,
696
+ bytes: data.bytes,
697
+ truncated: data.truncated,
698
+ content: data.content,
699
+ };
700
+ },
701
+ });
702
+
703
+ register({
704
+ name: 'list_dir',
705
+ description: 'List entries in a directory inside the workspace.',
706
+ risk: 'read_only',
707
+ parameters: {
708
+ type: 'object',
709
+ properties: { path: { type: 'string', description: 'Relative directory path (default .)' } },
710
+ },
711
+ async execute(args, ctx) {
712
+ const resolved = resolveInsideRoot(cwd, args.path || '.');
713
+ assertFileReadable({ ...resolved, userDoc: ctx?.userDoc || userDoc, memoryStore, turnClassification: ctx?.turnClassification });
714
+ const isExt = ctx?.turnClassification?.contentAudience === 'external';
715
+ const entries = fs.readdirSync(resolved.target, { withFileTypes: true })
716
+ .filter((e) => {
717
+ if (e.name.startsWith('.')) return false;
718
+ const low = e.name.toLowerCase();
719
+ if (low === 'user.md' && resolved.rel === '.') return false;
720
+ if (isExt && EXTERNAL_SENSITIVE_FILES.has(low)) return false;
721
+ return true;
722
+ })
723
+ .slice(0, 200)
724
+ .map((e) => ({ name: e.name, kind: e.isDirectory() ? 'dir' : 'file' }));
725
+ return { path: resolved.rel, entries };
726
+ },
727
+ });
728
+
729
+ register({
730
+ name: 'web_fetch',
731
+ description: 'Fetch a public HTTP/HTTPS URL (enforces DNS/IPv6/CGNAT SSRF guard, manual redirect checks, and egress_allow).',
732
+ risk: 'read_only',
733
+ trustedOutput: false,
734
+ parameters: {
735
+ type: 'object',
736
+ properties: {
737
+ url: { type: 'string' },
738
+ maxChars: { type: 'number' },
739
+ },
740
+ required: ['url'],
741
+ },
742
+ async execute(args, ctx) {
743
+ const audience = ctx?.turnClassification?.contentAudience || 'internal';
744
+ let currentUrl = String(args.url || '');
745
+ let res = null;
746
+ let lastCheck = null;
747
+ const usePinnedSocket = fetchImpl === globalThis.fetch;
748
+ for (let hop = 0; hop < 6; hop++) {
749
+ const check = await resolveAndValidatePublicUrl(currentUrl, {
750
+ egressAllow: effectiveEgressAllow,
751
+ contentAudience: audience,
752
+ dnsLookup,
753
+ });
754
+ if (!check.ok) throw new Error(check.reason);
755
+ lastCheck = check;
756
+ if (usePinnedSocket && check.resolvedIp) {
757
+ res = await pinnedHttpGet(check.url, {
758
+ resolvedIp: check.resolvedIp,
759
+ resolvedFamily: check.resolvedFamily,
760
+ signal: ctx?.signal || null,
761
+ maxBytes: maxWebFetchBytes,
762
+ });
763
+ } else {
764
+ res = await fetchImpl(check.url, { method: 'GET', redirect: 'manual', signal: ctx?.signal || undefined });
765
+ }
766
+ if (res.status >= 300 && res.status < 400) {
767
+ const loc = res.headers && typeof res.headers.get === 'function' ? res.headers.get('location') : null;
768
+ if (!loc) break;
769
+ currentUrl = new URL(loc, check.url).toString();
770
+ continue;
771
+ }
772
+ break;
773
+ }
774
+ if (!res) throw new Error('web_fetch_no_response');
775
+ if (res.status >= 300 && res.status < 400) throw new Error('web_fetch_too_many_redirects');
776
+ const finalUrl = res.url || currentUrl;
777
+ const finalCheck = finalUrl === lastCheck?.url
778
+ ? lastCheck
779
+ : await resolveAndValidatePublicUrl(finalUrl, {
780
+ egressAllow: effectiveEgressAllow,
781
+ contentAudience: audience,
782
+ dnsLookup,
783
+ });
784
+ if (!finalCheck.ok) throw new Error(`redirect_${finalCheck.reason}`);
785
+ const cap = Math.min(24_000, Math.max(500, Number(args.maxChars || 8000)));
786
+ const bodyRead = typeof res.bodyText === 'string'
787
+ ? { text: res.bodyText, truncated: Boolean(res.truncated) }
788
+ : await readBoundedStreamText(res, maxWebFetchBytes);
789
+ return {
790
+ url: finalCheck.url,
791
+ status: res.status,
792
+ truncated: bodyRead.truncated || bodyRead.text.length > cap,
793
+ body: bodyRead.text.slice(0, cap),
794
+ untrustedExternal: true,
795
+ };
796
+ },
797
+ });
798
+
799
+ register({
800
+ name: 'web_search',
801
+ description: 'Search the web using a configured search provider.',
802
+ risk: 'read_only',
803
+ trustedOutput: false,
804
+ parameters: {
805
+ type: 'object',
806
+ properties: {
807
+ query: { type: 'string' },
808
+ limit: { type: 'number' },
809
+ },
810
+ required: ['query'],
811
+ },
812
+ async execute(args) {
813
+ if (typeof webSearchFn === 'function') {
814
+ return webSearchFn(String(args.query || ''), { limit: Number(args.limit || 5) });
815
+ }
816
+ const braveKey = process.env.BRAVE_API_KEY;
817
+ if (!braveKey) throw new Error('web_search_not_configured: provide webSearchFn or BRAVE_API_KEY');
818
+ const limit = Math.min(10, Math.max(1, Number(args.limit || 5)));
819
+ const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(String(args.query || ''))}&count=${limit}`;
820
+ const res = await fetchImpl(url, { headers: { Accept: 'application/json', 'X-Subscription-Token': braveKey } });
821
+ if (!res.ok) throw new Error(`web_search_failed:${res.status}`);
822
+ const json = await res.json();
823
+ const results = (json.web?.results || []).slice(0, limit).map((r) => ({
824
+ title: r.title, url: r.url, snippet: r.description || '',
825
+ }));
826
+ return { query: args.query, results, untrustedExternal: true };
827
+ },
828
+ });
829
+
830
+ if (knowledgeIndex) {
831
+ register({
832
+ name: 'knowledge_search',
833
+ description: 'Search the indexed deployment knowledge base (SOPs, manuals, tariffs, FAQs).',
834
+ risk: 'read_only',
835
+ trustedOutput: true,
836
+ parameters: {
837
+ type: 'object',
838
+ properties: {
839
+ query: { type: 'string' },
840
+ topK: { type: 'number' },
841
+ },
842
+ required: ['query'],
843
+ },
844
+ async execute(args) {
845
+ const res = knowledgeIndex.retrieve(String(args.query || ''), { topK: Number(args.topK || 4) });
846
+ return {
847
+ query: res.query,
848
+ hits: res.hits.map((h) => ({ file: h.file, heading: h.heading, score: h.score, text: h.text })),
849
+ };
850
+ },
851
+ });
852
+ }
853
+
854
+ function registerSkills(skillsReg) {
855
+ if (!skillsReg || typeof skillsReg.tools !== 'function') return [];
856
+ const raw = skillsReg.tools();
857
+ const list = Array.isArray(raw)
858
+ ? raw
859
+ : Object.entries(raw || {}).map(([k, v]) => ({ name: v?.name || k, ...v }));
860
+ const registered = [];
861
+ for (const item of list) {
862
+ if (!item || !item.name || typeof item.run !== 'function') continue;
863
+ register({
864
+ name: String(item.name),
865
+ description: String(item.description || ''),
866
+ risk: 'read_only',
867
+ trustedOutput: true,
868
+ parameters: item.parameters || { type: 'object', properties: {} },
869
+ async execute(args) {
870
+ return item.run(args || {});
871
+ },
872
+ });
873
+ registered.push(String(item.name));
874
+ }
875
+ return registered;
876
+ }
877
+
878
+ if (skills) {
879
+ registerSkills(skills);
880
+ }
881
+
882
+ if (memoryStore) {
883
+ register({
884
+ name: 'memory_search',
885
+ description: 'Search subject memory for facts, sessions, cards, or day notes.',
886
+ risk: 'read_only',
887
+ parameters: {
888
+ type: 'object',
889
+ properties: {
890
+ query: { type: 'string' },
891
+ scope: { type: 'string', enum: ['all', 'facts', 'sessions', 'cards', 'days'] },
892
+ limit: { type: 'number' },
893
+ },
894
+ required: ['query'],
895
+ },
896
+ async execute(args, ctx) {
897
+ const sid = ctx.subjectSid;
898
+ if (!sid) return { hits: [], note: 'no_subject_bound' };
899
+ return memoryStore.search(sid, {
900
+ query: String(args.query || ''),
901
+ scope: args.scope || 'all',
902
+ limit: Number(args.limit || 6),
903
+ session: ctx.memorySessionId || null,
904
+ });
905
+ },
906
+ });
907
+
908
+ register({
909
+ name: 'memory_remember',
910
+ description: 'Propose a grounded fact into subject memory with a verbatim quote from the current turn.',
911
+ risk: 'reversible_write',
912
+ parameters: {
913
+ type: 'object',
914
+ properties: {
915
+ key: { type: 'string' },
916
+ value: { type: 'string' },
917
+ quote: { type: 'string' },
918
+ },
919
+ required: ['key', 'value', 'quote'],
920
+ },
921
+ async execute(args, ctx) {
922
+ if (!ctx.subjectSid || !ctx.turnRef) return { ok: false, reason: 'no_turn_reference' };
923
+ return memoryStore.remember(ctx.subjectSid, {
924
+ key: args.key,
925
+ value: args.value,
926
+ quote: args.quote,
927
+ ref: ctx.turnRef,
928
+ });
929
+ },
930
+ });
931
+
932
+ register({
933
+ name: 'memory_forget',
934
+ description: 'Permanently forget and redact fact IDs from subject memory.',
935
+ risk: 'destructive',
936
+ ground: ['ids'],
937
+ confirm: { mode: 'none', reason: 'tombstone_atomic_journal_verified' },
938
+ parameters: {
939
+ type: 'object',
940
+ properties: {
941
+ ids: { type: 'array', items: { type: 'string' } },
942
+ reason: { type: 'string' },
943
+ },
944
+ required: ['ids'],
945
+ },
946
+ async execute(args, ctx) {
947
+ if (!ctx.subjectSid) return { ok: false, reason: 'no_subject_bound' };
948
+ return memoryStore.forget(ctx.subjectSid, args.ids, { reason: args.reason || 'user_request' });
949
+ },
950
+ });
951
+ }
952
+
953
+ if (scheduler) {
954
+ register({
955
+ name: 'automations',
956
+ description: 'List, create, toggle, update, or delete timezone-aware scheduled cron jobs and reminders.',
957
+ risk: 'reversible_write',
958
+ parameters: {
959
+ type: 'object',
960
+ properties: {
961
+ action: { type: 'string', enum: ['list', 'create', 'update', 'toggle', 'delete'] },
962
+ jobId: { type: 'string' },
963
+ name: { type: 'string' },
964
+ cron: { type: 'string' },
965
+ everyMs: { type: 'number' },
966
+ at: { type: 'string' },
967
+ tz: { type: 'string' },
968
+ targetChatId: { type: 'string' },
969
+ prompt: { type: 'string' },
970
+ enabled: { type: 'boolean' },
971
+ },
972
+ required: ['action'],
973
+ },
974
+ async execute(args, ctx) {
975
+ const actor = {
976
+ id: ctx.turnClassification?.speakerId || ctx.sender?.id || null,
977
+ roles: ctx.turnClassification?.speakerRoles || [],
978
+ isInternal: ctx.turnClassification?.speakerTrust === 'internal',
979
+ isDm: !ctx.turnClassification?.isGroup,
980
+ };
981
+ if (args.action === 'list') {
982
+ return { jobs: scheduler.listJobs({ chatId: args.targetChatId || null }) };
983
+ }
984
+ if (args.action === 'create') {
985
+ if (!actor.isInternal) return { ok: false, reason: 'owner_or_internal_required' };
986
+ const job = scheduler.addJob({
987
+ id: args.jobId || undefined,
988
+ name: args.name || 'Scheduled task',
989
+ cron: args.cron || null,
990
+ everyMs: args.everyMs || null,
991
+ at: args.at || null,
992
+ tz: args.tz || undefined,
993
+ targetChatId: args.targetChatId || ctx.chatId || null,
994
+ prompt: args.prompt || '',
995
+ enabled: args.enabled !== false,
996
+ ownerId: actor.id,
997
+ });
998
+ return { ok: true, job };
999
+ }
1000
+ const existing = scheduler.getJob(args.jobId);
1001
+ if (!existing) return { ok: false, reason: 'job_not_found' };
1002
+ if (!scheduler.canManageJob(actor, existing)) {
1003
+ return { ok: false, reason: 'forbidden_manage_job' };
1004
+ }
1005
+ if (args.action === 'delete') return scheduler.removeJob(args.jobId);
1006
+ if (args.action === 'toggle') return { ok: true, job: scheduler.updateJob(args.jobId, { enabled: args.enabled !== undefined ? Boolean(args.enabled) : !existing.enabled }) };
1007
+ return {
1008
+ ok: true,
1009
+ job: scheduler.updateJob(args.jobId, {
1010
+ ...(args.name != null ? { name: args.name } : {}),
1011
+ ...(args.cron != null ? { cron: args.cron } : {}),
1012
+ ...(args.tz != null ? { tz: args.tz } : {}),
1013
+ ...(args.prompt != null ? { prompt: args.prompt } : {}),
1014
+ ...(args.enabled != null ? { enabled: Boolean(args.enabled) } : {}),
1015
+ }),
1016
+ };
1017
+ },
1018
+ });
1019
+ }
1020
+
1021
+ if (workerPool) {
1022
+ register({
1023
+ name: 'spawn_worker',
1024
+ description: 'Launch an asynchronous background subagent worker without blocking the chat turn.',
1025
+ risk: 'reversible_write',
1026
+ parameters: {
1027
+ type: 'object',
1028
+ properties: {
1029
+ label: { type: 'string' },
1030
+ task: { type: 'string' },
1031
+ },
1032
+ required: ['task'],
1033
+ },
1034
+ async execute(args, ctx) {
1035
+ if (typeof ctx.spawnWorkerFn !== 'function') {
1036
+ return { ok: false, reason: 'worker_runner_not_configured' };
1037
+ }
1038
+ const job = workerPool.submit({
1039
+ label: args.label || 'background-worker',
1040
+ chatId: ctx.chatId || null,
1041
+ fn: ({ signal, jobId }) => ctx.spawnWorkerFn(String(args.task || ''), { ...ctx, signal, jobId }),
1042
+ });
1043
+ return { ok: true, jobId: job.id, status: job.status };
1044
+ },
1045
+ });
1046
+ }
1047
+
1048
+ const execEnabled = enableExec !== null
1049
+ ? Boolean(enableExec)
1050
+ : (!strictExec);
1051
+
1052
+ if (execEnabled) {
1053
+ register({
1054
+ name: 'exec',
1055
+ description: 'Execute a single binary inside the OS sandbox (destructive tier; requires approval & sanitized env).',
1056
+ risk: 'destructive',
1057
+ ground: ['command', 'args'],
1058
+ confirm: { mode: 'none', reason: 'process_exit_verified' },
1059
+ parameters: {
1060
+ type: 'object',
1061
+ properties: {
1062
+ command: { type: 'string' },
1063
+ args: { type: 'array', items: { type: 'string' } },
1064
+ timeoutMs: { type: 'number' },
1065
+ },
1066
+ required: ['command'],
1067
+ },
1068
+ async execute(args, ctx) {
1069
+ const bin = String(args.command || '').trim();
1070
+ if (!bin) throw new Error('exec: command is required');
1071
+ const cmdArgs = Array.isArray(args.args) ? args.args.map(String) : [];
1072
+ if (strictExec && (!Array.isArray(effectiveExecAllow) || !effectiveExecAllow.length)) {
1073
+ throw new Error('exec_disabled_strict_allowlist_required');
1074
+ }
1075
+ const execPol = evaluateExecPolicy({
1076
+ command: bin,
1077
+ args: cmdArgs,
1078
+ allowRules: Array.isArray(effectiveExecAllow) ? effectiveExecAllow : null,
1079
+ denyRules: Array.isArray(effectiveExecDeny) ? effectiveExecDeny : null,
1080
+ });
1081
+ if (!execPol.ok) {
1082
+ throw new Error(execPol.reason || `exec_binary_not_allowed:${bin}`);
1083
+ }
1084
+ const res = await runSandboxedExec({
1085
+ command: bin,
1086
+ args: cmdArgs,
1087
+ cwd,
1088
+ timeoutMs: Math.min(60_000, Number(args.timeoutMs || 15_000)),
1089
+ sandbox: execSandbox,
1090
+ requireSandbox,
1091
+ allowNetwork: false,
1092
+ execRunner,
1093
+ signal: ctx?.signal || null,
1094
+ });
1095
+ return {
1096
+ stdout: String(res.stdout || '').slice(0, 12_000),
1097
+ stderr: String(res.stderr || '').slice(0, 4000),
1098
+ sandbox: res.sandbox || execSandbox,
1099
+ };
1100
+ },
1101
+ });
1102
+ }
1103
+
1104
+ function resolveToolEntry(name) {
1105
+ const direct = tools.get(name);
1106
+ if (direct) return { name, def: direct };
1107
+ const canonical = shortAliasMap.get(name);
1108
+ if (canonical && tools.has(canonical)) return { name: canonical, def: tools.get(canonical) };
1109
+ return null;
1110
+ }
1111
+
1112
+ function resolveEffectiveTier(name, def) {
1113
+ // Operator `.mcp.json` or `IDENTITY.security.risk_defaults` rules take precedence and can NEVER be
1114
+ // downgraded by a tool's self-declared `def.risk`. When no explicit operator rule matches (`via === 'fallback'`),
1115
+ // honor `def.risk` (still subject to `BUILTIN_TIER_FLOOR`).
1116
+ const policyResolved = resolveTier(name, { mcpTools: mcpRisk, riskDefaults: mergedRiskDefaults });
1117
+ if (def?.risk) {
1118
+ const defResolved = resolveTier(name, {
1119
+ mcpTools: { [name]: { risk: def.risk, ground: def.ground || [], confirm: def.confirm || null } },
1120
+ riskDefaults: {},
1121
+ });
1122
+ if (policyResolved.via === 'fallback') {
1123
+ return { tier: defResolved.tier, via: 'tool_def' };
1124
+ }
1125
+ const highest = maxTier(policyResolved.tier, defResolved.tier);
1126
+ const via = highest === policyResolved.tier ? policyResolved.via : `${policyResolved.via}+tool_def`;
1127
+ return { tier: highest, via };
1128
+ }
1129
+ return policyResolved;
1130
+ }
1131
+
1132
+ function isToolAllowedByPolicy(name, turnToolsAllow = null) {
1133
+ if (name === 'tool_search' || name === 'tool_invoke') return true;
1134
+ if (!matchesToolAllow(name, effectiveIdentityToolsAllow)) return false;
1135
+ if (turnToolsAllow != null && !matchesToolAllow(name, turnToolsAllow)) return false;
1136
+ return true;
1137
+ }
1138
+
1139
+ function syncMcpTools() {
1140
+ if (!mcpManager) return [];
1141
+ const discovered = mcpManager.listDiscoveredTools();
1142
+ const added = [];
1143
+ const bareCounts = new Map();
1144
+ for (const t of discovered) {
1145
+ bareCounts.set(t.name, (bareCounts.get(t.name) || 0) + 1);
1146
+ }
1147
+ for (const t of discovered) {
1148
+ const fullName = t.fullName || `mcp.${t.server}.${t.name}`;
1149
+ // Scan MCP description & parameter text for prompt-injection / hidden Unicode (`ASI01`)
1150
+ const descText = `${t.description || ''} ${JSON.stringify(t.parameters || {})}`;
1151
+ const findings = scanText(descText, fullName);
1152
+ const severe = findings.filter((f) => f.severity === 'critical' || f.severity === 'high');
1153
+ if (severe.length) {
1154
+ quarantinedMcp.set(fullName, { reason: 'mcp_description_injection_blocked', findings: severe });
1155
+ recordAudit({ tool: fullName, decision: 'quarantine', reason: 'mcp_description_injection_blocked', findings: severe.map((f) => f.id) });
1156
+ continue;
1157
+ }
1158
+
1159
+ // Canonical registration under `mcp.<server>.<tool>` so `mcp.*` and `mcp.<server>.*` globs work!
1160
+ register({
1161
+ name: fullName,
1162
+ namespace: t.namespace || `mcp.${t.server}`,
1163
+ server: t.server,
1164
+ serverDescription: t.serverDescription || '',
1165
+ description: t.description,
1166
+ shortDescription: t.shortDescription || null,
1167
+ parameters: t.parameters,
1168
+ risk: t.risk || null, // null lets IDENTITY `mcp.*` risk_defaults resolve before falling back to `destructive`!
1169
+ ground: t.ground,
1170
+ confirm: t.confirm,
1171
+ deferLoading: t.deferLoading,
1172
+ tags: t.tags,
1173
+ examples: t.examples,
1174
+ schemaHash: t.schemaHash,
1175
+ trustedOutput: false,
1176
+ async execute(args, ctx) {
1177
+ return mcpManager.callTool(t.server, t.name, args, { signal: ctx?.signal || null });
1178
+ },
1179
+ });
1180
+ if (!tools.has(t.name) && bareCounts.get(t.name) === 1) {
1181
+ shortAliasMap.set(t.name, fullName);
1182
+ }
1183
+ added.push(fullName);
1184
+ }
1185
+ return added;
1186
+ }
1187
+
1188
+ function buildCatalog({ turnToolsAllow = null } = {}) {
1189
+ const out = [];
1190
+ for (const def of tools.values()) {
1191
+ if (def.name === 'tool_search' || def.name === 'tool_invoke') continue;
1192
+ if (!isToolAllowedByPolicy(def.name, turnToolsAllow)) continue;
1193
+ const { tier } = resolveEffectiveTier(def.name, def);
1194
+ out.push({
1195
+ name: def.name,
1196
+ namespace: def.namespace,
1197
+ serverDescription: def.serverDescription,
1198
+ description: def.description,
1199
+ shortDescription: def.shortDescription,
1200
+ parameters: def.parameters,
1201
+ tags: def.tags,
1202
+ examples: def.examples,
1203
+ ground: def.ground,
1204
+ deferLoading: def.deferLoading,
1205
+ schemaHash: def.schemaHash,
1206
+ tier,
1207
+ });
1208
+ }
1209
+ out.sort((a, b) => a.name.localeCompare(b.name));
1210
+ return out;
1211
+ }
1212
+
1213
+ function getRetriever(catalog) {
1214
+ const catalogKey = `${registryVersion}:${(catalog || []).map((c) => c.name).join('|')}`;
1215
+ if (!retrieverCache || retrieverCache.key !== catalogKey) {
1216
+ retrieverCache = {
1217
+ key: catalogKey,
1218
+ version: registryVersion,
1219
+ engine: buildToolRetriever(catalog, { embedFn }),
1220
+ };
1221
+ }
1222
+ return retrieverCache.engine;
1223
+ }
1224
+
1225
+ // Filter whether a tool is callable for the current turn's speaker posture
1226
+ function isVisibleForTurn(entry, { allowWriteTools = true, delegatedTools = null, turnToolsAllow = null } = {}) {
1227
+ if (!isToolAllowedByPolicy(entry.name, turnToolsAllow)) return false;
1228
+ if (allowWriteTools) return true;
1229
+ if (entry.tier === 'read_only') return true;
1230
+ const delegatedSet = Array.isArray(delegatedTools) && delegatedTools.length ? new Set(delegatedTools.map(String)) : null;
1231
+ return Boolean(delegatedSet && delegatedSet.has(entry.name));
1232
+ }
1233
+
1234
+ function searchTools({
1235
+ query = '',
1236
+ queries = null,
1237
+ namespace = null,
1238
+ risk = 'all',
1239
+ limit = retrievalCfg.maxSearchResults || 5,
1240
+ allowWriteTools = true,
1241
+ delegatedTools = null,
1242
+ turnToolsAllow = null,
1243
+ includeForbiddenHints = false,
1244
+ } = {}) {
1245
+ const catalog = buildCatalog({ turnToolsAllow });
1246
+ const engine = getRetriever(catalog);
1247
+ const res = engine.search({
1248
+ query,
1249
+ queries,
1250
+ namespace,
1251
+ risk,
1252
+ limit,
1253
+ filterFn: includeForbiddenHints
1254
+ ? (entry) => isToolAllowedByPolicy(entry.name, turnToolsAllow)
1255
+ : (entry) => isVisibleForTurn(entry, { allowWriteTools, delegatedTools, turnToolsAllow }),
1256
+ });
1257
+ return {
1258
+ trust: 'third_party',
1259
+ queries: res.queries,
1260
+ totalMatches: res.totalMatches,
1261
+ availableNamespaces: res.availableNamespaces,
1262
+ tools: res.hits.map((h) => ({
1263
+ name: h.name,
1264
+ namespace: h.namespace,
1265
+ risk: h.tier,
1266
+ policy: policyForTier(h.tier, mergedApprovalOverrides),
1267
+ ground: h.ground || [],
1268
+ schemaHash: h.schemaHash,
1269
+ callable_by_current_speaker: isVisibleForTurn(h, { allowWriteTools, delegatedTools, turnToolsAllow }),
1270
+ description: h.description,
1271
+ parameters: h.parameters,
1272
+ ...(h.examples?.length ? { examples: h.examples } : {}),
1273
+ })),
1274
+ };
1275
+ }
1276
+
1277
+ // Register meta-tools lazily when Portable Retrieval is active
1278
+ function ensureMetaToolsRegistered() {
1279
+ if (!tools.has('tool_search')) {
1280
+ register({
1281
+ name: 'tool_search',
1282
+ description: 'Search deferred tools by keyword or batch queries to inspect exact JSON parameter schemas before calling tool_invoke.',
1283
+ risk: 'read_only',
1284
+ parameters: {
1285
+ type: 'object',
1286
+ properties: {
1287
+ query: { type: 'string', description: 'Single search query' },
1288
+ queries: { type: 'array', items: { type: 'string' }, description: 'Batch queries for multi-system tasks in 1 round-trip' },
1289
+ namespace: { type: 'string', description: 'Optional namespace filter (e.g. mcp.github, builtin)' },
1290
+ risk: { type: 'string', enum: ['all', 'read_only', 'write'] },
1291
+ limit: { type: 'number' },
1292
+ },
1293
+ },
1294
+ async execute(args, ctx) {
1295
+ const allowWrite = ctx?.turnClassification ? Boolean(ctx.turnClassification.writeToolsAllowed) : true;
1296
+ const result = searchTools({
1297
+ query: args.query || '',
1298
+ queries: Array.isArray(args.queries) ? args.queries : null,
1299
+ namespace: args.namespace || null,
1300
+ risk: args.risk || 'all',
1301
+ limit: Number(args.limit || retrievalCfg.maxSearchResults || 5),
1302
+ allowWriteTools: allowWrite,
1303
+ delegatedTools: ctx?.delegatedTools || null,
1304
+ turnToolsAllow: ctx?.toolsAllow || null,
1305
+ });
1306
+ if (ctx?.hydratedTools && typeof ctx.hydratedTools.set === 'function') {
1307
+ for (const item of result.tools) {
1308
+ ctx.hydratedTools.set(item.name, item.schemaHash);
1309
+ }
1310
+ }
1311
+ return result;
1312
+ },
1313
+ });
1314
+ }
1315
+ if (!tools.has('tool_invoke')) {
1316
+ // NOTE: `tool_invoke` is transparently unwrapped inside `executeTool()` BEFORE any security gate!
1317
+ register({
1318
+ name: 'tool_invoke',
1319
+ description: 'Invoke a deferred tool discovered via tool_search by exact name and JSON arguments.',
1320
+ risk: 'destructive', // never relies on this tier; unwrap enforces the real target tool's tier/policy/gates!
1321
+ confirm: { mode: 'none', reason: 'unwrapped_to_target_tool_gate' },
1322
+ parameters: {
1323
+ type: 'object',
1324
+ properties: {
1325
+ name: { type: 'string', description: 'Exact canonical tool name returned by tool_search' },
1326
+ arguments: { type: 'object', description: 'JSON object matching the tool parameter schema' },
1327
+ },
1328
+ required: ['name', 'arguments'],
1329
+ },
1330
+ async execute() {
1331
+ throw new Error('tool_invoke_must_be_unwrapped_by_executeTool');
1332
+ },
1333
+ });
1334
+ }
1335
+ }
1336
+
1337
+ // Legacy/simple flat list (still sorted deterministically by name, honors IDENTITY.security.tools_allow!)
1338
+ function listSchemas({ allowWriteTools = true, delegatedTools = null, turnToolsAllow = null } = {}) {
1339
+ const catalog = buildCatalog({ turnToolsAllow });
1340
+ return catalog
1341
+ .filter((entry) => isVisibleForTurn(entry, { allowWriteTools, delegatedTools, turnToolsAllow }))
1342
+ .map((entry) => ({
1343
+ name: entry.name,
1344
+ description: entry.description,
1345
+ parameters: entry.parameters,
1346
+ tier: entry.tier,
1347
+ schemaHash: entry.schemaHash,
1348
+ }));
1349
+ }
1350
+
1351
+ // §47.2 Prompt Surface Builder (3-Set C / V / E + Room-Sticky Cache Invariance!)
1352
+ // - When `roomSticky: true` (group rooms), Region A schemas & `<available_tools>` are built from
1353
+ // deployment Catalog C (speaker-independent) so alternating Owner/Teammate turns NEVER flip `prefixHash`!
1354
+ // - Enforcement happens strictly at `tool_search` (Visible V) and `executeTool` (Executable E).
1355
+ function getPromptSurface({
1356
+ allowWriteTools = true,
1357
+ delegatedTools = null,
1358
+ turnToolsAllow = null,
1359
+ roomSticky = false,
1360
+ mode = retrievalCfg.mode,
1361
+ } = {}) {
1362
+ const catalogC = buildCatalog({ turnToolsAllow: roomSticky ? null : turnToolsAllow });
1363
+ const surfaceList = roomSticky
1364
+ ? catalogC
1365
+ : catalogC.filter((entry) => isVisibleForTurn(entry, { allowWriteTools, delegatedTools, turnToolsAllow }));
1366
+
1367
+ const schemaBytes = surfaceList.reduce(
1368
+ (sum, t) => sum + Buffer.byteLength(JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters }), 'utf8'),
1369
+ 0
1370
+ );
1371
+
1372
+ const shouldDefer = mode === 'portable' || (
1373
+ mode !== 'off' && (
1374
+ surfaceList.length > Number(retrievalCfg.deferThreshold || 15)
1375
+ || schemaBytes >= Number(retrievalCfg.maxSchemaBytes || 8192)
1376
+ )
1377
+ );
1378
+
1379
+ if (!shouldDefer) {
1380
+ return {
1381
+ mode: 'direct',
1382
+ activeSchemas: surfaceList.map((t) => ({
1383
+ name: t.name,
1384
+ description: t.description,
1385
+ parameters: t.parameters,
1386
+ tier: t.tier,
1387
+ schemaHash: t.schemaHash,
1388
+ })),
1389
+ availableToolsIndex: { text: '', hash: 'direct', deferredCount: 0, estimatedTokens: 0, tier: 'none' },
1390
+ deferredNames: new Set(),
1391
+ };
1392
+ }
1393
+
1394
+ ensureMetaToolsRegistered();
1395
+ const alwaysSet = new Set(Array.isArray(retrievalCfg.alwaysLoad) ? retrievalCfg.alwaysLoad.map(String) : CORE_ALWAYS_LOAD_DEFAULTS);
1396
+ const active = [];
1397
+ const deferred = [];
1398
+ const nsDescs = {};
1399
+
1400
+ for (const t of surfaceList) {
1401
+ if (t.serverDescription && t.namespace) nsDescs[t.namespace] = t.serverDescription;
1402
+ const isAlways = t.deferLoading === false || (t.deferLoading !== true && alwaysSet.has(t.name));
1403
+ if (isAlways && active.length < 10) {
1404
+ active.push({ name: t.name, description: t.description, parameters: t.parameters, tier: t.tier, schemaHash: t.schemaHash });
1405
+ } else {
1406
+ deferred.push(t);
1407
+ }
1408
+ }
1409
+
1410
+ for (const metaName of ['tool_search', 'tool_invoke']) {
1411
+ const def = tools.get(metaName);
1412
+ if (def) {
1413
+ active.push({ name: def.name, description: def.description, parameters: def.parameters, tier: def.risk || 'read_only', schemaHash: def.schemaHash });
1414
+ }
1415
+ }
1416
+ active.sort((a, b) => a.name.localeCompare(b.name));
1417
+
1418
+ const availableToolsIndex = buildAvailableToolsIndex(deferred, {
1419
+ maxIndexTokens: retrievalCfg.maxIndexTokens || 1500,
1420
+ namespaceDescriptions: nsDescs,
1421
+ });
1422
+ return {
1423
+ mode: 'portable',
1424
+ activeSchemas: active,
1425
+ availableToolsIndex,
1426
+ deferredNames: new Set(deferred.map((d) => d.name)),
1427
+ };
1428
+ }
1429
+
1430
+ async function executeTool(rawName, args = {}, ctx = {}) {
1431
+ // ── Stage 0: Transparent Unwrap for `tool_invoke` BEFORE EVERY GATE! ──
1432
+ if (rawName === 'tool_invoke') {
1433
+ const targetNameRaw = String(args?.name || '').trim();
1434
+ const targetArgs = args?.arguments && typeof args.arguments === 'object' && !Array.isArray(args.arguments)
1435
+ ? args.arguments
1436
+ : {};
1437
+ if (!targetNameRaw) {
1438
+ const res = { ok: false, decision: 'deny', reason: 'tool_invoke_missing_target_name' };
1439
+ recordAudit({ tool: 'tool_invoke', decision: 'deny', reason: res.reason });
1440
+ return res;
1441
+ }
1442
+ if (targetNameRaw === 'tool_invoke' || targetNameRaw === 'tool_search') {
1443
+ const res = { ok: false, decision: 'deny', reason: 'recursive_meta_tool_denied' };
1444
+ recordAudit({ tool: targetNameRaw, viaMetaTool: 'tool_invoke', decision: 'deny', reason: res.reason });
1445
+ return res;
1446
+ }
1447
+ const resolvedTarget = resolveToolEntry(targetNameRaw);
1448
+ if (!resolvedTarget) {
1449
+ const res = { ok: false, decision: 'deny', error: `unknown_tool:${targetNameRaw}` };
1450
+ recordAudit({ tool: targetNameRaw, viaMetaTool: 'tool_invoke', decision: 'deny', reason: res.error });
1451
+ return res;
1452
+ }
1453
+ const { name: targetName, def: targetDef } = resolvedTarget;
1454
+
1455
+ // Require search-before-invoke for deferred tools when enabled & hydratedTools Map is tracked
1456
+ if (retrievalCfg.requireSearchBeforeInvoke && ctx?.hydratedTools instanceof Map && ctx?.deferredNames instanceof Set && ctx.deferredNames.has(targetName)) {
1457
+ const pinnedHash = ctx.hydratedTools.get(targetName);
1458
+ if (!pinnedHash) {
1459
+ const res = {
1460
+ ok: false,
1461
+ decision: 'deny',
1462
+ reason: 'deferred_tool_not_searched_yet: call tool_search first',
1463
+ targetTool: targetName,
1464
+ };
1465
+ recordAudit({ tool: targetName, viaMetaTool: 'tool_invoke', decision: 'deny', reason: res.reason });
1466
+ return res;
1467
+ }
1468
+ if (pinnedHash !== targetDef.schemaHash) {
1469
+ const res = {
1470
+ ok: false,
1471
+ decision: 'deny',
1472
+ reason: 'mcp_schema_hash_changed_mid_session_asi04',
1473
+ targetTool: targetName,
1474
+ };
1475
+ recordAudit({ tool: targetName, viaMetaTool: 'tool_invoke', decision: 'deny', reason: res.reason });
1476
+ return res;
1477
+ }
1478
+ }
1479
+
1480
+ // Host JSON Schema argument validation (compensates for provider not constraining `arguments: object`)
1481
+ const schemaCheck = validateToolArgs(targetArgs, targetDef.parameters);
1482
+ if (!schemaCheck.ok) {
1483
+ const res = {
1484
+ ok: false,
1485
+ decision: 'deny',
1486
+ reason: 'invalid_tool_arguments',
1487
+ validationErrors: schemaCheck.errors,
1488
+ expectedParameters: targetDef.parameters,
1489
+ };
1490
+ recordAudit({ tool: targetName, viaMetaTool: 'tool_invoke', decision: 'deny', reason: res.reason, validationErrors: schemaCheck.errors });
1491
+ return res;
1492
+ }
1493
+
1494
+ // Delegate straight into the SINGLE unified gate under the REAL target tool name!
1495
+ return executeTool(targetName, targetArgs, { ...ctx, viaMetaTool: 'tool_invoke' });
1496
+ }
1497
+
1498
+ const resolved = resolveToolEntry(rawName);
1499
+ if (!resolved) {
1500
+ const res = { ok: false, decision: 'deny', error: `unknown_tool:${rawName}` };
1501
+ recordAudit({ tool: rawName, viaMetaTool: ctx.viaMetaTool || null, decision: 'deny', reason: res.error });
1502
+ return res;
1503
+ }
1504
+ const { name, def } = resolved;
1505
+
1506
+ // ── Stage 0B: Host JSON Schema Argument Validation for ALL calls (direct & unwrapped) ──
1507
+ if (def.parameters && typeof def.parameters === 'object') {
1508
+ const argCheck = validateToolArgs(args || {}, def.parameters);
1509
+ if (!argCheck.ok) {
1510
+ const res = {
1511
+ ok: false,
1512
+ decision: 'deny',
1513
+ reason: 'invalid_tool_arguments',
1514
+ validationErrors: argCheck.errors,
1515
+ };
1516
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, decision: 'deny', reason: res.reason, validationErrors: argCheck.errors });
1517
+ return res;
1518
+ }
1519
+ }
1520
+
1521
+ // ── Stage 1: Unified Allow-List (`IDENTITY.security.tools_allow` ∩ per-turn `toolsAllow`) ──
1522
+ if (!isToolAllowedByPolicy(name, ctx.toolsAllow || null)) {
1523
+ const res = { ok: false, decision: 'deny', reason: `tool_not_in_allowlist:${name}` };
1524
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, decision: 'deny', reason: res.reason });
1525
+ return res;
1526
+ }
1527
+
1528
+ const { tier, via } = resolveEffectiveTier(name, def);
1529
+ const policy = policyForTier(tier, mergedApprovalOverrides);
1530
+
1531
+ // ── Stage 2: §42 Boundary Wall (external / mixed-group turns strictly read_only unless delegated) ──
1532
+ const delegatedSet = Array.isArray(ctx.delegatedTools) ? new Set(ctx.delegatedTools.map(String)) : null;
1533
+ if (ctx.turnClassification && !ctx.turnClassification.writeToolsAllowed && tier !== 'read_only' && !(delegatedSet && delegatedSet.has(name))) {
1534
+ const res = { ok: false, decision: 'deny', tier, policy, reason: 'boundary_wall_write_tools_blocked' };
1535
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, decision: 'deny', reason: res.reason });
1536
+ return res;
1537
+ }
1538
+
1539
+ // ── Stage 3: §28 Fail-Closed Confirm Spec Check BEFORE running high-risk actions ──
1540
+ const isHighRisk = tier === 'financial' || tier === 'destructive';
1541
+ if (isHighRisk) {
1542
+ const hasValidConfirm = Boolean(
1543
+ def.confirm && (
1544
+ (def.confirm.probe && def.confirm.expect)
1545
+ || (def.confirm.mode === 'none' && typeof def.confirm.reason === 'string' && def.confirm.reason.trim().length > 0)
1546
+ )
1547
+ );
1548
+ if (!hasValidConfirm) {
1549
+ const res = { ok: false, decision: 'deny', tier, policy, reason: 'confirm_spec_required_for_high_risk_tool' };
1550
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1551
+ return res;
1552
+ }
1553
+ }
1554
+
1555
+ // ── Stage 4: §22 Provenance-Aware Grounding Pre-Check (FAIL CLOSED!) ──
1556
+ const groundingRequired = needsGrounding(tier);
1557
+ let grounded = null;
1558
+ let groundingMissing = [];
1559
+ if (groundingRequired) {
1560
+ const mcpEntry = mcpRisk[name];
1561
+ // Union ground keys from `.mcp.json` AND tool definition so neither can silently erase the other
1562
+ const groundKeys = [...new Set([
1563
+ ...(Array.isArray(mcpEntry?.ground) ? mcpEntry.ground : []),
1564
+ ...(Array.isArray(def.ground) ? def.ground : []),
1565
+ ])];
1566
+ if (!groundKeys.length) {
1567
+ // High-risk tool without declared grounding specification -> FAIL CLOSED!
1568
+ const res = {
1569
+ ok: false,
1570
+ decision: 'deny',
1571
+ tier,
1572
+ policy,
1573
+ reason: 'grounding_spec_required_for_high_risk_tool',
1574
+ missingGrounding: ['_missing_ground_spec'],
1575
+ };
1576
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1577
+ return res;
1578
+ }
1579
+ const subset = {};
1580
+ const missingArgs = [];
1581
+ for (const k of groundKeys) {
1582
+ const val = args ? args[k] : undefined;
1583
+ if (Array.isArray(val)) {
1584
+ // Optional array field (`exec.args`): if provided & non-empty, ground EVERY element;
1585
+ // for all other required high-risk fields, an empty array [] is missing!
1586
+ const items = val.map((x) => String(x ?? '').trim()).filter(Boolean);
1587
+ if (!items.length && !(name === 'exec' && k === 'args')) {
1588
+ missingArgs.push(k);
1589
+ } else {
1590
+ for (let i = 0; i < items.length; i++) {
1591
+ subset[`${k}[${i}]`] = items[i];
1592
+ }
1593
+ }
1594
+ } else if (val !== undefined && val !== null && String(val).trim() !== '') {
1595
+ subset[k] = val;
1596
+ } else if (!(name === 'exec' && k === 'args')) {
1597
+ missingArgs.push(k);
1598
+ }
1599
+ }
1600
+ if (missingArgs.length) {
1601
+ grounded = false;
1602
+ groundingMissing = missingArgs;
1603
+ } else {
1604
+ // Provenance-safe grounding: prefer `trustedGroundingSources` (excludes untrusted web_fetch/external pages!)
1605
+ const sourceText = ctx.trustedGroundingSources !== undefined
1606
+ ? ctx.trustedGroundingSources
1607
+ : (ctx.groundingSources || '');
1608
+ const g = checkGrounding(subset, sourceText);
1609
+ grounded = g.ok;
1610
+ groundingMissing = g.missing;
1611
+ }
1612
+ }
1613
+
1614
+ // ── Stage 5: Per-Call Approval Verification & HITL Callback (NO bare `approved: true` bypass!) ──
1615
+ const effectiveUserDoc = ctx.userDoc || userDoc;
1616
+ const actionAmount = args?.amount != null && Number.isFinite(Number(args.amount)) ? Number(args.amount) : null;
1617
+ let approved = false;
1618
+ let approverId = null;
1619
+
1620
+ if (ctx.approvalTokenId && approvalStore) {
1621
+ const chk = approvalStore.consume({
1622
+ tokenId: ctx.approvalTokenId,
1623
+ tool: name,
1624
+ args,
1625
+ userDoc: effectiveUserDoc,
1626
+ tier,
1627
+ amount: actionAmount,
1628
+ conversationId: ctx.chatId || null,
1629
+ turnId: ctx.turnId || null,
1630
+ schemaHash: def.schemaHash || null,
1631
+ });
1632
+ if (!chk.ok) {
1633
+ const res = { ok: false, decision: 'deny', tier, policy, reason: chk.reason };
1634
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1635
+ return res;
1636
+ }
1637
+ approved = true;
1638
+ approverId = chk.token.approver || null;
1639
+ } else if (ctx.approved === true) {
1640
+ // Strictly reject bare turn-wide `approved: true` AND enforce single-use latch so two identical tool calls
1641
+ // in the same turn cannot replay the same inline approval!
1642
+ if (ctx.inlineApprovalState?.used || ctx._inlineApprovalUsed) {
1643
+ const res = { ok: false, decision: 'deny', tier, policy, reason: 'approval_already_used' };
1644
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1645
+ return res;
1646
+ }
1647
+ if (!ctx.approvedTool || ctx.approvedTool !== name) {
1648
+ const res = {
1649
+ ok: false,
1650
+ decision: 'deny',
1651
+ tier,
1652
+ policy,
1653
+ reason: ctx.approvedTool ? 'approval_tool_mismatch' : 'approval_binding_required',
1654
+ };
1655
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1656
+ return res;
1657
+ }
1658
+ const actualArgsHash = hashArgs(args || {});
1659
+ if (!ctx.approvedArgsHash || ctx.approvedArgsHash !== actualArgsHash) {
1660
+ const res = { ok: false, decision: 'deny', tier, policy, reason: 'approval_args_hash_mismatch' };
1661
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1662
+ return res;
1663
+ }
1664
+ if (effectiveUserDoc && effectiveUserDoc.active && typeof effectiveUserDoc.canApprove === 'function') {
1665
+ if (!ctx.approver) {
1666
+ const res = { ok: false, decision: 'deny', tier, policy, reason: 'approval_missing_approver' };
1667
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1668
+ return res;
1669
+ }
1670
+ const authChk = effectiveUserDoc.canApprove(ctx.approver, { tier, amount: actionAmount });
1671
+ if (authChk && authChk.ok === false) {
1672
+ const res = { ok: false, decision: 'deny', tier, policy, reason: authChk.reason || 'approver_not_authorized' };
1673
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', approver: ctx.approver, reason: res.reason });
1674
+ return res;
1675
+ }
1676
+ }
1677
+ if (ctx.inlineApprovalState && typeof ctx.inlineApprovalState === 'object') {
1678
+ ctx.inlineApprovalState.used = true;
1679
+ }
1680
+ ctx._inlineApprovalUsed = true;
1681
+ approved = true;
1682
+ approverId = ctx.approver || null;
1683
+ }
1684
+
1685
+ let evalRes = evaluateAction({ tier, policy, approved, groundingRequired, grounded });
1686
+
1687
+ if (evalRes.decision === 'deny') {
1688
+ const res = { ok: false, decision: 'deny', tier, policy, reason: evalRes.reason, missingGrounding: groundingMissing };
1689
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: evalRes.reason, missingGrounding: groundingMissing });
1690
+ return res;
1691
+ }
1692
+
1693
+ if (evalRes.decision === 'await') {
1694
+ const approverFn = ctx.requestApproval || requestApproval;
1695
+ if (typeof approverFn === 'function') {
1696
+ if (typeof ctx.onApprovalRequested === 'function') {
1697
+ try { ctx.onApprovalRequested({ tool: name, tier }); } catch { /* ignore */ }
1698
+ }
1699
+ const decision = await approverFn({
1700
+ tool: name,
1701
+ server: def.server || null,
1702
+ schemaHash: def.schemaHash,
1703
+ tier,
1704
+ policy,
1705
+ args,
1706
+ amount: actionAmount,
1707
+ chatId: ctx.chatId || null,
1708
+ sender: ctx.sender || null,
1709
+ });
1710
+ const isApproved = Boolean(decision === true || (decision && decision.approved === true));
1711
+ const by = (decision && typeof decision === 'object' && (decision.approver || decision.by)) || null;
1712
+ if (isApproved) {
1713
+ if (effectiveUserDoc && effectiveUserDoc.active && typeof effectiveUserDoc.canApprove === 'function') {
1714
+ if (!by) {
1715
+ const res = { ok: false, decision: 'deny', tier, policy, reason: 'approval_missing_approver' };
1716
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', reason: res.reason });
1717
+ return res;
1718
+ }
1719
+ const authChk = effectiveUserDoc.canApprove(by, { tier, amount: actionAmount });
1720
+ if (authChk && authChk.ok === false) {
1721
+ const res = { ok: false, decision: 'deny', tier, policy, reason: authChk.reason || 'approver_not_authorized' };
1722
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', approver: by, reason: res.reason });
1723
+ return res;
1724
+ }
1725
+ }
1726
+ if (approvalStore) {
1727
+ const tok = approvalStore.issue({
1728
+ tool: name,
1729
+ args,
1730
+ approver: by,
1731
+ tier,
1732
+ amount: actionAmount,
1733
+ conversationId: ctx.chatId || null,
1734
+ turnId: ctx.turnId || null,
1735
+ schemaHash: def.schemaHash || null,
1736
+ });
1737
+ const consumed = approvalStore.consume({
1738
+ tokenId: tok.id,
1739
+ tool: name,
1740
+ args,
1741
+ userDoc: effectiveUserDoc,
1742
+ tier,
1743
+ amount: actionAmount,
1744
+ conversationId: ctx.chatId || null,
1745
+ turnId: ctx.turnId || null,
1746
+ schemaHash: def.schemaHash || null,
1747
+ });
1748
+ approved = consumed.ok;
1749
+ approverId = by;
1750
+ if (!consumed.ok) {
1751
+ const res = { ok: false, decision: 'deny', tier, policy, reason: consumed.reason };
1752
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'deny', approver: by, reason: res.reason });
1753
+ return res;
1754
+ }
1755
+ } else {
1756
+ approved = true;
1757
+ approverId = by;
1758
+ }
1759
+ }
1760
+ evalRes = evaluateAction({ tier, policy, approved, groundingRequired, grounded });
1761
+ }
1762
+ if (evalRes.decision !== 'allow') {
1763
+ const res = { ok: false, decision: 'await', tier, policy, reason: evalRes.reason };
1764
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'await', reason: evalRes.reason });
1765
+ return res;
1766
+ }
1767
+ }
1768
+
1769
+ // ── Stage 6: Execute Tool + §28 Read-Only Probe Confirmation + Spill-to-File Limiter ──
1770
+ try {
1771
+ const rawOutput = await def.execute(args || {}, ctx);
1772
+ const output = applySpillToFileLimit(rawOutput, {
1773
+ toolName: name,
1774
+ maxChars: ctx.maxToolOutputChars || maxToolOutputChars,
1775
+ spillDir: ctx.spillDir || effectiveSpillDir,
1776
+ });
1777
+ let confirmation = null;
1778
+ if (def.confirm && def.confirm.mode !== 'none') {
1779
+ confirmation = await confirmEffect({
1780
+ tool: name,
1781
+ tier,
1782
+ confirm: def.confirm,
1783
+ params: args || {},
1784
+ invoke: async (probeName, probeParams) => {
1785
+ const probeResolved = resolveToolEntry(probeName);
1786
+ if (!probeResolved) throw new Error(`confirm_probe_not_found:${probeName}`);
1787
+ const probeTier = resolveEffectiveTier(probeResolved.name, probeResolved.def).tier;
1788
+ if (probeTier !== 'read_only') {
1789
+ throw new Error(`confirm_probe_must_be_read_only:${probeResolved.name}:${probeTier}`);
1790
+ }
1791
+ return probeResolved.def.execute(probeParams || {}, ctx);
1792
+ },
1793
+ });
1794
+ if (!confirmation.ok) {
1795
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'unconfirmed', reason: confirmation.reason });
1796
+ return { ok: false, decision: 'unconfirmed', executed: true, tier, policy, output, confirmation, error: confirmation.reason };
1797
+ }
1798
+ }
1799
+ recordAudit({
1800
+ tool: name,
1801
+ viaMetaTool: ctx.viaMetaTool || null,
1802
+ tier,
1803
+ policy,
1804
+ via,
1805
+ decision: 'allow',
1806
+ ok: true,
1807
+ approved,
1808
+ approver: approverId,
1809
+ trustedOutput: def.trustedOutput,
1810
+ });
1811
+ return { ok: true, decision: 'allow', executed: true, tier, policy, output, confirmation, trustedOutput: def.trustedOutput };
1812
+ } catch (err) {
1813
+ const msg = String(err?.message || err);
1814
+ recordAudit({ tool: name, viaMetaTool: ctx.viaMetaTool || null, tier, policy, via, decision: 'error', error: msg });
1815
+ return { ok: false, decision: 'error', executed: true, tier, policy, error: msg };
1816
+ }
1817
+ }
1818
+
1819
+ return {
1820
+ register,
1821
+ registerSkills,
1822
+ unregister,
1823
+ syncMcpTools,
1824
+ listSchemas,
1825
+ getPromptSurface,
1826
+ searchTools,
1827
+ executeTool,
1828
+ has: (name) => Boolean(resolveToolEntry(name)),
1829
+ getAuditLog: () => [...auditLog],
1830
+ getQuarantinedTools: () => [...quarantinedMcp.entries()].map(([name, info]) => ({ name, ...info })),
1831
+ get securityConfig() { return sec; },
1832
+ };
1833
+ }