lazyclaw 6.3.1 → 6.4.0

package/mas/prompt_stack.mjs

@@ -18,10 +18,39 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { skillsIndex } from '../skills.mjs';
 import { loadCore, recentPath, defaultConfigDir } from '../memory.mjs';
+import { recall as _recall } from './index_db.mjs';
+
+// Static layer files (global SOUL.md, workspace SOUL.md, personality, USER.md)
+// are re-read on every composePromptStack call — and that runs once per
+// iteration of the per-message agent loop (mention_router), where these layers
+// are byte-identical every pass. Memoize by path + mtime so an unchanged file
+// is read from disk once, not N times; editing the file bumps its mtime and
+// busts the entry, so correctness is preserved. Mirrors the skills.mjs
+// _indexCache pattern. Layers 7-8 (recent.jsonl tail, FTS recall) deliberately
+// stay un-memoized — they are meant to be volatile per turn.
+const _readCache = new Map();  // path → { mtimeMs, content }
+
+export function _invalidateReadCache() { _readCache.clear(); }
 
 function readOpt(p) {
-  try { return fs.readFileSync(p, 'utf8').trim(); }
-  catch { return ''; }
+  let mtimeMs;
+  try {
+    mtimeMs = fs.statSync(p).mtimeMs;
+  } catch {
+    // Missing/unreadable — drop any stale entry and return empty.
+    _readCache.delete(p);
+    return '';
+  }
+  const hit = _readCache.get(p);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.content;
+  try {
+    const content = fs.readFileSync(p, 'utf8').trim();
+    _readCache.set(p, { mtimeMs, content });
+    return content;
+  } catch {
+    _readCache.delete(p);
+    return '';
+  }
 }
 
 function lastRecentLine(cfgDir) {
@@ -36,7 +65,31 @@ function lastRecentLine(cfgDir) {
   } catch { return ''; }
 }
 
