skimpyclaw 0.1.9 → 0.3.0

package/dist/setup.js

@@ -56,6 +56,66 @@ function loadExistingSetup() {
     }
     return { config, env };
 }
+function detectSandboxRuntime(preferred) {
+    if (preferred) {
+        const check = spawnSync(preferred, ['--version'], { encoding: 'utf-8' });
+        return check.status === 0 ? preferred : null;
+    }
+    const containerCheck = spawnSync('container', ['--version'], { encoding: 'utf-8' });
+    if (containerCheck.status === 0)
+        return 'container';
+    const dockerCheck = spawnSync('docker', ['--version'], { encoding: 'utf-8' });
+    if (dockerCheck.status === 0)
+        return 'docker';
+    return null;
+}
+function sandboxRuntimeRunning(runtime) {
+    if (runtime === 'container') {
+        return spawnSync('container', ['system', 'status'], { encoding: 'utf-8' }).status === 0;
+    }
+    return spawnSync('docker', ['info'], { encoding: 'utf-8' }).status === 0;
+}
+function sandboxNetworkExists(runtime, network) {
+    if (runtime === 'container') {
+        const result = spawnSync('container', ['network', 'ls'], { encoding: 'utf-8' });
+        if (result.status !== 0)
+            return false;
+        return result.stdout
+            .split('\n')
+            .some((line) => line.trim().split(/\s+/)[0] === network);
+    }
+    return spawnSync('docker', ['network', 'inspect', network], { encoding: 'utf-8' }).status === 0;
+}
+function defaultSandboxNetwork(runtime) {
+    return runtime === 'container' ? 'default' : 'bridge';
+}
+function bootstrapSandbox(runtime, image, network) {
+    const sandboxDir = join(__dirname, '..', 'sandbox');
+    const dockerfile = join(sandboxDir, 'Dockerfile');
+    if (!existsSync(dockerfile)) {
+        return { ok: false, message: `Sandbox Dockerfile not found: ${dockerfile}` };
+    }
+    if (!sandboxRuntimeRunning(runtime)) {
+        const hint = runtime === 'container'
+            ? 'Run `container system start` and rerun onboarding.'
+            : 'Start Docker Desktop and rerun onboarding.';
+        return { ok: false, message: `Runtime "${runtime}" is not running. ${hint}` };
+    }
+    if (!sandboxNetworkExists(runtime, network)) {
+        return { ok: false, message: `Network "${network}" not found for ${runtime}. Update sandbox.network and run \`skimpyclaw sandbox init\`.` };
+    }
+    const build = spawnSync(runtime, ['build', '--build-arg', 'SKIMPY_PROFILE=minimal', '-t', image, sandboxDir], { encoding: 'utf-8' });
+    if (build.status !== 0) {
+        const detail = `${build.stderr || ''}\n${build.stdout || ''}`.trim();
+        return { ok: false, message: `Image build failed: ${detail.slice(-800)}` };
+    }
+    const smoke = spawnSync(runtime, ['run', '--rm', '--network', network, image, 'sh', '-lc', 'hostname && command -v gh >/dev/null && command -v rg >/dev/null && echo sandbox-ok'], { encoding: 'utf-8' });
+    if (smoke.status !== 0) {
+        const detail = `${smoke.stderr || ''}\n${smoke.stdout || ''}`.trim();
+        return { ok: false, message: `Sandbox smoke test failed: ${detail.slice(-800)}` };
+    }
+    return { ok: true, message: (smoke.stdout || '').trim().split('\n').join(' | ') };
+}
 function ask(rl, question) {
     return new Promise((resolve) => {
         rl.question(question, (answer) => {
@@ -162,6 +222,40 @@ async function askProviders(rl, existingProviders) {
         return choices;
     }
 }
+function buildStarterCronJobs(starters) {
+    const jobs = [];
+    if (starters.cronTechNews) {
+        jobs.push({
+            id: 'tech-digest',
+            name: 'Tech News',
+            schedule: {
+                kind: 'cron',
+                expr: '0 8 * * *',
+                tz: starters.timezone,
+            },
+            payload: {
+                kind: 'agentTurn',
+                message: 'Use WebSearch to fetch today\'s top 10 Hacker News stories. Reply with title, URL, and 1-line summary for each item.',
+            },
+        });
+    }
+    if (starters.cronWeather) {
+        jobs.push({
+            id: 'weather',
+            name: 'Weather',
+            schedule: {
+                kind: 'cron',
+                expr: '0 7 * * *',
+                tz: starters.timezone,
+            },
+            payload: {
+                kind: 'agentTurn',
+                message: `Check current weather and today forecast for ${starters.weatherLocation}. Keep it concise: current temp/conditions, highs/lows, precipitation chance, and 1 recommendation.`,
+            },
+        });
+    }
+    return jobs;
+}
 async function collectProviderSecrets(rl, providers, existingEnv) {
     const secrets = {};
     const env = existingEnv || {};
@@ -346,7 +440,23 @@ function buildEnvContent(telegramToken, providers, secrets, discordToken) {
 }
 export function buildSetupConfig(input) {
     const useDiscord = Boolean(input.discordToken);
-    const features = input.features ?? { browser: false, voice: false, mcp: false };
+    const features = input.features ?? { browser: false, voice: false, mcp: false, sandbox: false };
+    const starters = input.starters ?? {
+        cronTechNews: false,
+        cronWeather: false,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
+        weatherLocation: 'New York, NY',
+        skillCodeReview: false,
+        skillDailyNotes: false,
+    };
+    const basePaths = ['${HOME}/.skimpyclaw'];
+    const allPaths = [...basePaths, ...(input.extraAllowedPaths || [])];
+    const starterCronJobs = buildStarterCronJobs(starters);
+    const starterSkillEntries = {};
+    if (starters.skillCodeReview)
+        starterSkillEntries['code-review'] = true;
+    if (starters.skillDailyNotes)
+        starterSkillEntries['daily-notes'] = true;
     return {
         gateway: {
             port: 18790,
@@ -377,25 +487,25 @@ export function buildSetupConfig(input) {
                 token: '${TELEGRAM_BOT_TOKEN}',
                 allowFrom: [parseInt(input.telegramId, 10) || input.telegramId],
                 dailyNotesDir: '${HOME}/.skimpyclaw/Daily Notes',
-                defaultAllowedPaths: ['${HOME}/.skimpyclaw'],
+                defaultAllowedPaths: allPaths,
             },
             discord: {
                 enabled: useDiscord,
                 token: useDiscord ? '${DISCORD_BOT_TOKEN}' : '',
                 allowFrom: useDiscord ? [input.discordUserId || ''] : [],
-                defaultAllowedPaths: ['${HOME}/.skimpyclaw'],
+                defaultAllowedPaths: allPaths,
                 ...(input.discordDefaultChannelId ? { defaultChannelId: input.discordDefaultChannelId } : {}),
             },
         },
         cron: {
-            jobs: [],
+            jobs: starterCronJobs,
         },
         heartbeat: {
             intervalMs: 1800000,
             prompt: 'Read ~/.skimpyclaw/agents/main/HEARTBEAT.md. Follow it strictly. If nothing needs attention, reply HEARTBEAT_OK.',
             tools: {
                 enabled: true,
-                allowedPaths: ['${HOME}/.skimpyclaw'],
+                allowedPaths: allPaths,
                 maxIterations: 10,
                 bashTimeout: 15000,
                 ...(features.browser ? { browser: { enabled: true } } : { browser: { enabled: false } }),
@@ -414,6 +524,22 @@ export function buildSetupConfig(input) {
                 },
             },
         } : {}),
+        ...(features.sandbox ? {
+            sandbox: {
+                enabled: true,
+                image: 'skimpyclaw-sandbox',
+                cpus: 2,
+                memory: '2G',
+                network: 'bridge',
+                idleTimeoutMs: 3600000,
+            },
+        } : {}),
+        ...(Object.keys(starterSkillEntries).length > 0 ? {
+            skills: {
+                enabled: true,
+                entries: starterSkillEntries,
+            },
+        } : {}),
         dashboard: {
             token: randomUUID(),
         },
@@ -433,6 +559,34 @@ const REQUIRED_TEMPLATE_DEFAULTS = {
     'USER.md': '# USER\n\nName: User\n',
     'HEARTBEAT.md': '# HEARTBEAT\n\nIf nothing needs attention, reply HEARTBEAT_OK.\n',
 };
+const STARTER_SKILL_TEMPLATES = {
+    'code-review': `---
+name: code-review
+description: Structured code review checklist for bugs, regressions, and missing tests.
+triggers: ["review", "pr", "regression", "tests"]
+priority: 80
+---
+
+When asked to review code:
+1. Focus on correctness and regressions first.
+2. Call out missing or weak test coverage.
+3. Prefer concrete file-level findings.
+4. End with risk summary and recommended fixes.
+`,
+    'daily-notes': `---
+name: daily-notes
+description: Keep daily notes organized under the configured daily notes directory.
+triggers: ["daily note", "standup", "plan day", "journal"]
+priority: 90
+---
+
+When writing daily notes:
+1. Use today's date in the file name if missing.
+2. Include sections: Priorities, Schedule, Notes, Follow-ups.
+3. Keep entries concise and actionable.
+4. Avoid creating files outside the configured daily notes directory.
+`,
+};
 function ensureCoreTemplates(agentDir) {
     const created = [];
     for (const [file, content] of Object.entries(REQUIRED_TEMPLATE_DEFAULTS)) {
@@ -444,6 +598,26 @@ function ensureCoreTemplates(agentDir) {
     }
     return created;
 }
+function ensureStarterSkills(starters) {
+    const created = [];
+    const skillsDir = join(CONFIG_DIR, 'skills');
+    mkdirSync(skillsDir, { recursive: true });
+    const requested = [];
+    if (starters.skillCodeReview)
+        requested.push('code-review');
+    if (starters.skillDailyNotes)
+        requested.push('daily-notes');
+    for (const skillName of requested) {
+        const dir = join(skillsDir, skillName);
+        const skillPath = join(dir, 'SKILL.md');
+        if (!existsSync(skillPath)) {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(skillPath, STARTER_SKILL_TEMPLATES[skillName], 'utf-8');
+            created.push(skillName);
+        }
+    }
+    return created;
+}
 async function quickFetch(url, init) {
     return await fetch(url, { ...init, signal: AbortSignal.timeout(12000) });
 }
@@ -526,8 +700,11 @@ export async function runSetup(options = {}) {
         if (templates.length === 0) {
             throw new Error(`No markdown templates found in ${TEMPLATES_DIR}`);
         }
-        // Validate launchd template rendering with current environment and install root.
-        renderGatewayPlist();
+        // Validate launchd template exists. Full render validation requires built dist/
+        // which may not be present in dry-run contexts (e.g. CI test-only jobs).
+        if (!existsSync(GATEWAY_PLIST_TEMPLATE)) {
+            throw new Error(`Gateway launchd template not found: ${GATEWAY_PLIST_TEMPLATE}`);
+        }
         console.log('✅ Onboarding dry run successful.');
         console.log(`Would create config under: ${CONFIG_DIR}`);
         console.log(`Would copy ${templates.length} templates to: ${AGENTS_DIR}`);
@@ -612,7 +789,42 @@ export async function runSetup(options = {}) {
         sectionHeader('5. Your Name');
         const userName = (await ask(rl, '   What should I call you? ')) || 'User';
         statusOk(userName);
-        // 6. Optional Features
+        // 6. Workspace Directory
+        sectionHeader('6. Workspace Directory');
+        console.log('   The agent can read/write files in allowed directories.');
+        console.log('   ~/.skimpyclaw is always included. Add project directories here.');
+        const existingExtraPaths = existing.config?.channels?.telegram?.defaultAllowedPaths
+            ?.filter((p) => p !== '${HOME}/.skimpyclaw') || [];
+        const existingExtra = existingExtraPaths.join(', ');
+        const workspaceDirInput = await ask(rl, `   Additional directory to allow (or Enter to skip)${existingExtra ? ` [${existingExtra}]` : ''}: `);
+        const extraAllowedPaths = [];
+        if (workspaceDirInput) {
+            extraAllowedPaths.push(workspaceDirInput);
+            statusOk(`Added: ${workspaceDirInput}`);
+        }
+        else if (existingExtra) {
+            extraAllowedPaths.push(...existingExtraPaths);
+            statusOk(`Keeping: ${existingExtra}`);
+        }
+        else {
+            statusOk('Only ~/.skimpyclaw (default)');
+        }
+        // 7. Tool Safety Consent
+        sectionHeader('7. Safety Notice');
+        console.log('   ⚠ This agent can:');
+        console.log('     • Read and write files in allowed directories');
+        console.log('     • Run terminal commands (with safety filters and approval gates)');
+        console.log('     • Send messages via configured channels (Telegram, Discord)');
+        console.log('     • Access MCP tools if configured');
+        console.log('');
+        const consent = /^y(es)?$/i.test(await ask(rl, '   Do you understand and accept these capabilities? [y/N]: '));
+        if (!consent) {
+            console.log(`\n${c.red('Setup cancelled.')} Re-run when ready.`);
+            rl.close();
+            return;
+        }
+        statusOk('Acknowledged');
+        // 8. Optional Features
         const existingBrowser = existing.config?.heartbeat?.tools?.browser?.enabled === true
             || existing.config?.channels?.telegram?.tools?.browser?.enabled === true;
         const existingVoice = existing.config?.voice?.enabled === true;
@@ -663,13 +875,62 @@ export async function runSetup(options = {}) {
         else {
             statusOk('MCP tools disabled');
         }
+        // 6d. Sandbox (container isolation)
+        const existingSandbox = existing.config?.sandbox?.enabled === true;
+        const sandboxDefault = existingSandbox ? 'Y' : 'N';
+        const enableSandbox = /^y(es)?$/i.test(await ask(rl, `   Enable sandbox? (requires Docker or Apple Containers) [${existingSandbox ? 'Y/n' : 'y/N'}]: `) || sandboxDefault);
+        let detectedSandboxRuntime = null;
+        if (enableSandbox) {
+            const containerCli = spawnSync('which', ['container'], { encoding: 'utf-8' });
+            const docker = spawnSync('which', ['docker'], { encoding: 'utf-8' });
+            if (containerCli.status === 0) {
+                detectedSandboxRuntime = 'container';
+                statusOk('Apple Containers detected');
+            }
+            else if (docker.status === 0) {
+                detectedSandboxRuntime = 'docker';
+                statusOk('Docker detected');
+            }
+            else {
+                statusWarn('No container runtime found — sandbox features won\'t work until Docker or Apple Containers is installed');
+            }
+        }
+        else {
+            statusOk('sandbox disabled');
+        }
         const features = {
             browser: enableBrowser,
             voice: enableVoice,
             mcp: enableMcp,
+            sandbox: enableSandbox,
+        };
+        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) {
+            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';
+        }
+        const addCodeReviewSkill = /^y(es)?$/i.test(await ask(rl, '   Add starter skill: code-review? [y/N]: '));
+        const addDailyNotesSkill = /^y(es)?$/i.test(await ask(rl, '   Add starter skill: daily-notes? [y/N]: '));
+        const starters = {
+            cronTechNews: addTechNewsCron,
+            cronWeather: addWeatherCron,
+            timezone: cronTimezone,
+            weatherLocation,
+            skillCodeReview: addCodeReviewSkill,
+            skillDailyNotes: addDailyNotesSkill,
         };
-        const { configJson: rawConfigJson, envContent, config: generatedConfig } = buildSetupArtifacts({
-            workspaceDir: process.cwd(),
+        const { envContent, config: generatedConfig } = buildSetupArtifacts({
+            workspaceDir: extraAllowedPaths[0] || join(homedir(), '.skimpyclaw'),
+            extraAllowedPaths,
             telegramId,
             telegramToken,
             discordToken: useDiscord ? discordToken : undefined,
@@ -679,14 +940,26 @@ export async function runSetup(options = {}) {
             selectedProviders,
             providerSecrets,
             features,
+            starters,
         });
         // On reconfigure, preserve dashboard token, cron jobs, subagents, security, langfuse
         if (isReconfigure && existing.config) {
             if (existing.config.dashboard?.token) {
                 generatedConfig.dashboard = existing.config.dashboard;
             }
-            if (Array.isArray(existing.config.cron?.jobs) && existing.config.cron.jobs.length > 0) {
-                generatedConfig.cron = existing.config.cron;
+            if (Array.isArray(existing.config.cron?.jobs)) {
+                const existingCronJobs = existing.config.cron.jobs;
+                const starterCronJobs = (generatedConfig.cron?.jobs || []);
+                const mergedCronJobs = [...existingCronJobs];
+                for (const starter of starterCronJobs) {
+                    const id = String(starter.id || '');
+                    if (!id)
+                        continue;
+                    if (!mergedCronJobs.some((job) => String(job.id) === id)) {
+                        mergedCronJobs.push(starter);
+                    }
+                }
+                generatedConfig.cron = { ...(existing.config.cron || {}), jobs: mergedCronJobs };
             }
             if (existing.config.subagents) {
                 generatedConfig.subagents = existing.config.subagents;
@@ -697,12 +970,35 @@ export async function runSetup(options = {}) {
             if (existing.config.langfuse) {
                 generatedConfig.langfuse = existing.config.langfuse;
             }
+            if (existing.config.sandbox) {
+                generatedConfig.sandbox = existing.config.sandbox;
+            }
             // Preserve voice provider config if voice was already configured
             if (existing.config.voice?.providers && Object.keys(existing.config.voice.providers).length > 0) {
                 generatedConfig.voice = existing.config.voice;
             }
+            if (existing.config.skills) {
+                const generatedSkills = (generatedConfig.skills || {});
+                generatedConfig.skills = {
+                    ...existing.config.skills,
+                    ...generatedSkills,
+                    entries: {
+                        ...(existing.config.skills.entries || {}),
+                        ...(generatedSkills.entries || {}),
+                    },
+                };
+            }
+        }
+        if (enableSandbox && generatedConfig.sandbox) {
+            const runtime = detectSandboxRuntime(detectedSandboxRuntime) || detectSandboxRuntime();
+            if (runtime) {
+                generatedConfig.sandbox.runtime = runtime;
+                generatedConfig.sandbox.network = defaultSandboxNetwork(runtime);
+            }
+            if (!generatedConfig.sandbox.image) {
+                generatedConfig.sandbox.image = 'skimpyclaw-sandbox:latest';
+            }
         }
-        const configJson = JSON.stringify(generatedConfig, null, 2);
         // Create directories
         console.log('Creating directories...');
         mkdirSync(CONFIG_DIR, { recursive: true });
@@ -712,6 +1008,7 @@ export async function runSetup(options = {}) {
         mkdirSync(AGENTS_DIR, { recursive: true });
         mkdirSync(join(AGENTS_DIR, 'memory'), { recursive: true });
         const configPath = join(CONFIG_DIR, 'config.json');
+        const configJson = JSON.stringify(generatedConfig, null, 2);
         writeFileSync(configPath, configJson);
         console.log(`✓ Config written to ${configPath}`);
         // Copy templates
@@ -733,6 +1030,10 @@ export async function runSetup(options = {}) {
         if (createdFallbackTemplates.length > 0) {
             console.log(`✓ Added missing core templates: ${createdFallbackTemplates.join(', ')}`);
         }
+        const createdSkills = ensureStarterSkills(starters);
+        if (createdSkills.length > 0) {
+            console.log(`✓ Starter skills created: ${createdSkills.join(', ')}`);
+        }
         // Merge secrets into .env (preserve existing keys not in new content)
         const envPath = join(CONFIG_DIR, '.env');
         if (isReconfigure && existsSync(envPath)) {
@@ -756,6 +1057,27 @@ export async function runSetup(options = {}) {
             writeFileSync(envPath, envContent);
             console.log(`✓ Secrets written to ${envPath}`);
         }
+        if (enableSandbox) {
+            sectionHeader('Sandbox Bootstrap');
+            const sandboxCfg = generatedConfig.sandbox || {};
+            const runtime = detectSandboxRuntime(sandboxCfg.runtime);
+            const image = String(sandboxCfg.image || 'skimpyclaw-sandbox:latest');
+            const network = String(sandboxCfg.network || (runtime ? defaultSandboxNetwork(runtime) : 'bridge'));
+            if (!runtime) {
+                statusWarn('Sandbox enabled, but no runtime detected. Run `skimpyclaw sandbox init` later.');
+            }
+            else {
+                console.log(`   Building sandbox image (${runtime}, network=${network})...`);
+                const bootstrap = bootstrapSandbox(runtime, image, network);
+                if (bootstrap.ok) {
+                    statusOk(`sandbox ready (${bootstrap.message})`);
+                }
+                else {
+                    statusWarn(bootstrap.message);
+                    console.log(`   ${c.dim('You can retry later with: skimpyclaw sandbox init')}`);
+                }
+            }
+        }
         // Update USER.md with name
         writeFileSync(join(AGENTS_DIR, 'USER.md'), `# USER.md - About ${userName}\n\nName: ${userName}\n\n## Preferences\n\n- Direct communication, no fluff\n\n## Routines\n\n- Morning: Review tasks and messages\n- EOD: Review completed work, plan tomorrow\n`);
         // Create launchd plist from template

package/dist/skills.d.ts

@@ -27,6 +27,5 @@ export declare function getSkillsForContext(skills: LoadedSkill[], context?: {
 }): LoadedSkill[];
 /**
  * Format eligible, context-filtered skills into a markdown prompt section.
- * Respects maxPromptTokens budget (approximate).
  */
-export declare function formatSkillsPrompt(skills: LoadedSkill[], maxTokens?: number): string;
+export declare function formatSkillsPrompt(skills: LoadedSkill[], _maxTokens?: number): string;

package/dist/skills.js

@@ -7,9 +7,6 @@ import matter from 'gray-matter';
 import { TTLCache } from './cache.js';
 const DEFAULT_SKILLS_DIR = join(homedir(), '.skimpyclaw', 'skills');
 const DEFAULT_PRIORITY = 100;
-const DEFAULT_MAX_PROMPT_TOKENS = 4000;
-// Rough chars-per-token estimate for prompt budgeting
-const CHARS_PER_TOKEN = 4;
 /**
  * Check if a binary exists on PATH.
  * Returns true if found, false otherwise.
@@ -233,26 +230,17 @@ export function getSkillsForContext(skills, context) {
 }
 /**
  * Format eligible, context-filtered skills into a markdown prompt section.
- * Respects maxPromptTokens budget (approximate).
  */
-export function formatSkillsPrompt(skills, maxTokens) {
+export function formatSkillsPrompt(skills, _maxTokens) {
     if (skills.length === 0)
         return '';
-    const budget = (maxTokens ?? DEFAULT_MAX_PROMPT_TOKENS) * CHARS_PER_TOKEN;
     const sections = [];
-    let totalChars = 0;
     // Header
     const header = '## Active Skills\n';
-    totalChars += header.length;
     for (const skill of skills) {
         const emoji = skill.frontmatter.emoji ? `${skill.frontmatter.emoji} ` : '';
         const section = `### ${emoji}${skill.name}\n\n${skill.body}`;
-        if (totalChars + section.length > budget) {
-            console.warn(`[skills] Token budget exceeded, skipping remaining skills (included ${sections.length}/${skills.length})`);
-            break;
-        }
         sections.push(section);
-        totalChars += section.length;
     }
     if (sections.length === 0)
         return '';

package/dist/tools/bash-path-validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns true if a shell token looks like a file/directory path.
+ * Matches: /foo, ./foo, ../foo, ~/foo
+ * Does NOT match: flags (-f, --file), bare words (foo), URLs (https://...)
+ */
+export declare function isPathLikeToken(token: string): boolean;
+/**
+ * For an interpreter command segment, extract the script file path if present.
+ * Returns null if the command uses inline execution (-c, -e) or reads from stdin.
+ */
+export declare function extractScriptTarget(segment: string[]): string | null;
+/**
+ * Extract all file-path-like tokens from a shell command.
+ * Handles piped/chained commands. Resolves ~ and relative paths using cwd.
+ * Also extracts script targets from interpreter commands.
+ */
+export declare function extractPathsFromCommand(command: string, cwd?: string): string[];
+/**
+ * Validate that all file paths in a bash command are within allowedPaths.
+ * Returns null if all paths are valid, or an error message string if any are outside.
+ */
+export declare function validateBashPaths(command: string, cwd: string | undefined, allowedPaths: string[]): string | null;

package/dist/tools/bash-path-validation.js

@@ -0,0 +1,130 @@
+// Bash argument path validation — extracts file paths from command tokens
+// and validates them against the allowedPaths list.
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { getCommandSegments, getSegmentCommandIndex, getExecutableName, } from '../exec-approval.js';
+import { isPathAllowed } from './path-utils.js';
+// --- Path-like token detection ---
+/**
+ * Returns true if a shell token looks like a file/directory path.
+ * Matches: /foo, ./foo, ../foo, ~/foo
+ * Does NOT match: flags (-f, --file), bare words (foo), URLs (https://...)
+ */
+export function isPathLikeToken(token) {
+    const t = token.trim();
+    if (!t || t === '-' || t === '--')
+        return false;
+    // Absolute path
+    if (t.startsWith('/'))
+        return true;
+    // Relative paths
+    if (t.startsWith('./') || t.startsWith('../') || t === '.' || t === '..')
+        return true;
+    // Home-relative path
+    if (t.startsWith('~/') || t === '~')
+        return true;
+    return false;
+}
+// --- Interpreter script target extraction ---
+const INTERPRETERS = new Set([
+    'python', 'python3', 'python3.11', 'python3.12', 'python3.13',
+    'node', 'deno', 'bun',
+    'perl', 'ruby', 'php', 'lua',
+    'bash', 'sh', 'zsh', 'fish',
+]);
+/** Flags that consume the next argument (so it's not a script path). */
+const INTERPRETER_FLAGS_WITH_VALUE = new Set([
+    '-c', '-e', '-m', '-W', '-X', '-O',
+    '--eval', '--execute', '--require',
+]);
+/** Flags that mean "read from stdin" or "inline code follows" — stop looking for script path. */
+const INTERPRETER_INLINE_FLAGS = new Set([
+    '-c', '-e', '--eval', '--execute', '-r', '-Command',
+]);
+/**
+ * For an interpreter command segment, extract the script file path if present.
+ * Returns null if the command uses inline execution (-c, -e) or reads from stdin.
+ */
+export function extractScriptTarget(segment) {
+    const cmdIdx = getSegmentCommandIndex(segment);
+    if (cmdIdx >= segment.length)
+        return null;
+    const cmd = getExecutableName(segment[cmdIdx]);
+    if (!INTERPRETERS.has(cmd))
+        return null;
+    const args = segment.slice(cmdIdx + 1);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        // Inline execution — no script file to validate
+        if (INTERPRETER_INLINE_FLAGS.has(arg))
+            return null;
+        // Flag that consumes next arg — skip both
+        if (INTERPRETER_FLAGS_WITH_VALUE.has(arg)) {
+            i++;
+            continue;
+        }
+        // Skip other flags (single or double dash)
+        if (arg.startsWith('-'))
+            continue;
+        // First non-flag argument is the script path
+        return arg;
+    }
+    return null;
+}
+// --- Path extraction from full command ---
+/**
+ * Extract all file-path-like tokens from a shell command.
+ * Handles piped/chained commands. Resolves ~ and relative paths using cwd.
+ * Also extracts script targets from interpreter commands.
+ */
+export function extractPathsFromCommand(command, cwd) {
+    const segments = getCommandSegments(command);
+    const paths = [];
+    const baseCwd = cwd || process.cwd();
+    for (const segment of segments) {
+        const cmdIdx = getSegmentCommandIndex(segment);
+        // Check for interpreter script target
+        const scriptTarget = extractScriptTarget(segment);
+        if (scriptTarget) {
+            paths.push(resolvePath(scriptTarget, baseCwd));
+        }
+        // Check all non-command tokens for path-like values
+        for (let i = cmdIdx + 1; i < segment.length; i++) {
+            const token = segment[i];
+            if (isPathLikeToken(token)) {
+                paths.push(resolvePath(token, baseCwd));
+            }
+        }
+    }
+    // Deduplicate
+    return [...new Set(paths)];
+}
+/**
+ * Resolve a token to an absolute path, expanding ~ and relative paths.
+ */
+function resolvePath(token, cwd) {
+    if (token.startsWith('~/') || token === '~') {
+        return resolve(homedir(), token.slice(2) || '.');
+    }
+    return resolve(cwd, token);
+}
+// --- Validation ---
+/**
+ * Validate that all file paths in a bash command are within allowedPaths.
+ * Returns null if all paths are valid, or an error message string if any are outside.
+ */
+export function validateBashPaths(command, cwd, allowedPaths) {
+    // If no allowedPaths configured, skip validation (permissive mode)
+    if (!allowedPaths || allowedPaths.length === 0)
+        return null;
+    const paths = extractPathsFromCommand(command, cwd);
+    const blocked = [];
+    for (const p of paths) {
+        if (!isPathAllowed(p, allowedPaths)) {
+            blocked.push(p);
+        }
+    }
+    if (blocked.length === 0)
+        return null;
+    return `Error: Command references paths outside allowed directories: ${blocked.join(', ')}`;
+}