skimpyclaw 0.3.6 → 0.3.9

package/dist/providers/context-manager.js

@@ -0,0 +1,100 @@
+// Context manager for agentic tool loops.
+// When accumulated messages exceed the token threshold, compacts old tool results
+// to keep context size bounded without breaking message structure.
+//
+// Key constraint: tool_use/tool_result pairs (Anthropic) and
+// function_call/function_call_output pairs (Codex) must stay structurally intact.
+// We truncate the CONTENT of old results — never remove blocks entirely.
+const DEFAULT_MAX_CONTEXT_TOKENS = 200_000;
+const KEEP_TAIL = 8; // always keep last N messages/items untouched
+const RESULT_MAX_CHARS = 500; // compact old results to this length
+/** Rough token estimate: 1 token ≈ 4 chars of JSON. */
+export function estimateTokens(data) {
+    return Math.ceil(JSON.stringify(data).length / 4);
+}
+/**
+ * Compact Anthropic-format apiMessages when over threshold.
+ * Truncates content of old tool_result blocks; leaves last KEEP_TAIL messages intact.
+ * Does NOT mutate the input array — returns a new array.
+ */
+export function compactAnthropicMessages(messages, config, iteration = 0) {
+    if (config?.enabled === false)
+        return messages;
+    const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+    const estimated = estimateTokens(messages);
+    if (estimated <= maxTokens)
+        return messages;
+    console.log(`[context-manager] Compacting at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
+    const tail = messages.slice(-KEEP_TAIL);
+    const head = messages.slice(0, -KEEP_TAIL);
+    const compacted = head.map(msg => {
+        if (!Array.isArray(msg.content))
+            return msg;
+        let changed = false;
+        const newContent = msg.content.map((block) => {
+            if (block.type !== 'tool_result')
+                return block;
+            const raw = typeof block.content === 'string'
+                ? block.content
+                : JSON.stringify(block.content);
+            if (raw.length <= RESULT_MAX_CHARS)
+                return block;
+            changed = true;
+            return { ...block, content: raw.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
+        });
+        return changed ? { ...msg, content: newContent } : msg;
+    });
+    return [...compacted, ...tail];
+}
+/**
+ * Compact OpenAI-format apiMessages when over threshold.
+ * Truncates content of old `role: 'tool'` messages; leaves last KEEP_TAIL messages intact.
+ * Does NOT mutate the input array — returns a new array.
+ */
+export function compactOpenAIMessages(messages, config, iteration = 0) {
+    if (config?.enabled === false)
+        return messages;
+    const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+    const estimated = estimateTokens(messages);
+    if (estimated <= maxTokens)
+        return messages;
+    console.log(`[context-manager] Compacting OpenAI messages at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
+    const tail = messages.slice(-KEEP_TAIL);
+    const head = messages.slice(0, -KEEP_TAIL);
+    const compacted = head.map(msg => {
+        if (msg.role !== 'tool')
+            return msg;
+        if (typeof msg.content !== 'string')
+            return msg;
+        if (msg.content.length <= RESULT_MAX_CHARS)
+            return msg;
+        return { ...msg, content: msg.content.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
+    });
+    return [...compacted, ...tail];
+}
+/**
+ * Compact Codex-format input items when over threshold.
+ * Truncates output of old function_call_output items; leaves last KEEP_TAIL items intact.
+ * Does NOT mutate the input array — returns a new array.
+ */
+export function compactCodexMessages(input, config, iteration = 0) {
+    if (config?.enabled === false)
+        return input;
+    const maxTokens = config?.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+    const estimated = estimateTokens(input);
+    if (estimated <= maxTokens)
+        return input;
+    console.log(`[context-manager] Compacting Codex input at iteration ${iteration} (~${Math.round(estimated / 1000)}k tokens > ${Math.round(maxTokens / 1000)}k threshold)`);
+    const tail = input.slice(-KEEP_TAIL);
+    const head = input.slice(0, -KEEP_TAIL);
+    const compacted = head.map(item => {
+        if (item.type !== 'function_call_output')
+            return item;
+        if (typeof item.output !== 'string')
+            return item;
+        if (item.output.length <= RESULT_MAX_CHARS)
+            return item;
+        return { ...item, output: item.output.slice(0, RESULT_MAX_CHARS) + ' [truncated]' };
+    });
+    return [...compacted, ...tail];
+}

package/dist/providers/openai.js

@@ -1,9 +1,11 @@
 // OpenAI-Compatible Provider (OpenAI, OpenRouter, Groq, etc.)
 import { startObservation } from '@langfuse/tracing';
 import { stripProvider, toOpenAITools, truncateToolResult } from './utils.js';
+import { compactOpenAIMessages } from './context-manager.js';
 import { toOpenAIContent } from './content.js';
 import { toUsageDetails, toCostDetails } from './observability.js';
 import { getToolDefinitions, executeTool } from '../tools.js';
+import { toErrorMessage } from '../utils.js';
 import { ToolCallGuard } from './tool-guard.js';
 import { addEvent } from '../audit.js';
 import { buildUsageRecord, recordUsage } from '../usage.js';
@@ -106,7 +108,7 @@ export async function chatOpenAI(params, provider) {
         return content;
     }
     catch (err) {
-        const errorMessage = err instanceof Error ? err.message : String(err);
+        const errorMessage = toErrorMessage(err);
         genObs?.update({ level: 'ERROR', statusMessage: errorMessage, output: { error: errorMessage } });
         genObs?.end();
         throw err;
@@ -123,7 +125,7 @@ export async function chatWithToolsOpenAI(params, provider) {
     // Resolve tools once at start
     const includeSpawn = !!(toolContext?.fullConfig && (toolContext?.chatId || toolContext?.isCronJob));
     const toolDefs = await getToolDefinitions(toolConfig, {
-        includeSpawnSubagent: includeSpawn,
+        includeAgentTools: includeSpawn,
         includeMcp: false,
         projects: toolContext?.fullConfig?.projects
     });
@@ -150,6 +152,8 @@ export async function chatWithToolsOpenAI(params, provider) {
                 toolCalls: toolLog,
             };
         }
+        // Compact old tool results if context is growing large
+        const messagesForApi = compactOpenAIMessages(apiMessages, toolConfig.contextManagement, i + 1);
         console.log(`[agent:openai-tools] Iteration ${i + 1}/${maxIterations} (provider: ${provider}, model: ${modelId})`);
         const genObs = await startGenerationObservation(`${provider}:${modelId}`, {
             input: { messages: apiMessages },
@@ -164,7 +168,7 @@ export async function chatWithToolsOpenAI(params, provider) {
         try {
             completion = await client.chat.completions.create({
                 model: modelId,
-                messages: apiMessages,
+                messages: messagesForApi,
                 tools: openaiTools,
                 max_tokens: options.maxTokens || 4096,
                 temperature: options.temperature,
@@ -187,7 +191,7 @@ export async function chatWithToolsOpenAI(params, provider) {
             guard.recordTokens(completion.usage?.prompt_tokens ?? 0, completion.usage?.completion_tokens ?? 0);
         }
         catch (err) {
-            const errorMessage = err instanceof Error ? err.message : String(err);
+            const errorMessage = toErrorMessage(err);
             genObs?.update({ level: 'ERROR', statusMessage: errorMessage, output: { error: errorMessage } });
             genObs?.end();
             throw err;
@@ -315,7 +319,7 @@ export async function chatWithToolsOpenAI(params, provider) {
                 }
             }
             catch (err) {
-                const errorMessage = err instanceof Error ? err.message : String(err);
+                const errorMessage = toErrorMessage(err);
                 toolObs?.update({ level: 'ERROR', statusMessage: errorMessage, output: { error: errorMessage } });
                 toolObs?.end();
                 if (toolContext?.auditTraceId) {

package/dist/providers/types.d.ts

@@ -1,5 +1,6 @@
 import type { Config, ChatMessage, ChatOptions, ToolConfig } from '../types.js';
 import type { ExecuteToolContext } from '../tools/execute-context.js';
+export type ContextManagementConfig = NonNullable<ToolConfig['contextManagement']>;
 export interface ToolChatResult {
     response: string;
     toolCalls: string[];

package/dist/security.js

@@ -77,10 +77,19 @@ export function isRateLimited(userId) {
     const timestamps = rateLimiter.get(key) || [];
     const recent = timestamps.filter(t => now - t < WINDOW_MS);
     if (recent.length >= RATE_LIMIT) {
+        rateLimiter.set(key, recent);
         return true;
     }
     recent.push(now);
     rateLimiter.set(key, recent);
+    // Prune stale entries periodically (every 100th call)
+    if (rateLimiter.size > 50) {
+        for (const [k, ts] of rateLimiter) {
+            if (ts.every(t => now - t >= WINDOW_MS)) {
+                rateLimiter.delete(k);
+            }
+        }
+    }
     return false;
 }
 export function clearRateLimiter() {

package/dist/setup.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
 import { randomUUID } from 'crypto';
 import { runDoctor as runDoctorChecks } from './doctor/runner.js';
+import { toErrorMessage } from './utils.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // ANSI color helpers (no chalk dependency)
@@ -224,6 +225,28 @@ async function askProviders(rl, existingProviders) {
 }
 function buildStarterCronJobs(starters) {
     const jobs = [];
+    // Memory trim is always included — runs 2x/day on a cheap model
+    jobs.push({
+        id: 'memory-trim',
+        name: 'Memory Trim',
+        model: 'claude-haiku',
+        schedule: {
+            kind: 'cron',
+            expr: '0 0,12 * * *',
+            tz: starters.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
+        },
+        payload: {
+            kind: 'agentTurn',
+            message: '~/.skimpyclaw/prompts/memory-trim.md',
+            tools: {
+                enabled: true,
+                allowedPaths: [`${homedir()}/.skimpyclaw`],
+                maxIterations: 30,
+                bashTimeout: 10000,
+                toolProfile: 'minimal',
+            },
+        },
+    });
     if (starters.cronTechNews) {
         jobs.push({
             id: 'tech-digest',
@@ -532,7 +555,7 @@ export function buildSetupConfig(input) {
             jobs: starterCronJobs,
         },
         heartbeat: {
-            intervalMs: 1800000,
+            intervalMs: 3600000,
             prompt: 'Read ~/.skimpyclaw/agents/main/HEARTBEAT.md. Follow it strictly. If nothing needs attention, reply HEARTBEAT_OK.',
             tools: {
                 enabled: true,
@@ -640,6 +663,62 @@ When asked to search the web:
 5. Close the browser when done.
 
 Do NOT fabricate results. If the search returns nothing useful, say so.
+`,
+    'duckduckgo-html-search': `---
+name: duckduckgo-html-search
+description: Search the web via DuckDuckGo HTML results using the Browser tool
+emoji: 🦆
+tags: [search, web, browser]
+priority: 45
+enabled: true
+---
+
+# DuckDuckGo HTML Search Skill
+
+Use this skill when the user asks for web search, source gathering, or lightweight browsing.
+
+## Priority rule
+DuckDuckGo HTML via Browser is the default search path.
+- Prefer DuckDuckGo first, even if \\\`$web_search\\\` is available.
+- Use \\\`$web_search\\\` only when the user explicitly asks for it, DuckDuckGo is blocked, or Browser is unavailable.
+
+## Default workflow
+1. Build query URL: \\\`https://duckduckgo.com/html/?q=<urlencoded query>\\\`
+2. Open the URL with Browser.
+3. Wait for result anchors (\\\`a.result__a\\\`) or fallback body text.
+4. Extract results using one Browser \\\`evaluate\\\` call when possible.
+5. Return only actually extracted items (never pad count).
+
+## Extraction requirements
+For each result, capture when available:
+- title
+- url
+- snippet
+
+If a field is missing, set it to \\\`UNAVAILABLE\\\`.
+
+## Integrity rules
+- Never fabricate results.
+- If the page blocks, fails, or no results render, return \\\`UNAVAILABLE\\\` and state why.
+- Never mix real and invented entries.
+- Include source URLs in output.
+
+## Browser strategy
+- Prefer one-page extraction via \\\`evaluate\\\`:
+  - Collect \\\`a.result__a\\\` for title + href
+  - Collect nearby snippet nodes (\\\`.result__snippet\\\`) when present
+- Use minimal actions: open → waitFor → evaluate → optional screenshot.
+- If selectors change, fallback to visible text extraction and clearly mark reduced confidence.
+
+## Output format (concise)
+- Query used
+- Result count actually extracted
+- Bulleted results with title + URL + snippet
+- Notes section for failures/limits
+
+## Safe defaults
+- Default top results target: 5 (or user-specified)
+- If user asks for deep research, gather multiple queries but keep each query's extraction explicit and separated.
 `,
 };
 function ensureCoreTemplates(agentDir) {
@@ -657,7 +736,7 @@ function ensureStarterSkills(starters) {
     const created = [];
     const skillsDir = join(CONFIG_DIR, 'skills');
     mkdirSync(skillsDir, { recursive: true });
-    const requested = [];
+    const requested = ['duckduckgo-html-search']; // always installed
     if (starters.skillDailyNotes)
         requested.push('daily-notes');
     if (starters.skillWeather)
@@ -690,7 +769,7 @@ async function validateTelegramToken(token) {
         return { ok: true, detail: body.result?.username ? `@${body.result.username}` : 'valid token' };
     }
     catch (err) {
-        return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+        return { ok: false, detail: toErrorMessage(err) };
     }
 }
 async function validateProviderAuth(providers, secrets) {
@@ -709,7 +788,7 @@ async function validateProviderAuth(providers, secrets) {
             checks.push({ name: 'Anthropic API', ok: res.ok, detail: res.ok ? 'auth ok' : `HTTP ${res.status}` });
         }
         catch (err) {
-            checks.push({ name: 'Anthropic API', ok: false, detail: err instanceof Error ? err.message : String(err) });
+            checks.push({ name: 'Anthropic API', ok: false, detail: toErrorMessage(err) });
         }
     }
     if (providers.has('openai-api') && secrets.openaiKey) {
@@ -720,7 +799,7 @@ async function validateProviderAuth(providers, secrets) {
             checks.push({ name: 'OpenAI API', ok: res.ok, detail: res.ok ? 'auth ok' : `HTTP ${res.status}` });
         }
         catch (err) {
-            checks.push({ name: 'OpenAI API', ok: false, detail: err instanceof Error ? err.message : String(err) });
+            checks.push({ name: 'OpenAI API', ok: false, detail: toErrorMessage(err) });
         }
     }
     if (providers.has('minimax-api') && secrets.minimaxKey) {
@@ -737,7 +816,7 @@ async function validateProviderAuth(providers, secrets) {
             checks.push({ name: 'MiniMax API', ok: res.ok, detail: res.ok ? 'auth ok' : `HTTP ${res.status}` });
         }
         catch (err) {
-            checks.push({ name: 'MiniMax API', ok: false, detail: err instanceof Error ? err.message : String(err) });
+            checks.push({ name: 'MiniMax API', ok: false, detail: toErrorMessage(err) });
         }
     }
     if (providers.has('codex-oauth')) {
@@ -1006,28 +1085,27 @@ export async function runSetup(options = {}) {
         sectionHeader('Starter Packs (optional)');
         const localTz = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
         const addTechNewsCron = /^y(es)?$/i.test(await ask(rl, '   Add starter cron: top 10 Hacker News daily? [y/N]: '));
-        const addWeatherCron = /^y(es)?$/i.test(await ask(rl, '   Add starter cron: weather check daily at 7:00am? [y/N]: '));
         let cronTimezone = localTz;
-        let weatherLocation = 'New York, NY';
-        if (addTechNewsCron || addWeatherCron) {
+        if (addTechNewsCron) {
             const tzInput = await ask(rl, `   Timezone for starter cron jobs [${localTz}]: `);
             cronTimezone = tzInput || localTz;
-        }
-        if (addWeatherCron) {
-            const locationInput = await ask(rl, '   Weather location (city, state/country) [New York, NY]: ');
-            weatherLocation = locationInput || 'New York, NY';
+            try {
+                Intl.DateTimeFormat(undefined, { timeZone: cronTimezone });
+            }
+            catch {
+                console.log(`   ⚠ Invalid timezone "${cronTimezone}", using ${localTz}`);
+                cronTimezone = localTz;
+            }
         }
         const addDailyNotesSkill = /^y(es)?$/i.test(await ask(rl, '   Add starter skill: daily-notes? [y/N]: '));
-        const addWeatherSkill = /^y(es)?$/i.test(await ask(rl, '   Add starter skill: weather? [y/N]: '));
-        const addWebSearchSkill = /^y(es)?$/i.test(await ask(rl, '   Add starter skill: web-search (uses Browser tool)? [y/N]: '));
         const starters = {
             cronTechNews: addTechNewsCron,
-            cronWeather: addWeatherCron,
+            cronWeather: false,
             timezone: cronTimezone,
-            weatherLocation,
+            weatherLocation: '',
             skillDailyNotes: addDailyNotesSkill,
-            skillWeather: addWeatherSkill,
-            skillWebSearch: addWebSearchSkill,
+            skillWeather: false,
+            skillWebSearch: false,
         };
         const { envContent, config: generatedConfig } = buildSetupArtifacts({
             workspaceDir: extraAllowedPaths[0] || join(homedir(), '.skimpyclaw'),
@@ -1043,7 +1121,7 @@ export async function runSetup(options = {}) {
             features,
             starters,
         });
-        // On reconfigure, preserve dashboard token, cron jobs, subagents, security, langfuse
+        // On reconfigure, preserve dashboard token, cron jobs, codeAgents config, security, langfuse
         if (isReconfigure && existing.config) {
             if (existing.config.dashboard?.token) {
                 generatedConfig.dashboard = existing.config.dashboard;
@@ -1062,8 +1140,8 @@ export async function runSetup(options = {}) {
                 }
                 generatedConfig.cron = { ...(existing.config.cron || {}), jobs: mergedCronJobs };
             }
-            if (existing.config.subagents) {
-                generatedConfig.subagents = existing.config.subagents;
+            if (existing.config.codeAgents) {
+                generatedConfig.codeAgents = existing.config.codeAgents;
             }
             if (existing.config.security) {
                 generatedConfig.security = existing.config.security;
@@ -1215,13 +1293,30 @@ export async function runSetup(options = {}) {
         console.log(`   Token: ${c.cyan(dashboardToken)}`);
         console.log(`   ${c.dim('(also available via: skimpyclaw status)')}`);
         console.log('\nNext steps:');
-        console.log('1. Review templates in ~/.skimpyclaw/agents/main/');
-        console.log('2. Start the daemon:');
+        let step = 1;
+        console.log(`${step++}. Review templates in ~/.skimpyclaw/agents/main/`);
+        if (enableSandbox) {
+            const runtimeHint = detectedSandboxRuntime === 'docker'
+                ? 'open -a Docker    # or start Docker Desktop'
+                : 'container system start';
+            console.log(`${step++}. Start the container runtime (if not already running):`);
+            console.log(`   ${runtimeHint}`);
+            console.log(`${step++}. Initialize the sandbox:`);
+            console.log('   skimpyclaw sandbox init');
+            console.log(`${step++}. Verify sandbox is working:`);
+            console.log('   skimpyclaw sandbox doctor');
+        }
+        console.log(`${step++}. Start the daemon:`);
         console.log('   skimpyclaw start --daemon');
-        console.log('3. Check health:');
+        console.log(`${step++}. Check health:`);
         console.log('   skimpyclaw status');
-        console.log(`4. Optional daemon controls: skimpyclaw stop | skimpyclaw restart`);
-        console.log(`5. Send /help in your ${useDiscord ? 'Discord bot DM/server' : 'Telegram bot'}`);
+        console.log(`${step++}. Optional daemon controls: skimpyclaw stop | skimpyclaw restart`);
+        console.log(`${step++}. Send /help in your ${useDiscord ? 'Discord bot DM/server' : 'Telegram bot'}`);
+        console.log('');
+        console.log(`${c.yellow('Note:')} The /team and /code tools require an external coding CLI on your PATH:`);
+        console.log('   • Claude Code CLI  →  https://docs.anthropic.com/en/docs/claude-code');
+        console.log('   • Codex CLI        →  https://github.com/openai/codex');
+        console.log('   Install at least one to use code_with_agent / code_with_team.');
         console.log('\n👙🦞 Enjoy!');
     }
     finally {

package/dist/skills.js

@@ -5,18 +5,25 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 import matter from 'gray-matter';
 import { TTLCache } from './cache.js';
+import { toErrorMessage } from './utils.js';
 const DEFAULT_SKILLS_DIR = join(homedir(), '.skimpyclaw', 'skills');
 const DEFAULT_PRIORITY = 100;
 /**
  * Check if a binary exists on PATH.
  * Returns true if found, false otherwise.
  */
+const binExistsCache = new Map();
 function binExists(name) {
+    const cached = binExistsCache.get(name);
+    if (cached !== undefined)
+        return cached;
     try {
         execSync(`which ${name}`, { stdio: 'ignore' });
+        binExistsCache.set(name, true);
         return true;
     }
     catch {
+        binExistsCache.set(name, false);
         return false;
     }
 }
@@ -64,7 +71,7 @@ export function checkEligibility(skill, toolConfig) {
                 if (!toolConfig.browser?.enabled)
                     missing.push(tool);
             }
-            // spawn_subagent and other built-ins are available whenever tools.enabled is true
+            // built-in tools are available whenever tools.enabled is true
         }
         if (missing.length > 0) {
             return { eligible: false, reason: `Tools not enabled (needs: ${missing.join(', ')})` };
@@ -128,7 +135,7 @@ function parseSkillFile(dirPath, dirName, skillConfig, toolConfig) {
         };
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         console.warn(`[skills] Failed to parse ${skillPath}: ${msg}`);
         return null;
     }

package/dist/subagent.js

@@ -18,7 +18,8 @@ const PRESETS = {
             enabled: true,
             allowedPaths: [join(homedir(), '.skimpyclaw')],
             maxIterations: 50,
-            bashTimeout: 30000
+            bashTimeout: 30000,
+            toolProfile: 'minimal',
         },
         description: 'Code tasks with broad file + bash access'
     },
@@ -29,7 +30,8 @@ const PRESETS = {
             enabled: true,
             allowedPaths: [join(homedir(), '.skimpyclaw')],
             maxIterations: 30,
-            bashTimeout: 15000
+            bashTimeout: 15000,
+            toolProfile: 'minimal',
         },
         description: 'Research tasks with configurable file access'
     },
@@ -63,6 +65,21 @@ within your allowed paths (provided at runtime).
 You have a LIMITED number of tool iterations. Every message you spend talking about what
 you're going to do is one less chance to actually do it.
 
+## Tool Priority — Use Native Tools First
+
+**For file operations, always prefer native tools over bash scripts. They are faster, safer, and use fewer iterations.**
+
+| Task | Use this | NOT this |
+|------|----------|----------|
+| List files/dirs | \`Glob\` | \`ls\`, \`find\`, \`python3\` scripts |
+| Read a file | \`Read\` | \`cat\`, \`python3\` scripts |
+| Write a file | \`Write\` | \`echo >\`, \`tee\`, \`python3\` scripts |
+| Run builds/tests | \`Bash\` | — |
+| Git operations | \`Bash\` | — |
+| Install packages | \`Bash\` | — |
+
+**NEVER use \`python3 -\`, \`perl -e\`, \`ruby -e\`, or other inline interpreter scripts to explore the filesystem. Use Glob and Read instead.**
+
 ## Your 4 Tools
 
 ### Read
@@ -76,6 +93,7 @@ List files and directories at a path. Parameter: \`path\` (string, required)
 
 ### Bash
 Execute a shell command. Parameters: \`command\` (string, required), \`cwd\` (string, optional)
+Reserved for: builds, tests, git, package managers, and commands that have no native tool equivalent.
 
 ## Key Paths
 - Config: ~/.skimpyclaw/config.json
@@ -106,6 +124,18 @@ You are a research subagent dispatched for a specific task.
 
 **NEVER say "let me check" or "I'll look into that" — just call the tool.**
 
+## Tool Priority — Use Native Tools First
+
+**For file operations, always prefer native tools over bash scripts.**
+
+| Task | Use this | NOT this |
+|------|----------|----------|
+| List files/dirs | \`Glob\` | \`ls\`, \`find\`, \`python3\` scripts |
+| Read a file | \`Read\` | \`cat\`, \`python3\` scripts |
+| Write a file | \`Write\` | \`echo >\`, \`tee\` |
+
+**NEVER use \`python3 -\`, \`perl -e\`, or other inline interpreter scripts to explore the filesystem.**
+
 ## Your 4 Tools
 
 ### Read
@@ -119,6 +149,7 @@ List files and directories at a path. Parameter: \`path\` (string, required)
 
 ### Bash
 Execute a shell command. Parameters: \`command\` (string, required), \`cwd\` (string, optional)
+Reserved for: git, package managers, and commands with no native tool equivalent.
 
 ## Key Paths
 - Config: ~/.skimpyclaw/config.json

package/dist/tools/bash-tool.js

@@ -37,6 +37,14 @@ export async function executeBash(command, cwd, config, context) {
     if (approvalConfig?.enabled !== false) {
         const classification = classifyCommandRisk(command);
         if (requiresApproval(classification, approvalConfig)) {
+            // Unattended contexts (cron, no approver) have no human available to approve.
+            // Fast-deny instead of blocking for the full TTL.
+            const isUnattended = context?.channel === 'subagent' ||
+                context?.isCronJob === true ||
+                (!context?.approverUserId && !context?.channelTargetId && !context?.chatId);
+            if (isUnattended) {
+                return `⛔ Command blocked — tier ${classification.tier} commands require approval but no approver is available in this context (${classification.reason}). Use safer alternatives or request approval via an interactive channel.`;
+            }
             // Build channel metadata from context for notification routing
             const channelMeta = context?.channel
                 ? {

package/dist/tools/browser-tool.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { isPathAllowed } from './path-utils.js';
+import { toErrorMessage } from '../utils.js';
 let playwrightModule = null;
 let browserContext = null;
 let browserPage = null;
@@ -101,7 +102,7 @@ async function ensureBrowser(config, overrides) {
         });
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = toErrorMessage(err);
         throw new Error(`Failed to launch browser (${options.type}): ${msg}. Ensure the browser is installed: npx playwright install ${options.type}`);
     }
     const pages = browserContext.pages();

package/dist/tools/definitions.d.ts

@@ -305,33 +305,6 @@ export declare const TOOL_DEFINITIONS: ({
         required: string[];
     };
 })[];
-export declare const SPAWN_SUBAGENT_TOOL: {
-    name: string;
-    description: string;
-    input_schema: {
-        type: "object";
-        properties: {
-            task: {
-                type: string;
-                description: string;
-            };
-            type: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
-            model: {
-                type: string;
-                description: string;
-            };
-            label: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
 export declare const CODE_WITH_AGENT_TOOL: {
     name: string;
     description: string;

package/dist/tools/definitions.js

@@ -112,24 +112,6 @@ export const BROWSER_TOOL_DEFINITION = {
 };
 // Legacy export for backward compat — static list (built-ins + browser + no MCP)
 export const TOOL_DEFINITIONS = [...BUILTIN_TOOL_DEFINITIONS, BROWSER_TOOL_DEFINITION];
-export const SPAWN_SUBAGENT_TOOL = {
-    name: 'spawn_subagent',
-    description: 'Spawn a background subagent to handle a task independently. Returns immediately with a run ID. Results are announced back to this chat when done. Use for tasks that benefit from parallel work or long-running operations.',
-    input_schema: {
-        type: 'object',
-        properties: {
-            task: { type: 'string', description: 'What the subagent should do — be specific and self-contained' },
-            type: {
-                type: 'string',
-                enum: ['coding', 'research'],
-                description: 'Agent type: coding (code/files/bash), research (investigation/reading)',
-            },
-            model: { type: 'string', description: 'Optional model override (e.g. claude-opus, claude-think)' },
-            label: { type: 'string', description: 'Short label for status display (e.g. "write tests", "check logs")' },
-        },
-        required: ['task', 'type'],
-    },
-};
 export const CODE_WITH_AGENT_TOOL = {
     name: 'code_with_agent',
     description: 'Delegate a coding task to a coding agent CLI (Claude Code or Codex). The agent will edit files, run commands, and return results. Always use this for code changes instead of writing code directly.',