-export function composePromptStack({ cfgDir, agent, workspace, sessionId } = {}) {
+// Top-k recalled context for the CURRENT user message. Off (and byte-stable)
+// when no `query` is passed. Scoped to prior sessions / trajectories /
+// memories — the skill index already has its own layer above. Best-effort:
+// any index/FTS hiccup yields no layer rather than breaking prompt composition.
+export function recalledLayer(dir, query, k) {
+  if (!query || !String(query).trim()) return '';
+  // FTS5 ANDs space-separated terms, so a natural-language message rarely
+  // matches a prior doc. Build an OR query over the significant terms (bm25
+  // still ranks rarer, more-relevant matches first) and pass it raw — each
+  // term is [a-z0-9] only, so no FTS operator can be injected.
+  const terms = [...new Set((String(query).toLowerCase().match(/[a-z0-9]{3,}/g) || []))].slice(0, 12);
+  if (!terms.length) return '';
+  try {
+    const r = _recall(terms.join(' OR '), { configDir: dir, scope: ['sessions', 'trajectories', 'memories'], k, raw: true });
+    const hits = (r && Array.isArray(r.hits)) ? r.hits : [];
+    const lines = hits
+      .map((h) => `- [${h.scope}] ${String(h.snippet || '').replace(/\s+/g, ' ').trim()}`)
+      .filter((l) => l.length > 6);
+    return lines.length ? `## Relevant recalled context\n${lines.join('\n')}` : '';
+  } catch {
+    return '';
+  }
+}
+
+export function composePromptStack({ cfgDir, agent, workspace, sessionId, query, recallK = 5 } = {}) {
   const dir = cfgDir || defaultConfigDir();
   const a = agent || {};
   const parts = [];
@@ -76,5 +129,9 @@ export function composePromptStack({ cfgDir, agent, workspace, sessionId } = {})
   const tail = lastRecentLine(dir);
   if (tail) parts.push(`## Most-recent turn\n${tail}`);
 
+  // 8. recalled context for the current message (opt-in via `query`).
+  const recalled = recalledLayer(dir, query, recallK);
+  if (recalled) parts.push(recalled);
+
   return parts.join('\n\n');
 }

package/mas/recall_blend.mjs

@@ -0,0 +1,56 @@
+// mas/recall_blend.mjs — pure helpers for hybrid recall (JS cosine + bm25
+// blend). No native vector extension and no DB access: index_db.mjs owns the
+// SQLite handle and passes a getVec(scope, rowid) lookup in. Kept here so
+// index_db.mjs stays one-responsibility (and under its size ceiling).
+
+// Float32 vector <-> SQLite BLOB.
+export function f32ToBlob(vec) {
+  return Buffer.from(Float32Array.from(vec).buffer);
+}
+export function blobToF32(buf) {
+  if (!buf || !buf.byteLength) return null;
+  const out = new Float32Array(buf.byteLength >> 2);
+  for (let i = 0; i < out.length; i++) out[i] = buf.readFloatLE(i * 4);
+  return out;
+}
+
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+// Re-rank FTS candidates by a fused bm25 + cosine score. bm25 is
+// ascending-better and cosine is descending-better, so each is min-max
+// normalized to [0,1] (higher = better) before the weighted sum. Candidates
+// with no stored vector (or a dim mismatch) get vecNorm 0 — they keep their
+// bm25 standing and never outrank a real semantic match. Strictly additive:
+// it only re-orders the same hit set, never drops a hit.
+//   hits     — [{ bm25, ... }]
+//   rowmeta  — parallel [{ scope, rowid }]
+//   qvec     — query embedding (Float32Array)
+//   getVec   — (scope, rowid) => Float32Array | null
+export function blendHybrid(hits, rowmeta, qvec, getVec, weights) {
+  const wFts = Number.isFinite(weights?.fts) ? weights.fts : 0.5;
+  const wVec = Number.isFinite(weights?.vec) ? weights.vec : 0.5;
+  const bm25s = hits.map((h) => h.bm25);
+  const bMin = Math.min(...bm25s), bMax = Math.max(...bm25s);
+  const ftsScore = (b) => (bMax === bMin ? 1 : (bMax - b) / (bMax - bMin)); // best (lowest) bm25 → 1
+  const vecScores = hits.map((_, i) => {
+    try {
+      const dv = getVec(rowmeta[i].scope, rowmeta[i].rowid);
+      if (!dv || dv.length !== qvec.length) return null;
+      return cosine(qvec, dv);
+    } catch { return null; }
+  });
+  const present = vecScores.filter((v) => v != null);
+  const vMin = present.length ? Math.min(...present) : 0;
+  const vMax = present.length ? Math.max(...present) : 1;
+  const vNorm = (v) => (v == null ? 0 : (vMax === vMin ? 1 : (v - vMin) / (vMax - vMin)));
+  return hits
+    .map((h, i) => ({ h, score: wFts * ftsScore(h.bm25) + wVec * vNorm(vecScores[i]) }))
+    .sort((a, b) => b.score - a.score)
+    .map((x) => x.h);
+}

package/mas/redact.mjs

@@ -34,6 +34,61 @@ export function redactSecrets(text) {
     .replace(/\b([\w-]*(?:key|token|secret|password))\s*[:=]\s*["']?[^\s"']+/gi, '$1=[REDACTED]');
 }
 
+// Object keys whose STRING values carry credential material. Matched
+// case-insensitively as a substring of each key, so apiKey / api-key /
+// botToken / appToken / accessToken / clientSecret / authorization / password
+// / privateKey are all caught at any nesting depth. Only STRING values are
+// masked, so a numeric budget (chatWindow.tokens) or a rate card never is.
+const SENSITIVE_KEY_RE = /(api[-_]?key|apikey|secret|passwd|password|token|authorization|credential|bearer|private[-_]?key|access[-_]?key)/i;
+
+// Deep-redact a config-shaped value: recursively clone, masking the string
+// value of any secret-named key. Structure, arrays, numbers, and non-secret
+// strings are preserved; the input is never mutated. `mask` lets the caller
+// substitute a hinted masker (maskApiKey) instead of the default sentinel.
+export function redactConfigTree(value, mask = () => '[REDACTED]', keyName = '') {
+  if (Array.isArray(value)) return value.map((v) => redactConfigTree(v, mask));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redactConfigTree(v, mask, k);
+    return out;
+  }
+  if (typeof value === 'string' && keyName && SENSITIVE_KEY_RE.test(keyName)) {
+    return value ? mask(value) : value;
+  }
+  return value;
+}
+
+const MAX_SKILL_BODY_BYTES = 8 * 1024;
+
+// Sanitise a skill body before it is persisted and later loaded into other
+// agents' context — for BOTH synthesised skills and remotely-installed ones:
+// redact secrets, neutralise the [[TASK_DONE]] router marker (so reference
+// material can't drive the router loop), strip control characters, and cap the
+// size. Lives here (zero-dep) so the install path can use it without pulling
+// better-sqlite3 in via skill_synth.
+export function sanitizeSkillBody(text) {
+  let s = redactSecrets(text);
+  s = s.replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]');
+  // Strip control characters except tab/newline/carriage-return.
+  s = s.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
+  if (Buffer.byteLength(s, 'utf8') > MAX_SKILL_BODY_BYTES) {
+    s = Buffer.from(s, 'utf8').subarray(0, MAX_SKILL_BODY_BYTES).toString('utf8').replace(/\uFFFD+$/, '') + '\n\n\u2026[truncated]';
+  }
+  return s;
+}
+
+// Sanitise the one-line description (it lands in every agent's system prompt
+// via the skills index): redact, collapse to a single line, neutralise the
+// marker, cap to 120 chars.
+export function sanitizeDescription(text) {
+  return redactSecrets(text)
+    .replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]')
+    .replace(/[\u0000-\u001F\u007F]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 120);
+}
+
 // Neutralise forged conversation role labels embedded in untrusted model
 // text. The reflection/synthesis transcript is rendered as
 // `[User]/[System]/<agent>` lines from the TRUSTED turn.agent field; a

