arisa 4.0.24 → 4.1.2

package/README.md

@@ -132,13 +132,15 @@ Notes:
 On first run, Arisa will:
 
 1. ask for a Telegram bot token
-2. ask for the maximum number of authorized chat ids
-3. show Pi providers discovered from Pi Agent's model registry
-4. show the models available for the selected provider
-5. resolve authentication for the selected Pi provider
+2. validate the token and ask whether to continue bootstrap from Telegram (default: yes)
+3. when Telegram setup is selected, show a `https://t.me/<bot>?start=<setup-token>` link
+4. authorize that Telegram chat and continue setup there: Pi provider, model, and Pi auth
+5. ask from Telegram whether Arisa should keep running in background
 6. validate that Pi Agent works
 7. only then start listening to Telegram
 
+Choosing `n` at the Telegram setup prompt keeps the previous CLI-only bootstrap flow.
+
 Arisa does not run a persistent HTTP health server or Telegram webhook; Telegram uses long polling.
 
 Telegram bot tokens can be created with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "4.0.24",
+  "version": "4.1.2",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",

package/src/core/agent/agent-manager.js

@@ -1,13 +1,26 @@
 import path from "node:path";
-import { unlink } from "node:fs/promises";
+import { stat, unlink } from "node:fs/promises";
 import { createAgentSession, SessionManager, defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { createPiRuntime, hasProviderAuth } from "./pi-runtime.js";
 import { arisaInstallDir, buildAgentRuntimeContext } from "./runtime-context.js";
 import { withTimeout } from "./prompt-timeout.js";
+import { buildPiToolPolicy, getCoreCodingTools } from "./core-tools.js";
+import { createSystemShellTool } from "./system-shell-tool.js";
 import { arisaHomeDir, getChatPiSessionsDir } from "../../runtime/paths.js";
 
 const piValidationTimeoutMs = 60_000;
+const arisaToolNames = [
+  "list_tools",
+  "tool_help",
+  "tool_skills",
+  "set_tool_config",
+  "run_tool",
+  "list_scheduled_tasks",
+  "cancel_scheduled_task",
+  "cancel_all_scheduled_tasks",
+  "send_media_reply"
+];
 
 function isLocalBaseUrl(value) {
   if (typeof value !== "string" || !value.trim()) return false;
@@ -68,6 +81,13 @@ function selectMediaReplyTool(toolRegistry) {
   return tools.find(looksLikeTextToSpeechTool) || tools[0] || null;
 }
 
+async function assertDirectory(dir, label) {
+  const stats = await stat(dir);
+  if (!stats.isDirectory()) {
+    throw new Error(`${label} is not a directory: ${dir}`);
+  }
+}
+
 export class AgentManager {
   constructor({ config, artifactStore, toolRegistry, taskStore, logger }) {
     this.config = config;
@@ -95,15 +115,15 @@ export class AgentManager {
     this.sessions.delete(String(chatId));
   }
 
-  createSessionManager(chatId) {
+  createSessionManager(chatId, workspaceDir = arisaInstallDir) {
     const sessionKey = String(chatId);
     const sessionDir = getChatPiSessionsDir(sessionKey);
     if (this.pendingNewSessions.has(sessionKey)) {
       this.logger?.log("agent", `starting new persisted session for chat ${sessionKey}`);
-      return { sessionManager: SessionManager.create(arisaInstallDir, sessionDir), isNewSession: true };
+      return { sessionManager: SessionManager.create(workspaceDir, sessionDir), isNewSession: true };
     }
     this.logger?.log("agent", `recovering persisted session for chat ${sessionKey}`);
-    return { sessionManager: SessionManager.continueRecent(arisaInstallDir, sessionDir), isNewSession: false };
+    return { sessionManager: SessionManager.continueRecent(workspaceDir, sessionDir), isNewSession: false };
   }
 
   async validatePiAgent() {
@@ -156,23 +176,36 @@ export class AgentManager {
       throw new Error(`No auth found for ${this.config.pi.provider}. Re-run bootstrap and complete login for this provider before Telegram starts.`);
     }
 
-    const { sessionManager, isNewSession } = this.createSessionManager(sessionKey);
+    const policy = buildPiToolPolicy({
+      config: this.config,
+      customToolNames: [...arisaToolNames, "system_shell"]
+    });
+    await assertDirectory(policy.workspaceDir, "pi.workspaceDir");
+    const { sessionManager, isNewSession } = this.createSessionManager(sessionKey, policy.workspaceDir);
     const hasExistingSession = sessionManager.buildSessionContext().messages.length > 0;
     this.logger?.log("agent", `${hasExistingSession ? "resuming" : "creating"} session for chat ${sessionKey} with model ${effectiveModelId}`);
-    const customTools = this.createTools(telegram, chatId);
+    const customTools = [
+      ...this.createTools(telegram, chatId, policy),
+      createSystemShellTool({ workspaceDir: policy.workspaceDir, shell: policy.shell })
+    ];
     const { session } = await createAgentSession({
-      cwd: arisaInstallDir,
+      cwd: policy.workspaceDir,
       agentDir: arisaHomeDir,
       authStorage,
       modelRegistry,
       model,
+      tools: policy.tools,
+      excludeTools: policy.excludeTools,
       customTools,
       sessionManager
     });
 
     if (!hasExistingSession) {
       this.logger?.log("agent", `created new session for chat ${sessionKey}`);
-      this.logger?.log("agent", `runtime context for chat ${sessionKey}:\n${buildAgentRuntimeContext()}`);
+      this.logger?.log("agent", `runtime context for chat ${sessionKey}:\n${buildAgentRuntimeContext({
+        workspaceDir: policy.workspaceDir,
+        coreTools: policy.coreTools
+      })}`);
     }
 
     const ctx = { session, modelId: effectiveModelId };
@@ -226,20 +259,44 @@ export class AgentManager {
     return result;
   }
 
-  createTools(telegram, chatId) {
+  createTools(telegram, chatId, policy = buildPiToolPolicy({ config: this.config, customToolNames: arisaToolNames })) {
     const chatArtifactStore = this.artifactStore.forChat(chatId);
 
     return [
       defineTool({
         name: "list_tools",
         label: "List tools",
-        description: "List registered CLI tools and their capabilities.",
+        description: "List Arisa core, native shell, and modular CLI tools with their capabilities.",
         parameters: Type.Object({}),
         execute: async () => {
           await this.toolRegistry.load();
+          const coreTools = getCoreCodingTools({
+            tools: policy.tools,
+            excludeTools: policy.excludeTools
+          });
+          const nativeTools = [{
+            name: "system_shell",
+            source: "arisa-native",
+            description: "Run native system shell commands in the active Arisa workspace.",
+            workspaceDir: policy.workspaceDir,
+            shell: policy.shell.shellPath || (process.platform === "win32" ? "powershell" : "sh"),
+            enabled: !(policy.excludeTools || []).includes("system_shell")
+          }];
+          const cliTools = this.toolRegistry.list().map((tool) => ({
+            ...tool,
+            source: "arisa-modular",
+            invocation: "run_tool"
+          }));
+          const result = {
+            workspaceDir: policy.workspaceDir,
+            coreTools,
+            nativeTools,
+            cliTools,
+            tools: [...coreTools.filter((tool) => tool.enabled), ...nativeTools.filter((tool) => tool.enabled), ...cliTools]
+          };
           return {
-            content: [{ type: "text", text: JSON.stringify(this.toolRegistry.list(), null, 2) }],
-            details: { tools: this.toolRegistry.list() }
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            details: result
           };
         }
       }),

package/src/core/agent/core-tools.js

@@ -0,0 +1,139 @@
+import os from "node:os";
+import path from "node:path";
+import { arisaHomeDir } from "../../runtime/paths.js";
+
+const defaultShellTimeoutMs = 60_000;
+
+export const coreCodingToolCatalog = [
+  {
+    name: "read",
+    source: "pi-builtin",
+    description: "Read files and supported images from the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "bash",
+    source: "pi-builtin",
+    description: "Run bash-compatible commands from the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "edit",
+    source: "pi-builtin",
+    description: "Patch existing files in the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "write",
+    source: "pi-builtin",
+    description: "Create or overwrite files in the active workspace.",
+    defaultEnabled: true
+  },
+  {
+    name: "grep",
+    source: "pi-builtin",
+    description: "Search file contents from the active workspace.",
+    defaultEnabled: false
+  },
+  {
+    name: "find",
+    source: "pi-builtin",
+    description: "Find files from the active workspace.",
+    defaultEnabled: false
+  },
+  {
+    name: "ls",
+    source: "pi-builtin",
+    description: "List directories from the active workspace.",
+    defaultEnabled: false
+  }
+];
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function expandHomeDir(value) {
+  if (typeof value !== "string") return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+export function normalizeToolList(value) {
+  if (Array.isArray(value)) {
+    const tools = value
+      .map((item) => String(item || "").trim())
+      .filter(Boolean);
+    return tools.length ? unique(tools) : undefined;
+  }
+
+  if (typeof value === "string") {
+    const tools = value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+    return tools.length ? unique(tools) : undefined;
+  }
+
+  return undefined;
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return fallback;
+  return Math.floor(number);
+}
+
+export function resolveWorkspaceDir(value, defaultWorkspaceDir = arisaHomeDir) {
+  const raw = typeof value === "string" && value.trim()
+    ? value.trim()
+    : defaultWorkspaceDir;
+  return path.resolve(expandHomeDir(raw));
+}
+
+function buildAllowedTools({ configuredTools, customToolNames }) {
+  if (!configuredTools) return undefined;
+  return unique([...configuredTools, ...customToolNames]);
+}
+
+export function getCoreCodingTools({ tools, excludeTools } = {}) {
+  const allowed = tools ? new Set(tools) : null;
+  const excluded = new Set(excludeTools || []);
+
+  return coreCodingToolCatalog.map((tool) => {
+    const enabled = allowed
+      ? allowed.has(tool.name)
+      : tool.defaultEnabled;
+    return {
+      ...tool,
+      enabled: enabled && !excluded.has(tool.name)
+    };
+  });
+}
+
+export function buildPiToolPolicy({
+  config,
+  customToolNames = [],
+  defaultWorkspaceDir = arisaHomeDir
+} = {}) {
+  const configuredTools = normalizeToolList(config?.pi?.tools);
+  const excludeTools = normalizeToolList(config?.pi?.excludeTools);
+  const tools = buildAllowedTools({ configuredTools, customToolNames });
+  const workspaceDir = resolveWorkspaceDir(config?.pi?.workspaceDir, defaultWorkspaceDir);
+
+  return {
+    workspaceDir,
+    tools,
+    excludeTools,
+    coreTools: getCoreCodingTools({ tools, excludeTools }),
+    shell: {
+      shellPath: typeof config?.pi?.shellPath === "string" && config.pi.shellPath.trim()
+        ? config.pi.shellPath.trim()
+        : "",
+      timeoutMs: normalizePositiveInteger(config?.pi?.shellTimeoutMs, defaultShellTimeoutMs)
+    }
+  };
+}

package/src/core/agent/runtime-context.js

@@ -1,15 +1,26 @@
 import { fileURLToPath } from "node:url";
-import { arisaHomeDir, chatsDir, stateDir, toolStateDir, toolsDir } from "../../runtime/paths.js";
+import { arisaHomeDir, arisaPackageDir, chatsDir, stateDir, toolStateDir, toolsDir } from "../../runtime/paths.js";
 
 export const arisaInstallDir = fileURLToPath(new URL("../../..", import.meta.url));
 
-export function buildAgentRuntimeContext() {
+function formatCoreTools(coreTools = []) {
+  const enabled = coreTools
+    .filter((tool) => tool.enabled)
+    .map((tool) => tool.name);
+  return enabled.length ? enabled.join(", ") : "(none)";
+}
+
+export function buildAgentRuntimeContext({ workspaceDir = arisaHomeDir, coreTools = [] } = {}) {
   return [
+    `workspaceDir: ${workspaceDir}`,
     `arisaHomeDir: ${arisaHomeDir}`,
+    `arisaPackageDir: ${arisaPackageDir}`,
     `arisaInstallDir: ${arisaInstallDir}`,
     `userToolsDir: ${toolsDir}`,
     `toolStateDir: ${toolStateDir}`,
     `chatsDir: ${chatsDir}`,
-    `stateDir: ${stateDir}`
+    `stateDir: ${stateDir}`,
+    `enabledCoreTools: ${formatCoreTools(coreTools)}`,
+    "Guidance: create or edit user tools under userToolsDir. Treat arisaPackageDir/arisaInstallDir as Arisa core and modify it only when the user explicitly asks for core changes."
   ].join("\n");
 }

package/src/core/agent/system-shell-tool.js

@@ -0,0 +1,207 @@
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants, existsSync } from "node:fs";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const maxOutputBytes = 50 * 1024;
+const defaultTimeoutMs = 60_000;
+
+function isPowerShell(shellPath) {
+  const name = path.basename(shellPath).toLowerCase();
+  return name === "powershell.exe" || name === "powershell" || name === "pwsh.exe" || name === "pwsh";
+}
+
+function isCmd(shellPath) {
+  const name = path.basename(shellPath).toLowerCase();
+  return name === "cmd.exe" || name === "cmd";
+}
+
+function resolveNativeShell(shellPath = "") {
+  if (shellPath) {
+    if (isPowerShell(shellPath)) {
+      return {
+        shell: shellPath,
+        label: "powershell",
+        argsFor: (command) => ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command]
+      };
+    }
+    if (isCmd(shellPath)) {
+      return {
+        shell: shellPath,
+        label: "cmd",
+        argsFor: (command) => ["/d", "/s", "/c", command]
+      };
+    }
+    return {
+      shell: shellPath,
+      label: "sh",
+      argsFor: (command) => ["-lc", command]
+    };
+  }
+
+  if (process.platform === "win32") {
+    return {
+      shell: "powershell.exe",
+      label: "powershell",
+      argsFor: (command) => ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command]
+    };
+  }
+
+  return {
+    shell: existsSync("/bin/bash") ? "/bin/bash" : "/bin/sh",
+    label: "sh",
+    argsFor: (command) => ["-lc", command]
+  };
+}
+
+function appendLimited(current, chunk, state) {
+  state.totalBytes += chunk.length;
+
+  const remaining = maxOutputBytes - state.storedBytes;
+  if (remaining <= 0) {
+    state.truncated = true;
+    return current;
+  }
+
+  const accepted = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
+  state.storedBytes += accepted.length;
+  if (accepted.length < chunk.length) {
+    state.truncated = true;
+  }
+  return current + accepted.toString("utf8");
+}
+
+function killProcessTree(child) {
+  if (!child.pid) return;
+  if (process.platform === "win32") {
+    spawn("taskkill", ["/F", "/T", "/PID", String(child.pid)], {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    return;
+  }
+
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // Process already exited.
+    }
+  }
+}
+
+function formatOutput({ stdout, stderr, exitCode, timedOut, truncated }) {
+  const sections = [];
+  if (stdout.trim()) sections.push(`stdout:\n${stdout.trimEnd()}`);
+  if (stderr.trim()) sections.push(`stderr:\n${stderr.trimEnd()}`);
+  if (!sections.length) sections.push(exitCode === 0 && !timedOut ? "(Success, no output)" : "(No output)");
+  if (timedOut) sections.push("Command timed out.");
+  if (truncated) sections.push(`[Output truncated to ${maxOutputBytes} bytes.]`);
+  return sections.join("\n\n");
+}
+
+async function runShellCommand({ command, cwd, shellPath, timeoutMs }) {
+  await access(cwd, constants.F_OK);
+  const nativeShell = resolveNativeShell(shellPath);
+  const child = spawn(nativeShell.shell, nativeShell.argsFor(command), {
+    cwd,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true
+  });
+
+  let stdout = "";
+  let stderr = "";
+  const outputState = {
+    storedBytes: 0,
+    totalBytes: 0,
+    truncated: false
+  };
+
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killProcessTree(child);
+  }, timeoutMs);
+
+  return new Promise((resolve) => {
+    child.stdout.on("data", (chunk) => {
+      stdout = appendLimited(stdout, chunk, outputState);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = appendLimited(stderr, chunk, outputState);
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        error,
+        stdout,
+        stderr,
+        shell: nativeShell,
+        timedOut,
+        truncated: outputState.truncated,
+        totalBytes: outputState.totalBytes
+      });
+    });
+    child.on("close", (exitCode) => {
+      clearTimeout(timer);
+      resolve({
+        ok: !timedOut && exitCode === 0,
+        exitCode,
+        stdout,
+        stderr,
+        shell: nativeShell,
+        timedOut,
+        truncated: outputState.truncated,
+        totalBytes: outputState.totalBytes
+      });
+    });
+  });
+}
+
+export function createSystemShellTool({ workspaceDir, shell = {} }) {
+  return defineTool({
+    name: "system_shell",
+    label: "System Shell",
+    description: "Run a command in the active Arisa workspace using the native system shell: PowerShell on Windows, and sh/bash-compatible shell on Unix.",
+    parameters: Type.Object({
+      command: Type.String({ description: "Command to execute in the active workspace." }),
+      timeoutMs: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds for this command." }))
+    }),
+    execute: async (_id, params) => {
+      const timeoutMs = Number.isFinite(Number(params.timeoutMs)) && Number(params.timeoutMs) > 0
+        ? Math.floor(Number(params.timeoutMs))
+        : (shell.timeoutMs || defaultTimeoutMs);
+      const result = await runShellCommand({
+        command: params.command,
+        cwd: workspaceDir,
+        shellPath: shell.shellPath,
+        timeoutMs
+      });
+      const details = {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode ?? null,
+        shell: result.shell.label,
+        shellPath: result.shell.shell,
+        cwd: workspaceDir,
+        timedOut: result.timedOut,
+        truncated: result.truncated,
+        totalBytes: result.totalBytes
+      };
+      if (result.error) {
+        details.error = result.error.message;
+      }
+      return {
+        content: [{ type: "text", text: result.error?.message || formatOutput(result) }],
+        details,
+        isError: !result.ok
+      };
+    }
+  });
+}

package/src/index.js

@@ -69,8 +69,20 @@ function toNestedOverrides(nestedFlags) {
 
 function toServiceRunnerArgs(nestedFlags) {
   const args = [];
-  if (nestedFlags["pi.model"]) {
-    args.push("--pi.model", nestedFlags["pi.model"]);
+  const serviceSafePiFlags = [
+    "pi.provider",
+    "pi.model",
+    "pi.workspaceDir",
+    "pi.tools",
+    "pi.excludeTools",
+    "pi.shellPath",
+    "pi.shellTimeoutMs"
+  ];
+
+  for (const flag of serviceSafePiFlags) {
+    if (nestedFlags[flag]) {
+      args.push(`--${flag}`, nestedFlags[flag]);
+    }
   }
   return args;
 }
@@ -104,14 +116,34 @@ async function startRuntimeApp() {
   await app.start();
 }
 
+async function startBackgroundService() {
+  const result = await startService({ verbose, cliArgs: toServiceRunnerArgs(cli.nestedFlags) });
+  if (!result.ok) {
+    console.log(`Arisa is already running in background (pid ${result.pid}).`);
+    return result;
+  }
+  console.log(`Arisa started in background (pid ${result.pid}).`);
+  console.log(`Log file: ${result.logFile}`);
+  return result;
+}
+
 async function runForeground() {
   const hasRuntimePiOverrides = Boolean(
     runtimeOverrides?.pi?.model
     || runtimeOverrides?.pi?.provider
     || runtimeOverrides?.pi?.apiKey
+    || runtimeOverrides?.pi?.workspaceDir
+    || runtimeOverrides?.pi?.tools
+    || runtimeOverrides?.pi?.excludeTools
+    || runtimeOverrides?.pi?.shellPath
+    || runtimeOverrides?.pi?.shellTimeoutMs
   );
   logger.log("app", `starting${verbose ? " in verbose mode" : ""}`);
-  await bootstrapIfNeeded({ force: forceBootstrap });
+  const bootstrapResult = await bootstrapIfNeeded({ force: forceBootstrap });
+  if (bootstrapResult.startInBackground) {
+    await startBackgroundService();
+    return;
+  }
   try {
     await startRuntimeApp();
   } catch (error) {
@@ -126,7 +158,11 @@ async function runForeground() {
         throw error;
       }
       console.log("Reopening bootstrap so you can provide a Pi API key or switch to a provider you already authenticated with.\n");
-      await bootstrapIfNeeded({ force: true });
+      const retryBootstrapResult = await bootstrapIfNeeded({ force: true });
+      if (retryBootstrapResult.startInBackground) {
+        await startBackgroundService();
+        return;
+      }
       await startRuntimeApp();
       return;
     }
@@ -142,14 +178,12 @@ async function main() {
   }
 
   if (command === "start") {
-    await bootstrapIfNeeded({ force: forceBootstrap });
-    const result = await startService({ verbose, cliArgs: toServiceRunnerArgs(cli.nestedFlags) });
-    if (!result.ok) {
-      console.log(`Arisa is already running in background (pid ${result.pid}).`);
+    const bootstrapResult = await bootstrapIfNeeded({ force: forceBootstrap });
+    if (bootstrapResult.configCreated && bootstrapResult.viaTelegram && !bootstrapResult.startInBackground) {
+      console.log("Config saved. Arisa was not started in background.");
       return;
     }
-    console.log(`Arisa started in background (pid ${result.pid}).`);
-    console.log(`Log file: ${result.logFile}`);
+    await startBackgroundService();
     return;
   }
 

package/src/runtime/bootstrap.js

@@ -1,7 +1,9 @@
+import crypto from "node:crypto";
 import { readFile, writeFile } from "node:fs/promises";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { spawn } from "node:child_process";
+import { Bot } from "grammy";
 import { createPiOAuthLogin } from "../core/agent/pi-auth-login.js";
 import { createPiRuntime, hasProviderAuth, listPiProviders, listProviderModels, supportsProviderOAuth } from "../core/agent/pi-runtime.js";
 import { configFile, ensureArisaHome } from "./paths.js";
@@ -24,13 +26,13 @@ async function exists(file) {
   }
 }
 
-function buildConfig({ telegramApiKey, telegramMaxChatIds, provider, model, piApiKey }) {
+function buildConfig({ telegramApiKey, telegramMaxChatIds, authorizedChatIds = [], chatMeta = {}, provider, model, piApiKey }) {
   return {
     telegram: {
       token: telegramApiKey,
       maxChatIds: telegramMaxChatIds,
-      authorizedChatIds: [],
-      chatMeta: {}
+      authorizedChatIds,
+      chatMeta
     },
     pi: {
       provider,
@@ -73,6 +75,64 @@ function sortBootstrapModels(provider, models) {
   });
 }
 
+function createSetupToken() {
+  return crypto.randomBytes(18).toString("base64url");
+}
+
+function parsePositiveInteger(value, fallback = null) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return fallback;
+  return Math.floor(number);
+}
+
+function selectByIndex(items, value, fallbackIndex = 0) {
+  const index = parsePositiveInteger(value, fallbackIndex + 1) - 1;
+  return items[Math.max(0, Math.min(items.length - 1, index))];
+}
+
+function parseYesNo(value, fallback = true) {
+  const text = String(value ?? "").trim().toLowerCase();
+  if (!text) return fallback;
+  if (["y", "yes", "s", "si", "sí"].includes(text)) return true;
+  if (["n", "no"].includes(text)) return false;
+  return null;
+}
+
+function buildInlineKeyboard(action, items) {
+  return {
+    inline_keyboard: items.map((item, index) => ([{
+      text: item.text,
+      callback_data: `${action}:${index}`
+    }]))
+  };
+}
+
+function getIncomingChatMeta(ctx) {
+  return {
+    languageCode: ctx.from?.language_code || "",
+    username: ctx.from?.username || "",
+    firstName: ctx.from?.first_name || "",
+    lastName: ctx.from?.last_name || ""
+  };
+}
+
+function formatProviderOption(item) {
+  const authLabel = item.authConfigured ? "auth configured" : item.supportsOAuth ? "login or API key" : "API key";
+  return `${item.provider} (${item.modelCount} models, ${authLabel})`;
+}
+
+function formatModelOption(model) {
+  const capabilities = [model.reasoning ? "reasoning" : null, model.input?.includes("image") ? "image" : null].filter(Boolean).join(", ");
+  return capabilities ? `${model.id} [${capabilities}]` : model.id;
+}
+
+function selectPiLoginOption(options = []) {
+  return options.find((option) => /device/i.test(`${option.id} ${option.label}`))
+    || options.find((option) => /browser|oauth|web/i.test(`${option.id} ${option.label}`))
+    || options[0]
+    || null;
+}
+
 async function maybeOpenExternal(url) {
   if (!url) return;
   await new Promise((resolve) => {
@@ -92,6 +152,12 @@ async function maybeOpenExternal(url) {
 async function runInternalPiLogin(provider, { rl = null } = {}) {
   const login = createPiOAuthLogin({
     provider,
+    onSelect: async ({ message, options }) => {
+      const selected = selectPiLoginOption(options);
+      if (!selected) return undefined;
+      console.log(`${message}\nUsing: ${selected.label || selected.id}\n`);
+      return selected.id;
+    },
     onAuth: async ({ url, instructions, controller }) => {
       console.log(`${instructions || "Open this URL to continue authentication:"}\n${url}\n`);
       await maybeOpenExternal(url);
@@ -118,43 +184,24 @@ async function runInternalPiLogin(provider, { rl = null } = {}) {
   await login.promise;
 }
 
-export async function bootstrapIfNeeded({ force = false } = {}) {
-  await ensureArisaHome();
-  if (!force && await exists(configFile)) return;
-
-  const rl = readline.createInterface({ input, output });
-  const ask = async (label, fallback = "") => {
-    const suffix = fallback ? ` (${fallback})` : "";
-    const value = (await rl.question(`${label}${suffix}: `)).trim();
-    return value || fallback;
-  };
-
-  console.log(`\n${ARISA_BANNER}`);
-  console.log("-------- https://arisa.sh --------\n");
-  console.log("Get Telegram bot token from https://t.me/BotFather");
-  const telegramApiKey = await ask("Telegram bot token");
+async function collectCliBootstrapChoices({ telegramApiKey, rl, ask }) {
   const telegramMaxChatIds = Number(await ask("Maximum authorized chat IDs", "1"));
 
   const runtime = createPiRuntime();
   const providers = sortBootstrapProviders(listPiProviders(runtime));
   console.log("\nAvailable Pi providers:");
   providers.forEach((item, index) => {
-    const authLabel = item.authConfigured ? "auth: configured" : item.supportsOAuth ? "auth: login or API key" : "auth: API key";
-    console.log(`${index + 1}. ${item.provider} (${item.modelCount} models, ${authLabel})`);
+    console.log(`${index + 1}. ${formatProviderOption(item)}`);
   });
 
-  const selectedProviderIndex = Number(await ask("Select Pi provider by number", "1"));
-  const selectedProvider = providers[Math.max(0, Math.min(providers.length - 1, selectedProviderIndex - 1))];
+  const selectedProvider = selectByIndex(providers, await ask("Select Pi provider by number", "1"));
   const models = sortBootstrapModels(selectedProvider.provider, listProviderModels(selectedProvider.provider, runtime));
   console.log(`\nAvailable models for ${selectedProvider.provider}:`);
   models.forEach((model, index) => {
-    const capabilities = [model.reasoning ? "reasoning" : null, model.input?.includes("image") ? "image" : null].filter(Boolean).join(", ");
-    const suffix = capabilities ? ` [${capabilities}]` : "";
-    console.log(`${index + 1}. ${model.id}${suffix}`);
+    console.log(`${index + 1}. ${formatModelOption(model)}`);
   });
 
-  const selectedModelIndex = Number(await ask("Select Pi model by number", "1"));
-  const selectedModel = models[Math.max(0, Math.min(models.length - 1, selectedModelIndex - 1))];
+  const selectedModel = selectByIndex(models, await ask("Select Pi model by number", "1"));
   const selectedAuthReady = hasProviderAuth(selectedProvider.provider, runtime);
   const providerSupportsOAuth = supportsProviderOAuth(selectedProvider.provider, runtime);
   console.log(`Selected model: ${selectedModel.provider}/${selectedModel.id}`);
@@ -189,17 +236,346 @@ export async function bootstrapIfNeeded({ force = false } = {}) {
     console.log(`Pi auth for ${selectedProvider.provider} is still missing after login.`);
   }
 
-  const config = buildConfig({
-    telegramApiKey,
-    telegramMaxChatIds,
-    provider: selectedProvider.provider,
-    model: selectedModel.id,
-    piApiKey
+  return {
+    config: buildConfig({
+      telegramApiKey,
+      telegramMaxChatIds,
+      provider: selectedProvider.provider,
+      model: selectedModel.id,
+      piApiKey
+    }),
+    startInBackground: false,
+    viaTelegram: false
+  };
+}
+
+async function runTelegramBootstrap({ telegramApiKey, setupToken, botInfo }) {
+  const bot = new Bot(telegramApiKey);
+  const runtime = createPiRuntime();
+  const providers = sortBootstrapProviders(listPiProviders(runtime));
+  let setupChatId = null;
+  let chatMeta = {};
+  let state = "await-start";
+  let telegramMaxChatIds = 1;
+  let selectedProvider = null;
+  let selectedModel = null;
+  let piApiKey = "";
+  let activeLogin = null;
+  let completed = false;
+  let resolveResult;
+  let rejectResult;
+
+  const resultPromise = new Promise((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  const sendSetupMessage = async (text, extra = {}) => {
+    if (!setupChatId) return;
+    await bot.api.sendMessage(setupChatId, text, extra);
+  };
+
+  const isSetupChat = (ctx) => setupChatId && ctx.chat?.id === setupChatId;
+
+  const complete = (startInBackground) => {
+    if (completed) return;
+    completed = true;
+    resolveResult({
+      config: buildConfig({
+        telegramApiKey,
+        telegramMaxChatIds,
+        authorizedChatIds: [setupChatId],
+        chatMeta: { [setupChatId]: chatMeta },
+        provider: selectedProvider.provider,
+        model: selectedModel.id,
+        piApiKey
+      }),
+      startInBackground,
+      viaTelegram: true
+    });
+  };
+
+  const askProvider = async () => {
+    state = "provider";
+    await sendSetupMessage("Select the Pi provider Arisa should use:", {
+      reply_markup: buildInlineKeyboard("provider", providers.map((provider) => ({ text: formatProviderOption(provider) })))
+    });
+  };
+
+  const askModel = async () => {
+    state = "model";
+    const models = sortBootstrapModels(selectedProvider.provider, listProviderModels(selectedProvider.provider, createPiRuntime()));
+    await sendSetupMessage(`Select the model for ${selectedProvider.provider}:`, {
+      reply_markup: buildInlineKeyboard("model", models.map((model) => ({ text: formatModelOption(model) })))
+    });
+  };
+
+  const askBackground = async () => {
+    state = "background";
+    await sendSetupMessage("Bootstrap complete. Keep Arisa running in background now?", {
+      reply_markup: {
+        inline_keyboard: [
+          [{ text: "Yes, start in background", callback_data: "background:yes" }],
+          [{ text: "No, continue in foreground", callback_data: "background:no" }]
+        ]
+      }
+    });
+  };
+
+  const askApiKey = async () => {
+    state = "pi-api-key";
+    await sendSetupMessage(`Send the Pi API key for ${selectedProvider.provider}.`);
+  };
+
+  const askAuthMethod = async () => {
+    const providerRuntime = createPiRuntime();
+    const selectedAuthReady = hasProviderAuth(selectedProvider.provider, providerRuntime);
+    const providerSupportsOAuth = supportsProviderOAuth(selectedProvider.provider, providerRuntime);
+    const buttons = [];
+
+    if (selectedAuthReady) {
+      buttons.push([{ text: "Use existing Pi auth", callback_data: "auth:existing" }]);
+    }
+    if (providerSupportsOAuth) {
+      buttons.push([{ text: selectedAuthReady ? "Run Pi login again" : "Start Pi login", callback_data: "auth:login" }]);
+    }
+    buttons.push([{ text: "Enter API key", callback_data: "auth:key" }]);
+
+    state = "auth-method";
+    await sendSetupMessage([
+      `Selected model: ${selectedProvider.provider}/${selectedModel.id}`,
+      `Existing Pi auth for ${selectedProvider.provider}: ${selectedAuthReady ? "yes" : "no"}`,
+      "Choose how Arisa should authenticate Pi."
+    ].join("\n"), {
+      reply_markup: { inline_keyboard: buttons }
+    });
+  };
+
+  const finishPiLogin = async (login) => {
+    try {
+      await login.promise;
+      activeLogin = null;
+      if (hasProviderAuth(selectedProvider.provider, createPiRuntime())) {
+        await sendSetupMessage(`Detected Pi auth for ${selectedProvider.provider}.`);
+        await askBackground();
+        return;
+      }
+      await sendSetupMessage(`Pi auth for ${selectedProvider.provider} is still missing after login.`);
+      await askAuthMethod();
+    } catch (error) {
+      activeLogin = null;
+      await sendSetupMessage(`Pi login failed: ${error instanceof Error ? error.message : String(error)}`);
+      await askAuthMethod();
+    }
+  };
+
+  const startPiLogin = async () => {
+    if (hasProviderAuth(selectedProvider.provider, createPiRuntime())) {
+      await sendSetupMessage(`Existing Pi auth for ${selectedProvider.provider} detected.`);
+      await askBackground();
+      return;
+    }
+
+    state = "pi-login";
+    const login = createPiOAuthLogin({
+      provider: selectedProvider.provider,
+      onSelect: async ({ message, options }) => {
+        const selected = selectPiLoginOption(options);
+        if (!selected) return undefined;
+        await sendSetupMessage(`${message}\nUsing: ${selected.label || selected.id}`);
+        return selected.id;
+      },
+      onAuth: async ({ url, instructions }) => {
+        await sendSetupMessage([
+          instructions || "Open this URL to continue Pi authentication:",
+          url,
+          "After login, paste the full redirect URL back here."
+        ].join("\n"));
+      },
+      onDeviceCode: async ({ userCode, verificationUri, expiresInSeconds }) => {
+        const expiry = expiresInSeconds ? `\nExpires in ${Math.round(expiresInSeconds / 60)} minute(s).` : "";
+        await sendSetupMessage(`Open this URL: ${verificationUri}\nThen enter code: ${userCode}${expiry}`);
+      },
+      onPrompt: async ({ message, controller }) => {
+        await sendSetupMessage(`${message}\nReply here with the value.`);
+        return controller.waitForManualCode();
+      },
+      onProgress: (message) => {
+        if (message) console.log(`[bootstrap] Pi auth progress: ${message}`);
+      }
+    });
+
+    activeLogin = login;
+    finishPiLogin(login);
+  };
+
+  bot.catch((error) => {
+    console.error("Telegram setup bot error:", error);
   });
 
-  await writeFile(configFile, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-  rl.close();
-  console.log(`\nConfig saved to ${configFile}\n`);
+  bot.command("start", async (ctx) => {
+    if (String(ctx.match || "").trim() !== setupToken) {
+      await ctx.reply("Invalid setup link. Use the link shown in the Arisa bootstrap terminal.");
+      return;
+    }
+
+    if (setupChatId && ctx.chat.id !== setupChatId) {
+      await ctx.reply("This setup session is already connected to another chat.");
+      return;
+    }
+
+    setupChatId = ctx.chat.id;
+    chatMeta = getIncomingChatMeta(ctx);
+    await ctx.reply([
+      `Connected to @${botInfo.username}.`,
+      "This chat will be the only Telegram chat authorized during setup."
+    ].join("\n"));
+    await askProvider();
+  });
+
+  bot.on("callback_query:data", async (ctx) => {
+    await ctx.answerCallbackQuery().catch(() => {});
+    if (!isSetupChat(ctx)) return;
+
+    const data = String(ctx.callbackQuery.data || "");
+    const [action, rawValue] = data.split(":");
+
+    if (action === "provider" && state === "provider") {
+      selectedProvider = providers[Number(rawValue)];
+      if (!selectedProvider) return;
+      await askModel();
+      return;
+    }
+
+    if (action === "model" && state === "model") {
+      const models = sortBootstrapModels(selectedProvider.provider, listProviderModels(selectedProvider.provider, createPiRuntime()));
+      selectedModel = models[Number(rawValue)];
+      if (!selectedModel) return;
+      await askAuthMethod();
+      return;
+    }
+
+    if (action === "auth" && state === "auth-method") {
+      if (rawValue === "existing") {
+        if (hasProviderAuth(selectedProvider.provider, createPiRuntime())) {
+          await askBackground();
+        } else {
+          await sendSetupMessage(`No existing Pi auth found for ${selectedProvider.provider}.`);
+          await askAuthMethod();
+        }
+        return;
+      }
+      if (rawValue === "login") {
+        await startPiLogin();
+        return;
+      }
+      if (rawValue === "key") {
+        await askApiKey();
+        return;
+      }
+    }
+
+    if (action === "background" && state === "background") {
+      await sendSetupMessage(rawValue === "yes"
+        ? "Saving config. Arisa will start in background now."
+        : "Saving config. Arisa will continue in foreground.");
+      complete(rawValue === "yes");
+    }
+  });
+
+  bot.on("message:text", async (ctx) => {
+    if (!isSetupChat(ctx)) return;
+    const text = String(ctx.message.text || "").trim();
+    if (!text || text.startsWith("/")) return;
+
+    if (state === "pi-api-key") {
+      piApiKey = text;
+      await askBackground();
+      return;
+    }
+
+    if (state === "pi-login" && activeLogin?.manualInputRequested) {
+      if (activeLogin.submitManualCode(text)) {
+        await ctx.reply("Got it. Finishing Pi login now...");
+      }
+      return;
+    }
+
+    if (state === "background") {
+      const answer = parseYesNo(text, true);
+      if (answer === null) {
+        await ctx.reply("Please answer yes or no.");
+        return;
+      }
+      await ctx.reply(answer
+        ? "Saving config. Arisa will start in background now."
+        : "Saving config. Arisa will continue in foreground.");
+      complete(answer);
+    }
+  });
+
+  await bot.api.deleteWebhook({ drop_pending_updates: true });
+  console.log("Waiting for Telegram setup to complete...");
+  const polling = bot.start().then(() => {
+    if (!completed) throw new Error("Telegram setup bot stopped before bootstrap completed.");
+  });
+
+  try {
+    return await Promise.race([resultPromise, polling]);
+  } catch (error) {
+    rejectResult(error);
+    throw error;
+  } finally {
+    bot.stop();
+    await polling.catch(() => {});
+  }
+}
+
+export async function bootstrapIfNeeded({ force = false } = {}) {
+  await ensureArisaHome();
+  if (!force && await exists(configFile)) {
+    return { configCreated: false, viaTelegram: false, startInBackground: false };
+  }
+
+  const rl = readline.createInterface({ input, output });
+  const ask = async (label, fallback = "") => {
+    const suffix = fallback ? ` (${fallback})` : "";
+    const value = (await rl.question(`${label}${suffix}: `)).trim();
+    return value || fallback;
+  };
+
+  console.log(`\n${ARISA_BANNER}`);
+  console.log("-------- https://arisa.sh --------\n");
+  console.log("Get Telegram bot token from https://t.me/BotFather");
+  const telegramApiKey = await ask("Telegram bot token");
+
+  try {
+    const setupProbeBot = new Bot(telegramApiKey);
+    const botInfo = await setupProbeBot.api.getMe();
+    const answer = parseYesNo(await ask("Continue bootstrap from Telegram?", "Y"), true);
+    const continueFromTelegram = answer === null ? true : answer;
+
+    let result;
+    if (continueFromTelegram) {
+      const setupToken = createSetupToken();
+      const setupLink = `https://t.me/${botInfo.username}?start=${setupToken}`;
+      console.log(`\nOpen this link to continue setup in Telegram:\n${setupLink}\n`);
+      await maybeOpenExternal(setupLink);
+      result = await runTelegramBootstrap({ telegramApiKey, setupToken, botInfo });
+    } else {
+      result = await collectCliBootstrapChoices({ telegramApiKey, rl, ask });
+    }
+
+    await writeFile(configFile, `${JSON.stringify(result.config, null, 2)}\n`, "utf8");
+    console.log(`\nConfig saved to ${configFile}\n`);
+    return {
+      configCreated: true,
+      viaTelegram: result.viaTelegram,
+      startInBackground: result.startInBackground
+    };
+  } finally {
+    rl.close();
+  }
 }
 
 export { configFile };

package/src/runtime/create-app.js

@@ -14,6 +14,31 @@ function normalizeString(value) {
   return text ? text : "";
 }
 
+function normalizeStringList(value) {
+  if (Array.isArray(value)) {
+    const items = value
+      .map((item) => normalizeString(item))
+      .filter(Boolean);
+    return items.length ? [...new Set(items)] : undefined;
+  }
+
+  if (typeof value === "string") {
+    const items = value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+    return items.length ? [...new Set(items)] : undefined;
+  }
+
+  return undefined;
+}
+
+function normalizePositiveInteger(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return undefined;
+  return Math.floor(number);
+}
+
 function splitModelOverride(modelOverride) {
   const separatorIndex = modelOverride.indexOf("/");
   if (separatorIndex <= 0 || separatorIndex === modelOverride.length - 1) {
@@ -25,23 +50,41 @@ function splitModelOverride(modelOverride) {
   };
 }
 
-function applyRuntimeOverrides(config, runtimeOverrides) {
+export function applyRuntimeOverrides(config, runtimeOverrides) {
+  const piRuntimeOverrides = runtimeOverrides?.pi || {};
+  const pi = {};
   const providerOverride = normalizeString(runtimeOverrides?.pi?.provider);
   const modelOverride = normalizeString(runtimeOverrides?.pi?.model);
-  if (!providerOverride && !modelOverride) return config;
 
-  const splitOverride = modelOverride ? splitModelOverride(modelOverride) : null;
-  const provider = providerOverride || splitOverride?.provider || config.pi.provider;
-  const model = splitOverride && (!providerOverride || providerOverride === splitOverride.provider)
-    ? splitOverride.model
-    : (modelOverride || config.pi.model);
+  if (providerOverride || modelOverride) {
+    const splitOverride = modelOverride ? splitModelOverride(modelOverride) : null;
+    pi.provider = providerOverride || splitOverride?.provider || config.pi.provider;
+    pi.model = splitOverride && (!providerOverride || providerOverride === splitOverride.provider)
+      ? splitOverride.model
+      : (modelOverride || config.pi.model);
+  }
+
+  for (const key of ["apiKey", "workspaceDir", "shellPath"]) {
+    const value = normalizeString(piRuntimeOverrides[key]);
+    if (value) pi[key] = value;
+  }
+
+  const tools = normalizeStringList(piRuntimeOverrides.tools);
+  if (tools) pi.tools = tools;
+
+  const excludeTools = normalizeStringList(piRuntimeOverrides.excludeTools);
+  if (excludeTools) pi.excludeTools = excludeTools;
+
+  const shellTimeoutMs = normalizePositiveInteger(piRuntimeOverrides.shellTimeoutMs);
+  if (shellTimeoutMs) pi.shellTimeoutMs = shellTimeoutMs;
+
+  if (!Object.keys(pi).length) return config;
 
   return {
     ...config,
     pi: {
       ...config.pi,
-      provider,
-      model
+      ...pi
     }
   };
 }

package/src/transport/telegram/bot.js

@@ -74,7 +74,8 @@ function buildPrompt({ ctx, artifact, transcript, toolResult }) {
     parts.push(`Important: pre-reasoning media normalization could not be completed, so you do not have a transcript for this audio/video message.`);
   }
 
-  parts.push(`If you need a CLI tool, use list_tools/tool_help/run_tool.`);
+  parts.push(`Use read/write/edit for file work in the active workspace, bash for bash-compatible commands, and system_shell for native system commands such as PowerShell on Windows.`);
+  parts.push(`If you need an Arisa modular CLI tool, use list_tools/tool_help/run_tool.`);
   parts.push(`If a tool config is missing, ask the user naturally and then use set_tool_config.`);
   parts.push(`If the user wants a generated media reply, use send_media_reply.`);
   return parts.join("\n");
@@ -130,7 +131,7 @@ async function buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, logger
   }
 
   parts.push("Treat this as a new request for the chat and fulfill it now.");
-  parts.push("If needed, use tools.");
+  parts.push("If needed, use read/write/edit, bash, system_shell, or Arisa modular tools via run_tool.");
   return parts.filter(Boolean).join("\n");
 }
 
@@ -142,7 +143,7 @@ function buildAsyncEventPrompt(task) {
     task.payload.prompt ? `event: ${task.payload.prompt}` : null,
     "A polling checker detected this external event. Evaluate it and decide the next action.",
     "If it warrants no action, you may stay silent.",
-    "If needed, use tools."
+    "If needed, use read/write/edit, bash, system_shell, or Arisa modular tools via run_tool."
   ].filter(Boolean).join("\n");
 }
 

package/test/agent-tool-policy.test.js

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { mkdtemp, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { buildPiToolPolicy } from "../src/core/agent/core-tools.js";
+import { createSystemShellTool } from "../src/core/agent/system-shell-tool.js";
+import { applyRuntimeOverrides } from "../src/runtime/create-app.js";
+import { arisaHomeDir } from "../src/runtime/paths.js";
+
+test("builds default Pi tool policy for the Arisa home workspace", () => {
+  const policy = buildPiToolPolicy({ config: { pi: {} } });
+
+  assert.equal(policy.workspaceDir, path.resolve(arisaHomeDir));
+  assert.equal(policy.tools, undefined);
+  assert.equal(policy.excludeTools, undefined);
+  assert.deepEqual(
+    policy.coreTools.filter((tool) => tool.enabled).map((tool) => tool.name),
+    ["read", "bash", "edit", "write"]
+  );
+});
+
+test("keeps Arisa custom tools available when pi.tools is configured", () => {
+  const policy = buildPiToolPolicy({
+    config: {
+      pi: {
+        tools: "read,bash",
+        excludeTools: "bash",
+        workspaceDir: "~/arisa-workspace",
+        shellTimeoutMs: "120000"
+      }
+    },
+    customToolNames: ["run_tool", "system_shell"]
+  });
+
+  assert.deepEqual(policy.tools, ["read", "bash", "run_tool", "system_shell"]);
+  assert.deepEqual(policy.excludeTools, ["bash"]);
+  assert.equal(policy.shell.timeoutMs, 120000);
+  assert.equal(policy.workspaceDir, path.join(os.homedir(), "arisa-workspace"));
+  assert.deepEqual(
+    policy.coreTools.filter((tool) => tool.enabled).map((tool) => tool.name),
+    ["read"]
+  );
+});
+
+test("applies runtime overrides without dropping persisted Pi config", () => {
+  const config = {
+    telegram: { token: "token" },
+    pi: {
+      provider: "openai-codex",
+      model: "gpt-5.5",
+      apiKey: "persisted"
+    }
+  };
+
+  const next = applyRuntimeOverrides(config, {
+    pi: {
+      model: "anthropic/claude-opus-4-5",
+      workspaceDir: "/tmp/arisa",
+      tools: "read,bash",
+      excludeTools: "write",
+      shellTimeoutMs: "90000"
+    }
+  });
+
+  assert.equal(next.pi.provider, "anthropic");
+  assert.equal(next.pi.model, "claude-opus-4-5");
+  assert.equal(next.pi.apiKey, "persisted");
+  assert.equal(next.pi.workspaceDir, "/tmp/arisa");
+  assert.deepEqual(next.pi.tools, ["read", "bash"]);
+  assert.deepEqual(next.pi.excludeTools, ["write"]);
+  assert.equal(next.pi.shellTimeoutMs, 90000);
+});
+
+test("system_shell runs commands from the configured workspace", async () => {
+  const workspaceDir = await mkdtemp(path.join(os.tmpdir(), "arisa-shell-"));
+  const tool = createSystemShellTool({
+    workspaceDir,
+    shell: { timeoutMs: 10_000 }
+  });
+
+  const result = await tool.execute("call-1", {
+    command: "node -e \"process.stdout.write(process.cwd())\""
+  });
+
+  const realWorkspaceDir = await realpath(workspaceDir);
+  assert.equal(result.isError, false);
+  assert.equal(result.details.cwd, workspaceDir);
+  assert.equal(result.details.exitCode, 0);
+  assert.equal(result.details.stdout, realWorkspaceDir);
+});