scalix 1.5.2 → 1.6.0

package/dist/secure-fetch.js

@@ -0,0 +1,117 @@
+// Connection-pinned fetch.
+//
+// The SSRF checks in tools-web.ts and mcp.ts resolve the hostname, decide the
+// address is public, and then let fetch() resolve the name AGAIN on its own.
+// Between the two lookups an attacker who controls DNS can flip the answer
+// (DNS rebinding): the validation sees a public address, the connection lands
+// on 127.0.0.1 / 169.254.169.254 / anything internal, with whatever
+// Authorization header the caller attached. Validating and connecting are two
+// different resolutions of the same name, so the check protects nothing.
+//
+// The fix is to make them the SAME resolution: resolve once, keep the
+// addresses, and hand them to the connection as a pinned `lookup` so the
+// socket can only ever reach an address that was actually validated.
+//
+// node:http/https are used rather than global fetch for exactly one reason —
+// fetch (undici) exposes no way to pin DNS. The hostname is left untouched, so
+// SNI, the Host header and the certificate's hostname check all still apply to
+// the real name; only the address it dials is constrained.
+import dns from 'node:dns';
+import http from 'node:http';
+import https from 'node:https';
+import zlib from 'node:zlib';
+import { Readable } from 'node:stream';
+/**
+ * Resolve a hostname for pinning. Returns [] when the name cannot be resolved
+ * (or the caller deliberately skipped pinning) — the request then falls back
+ * to ordinary fetch, whose own failure is the honest outcome.
+ */
+export async function resolveLookupAddresses(hostname) {
+    try {
+        const addresses = await dns.promises.lookup(hostname, { all: true });
+        return addresses.length > 0 ? addresses : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function pinnedLookup(addresses) {
+    const list = addresses.map((a) => ({ address: a.address, family: a.family }));
+    return function lookup(_hostname, options, callback) {
+        if (options && options.all) {
+            callback(null, list);
+        }
+        else {
+            const first = list[0];
+            callback(null, first.address, first.family);
+        }
+    };
+}
+/** Decode a compressed HTTP stream so callers see the same bytes fetch() would. */
+function decodeBody(res) {
+    const encoding = res.headers['content-encoding'];
+    if (encoding === 'gzip')
+        return res.pipe(zlib.createGunzip());
+    if (encoding === 'deflate')
+        return res.pipe(zlib.createInflate());
+    if (encoding === 'br')
+        return res.pipe(zlib.createBrotliDecompress());
+    return res;
+}
+/**
+ * fetch() with the connection pinned to pre-validated addresses.
+ *
+ * Drop-in for the call sites in tools-web.ts and mcp.ts: same RequestInit
+ * shape, same Response contract (streaming body included, so long-lived SSE
+ * responses such as MCP's keep working).
+ */
+export async function pinnedFetch(url, init, addresses) {
+    if (addresses.length === 0) {
+        // Nothing was validated to pin to; the caller decided this is allowed.
+        return fetch(url, init);
+    }
+    const transport = url.protocol === 'https:' ? https : http;
+    const headers = new Headers(init.headers);
+    const method = (init.method || 'GET').toUpperCase();
+    const body = init.body;
+    const nodeResponse = await new Promise((resolve, reject) => {
+        const request = transport.request(url, {
+            method,
+            // The whole point: dial only what we validated.
+            lookup: pinnedLookup(addresses),
+            // Fresh connection per request — a pooled socket is keyed by host:port
+            // and would carry no lookup of its own.
+            agent: false,
+            signal: init.signal ?? undefined,
+            headers: Object.fromEntries(headers.entries()),
+        }, resolve);
+        request.on('error', reject);
+        if (body !== undefined && body !== null) {
+            if (typeof body === 'string')
+                request.write(body);
+            else if (body instanceof Uint8Array)
+                request.write(body);
+            else if (body instanceof URLSearchParams)
+                request.write(body.toString());
+            else
+                reject(new Error(`pinnedFetch: unsupported request body type (${typeof body})`));
+        }
+        request.end();
+    });
+    const responseHeaders = new Headers();
+    for (const [key, value] of Object.entries(nodeResponse.headers)) {
+        if (value === undefined)
+            continue;
+        responseHeaders.set(key, Array.isArray(value) ? value.join(', ') : value);
+    }
+    // A decoded stream's length no longer matches the compressed original, and a
+    // stale content-length makes readers stop early.
+    const decoded = nodeResponse.headers['content-encoding'] !== undefined;
+    if (decoded)
+        responseHeaders.delete('content-length');
+    return new Response(Readable.toWeb(decodeBody(nodeResponse)), {
+        status: nodeResponse.statusCode ?? 502,
+        statusText: nodeResponse.statusMessage || '',
+        headers: responseHeaders,
+    });
+}

package/dist/settings.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { setSecurityConfig, setScopedPermissionRules } from './sandbox.js';
+import { COMMAND_SANDBOX_MODES } from './command-sandbox.js';
 import { DEFAULT_BASE_URL, DEFAULT_MODELS, AGENT_DEFAULTS, CONTEXT_DEFAULTS, WEB_DEFAULTS, TOOL_DEFAULTS, SUB_AGENT_DEFAULTS, MULTI_AGENT_DEFAULTS, USER_CONFIG_DIR, registerUserModels, setNetworkSecurityOverrides, normalizeModelId, } from './constants.js';
 import { getApiKeyFromKeychain, setApiKeyInKeychain, isKeychainAvailable } from './keychain.js';
 import { isProviderId } from './providers/index.js';
@@ -165,22 +166,41 @@ function validateConfig(parsed) {
     if (typeof parsed.disableUpdateCheck === 'boolean') {
         safe.disableUpdateCheck = parsed.disableUpdateCheck;
     }
+    // OS-level command sandbox (command-sandbox.ts). Opt-in: absent or invalid
+    // values resolve to 'off' so existing installs never change behaviour.
+    if (typeof parsed.commandSandbox === 'string' && COMMAND_SANDBOX_MODES.includes(parsed.commandSandbox)) {
+        safe.commandSandbox = parsed.commandSandbox;
+    }
     // BYOK (validateConfig drops unknown keys, so these MUST be whitelisted here
     // or they vanish on the next saveConfig — spec §4 migration gotcha #1).
     if (isProviderId(parsed.provider)) {
         safe.provider = parsed.provider;
     }
     if (parsed.providers && typeof parsed.providers === 'object' && !Array.isArray(parsed.providers)) {
-        const po = parsed.providers.openai;
-        if (po && typeof po === 'object' && !Array.isArray(po)) {
+        const registry = {};
+        for (const [key, raw] of Object.entries(parsed.providers)) {
+            if (!isProviderId(key))
+                continue;
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                continue;
+            const po = raw;
             const creds = {};
             if (typeof po.apiKey === 'string')
                 creds.apiKey = po.apiKey;
             if (typeof po.baseUrl === 'string' && po.baseUrl.length > 0)
                 creds.baseUrl = po.baseUrl;
+            if (typeof po.name === 'string' && po.name.trim())
+                creds.name = po.name.trim();
+            if (typeof po.enabled === 'boolean')
+                creds.enabled = po.enabled;
             if (Object.keys(creds).length > 0)
-                safe.providers = { openai: creds };
+                registry[key] = creds;
         }
+        if (Object.keys(registry).length > 0)
+            safe.providers = registry;
+    }
+    if (isStringArray(parsed.disabledProviders)) {
+        safe.disabledProviders = parsed.disabledProviders.filter((p) => isProviderId(p));
     }
     return safe;
 }
@@ -286,6 +306,33 @@ function validateScopedPermissions(raw) {
     }
     return valid;
 }
+/**
+ * Security fields a *project* file may set. Project-local settings ship inside
+ * the repo, so they are attacker-controllable; only fields that tighten the
+ * posture (more blocking, more read-only) may come from them. Anything that
+ * loosens the sandbox — reclassifying tools, disabling blocklist/injection
+ * patterns, allowing private hosts or env leakage — stays a user-level or
+ * managed-settings decision.
+ */
+const PROJECT_SAFE_SECURITY_FIELDS = new Set([
+    'additionalBlockedCommands',
+    'additionalBlockedHosts',
+    'additionalInjectionPatterns',
+    'additionalReadOnlyTools',
+    'additionalSensitiveEnvPatterns',
+    'maxImageSize',
+]);
+function filterProjectSafeSecurity(sec) {
+    if (!sec)
+        return undefined;
+    const safe = {};
+    for (const key of PROJECT_SAFE_SECURITY_FIELDS) {
+        const val = sec[key];
+        if (val !== undefined)
+            safe[key] = val;
+    }
+    return safe;
+}
 async function loadLocalOverrides(config) {
     // Project-local settings are attacker-controllable (they ship in the repo), so
     // only honor security-relevant overrides in a trusted workspace, and always
@@ -305,19 +352,36 @@ async function loadLocalOverrides(config) {
             const validated = validateConfig(overrides);
             if (validated.models)
                 config.models = validated.models;
-            if (validated.permissionMode)
+            // A repo may only TIGHTEN the permission mode (plan). 'auto'/'yolo' from
+            // a project file would silently disable confirmation prompts after a
+            // single "Trust" click — those stay user/managed-level decisions.
+            if (validated.permissionMode === 'plan') {
                 config.permissionMode = validated.permissionMode;
+            }
+            else if (validated.permissionMode === 'auto' || validated.permissionMode === 'yolo') {
+                process.stderr.write(`Project settings tried to set permissionMode "${validated.permissionMode}" — ignored (escalation from project files is not allowed; set it via \`scalix\` config or SCALIX_PERMISSION_MODE).\n`);
+            }
             if (validated.thinkingMode)
                 config.thinkingMode = validated.thinkingMode;
             if (validated.limits)
                 config.limits = { ...config.limits, ...validated.limits };
-            if (validated.security)
-                config.security = { ...config.security, ...validated.security };
+            const projectSecurity = filterProjectSafeSecurity(validated.security);
+            if (projectSecurity)
+                config.security = { ...config.security, ...projectSecurity };
             if (validated.customModels)
                 config.customModels = { ...config.customModels, ...validated.customModels };
+            // Scoped permissions from a project file may only DENY. An 'allow' rule
+            // in the repo would pre-approve exactly the tools the repo author chose.
             const scoped = validateScopedPermissions(overrides.scopedPermissions);
-            if (scoped)
-                config.scopedPermissions = scoped;
+            if (scoped) {
+                const denyOnly = scoped.filter(r => r.action === 'deny');
+                if (denyOnly.length > 0) {
+                    config.scopedPermissions = denyOnly;
+                }
+                else if (scoped.length > 0) {
+                    process.stderr.write('Project settings tried to add scoped permission "allow" rules — ignored (project files may only add deny rules).\n');
+                }
+            }
             break;
         }
         catch { }
@@ -332,16 +396,21 @@ async function loadManagedSettings(config) {
         try {
             const raw = await fs.readFile(managedPath, 'utf-8');
             const managed = JSON.parse(raw);
-            if (managed.permissionMode)
-                config.permissionMode = managed.permissionMode;
-            if (managed.security)
-                config.security = { ...config.security, ...managed.security };
-            if (managed.scopedPermissions)
+            // Managed settings are the highest-precedence trust anchor — validate
+            // them at least as strictly as user config so a malformed policy file
+            // can't corrupt permissionMode/security with unvalidated values.
+            const validated = validateConfig(managed);
+            if (validated.permissionMode)
+                config.permissionMode = validated.permissionMode;
+            if (validated.security)
+                config.security = { ...config.security, ...validated.security };
+            const scoped = validateScopedPermissions(managed.scopedPermissions);
+            if (scoped)
                 config.scopedPermissions = [
                     ...(config.scopedPermissions || []),
-                    ...managed.scopedPermissions,
+                    ...scoped,
                 ];
-            if (managed.disableUpdateCheck !== undefined)
+            if (typeof managed.disableUpdateCheck === 'boolean')
                 config.disableUpdateCheck = managed.disableUpdateCheck;
             break;
         }
@@ -361,11 +430,15 @@ export async function loadConfig() {
             if (keychainKey)
                 config.apiKey = keychainKey;
         }
-        // Per-provider keychain slot (BYOK): openai key lives under its own account.
-        if (config.providers?.openai && !config.providers.openai.apiKey) {
-            const k = await getApiKeyFromKeychain(OPENAI_KEYCHAIN_ACCOUNT).catch(() => null);
-            if (k)
-                config.providers.openai.apiKey = k;
+        // Per-provider keychain slots (BYOK): each provider key has its own account.
+        if (config.providers) {
+            for (const [key, creds] of Object.entries(config.providers)) {
+                if (creds.apiKey)
+                    continue;
+                const k = await getApiKeyFromKeychain(providerKeychainAccount(key)).catch(() => null);
+                if (k)
+                    creds.apiKey = k;
+            }
         }
         // Apply local overrides (project-level, gitignored)
         config = await loadLocalOverrides(config);
@@ -422,17 +495,19 @@ export async function saveConfig(config) {
             else
                 plaintextSecret = true;
         }
-        if (config.providers?.openai?.apiKey) {
-            const stored = await setApiKeyInKeychain(config.providers.openai.apiKey, OPENAI_KEYCHAIN_ACCOUNT).catch(() => false);
-            if (stored) {
-                configToWrite.providers = {
-                    ...configToWrite.providers,
-                    openai: { ...configToWrite.providers.openai, apiKey: '' },
-                };
-            }
-            else {
-                plaintextSecret = true;
+        if (config.providers) {
+            const nextProviders = {};
+            for (const [key, creds] of Object.entries(config.providers)) {
+                nextProviders[key] = { ...creds };
+                if (creds.apiKey) {
+                    const stored = await setApiKeyInKeychain(creds.apiKey, providerKeychainAccount(key)).catch(() => false);
+                    if (stored)
+                        nextProviders[key].apiKey = '';
+                    else
+                        plaintextSecret = true;
+                }
             }
+            configToWrite.providers = nextProviders;
         }
     }
     await fs.writeFile(getConfigFile(), JSON.stringify(configToWrite, null, 2), { encoding: 'utf-8', mode: 0o600 });
@@ -447,20 +522,85 @@ export function isConfigured(config) {
 }
 // ─── BYOK provider resolution ───
 export const OPENAI_KEYCHAIN_ACCOUNT = 'api-key-openai';
+/** Keychain account for a provider key. Scalix uses the legacy default account;
+ *  every other provider gets its own slot so keys never collide. */
+export function providerKeychainAccount(provider) {
+    return provider === 'scalix' ? undefined : `api-key-${provider}`;
+}
+/** Every provider key that should appear in the picker: the built-in Scalix
+ *  entry plus each configured registry entry, minus `disabledProviders` and
+ *  entries disabled individually. */
+export function listProviderKeys(config) {
+    const disabled = new Set(config.disabledProviders || []);
+    const keys = ['scalix'];
+    for (const [key, creds] of Object.entries(config.providers || {})) {
+        if (key === 'scalix')
+            continue;
+        if (creds.enabled === false)
+            continue;
+        if (disabled.has(key))
+            continue;
+        keys.push(key);
+    }
+    return keys;
+}
+/** Resolve one provider key from config only (no env override). Used for
+ *  explicit per-session overrides, where the caller's choice must win over the
+ *  process-wide `SCALIX_PROVIDER`. */
+export function resolveProviderByKey(config, provider) {
+    if (provider !== 'scalix') {
+        const creds = config.providers?.[provider] ?? {};
+        return {
+            provider,
+            baseUrl: creds.baseUrl || '',
+            apiKey: creds.apiKey || '',
+            cloudBaseUrl: config.baseUrl,
+            cloudApiKey: config.apiKey || '',
+        };
+    }
+    return {
+        provider: 'scalix',
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+        cloudBaseUrl: config.baseUrl,
+        cloudApiKey: config.apiKey,
+    };
+}
+/** Picker-facing provider list. Never includes keys — only identity/status. */
+export function summarizeProviders(config) {
+    const out = [];
+    for (const key of listProviderKeys(config)) {
+        if (key === 'scalix') {
+            out.push({ id: 'scalix', name: 'Scalix AI', adapter: 'scalix', configured: !!config.apiKey, builtIn: true });
+            continue;
+        }
+        const creds = config.providers?.[key] ?? {};
+        out.push({
+            id: key,
+            name: creds.name || key,
+            adapter: 'openai',
+            configured: !!(creds.baseUrl && creds.apiKey),
+            builtIn: false,
+        });
+    }
+    return out;
+}
 /**
  * Resolve which provider + credentials this session runs on.
  *
  * Precedence (mirrors the rest of config): env → config. `SCALIX_PROVIDER`
- * selects the provider; for `openai`, `OPENAI_API_KEY` / `OPENAI_BASE_URL`
- * override `providers.openai`. Scalix stays the zero-config default and its
- * path is byte-identical to the pre-BYOK behavior. There is NO default
- * third-party URL — an openai selection without a baseUrl resolves with an
- * empty one and the caller surfaces the configuration error.
+ * selects the provider key (built-in or registry); for any non-scalix provider
+ * the generic `SCALIX_PROVIDER_BASE_URL` / `SCALIX_PROVIDER_API_KEY` env vars
+ * win, and for `openai` the standard `OPENAI_API_KEY` / `OPENAI_BASE_URL` are
+ * also honored. Scalix stays the zero-config default and its path is
+ * byte-identical to the pre-BYOK behavior. There is NO default third-party URL
+ * — a BYOK selection without a baseUrl resolves with an empty one and the
+ * caller surfaces the configuration error.
  *
  * Scalix Cloud credentials resolve separately so BYOK sessions keep the
- * platform tools: under `openai` they come from `SCALIX_CLOUD_API_KEY` →
- * `SCALIX_API_KEY` → the top-level `config.apiKey`, and are simply empty when
- * the user never added one.
+ * platform tools: they come from `SCALIX_CLOUD_API_KEY` → `SCALIX_API_KEY` →
+ * the top-level `config.apiKey`, and are simply empty when the user never
+ * added one.
  */
 export function resolveActiveProvider(config, env = process.env) {
     const envProvider = env.SCALIX_PROVIDER?.trim().toLowerCase();
@@ -469,14 +609,23 @@ export function resolveActiveProvider(config, env = process.env) {
         : (config.provider ?? 'scalix');
     const scalixBaseUrl = env.SCALIX_BASE_URL?.trim() || config.baseUrl;
     const scalixApiKey = env.SCALIX_API_KEY?.trim() || config.apiKey;
-    if (provider === 'openai') {
-        const creds = config.providers?.openai ?? {};
+    const cloudBaseUrl = env.SCALIX_CLOUD_BASE_URL?.trim() || scalixBaseUrl;
+    const cloudApiKey = env.SCALIX_CLOUD_API_KEY?.trim() || scalixApiKey || '';
+    if (provider !== 'scalix') {
+        const creds = config.providers?.[provider] ?? {};
+        const legacyOpenAI = provider === 'openai';
         return {
             provider,
-            baseUrl: env.OPENAI_BASE_URL?.trim() || creds.baseUrl || '',
-            apiKey: env.OPENAI_API_KEY?.trim() || creds.apiKey || '',
-            cloudBaseUrl: env.SCALIX_CLOUD_BASE_URL?.trim() || scalixBaseUrl,
-            cloudApiKey: env.SCALIX_CLOUD_API_KEY?.trim() || scalixApiKey || '',
+            baseUrl: env.SCALIX_PROVIDER_BASE_URL?.trim()
+                || (legacyOpenAI ? env.OPENAI_BASE_URL?.trim() : '')
+                || creds.baseUrl
+                || '',
+            apiKey: env.SCALIX_PROVIDER_API_KEY?.trim()
+                || (legacyOpenAI ? env.OPENAI_API_KEY?.trim() : '')
+                || creds.apiKey
+                || '',
+            cloudBaseUrl,
+            cloudApiKey,
         };
     }
     return {

package/dist/slash-commands.js

@@ -42,6 +42,7 @@ export const SLASH_COMMANDS = [
     { cmd: '/update', desc: 'Check for and install updates' },
     { cmd: '/doctor', desc: 'Diagnose installation' },
     { cmd: '/mcp', desc: 'Add MCP server' },
+    { cmd: '/marketplace', desc: 'Browse & install from the Scalix curated catalog' },
     { cmd: '/cloud', desc: 'Scalix Cloud status, platform tools & refresh' },
     { cmd: '/login', desc: 'Link your Scalix account (API key)' },
     { cmd: '/setup', desc: 'Reconfigure API key, URL & models' },
@@ -125,6 +126,7 @@ export const HELP_LINES = [
     '  /skills       \u2014 list available skills',
     '  /setup        \u2014 reconfigure API key, URL & models',
     '  /mcp <l> <u>  \u2014 add MCP server',
+    '  /marketplace  \u2014 browse/install from the Scalix curated catalog (MCP, skills, rules, subagents)',
     '  /plugins      \u2014 show loaded plugins',
     '  /plugin       \u2014 install/enable/disable/uninstall plugins',
     '  /trust        \u2014 trust workspace (load project plugins/hooks/rules)',

package/dist/sub-agent.js

@@ -69,6 +69,8 @@ export async function spawnSubAgent(parentConfig, prompt, options = {}) {
         apiKey: parentConfig.apiKey,
         baseUrl: parentConfig.baseUrl,
         provider: parentConfig.provider,
+        cloudApiKey: parentConfig.cloudApiKey,
+        cloudBaseUrl: parentConfig.cloudBaseUrl,
         model,
         instructions: options.instructions || 'You are a focused research assistant. Be concise and factual. Respond in under 500 words.',
         tools,
@@ -145,6 +147,7 @@ export async function spawnSubAgent(parentConfig, prompt, options = {}) {
                     merged: mergeResult.merged,
                     commits: mergeResult.commitCount,
                     conflicts: mergeResult.conflicts?.length ?? 0,
+                    error: mergeResult.error,
                 });
             }
             catch (err) {

package/dist/tools-browser.js

@@ -467,10 +467,16 @@ export const browserGetTextTool = tool({
     },
 });
 const SESSION_DIR = '.scalix/browser-sessions';
+// Session names become file names under .scalix/browser-sessions/ — restrict
+// them to a safe charset so `../` cannot escape the sandbox root.
+const SESSION_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 async function saveSessionState(name) {
     if (!browserContext || !browserPage) {
         throw new Error('No active browser session to save');
     }
+    if (!SESSION_NAME_RE.test(name)) {
+        throw new Error(`Invalid session name "${name}" — use letters, digits, dot, dash, underscore`);
+    }
     const storageState = await browserContext.storageState();
     const url = browserPage.url();
     const sessionDir = path.join(getSandboxRoot(), SESSION_DIR);
@@ -496,7 +502,7 @@ export const browserSessionSaveTool = tool({
     name: 'browser_session_save',
     description: 'Save the current browser session (cookies, localStorage, URL) to disk for later restoration.',
     inputSchema: z.object({
-        name: z.string().max(100).describe('Session name (used to restore later)'),
+        name: z.string().max(100).regex(SESSION_NAME_RE, 'Session name may only contain letters, digits, dot, dash, underscore (no slashes)').describe('Session name (used to restore later)'),
     }),
     execute: async ({ name }) => {
         try {
@@ -512,7 +518,7 @@ export const browserSessionRestoreTool = tool({
     name: 'browser_session_restore',
     description: 'Restore a previously saved browser session. Recreates the browser context with saved cookies/localStorage and navigates to the saved URL.',
     inputSchema: z.object({
-        name: z.string().max(100).describe('Session name to restore'),
+        name: z.string().max(100).regex(SESSION_NAME_RE, 'Session name may only contain letters, digits, dot, dash, underscore (no slashes)').describe('Session name to restore'),
     }),
     execute: async ({ name }) => {
         const pw = await getPlaywright();

package/dist/tools-extra.js

@@ -102,7 +102,11 @@ export const searchFilesTool = tool({
         const beforeContext = args['-B'];
         try {
             const cwd = process.cwd();
-            const target = searchPath || '.';
+            // Contain the search target before ANY backend runs — the rg fast path
+            // takes arbitrary paths and would otherwise read outside the sandbox
+            // (the built-in fallback below already validates).
+            const safeTarget = searchPath ? sandboxPath(searchPath) : '.';
+            const target = safeTarget;
             // Try ripgrep first
             const rgArgs = [];
             if (outputMode === 'files_with_matches')
@@ -136,18 +140,34 @@ export const searchFilesTool = tool({
                 });
                 const lines = stdout.split('\n').filter(Boolean);
                 const sliced = lines.slice(offset, headLimit > 0 ? offset + headLimit : undefined);
+                // The target is resolved to an absolute sandbox path, so rg prints
+                // absolute paths — render them relative to cwd like the fallback does.
+                const relPath = (p) => {
+                    const abs = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+                    return path.relative(cwd, abs) || '.';
+                };
+                const splitPrefix = (line, parts) => {
+                    const segs = line.split(':');
+                    const file = segs.slice(0, segs.length - parts).join(':');
+                    const rest = segs.slice(segs.length - parts).join(':');
+                    return [relPath(file), rest];
+                };
                 if (outputMode === 'files_with_matches') {
-                    return { pattern, count: sliced.length, files: sliced };
+                    return { pattern, count: sliced.length, files: sliced.map(relPath) };
                 }
                 else if (outputMode === 'count') {
                     const counts = sliced.map(line => {
-                        const [file, cnt] = line.split(':');
+                        const [file, cnt] = splitPrefix(line, 1);
                         return { file, count: parseInt(cnt, 10) || 0 };
                     });
                     return { pattern, entries: counts };
                 }
                 else {
-                    return { pattern, matchCount: sliced.length, content: sliced.join('\n') };
+                    const contentLines = sliced.map(line => {
+                        const [file, rest] = splitPrefix(line, 2);
+                        return `${file}:${rest}`;
+                    });
+                    return { pattern, matchCount: sliced.length, content: contentLines.join('\n') };
                 }
             }
             catch (rgErr) {
@@ -339,6 +359,66 @@ export const findFilesTool = tool({
         }
     },
 });
+// Artifacts — the Antigravity-parity surface: reviewable, durable outputs a
+// turn produces (plan, walkthrough, task list, summary) instead of burying
+// them in chat scrollback. Files live under <workspace>/.scalix/artifacts/ so
+// they are plain markdown any editor can open, with frontmatter the UI reads.
+const ARTIFACT_TYPES = ['plan', 'walkthrough', 'tasklist', 'summary'];
+export const writeArtifactTool = tool({
+    name: 'write_artifact',
+    description: 'Write a reviewable artifact for this task: an implementation plan before multi-step work, a walkthrough of what was done after it, a task list, or a summary. ' +
+        'Markdown with a # title. Returns the artifact path.',
+    inputSchema: z.object({
+        type: z.enum(ARTIFACT_TYPES).describe('plan | walkthrough | tasklist | summary'),
+        title: z.string().min(1).max(120).describe('Short human title, e.g. "Auth refactor plan"'),
+        content: z.string().min(1).max(100_000).describe('Markdown body (no frontmatter — added automatically).'),
+    }),
+    execute: async ({ type, title, content }) => {
+        try {
+            const dir = sandboxPath('.scalix/artifacts');
+            await fs.mkdir(dir, { recursive: true });
+            const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'artifact';
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            const rel = `.scalix/artifacts/${stamp}-${type}-${slug}.md`;
+            const abs = sandboxPath(rel);
+            const frontmatter = `---\ntype: ${type}\ntitle: ${title.replace(/\n/g, ' ')}\ncreatedAt: ${new Date().toISOString()}\n---\n\n`;
+            await fs.writeFile(abs, frontmatter + content + (content.endsWith('\n') ? '' : '\n'), 'utf8');
+            return { ok: true, path: rel, type, title };
+        }
+        catch (error) {
+            return { error: error.message };
+        }
+    },
+});
+export const listArtifactsTool = tool({
+    name: 'list_artifacts',
+    description: 'List artifacts previously written in this workspace (.scalix/artifacts), newest first.',
+    inputSchema: z.object({}),
+    execute: async () => {
+        try {
+            const dir = sandboxPath('.scalix/artifacts');
+            const names = await fs.readdir(dir);
+            const files = names.filter((n) => n.endsWith('.md')).sort().reverse().slice(0, 50);
+            const artifacts = await Promise.all(files.map(async (n) => {
+                try {
+                    const head = (await fs.readFile(path.join(dir, n), 'utf8')).slice(0, 512);
+                    const type = head.match(/^type:\s*(\S+)/m)?.[1] ?? 'unknown';
+                    const title = head.match(/^title:\s*(.+)$/m)?.[1] ?? n;
+                    return { path: `.scalix/artifacts/${n}`, type, title };
+                }
+                catch {
+                    return { path: `.scalix/artifacts/${n}`, type: 'unknown', title: n };
+                }
+            }));
+            return { artifacts };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { artifacts: [] };
+            return { error: error.message };
+        }
+    },
+});
 export const gitStatusTool = tool({
     name: 'git_status',
     description: 'Get git repository status: current branch, staged/unstaged changes, untracked files.',
@@ -426,6 +506,8 @@ export const extraTools = [
     editFileTool,
     searchFilesTool,
     findFilesTool,
+    writeArtifactTool,
+    listArtifactsTool,
     gitStatusTool,
     gitDiffTool,
     gitCommitTool,