package/mas/router_posting.mjs

@@ -0,0 +1,96 @@
+// mas/router_posting.mjs — Slack thread I/O for the mention router.
+//
+// Extracted from mention_router.mjs (which one-file-one-responsibility kept
+// pushing over its size ceiling). These three helpers own every post the
+// multi-agent loop makes into a task's Slack thread: the agent reply, the
+// "thinking…" placeholder, and the placeholder cleanup. They are pure I/O —
+// no router state — so they live here and the router imports them.
+//
+// Each helper is best-effort: a missing Slack wiring or a failed post returns
+// a null-ish result and logs, never throws, so a Slack hiccup can't break the
+// task loop. A long-lived caller passes a started `sender` to reuse across the
+// whole run; when none is given the helper opens (and closes) its own client.
+
+// Post an agent reply (or a user/system note when agentRecord is null) into the
+// task's thread. Returns the message ts, or null when Slack isn't wired/failed.
+export async function postToThread({ task, agentRecord, text, logger = () => {}, sender }) {
+  if (!task.slackChannel || !task.slackThreadTs) return null;
+  let slack = sender;
+  let owned = false;
+  if (!slack) {
+    const { SlackChannel } = await import('../channels/slack.mjs');
+    slack = new SlackChannel({ requireInbound: false });
+    owned = true;
+    try {
+      await slack.start(async () => '', {});
+    } catch (err) {
+      logger(`[router] slack start failed: ${err?.message || err}\n`);
+      return null;
+    }
+  }
+  const threadId = `${task.slackChannel}:${task.slackThreadTs}`;
+  // When we have a real agent persona, push the text under that persona's
+  // username + icon. Otherwise (user message or system note) fall back to the
+  // bot's default identity with no decoration.
+  let body;
+  const sendOpts = {};
+  if (agentRecord) {
+    body = String(text);
+    if (agentRecord.displayName) sendOpts.username = agentRecord.displayName;
+    if (agentRecord.iconEmoji) sendOpts.icon_emoji = agentRecord.iconEmoji;
+  } else {
+    body = String(text);
+  }
+  try {
+    const res = await slack.send(threadId, body, sendOpts);
+    return res?.ts || null;
+  } catch (err) {
+    logger(`[router] slack send failed: ${err?.message || err}\n`);
+    return null;
+  } finally {
+    if (owned) await slack.stop().catch(() => {});
+  }
+}
+
+// "X is thinking…" placeholder posted into the thread before an agent turn so a
+// human reader knows work is happening. Returns the placeholder's ts (+ the
+// sender used) so the caller can delete it once the real reply lands. No-op
+// when Slack isn't wired or the post fails.
+export async function postTypingPlaceholder({ task, agentRecord, logger = () => {}, sender }) {
+  if (!task.slackChannel || !task.slackThreadTs) return { ts: null, sender: null };
+  let slack = sender;
+  let owned = false;
+  if (!slack) {
+    const { SlackChannel } = await import('../channels/slack.mjs');
+    slack = new SlackChannel({ requireInbound: false });
+    owned = true;
+    try {
+      await slack.start(async () => '', {});
+    } catch (err) {
+      logger(`[router] slack start failed: ${err?.message || err}\n`);
+      return { ts: null, sender: null };
+    }
+  }
+  const threadId = `${task.slackChannel}:${task.slackThreadTs}`;
+  const sendOpts = {};
+  if (agentRecord?.displayName) sendOpts.username = agentRecord.displayName;
+  if (agentRecord?.iconEmoji)   sendOpts.icon_emoji = agentRecord.iconEmoji;
+  try {
+    const res = await slack.send(threadId, `_:hourglass_flowing_sand: thinking…_`, sendOpts);
+    return { ts: res?.ts || null, sender: slack, owned, channel: task.slackChannel };
+  } catch (err) {
+    logger(`[router] slack typing post failed: ${err?.message || err}\n`);
+    if (owned) await slack.stop().catch(() => {});
+    return { ts: null, sender: null, owned: false };
+  }
+}
+
+// Delete a "thinking…" placeholder once the real reply is in. Only stops a
+// client this helper opened (a shared sender is closed once by run()).
+export async function clearTypingPlaceholder(placeholder, logger = () => {}) {
+  if (!placeholder?.ts || !placeholder?.channel || !placeholder?.sender) return;
+  const slack = placeholder.sender;
+  try { await slack.deleteMessage(placeholder.channel, placeholder.ts); }
+  catch (err) { logger(`[router] slack typing delete failed: ${err?.message || err}\n`); }
+  finally { if (placeholder.owned) await slack.stop().catch(() => {}); }
+}

package/mas/router_termination.mjs

@@ -0,0 +1,63 @@
+// Terminal-stop finalization for the mention router. Extracted from
+// mention_router.mjs so a non-DONE exit (budget / abort / idle) lands the
+// task on a terminal status AND posts a closing note to the thread, instead
+// of leaving status 'running' forever (a perpetual run on the dashboard) and
+// the thread silent. abort → 'abandoned'; budget/idle → 'paused' (resumable
+// via `task tick`). The DONE path flips status + posts a closing note; this
+// mirrors that for the stranded exits. Lives in its own module to keep
+// mention_router.mjs under its size ceiling.
+//
+// A non-DONE stop that wasn't an explicit abort (budget / idle → paused)
+// also fires the post-failure learning trigger so a stranded team task
+// teaches an anti-pattern skill. It's fire-and-forget (never awaited, never
+// throws into the router) and degrades to a no-op when the caller hasn't
+// threaded task/cfg through yet.
+
+import { runLearning as defaultRunLearning } from './learning.mjs';
+
+/**
+ * Patch task status + post a stop note for a non-DONE terminal exit, and
+ * fire post-failure learning for budget/idle (paused) stops (not abort).
+ * Returns the (possibly updated) task record. A 'done' stop is a no-op so
+ * the caller can invoke this unconditionally.
+ *
+ * `task`, `cfg` and `runLearningImpl` are optional so mention_router.mjs
+ * (not editable in this change) can keep its current call site; when
+ * `task` is absent the learning trigger degrades to a no-op.
+ *
+ * @param {{ stoppedBy: string, iterations: number, current: any, configDir: string,
+ *   tasksMod: { patchTask: Function }, postToThread: Function, slackSender: any,
+ *   logger?: Function, task?: any, cfg?: any, runLearningImpl?: Function }} args
+ */
+export async function finalizeTerminalStop({ stoppedBy, iterations, current, configDir, tasksMod, postToThread, slackSender, logger, task, cfg, runLearningImpl }) {
+  if (stoppedBy === 'done') return current;
+  // Map the stop reason to a terminal status (tasks.mjs VALID_STATUSES):
+  //   abort        → 'abandoned'  (explicit human stop)
+  //   budget/idle  → 'paused'     (didn't fail — resumable; `task tick` flips
+  //                                it back to 'running' for the next turn)
+  // This keeps a stopped task off the dashboard's perpetual-'running' list
+  // while being honest that hitting the turn budget or going idle is a pause,
+  // not a failure.
+  const terminalStatus = stoppedBy === 'abort' ? 'abandoned' : 'paused';
+  const stopNote = stoppedBy === 'abort'
+    ? ':octagonal_sign: task aborted.'
+    : stoppedBy === 'budget'
+      ? `:hourglass: paused after ${iterations} turns (turn budget reached) — \`task tick\` to resume.`
+      : ':zzz: paused — no agent had anything left to do; \`task tick\` to resume.';
+  const next = tasksMod.patchTask(current.id, { status: terminalStatus }, configDir);
+  await postToThread({ task: next, agentRecord: null, text: stopNote, logger, sender: slackSender });
+
+  // Fire-and-forget post-failure learning. Abort is a deliberate human
+  // stop, not a failed attempt, so it never teaches an anti-pattern. We
+  // only fire when a `task` was threaded through (degrade to no-op
+  // otherwise) and never await/throw into the router.
+  if (stoppedBy !== 'abort' && task) {
+    const fire = typeof runLearningImpl === 'function' ? runLearningImpl : defaultRunLearning;
+    queueMicrotask(() => {
+      Promise.resolve()
+        .then(() => fire('post-failure', { task: task || next, configDir, cfg, agent: null }))
+        .catch(() => { /* swallow — learning must never break a stop */ });
+    });
+  }
+  return next;
+}

package/mas/scrub_env.mjs

@@ -12,14 +12,28 @@
 // explicit `allow` list opts specific keys back in for the rare command that
 // genuinely needs one.
 
-// Matches keys whose final _-segment is a secret-ish noun: FOO_API_KEY,
-// ANTHROPIC_API_KEY, *_TOKEN (incl. CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN),
-// *_SECRET, *_PASSWORD/PASSWD, *_CREDENTIAL(S), *_PRIVATE_KEY, *_ACCESS_KEY.
+// Matches keys whose final _-segment is a secret-ish noun. Now includes bare
+// *_KEY / *_KEY_ID so the previously-missed STRIPE_SECRET_KEY, SUPABASE_KEY,
+// ENCRYPTION_KEY, AWS_ACCESS_KEY_ID are caught — while the suffix anchoring
+// still leaves KEYBOARD / TOKENIZER / MONKEY / BASE_URL alone.
 const SECRET_KEY_RE =
-  /(^|_)(API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|CREDENTIALS|PRIVATE_KEY|ACCESS_KEY|AUTH_TOKEN)$/i;
+  /(^|_)(API_?KEYS?|APIKEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_KEY|ACCESS_KEY|ACCESS_KEY_ID|KEY|KEY_ID|AUTH_TOKEN|SESSION_TOKEN)$/i;
+
+// Names that carry credentials but aren't caught by the suffix-noun rule —
+// connection strings (value is a URL with embedded creds) and the ssh-agent
+// socket (a child with it can use the agent's keys).
+const SECRET_NAME_SET = new Set([
+  'SSH_AUTH_SOCK', 'DATABASE_URL', 'DATABASE_URI', 'DB_URL', 'DB_URI', 'DSN',
+  'CONNECTION_STRING', 'PGPASSWORD', 'MYSQL_PWD', 'REDIS_URL', 'MONGODB_URI', 'MONGO_URL',
+]);
+
+// A value that is a credential-bearing URL (scheme://user:password@host) leaks
+// a secret regardless of the variable's name (e.g. a benign-looking *_URL).
+const URL_CRED_RE = /^[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i;
 
 export function isSecretKey(name) {
-  return SECRET_KEY_RE.test(String(name || ''));
+  const k = String(name || '');
+  return SECRET_KEY_RE.test(k) || SECRET_NAME_SET.has(k.toUpperCase());
 }
 
 export function scrubEnv(env = process.env, { allow = [] } = {}) {
@@ -27,7 +41,8 @@ export function scrubEnv(env = process.env, { allow = [] } = {}) {
   const out = {};
   for (const [k, v] of Object.entries(env || {})) {
     if (allowSet.has(k)) { out[k] = v; continue; }
-    if (isSecretKey(k)) continue; // drop secrets
+    if (isSecretKey(k)) continue;                 // drop by name
+    if (typeof v === 'string' && URL_CRED_RE.test(v)) continue; // drop creds embedded in a URL value
     out[k] = v;
   }
   return out;

package/mas/skill_synth.mjs

@@ -17,45 +17,19 @@
 
 import * as skills from '../skills.mjs';
 import { runTextCompletion } from './provider_adapters.mjs';
-import { redactSecrets, neutralizeRoleLabels } from './redact.mjs';
+import { redactSecrets, neutralizeRoleLabels, sanitizeSkillBody, sanitizeDescription } from './redact.mjs';
 import { indexSkill as _indexSkill } from './index_db.mjs';
 import { parseFrontmatter } from '../skills.mjs';
 
 const SECTION_RE = /^#{1,6}\s+/;
 const MAX_NAME_LEN = 48;
-const MAX_BODY_BYTES = 8 * 1024;
 
-// Re-export the shared secret redactor (mas/redact.mjs) so existing
-// callers of skill_synth.redactSecrets keep working while the single
-// implementation is shared with agent_memory.reflectOnce.
-export { redactSecrets };
-
-// Sanitise an agent-authored skill body before it is persisted and
-// later loaded into other agents' context: redact secrets, neutralise
-// the task-termination marker (so reference material can't drive the
-// router loop), strip control characters, and cap the size.
-export function sanitizeSkillBody(text) {
-  let s = redactSecrets(text);
-  s = s.replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]');
-  // Strip control characters except tab/newline/carriage-return.
-  s = s.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
-  if (Buffer.byteLength(s, 'utf8') > MAX_BODY_BYTES) {
-    s = Buffer.from(s, 'utf8').subarray(0, MAX_BODY_BYTES).toString('utf8').replace(/\uFFFD+$/, '') + '\n\n…[truncated]';
-  }
-  return s;
-}
-
-// Sanitise the one-line description (it lands in every agent's system
-// prompt via the skills index): redact, collapse to a single line,
-// neutralise the marker, cap to 120 chars.
-export function sanitizeDescription(text) {
-  return redactSecrets(text)
-    .replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]')
-    .replace(/[\u0000-\u001F\u007F]+/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .slice(0, 120);
-}
+// Re-export the shared redaction/sanitisation primitives (mas/redact.mjs) so
+// existing callers of skill_synth.{redactSecrets,sanitizeSkillBody,
+// sanitizeDescription} keep working. They live in the zero-dep redact module
+// now so the remote skill-install path can reuse them without pulling in
+// better-sqlite3 via this module.
+export { redactSecrets, sanitizeSkillBody, sanitizeDescription };
 
 // Lowercase, collapse every run of non-alphanumerics into a single
 // dash, and strip leading/trailing dashes. Empty input (or input with

package/mas/tool_runner.mjs

@@ -27,6 +27,7 @@ export function listToolSchemas(names) {
   for (const name of wanted) {
     const t = registry.lookup(name);
     if (!t) continue;
+    if (t.unavailable) continue; // not-implemented stubs stay registered but hidden from the model's tool schemas
     out.push({ name: t.name, description: t.description, parameters: t.parameters });
   }
   return out;
@@ -35,7 +36,7 @@ export function listToolSchemas(names) {
 export function isImplemented(name) { return registry.lookup(name) !== null; }
 export function knownTool(name)     { return registry.lookup(name) !== null; }
 
-export async function runTool({ agent, tool, args, taskId, configDir, cwd, approve, security } = {}) {
+export async function runTool({ agent, tool, args, taskId, configDir, cwd, approve, security, sandbox = null } = {}) {
   if (!agent || !Array.isArray(agent.tools)) {
     throw new ToolError('agent record with .tools[] is required', 'TOOL_BAD_AGENT');
   }
@@ -72,7 +73,7 @@ export async function runTool({ agent, tool, args, taskId, configDir, cwd, appro
   }
   let result;
   try {
-    result = await impl.exec(args || {}, { cwd: cwd || process.cwd(), configDir, taskId, agent });
+    result = await impl.exec(args || {}, { cwd: cwd || process.cwd(), configDir, taskId, agent, sandbox });
   } catch (err) {
     result = { ok: false, error: `${tool} threw: ${err?.message || err}` };
   }

package/mas/tools/bash.mjs

@@ -14,6 +14,7 @@
 
 import { spawn } from 'node:child_process';
 import { scrubEnv } from '../scrub_env.mjs';
+import { spawnSandboxed } from '../../sandbox.mjs';
 
 export const NAME = 'bash';
 export const DESCRIPTION = 'Run a shell command in the agent\'s workspace. Returns {stdout, stderr, exitCode}. Timeout 30s by default.';
@@ -30,7 +31,7 @@ const MAX_TIMEOUT_MS = 5 * 60_000;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 200_000;  // 200 KB per stream — bigger gets truncated
 
-export async function exec(args, { cwd = process.cwd() } = {}) {
+export async function exec(args, { cwd = process.cwd(), sandbox = null, _spawnSandboxed = spawnSandboxed } = {}) {
   if (!args || typeof args.command !== 'string' || args.command.trim() === '') {
     return { ok: false, error: 'bash: command is required (non-empty string)' };
   }
@@ -39,7 +40,13 @@ export async function exec(args, { cwd = process.cwd() } = {}) {
     MAX_TIMEOUT_MS
   );
   return new Promise((resolve) => {
-    const child = spawn('sh', ['-c', args.command], { cwd, env: scrubEnv(process.env) });
+    // When a sandbox spec is present, run the SAME scrubbed `sh -c <cmd>`
+    // inside it (containment ADDED, never replacing the approval gate); a
+    // null/absent spec keeps the byte-stable bare-host path (unchanged).
+    // _spawnSandboxed is a test injection seam — defaults to the real impl.
+    const child = sandbox
+      ? _spawnSandboxed(sandbox, 'sh', ['-c', args.command], { cwd, env: scrubEnv(process.env) })
+      : spawn('sh', ['-c', args.command], { cwd, env: scrubEnv(process.env) });
     let stdout = '', stderr = '';
     let outBytes = 0, errBytes = 0;
     let truncated = false;

package/mas/tools/coding.mjs

@@ -7,11 +7,27 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { TOOLS as webTools } from './web.mjs';
+import { scrubEnv } from '../scrub_env.mjs';
+import { spawnSandboxed } from '../../sandbox.mjs';
 
 function runProc(cmd, args, opts = {}) {
   return new Promise(resolve => {
     let p;
-    try { p = spawn(cmd, args, { cwd: opts.cwd, env: opts.env || process.env }); }
+    // Default to a SECRET-SCRUBBED env (mirrors bash.mjs) so a snippet can't
+    // read API keys/tokens out of process.env. A caller may pass an explicit
+    // env to opt out.
+    //
+    // When a sandbox spec is present, run the SAME scrubbed interpreter
+    // invocation inside it (containment ADDED, never replacing the approval
+    // gate); a null/absent spec keeps the byte-stable bare-host path. The
+    // _spawnSandboxed injection seam defaults to the real impl (mirrors bash.mjs).
+    const env = opts.env || scrubEnv(process.env);
+    const spawnInSandbox = opts._spawnSandboxed || spawnSandboxed;
+    try {
+      p = opts.sandbox
+        ? spawnInSandbox(opts.sandbox, cmd, args, { cwd: opts.cwd, env })
+        : spawn(cmd, args, { cwd: opts.cwd, env });
+    }
     catch (e) { return resolve({ ok: false, error: e.message }); }
     let out = '', err = '';
     const timeout = setTimeout(() => { try { p.kill('SIGKILL'); } catch {} }, opts.timeoutMs || 30_000);
@@ -25,7 +41,7 @@ function runProc(cmd, args, opts = {}) {
 
 const python_exec = {
   name: 'python_exec', category: 'coding', sensitive: true,
-  description: 'Run a Python snippet in a sandboxed subprocess. 30s timeout.',
+  description: 'Run a Python snippet in a subprocess (secret env vars stripped). 30s timeout.',
   parameters: {
     type: 'object',
     properties: { code: { type: 'string' }, timeoutMs: { type: 'number' } },
@@ -33,13 +49,16 @@ const python_exec = {
   },
   async exec(args, ctx) {
     const py = ctx?.python || process.env.LAZYCLAW_PYTHON || 'python3';
-    return runProc(py, ['-c', args.code], { cwd: ctx?.cwd, timeoutMs: args.timeoutMs });
+    return runProc(py, ['-c', args.code], {
+      cwd: ctx?.cwd, timeoutMs: args.timeoutMs,
+      sandbox: ctx?.sandbox, _spawnSandboxed: ctx?._spawnSandboxed,
+    });
   },
 };
 
 const node_exec = {
   name: 'node_exec', category: 'coding', sensitive: true,
-  description: 'Run a Node.js snippet in a sandboxed subprocess. 30s timeout.',
+  description: 'Run a Node.js snippet in a subprocess (secret env vars stripped). 30s timeout.',
   parameters: {
     type: 'object',
     properties: { code: { type: 'string' }, timeoutMs: { type: 'number' } },
@@ -47,12 +66,16 @@ const node_exec = {
   },
   async exec(args, ctx) {
     const node = ctx?.node || process.execPath;
-    return runProc(node, ['-e', args.code], { cwd: ctx?.cwd, timeoutMs: args.timeoutMs });
+    return runProc(node, ['-e', args.code], {
+      cwd: ctx?.cwd, timeoutMs: args.timeoutMs,
+      sandbox: ctx?.sandbox, _spawnSandboxed: ctx?._spawnSandboxed,
+    });
   },
 };
 
 const sql_query = {
   name: 'sql_query', category: 'coding', sensitive: true,
+  unavailable: true, // not implemented (ctx.db is never bound) — hidden from tool schemas until wired
   description: 'Run a read-only SQL query against the agent\'s bound database. Returns rows.',
   parameters: {
     type: 'object',