crewly 1.3.31 → 1.4.0

package/dist/backend/backend/src/services/agent/crewly-agent/tool-registry.js

@@ -8,8 +8,107 @@
  * @module services/agent/crewly-agent/tool-registry
  */
 import { promises as fsPromises } from 'fs';
+import { execSync, spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { z } from 'zod';
+/** TTL for delegation idle event subscriptions (minutes) */
+const DELEGATION_SUBSCRIPTION_TTL_MINUTES = 120;
+/** Maximum characters for git diff output */
+const GIT_DIFF_MAX_CHARS = 5000;
+/**
+ * Commands that could kill/signal the parent Crewly server process or
+ * cause irreversible system damage.  Checked against the raw command
+ * string (case-insensitive, word-boundary match via regex).
+ */
+const BLOCKED_COMMAND_PATTERNS = [
+    /\bkill\b/i,
+    /\bkillall\b/i,
+    /\bpkill\b/i,
+    /\bshutdown\b/i,
+    /\breboot\b/i,
+    /\brm\s+-[^\s]*r[^\s]*\s+\/(?!\S)/i, // rm -rf / (root wipe)
+    /\bmkfs\b/i,
+    /\bdd\s+.*of=\/dev\//i, // dd of=/dev/...
+    /\blaunchctl\b/i,
+    /\bsystemctl\b/i,
+];
+/**
+ * Bash commands that require explicit approval before execution.
+ * These are dangerous but not catastrophic — they modify remote state,
+ * delete files, or interact with container/network infrastructure.
+ *
+ * Matched against the raw command string (case-insensitive, word-boundary).
+ */
+export const APPROVAL_REQUIRED_BASH_PATTERNS = [
+    { pattern: /\bgit\s+push\b/i, label: 'git push (modifies remote repository)' },
+    { pattern: /\bgit\s+push\s+.*--force\b/i, label: 'git push --force (destructive remote rewrite)' },
+    { pattern: /\brm\s+/i, label: 'rm (file deletion)' },
+    { pattern: /\bdocker\s+(rm|rmi|stop|kill|exec|run|build|push|pull)\b/i, label: 'docker operation (container/image management)' },
+    { pattern: /\bcurl\b/i, label: 'curl (network request)' },
+    { pattern: /\bwget\b/i, label: 'wget (network download)' },
+    { pattern: /\bnpm\s+publish\b/i, label: 'npm publish (package registry push)' },
+    { pattern: /\bgit\s+reset\s+--hard\b/i, label: 'git reset --hard (destructive history rewrite)' },
+];
+/**
+ * Validate a shell command against the blocklist.
+ *
+ * @param command - Raw shell command string
+ * @returns Error message if blocked, or null if allowed
+ */
+export function validateBashCommand(command) {
+    for (const pattern of BLOCKED_COMMAND_PATTERNS) {
+        if (pattern.test(command)) {
+            return `Command blocked by security policy: matches forbidden pattern ${pattern}`;
+        }
+    }
+    return null;
+}
+/**
+ * Check if a bash command matches any approval-required pattern.
+ *
+ * @param command - Raw shell command string
+ * @returns Matching label if approval is required, or null if safe to proceed
+ */
+export function checkBashApprovalRequired(command) {
+    for (const { pattern, label } of APPROVAL_REQUIRED_BASH_PATTERNS) {
+        if (pattern.test(command)) {
+            return label;
+        }
+    }
+    return null;
+}
+/**
+ * Execute a shell command in an isolated process group so that signals
+ * (SIGTERM, SIGINT) from the child cannot propagate to the Crewly server.
+ *
+ * Uses spawnSync with setsid (macOS/Linux) to create a new session,
+ * preventing the child's process group signals from reaching the parent.
+ *
+ * @param cmd - Shell command to run
+ * @param workDir - Working directory
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Object with stdout, stderr, exitCode
+ */
+function execIsolated(cmd, workDir, timeoutMs) {
+    const result = spawnSync('/bin/sh', ['-c', cmd], {
+        cwd: workDir,
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        maxBuffer: 1024 * 1024,
+        env: { ...process.env, FORCE_COLOR: '0' },
+        // Run in a new process group — signals sent to the child group
+        // will NOT propagate to the Crewly server's process group.
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // If the process was killed by a signal (e.g. timeout → SIGTERM),
+    // reflect it in the exit code.
+    const exitCode = result.status ?? (result.signal ? 128 : 1);
+    return {
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        exitCode,
+    };
+}
 /**
  * Expand ~ and $HOME in a file path to the user's home directory.
  *
@@ -26,6 +125,72 @@ function expandPath(filePath) {
     }
     return filePath;
 }
+/** File extensions recognized as images for multimodal read_file support */
+const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg']);
+/** MIME type mapping for image extensions */
+const IMAGE_MIME_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+};
+/**
+ * Strip [NOTIFY]...[/NOTIFY] markers from text.
+ *
+ * The crewly-agent model sometimes wraps tool arguments in NOTIFY markers
+ * intended for the terminal gateway routing layer. When this leaks into
+ * reply_slack or other outward-facing tools, the raw markers appear in
+ * the Slack message. This function extracts the body content (after the
+ * --- separator if present) or the full block content.
+ *
+ * @param text - Text that may contain NOTIFY markers
+ * @returns Clean text with markers stripped and body content extracted
+ */
+export function stripNotifyMarkers(text) {
+    // Replace each [NOTIFY]...[/NOTIFY] block with its body content
+    const cleaned = text.replace(/\[NOTIFY\]([\s\S]*?)\[\/NOTIFY\]/gi, (_match, inner) => {
+        const trimmed = inner.trim();
+        // If there's a --- separator, extract only the body after it
+        const separatorIdx = trimmed.indexOf('---');
+        if (separatorIdx !== -1) {
+            return trimmed.slice(separatorIdx + 3).trim();
+        }
+        // No separator — return the full inner content
+        return trimmed;
+    });
+    return cleaned.trim();
+}
+/**
+ * Convert GitHub-flavored Markdown to Slack mrkdwn format (#181).
+ *
+ * Transformations applied (in order):
+ * 1. Escape &, <, > to HTML entities (Slack requirement)
+ * 2. Convert fenced code blocks (```lang\n...\n```) to Slack code blocks
+ * 3. Convert **bold** to *bold* (Slack uses single asterisks)
+ * 4. Convert [text](url) links to <url|text> (Slack link format)
+ *
+ * @param text - Markdown-formatted text
+ * @returns Text formatted for Slack mrkdwn
+ */
+export function convertMarkdownToSlackMrkdwn(text) {
+    // 1. Escape special Slack characters (must happen first, before adding <> for links)
+    let result = text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    // 2. Convert fenced code blocks: ```lang\n...\n``` → ```\n...\n```
+    // Slack doesn't support language hints in code blocks, so strip them
+    result = result.replace(/```\w*\n/g, '```\n');
+    // 3. Convert **bold** to *bold* (Slack bold is single asterisk)
+    // Must not touch single * (already italic in both formats)
+    result = result.replace(/\*\*(.+?)\*\*/g, '*$1*');
+    // 4. Convert [text](url) links to <url|text>
+    // The url may contain escaped &gt; from step 1, but real URLs won't have those
+    result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<$2|$1>');
+    return result;
+}
 /**
  * Sensitivity classification for each tool.
  * Used by the audit trail to classify tool invocations.
@@ -42,7 +207,9 @@ export const TOOL_SENSITIVITY = {
     recall_memory: 'safe',
     subscribe_event: 'safe',
     get_audit_log: 'safe',
+    get_scheduled_checks: 'safe',
     compact_memory: 'safe',
+    get_context_budget: 'safe',
     // Sensitive: modify state, communicate externally
     delegate_task: 'sensitive',
     send_message: 'sensitive',
@@ -60,6 +227,14 @@ export const TOOL_SENSITIVITY = {
     handle_agent_failure: 'destructive',
     edit_file: 'destructive',
     write_file: 'destructive',
+    // Git tools (#176)
+    git_status: 'safe',
+    git_diff: 'safe',
+    git_commit: 'sensitive',
+    // Shell execution (#176)
+    bash_exec: 'destructive',
+    // Task handoff (F12)
+    handoff_task: 'sensitive',
 };
 /**
  * Wrap a tool's execute function with audit logging.
@@ -107,10 +282,17 @@ function wrapWithAudit(toolName, executeFn, callbacks) {
                 };
                 if (callbacks?.onAuditLog)
                     callbacks.onAuditLog(entry);
+                // Enqueue for approval if not hard-blocked
+                let approvalId;
+                if (!approvalResult.blocked && callbacks?.onEnqueueApproval) {
+                    const enqueued = callbacks.onEnqueueApproval(toolName, sensitivity, sanitizedArgs);
+                    approvalId = enqueued.approvalId;
+                }
                 return {
                     success: false,
                     blocked: approvalResult.blocked ?? false,
                     requiresApproval: !approvalResult.blocked,
+                    approvalId,
                     error: approvalResult.reason || 'Tool execution denied by security policy',
                 };
             }
@@ -166,8 +348,8 @@ function sanitizeArgs(args) {
         if (sensitiveKeys.some(sk => key.toLowerCase().includes(sk))) {
             result[key] = '[REDACTED]';
         }
-        else if (typeof value === 'string' && value.length > 500) {
-            result[key] = value.substring(0, 500) + '...[truncated]';
+        else if (typeof value === 'string' && value.length > 2000) {
+            result[key] = value.substring(0, 2000) + '...[truncated]';
         }
         else {
             result[key] = value;
@@ -188,11 +370,17 @@ function sanitizeArgs(args) {
  * @param callbacks - Optional callbacks for compaction and audit logging
  * @returns Object of named tools ready to pass to generateText
  */
-export function createTools(client, sessionName, projectPath, callbacks) {
+export function createTools(client, sessionName, projectPath, callbacks, conversationId, slackContext, mcpTools) {
+    // Slack rate-limiting state: throttle messages within a 3-second window
+    let lastSlackSendMs = 0;
+    const SLACK_THROTTLE_MS = 3000;
+    // Slack dedup: ring buffer of recent messages to prevent duplicate sends
+    const recentSlackMessages = [];
+    const SLACK_DEDUP_WINDOW = 10;
     const rawTools = {
         // ===== Core Orchestration Tools =====
         delegate_task: {
-            description: 'Delegate a task to a worker agent. Sends the task message and creates a task tracking file.',
+            description: 'Delegate a task to a worker agent. Sends the task message and creates a task tracking file. Enforces TL hierarchy — if target has a parent TL, routes through TL instead.',
             inputSchema: z.object({
                 to: z.string().describe('Target agent session name'),
                 task: z.string().describe('Task description and instructions'),
@@ -201,6 +389,42 @@ export function createTools(client, sessionName, projectPath, callbacks) {
                 projectPath: z.string().optional().describe('Project path for task tracking'),
             }),
             execute: async ({ to, task, priority, context, projectPath }) => {
+                // #164: TL hierarchy validation — enforce that the caller has delegation authority
+                const teamsResult = await client.get('/teams').catch(() => null);
+                if (teamsResult?.success && Array.isArray(teamsResult.data)) {
+                    for (const team of teamsResult.data) {
+                        const targetMember = team.members?.find(m => m.sessionName === to);
+                        const callerMember = team.members?.find(m => m.sessionName === sessionName);
+                        if (targetMember?.parentMemberId) {
+                            const tlMember = team.members?.find(m => m.id === targetMember.parentMemberId);
+                            // If the caller is NOT the TL, redirect through TL
+                            if (tlMember && tlMember.sessionName !== sessionName) {
+                                return {
+                                    success: false,
+                                    error: `Hierarchy violation: ${to} reports to TL ${tlMember.sessionName} (${tlMember.id}). You must delegate through the TL, not directly. Use send_message to ask ${tlMember.sessionName} to delegate this task to ${to}.`,
+                                    redirectTo: tlMember.sessionName,
+                                    hint: 'Use send_message to the TL with the task details, and ask them to delegate to the worker.',
+                                };
+                            }
+                        }
+                        // Verify caller has canDelegate permission when delegating to a subordinate
+                        if (callerMember && targetMember && callerMember.canDelegate === false) {
+                            return {
+                                success: false,
+                                error: `You (${sessionName}) do not have delegation permission (canDelegate: false). Ask your TL to delegate this task.`,
+                            };
+                        }
+                        // Task stacking prevention — check if target already has in-progress tasks
+                        if (targetMember && targetMember.workingStatus === 'in_progress') {
+                            return {
+                                success: false,
+                                error: `Agent ${to} is already working on a task (workingStatus: in_progress). Wait for current task to complete before delegating a new one.`,
+                                agentStatus: targetMember.agentStatus,
+                                workingStatus: targetMember.workingStatus,
+                            };
+                        }
+                    }
+                }
                 const taskMessage = buildTaskMessage(to, task, priority, context, projectPath);
                 // Deliver the task message
                 const deliverResult = await client.post(`/terminal/${to}/deliver`, {
@@ -232,15 +456,20 @@ export function createTools(client, sessionName, projectPath, callbacks) {
                         taskId = createResult.data.taskId;
                     }
                 }
-                // Subscribe to idle event for monitoring
-                await client.post('/events/subscribe', {
-                    eventType: 'agent:idle',
-                    filter: { sessionName: to },
-                    subscriberSession: sessionName,
-                    oneShot: true,
-                    ttlMinutes: 120,
-                });
-                return { success: true, delegatedTo: to, taskId };
+                // Subscribe to idle event for monitoring (with dedup check)
+                const existingSubs = await client.get(`/events/subscriptions?subscriberSession=${encodeURIComponent(sessionName)}`).catch(() => null);
+                const alreadySubscribed = existingSubs?.success && Array.isArray(existingSubs.data) &&
+                    existingSubs.data.some(sub => sub.eventType === 'agent:idle' && sub.filter?.sessionName === to);
+                if (!alreadySubscribed) {
+                    await client.post('/events/subscribe', {
+                        eventType: 'agent:idle',
+                        filter: { sessionName: to },
+                        subscriberSession: sessionName,
+                        oneShot: true,
+                        ttlMinutes: DELEGATION_SUBSCRIPTION_TTL_MINUTES,
+                    });
+                }
+                return { success: true, delegatedTo: to, taskId, conversationId: conversationId || undefined };
             },
         },
         send_message: {
@@ -306,17 +535,53 @@ export function createTools(client, sessionName, projectPath, callbacks) {
             },
         },
         reply_slack: {
-            description: 'Send a reply to a Slack channel or thread.',
+            description: 'Send a reply to a Slack channel or thread. If channelId is omitted, uses the current Slack thread context. Messages sent within 3 seconds are batched to avoid spam.',
             inputSchema: z.object({
-                channelId: z.string().describe('Slack channel ID'),
+                channelId: z.string().optional().describe('Slack channel ID (auto-filled from current thread context if omitted)'),
                 text: z.string().describe('Message text'),
-                threadTs: z.string().optional().describe('Thread timestamp for replies'),
+                threadTs: z.string().optional().describe('Thread timestamp for replies (auto-filled from current thread context if omitted)'),
             }),
             execute: async ({ channelId, text, threadTs }) => {
-                const body = { channelId: channelId, text: text };
-                if (threadTs)
-                    body.threadTs = threadTs;
+                let cleanText = stripNotifyMarkers(text);
+                // #181: Convert markdown to Slack mrkdwn format
+                cleanText = convertMarkdownToSlackMrkdwn(cleanText);
+                // Auto-prefix with agent display name so Slack messages are attributable
+                // Session format: "crewly-{team}-{name}-{uuid}" → extract {name}
+                // Fallback: "crewly-orc" → "orc"
+                if (sessionName && !cleanText.startsWith('[')) {
+                    const parts = sessionName.split('-');
+                    // For "crewly-product-sam-217bfbbf": parts[2] = "sam"
+                    // For "crewly-orc": parts[1] = "orc"
+                    const namePart = parts.length >= 3 ? parts[2] : parts[parts.length - 1];
+                    const capitalized = namePart.charAt(0).toUpperCase() + namePart.slice(1);
+                    cleanText = `[${capitalized}] ${cleanText}`;
+                }
+                const resolvedChannelId = channelId || slackContext?.channelId;
+                const resolvedThreadTs = threadTs || slackContext?.threadTs;
+                if (!resolvedChannelId) {
+                    return { success: false, error: 'No channelId provided and no Slack thread context available. Use reply_slack with an explicit channelId.' };
+                }
+                // Dedup: skip if this exact message was recently sent
+                if (recentSlackMessages.includes(cleanText)) {
+                    return { success: true, sent: false, deduplicated: true, reason: 'Message already sent recently' };
+                }
+                // Issue 3: Rate-limit Slack messages — throttle within a 3s window
+                const now = Date.now();
+                if (now - lastSlackSendMs < SLACK_THROTTLE_MS) {
+                    return { success: true, sent: false, throttled: true, retryAfterMs: SLACK_THROTTLE_MS - (now - lastSlackSendMs) };
+                }
+                const body = { channelId: resolvedChannelId, text: cleanText };
+                if (resolvedThreadTs)
+                    body.threadTs = resolvedThreadTs;
                 const result = await client.post('/slack/send', body);
+                if (result.success) {
+                    lastSlackSendMs = Date.now();
+                    // Track for dedup
+                    recentSlackMessages.push(cleanText);
+                    if (recentSlackMessages.length > SLACK_DEDUP_WINDOW) {
+                        recentSlackMessages.shift();
+                    }
+                }
                 return result.success
                     ? { success: true, sent: true }
                     : { success: false, error: result.error };
@@ -324,16 +589,27 @@ export function createTools(client, sessionName, projectPath, callbacks) {
         },
         // ===== Scheduling Tools =====
         schedule_check: {
-            description: 'Schedule a future check-in reminder.',
+            description: 'Schedule a future check-in reminder. Include taskId to auto-cancel when the linked task completes. Deduplicates: skips if a similar check already exists for the same target.',
             inputSchema: z.object({
                 minutes: z.number().describe('Minutes from now'),
                 message: z.string().describe('Reminder message'),
                 target: z.string().optional().describe('Target session (defaults to self)'),
                 recurring: z.boolean().default(false),
                 maxOccurrences: z.number().optional(),
+                taskId: z.string().optional().describe('Link to a task ID — recurring check auto-cancels when this task completes'),
             }),
-            execute: async ({ minutes, message, target, recurring, maxOccurrences }) => {
+            execute: async ({ minutes, message, target, recurring, maxOccurrences, taskId }) => {
                 const targetSession = target || sessionName;
+                // Issue 2: Dedup check — list existing scheduled checks for this target
+                const existingResult = await client.get(`/schedule?session=${encodeURIComponent(targetSession)}`).catch(() => null);
+                if (existingResult?.success && Array.isArray(existingResult.data)) {
+                    const msgPrefix = message.slice(0, 50); // Match on message prefix
+                    const isDuplicate = existingResult.data.some(check => check.targetSession === targetSession &&
+                        (check.message?.startsWith(msgPrefix) || (taskId && check.taskId === taskId)));
+                    if (isDuplicate) {
+                        return { success: true, status: 'already_scheduled', targetSession, message };
+                    }
+                }
                 const body = {
                     targetSession,
                     minutes,
@@ -345,6 +621,8 @@ export function createTools(client, sessionName, projectPath, callbacks) {
                 }
                 if (maxOccurrences)
                     body.maxOccurrences = maxOccurrences;
+                if (taskId)
+                    body.taskId = taskId;
                 const result = await client.post('/schedule', body);
                 return result.success ? result.data : { error: result.error };
             },
@@ -359,14 +637,43 @@ export function createTools(client, sessionName, projectPath, callbacks) {
                 return result.success ? { success: true } : { error: result.error };
             },
         },
+        get_scheduled_checks: {
+            description: 'List all active scheduled checks. Use to identify stale or completed checks that should be cancelled.',
+            inputSchema: z.object({
+                session: z.string().optional().describe('Filter by target session name'),
+            }),
+            execute: async ({ session }) => {
+                const endpoint = session
+                    ? `/schedule?session=${encodeURIComponent(session)}`
+                    : '/schedule';
+                const result = await client.get(endpoint);
+                return result.success ? result.data : { error: result.error };
+            },
+        },
         // ===== Agent Lifecycle Tools =====
         start_agent: {
-            description: 'Start a specific agent within a team.',
+            description: 'Start a specific agent within a team. Safely skips if the agent is already active.',
             inputSchema: z.object({
                 teamId: z.string().describe('Team UUID'),
                 memberId: z.string().describe('Member UUID'),
             }),
             execute: async ({ teamId, memberId }) => {
+                // Pre-check: if the agent is already active, return immediately to avoid
+                // timeout and session interruption from redundant start calls
+                const teamResult = await client.get(`/teams/${teamId}`).catch(() => null);
+                if (teamResult?.success && teamResult.data) {
+                    const team = teamResult.data;
+                    const member = team.members?.find(m => m.id === memberId);
+                    if (member && member.agentStatus === 'active' && member.sessionName) {
+                        return {
+                            success: true,
+                            memberName: member.name,
+                            memberId: member.id,
+                            sessionName: member.sessionName,
+                            status: 'already_active',
+                        };
+                    }
+                }
                 const result = await client.post(`/teams/${teamId}/members/${memberId}/start`, {});
                 return result.success ? result.data : { error: result.error };
             },
@@ -384,13 +691,24 @@ export function createTools(client, sessionName, projectPath, callbacks) {
         },
         // ===== Event Tools =====
         subscribe_event: {
-            description: 'Subscribe to agent lifecycle events (e.g., agent:idle, agent:busy).',
+            description: 'Subscribe to agent lifecycle events (e.g., agent:idle, agent:busy). Deduplicates: skips if an identical subscription already exists.',
             inputSchema: z.object({
                 eventType: z.string().describe('Event type (e.g., "agent:idle")'),
                 filter: z.record(z.string()).optional().describe('Event filter criteria'),
                 oneShot: z.boolean().default(true),
             }),
             execute: async ({ eventType, filter, oneShot }) => {
+                // Issue 2: Dedup check — list existing subscriptions and skip if duplicate
+                const existingResult = await client.get(`/events/subscriptions?subscriberSession=${encodeURIComponent(sessionName)}`).catch(() => null);
+                if (existingResult?.success && Array.isArray(existingResult.data)) {
+                    const filterStr = JSON.stringify(filter || {});
+                    const isDuplicate = existingResult.data.some(sub => sub.eventType === eventType &&
+                        sub.subscriberSession === sessionName &&
+                        JSON.stringify(sub.filter || {}) === filterStr);
+                    if (isDuplicate) {
+                        return { success: true, status: 'already_subscribed', eventType, filter };
+                    }
+                }
                 const result = await client.post('/events/subscribe', {
                     eventType,
                     filter: filter || {},
@@ -480,7 +798,7 @@ export function createTools(client, sessionName, projectPath, callbacks) {
             },
         },
         complete_task: {
-            description: 'Mark a task as complete.',
+            description: 'Mark a task as complete. Also cancels any scheduled checks targeting the completing agent session.',
             inputSchema: z.object({
                 absoluteTaskPath: z.string().describe('Absolute path to the task file'),
                 sessionName: z.string().describe('Agent session that completed it'),
@@ -492,7 +810,27 @@ export function createTools(client, sessionName, projectPath, callbacks) {
                     sessionName: agent,
                     summary,
                 });
-                return result.success ? result.data : { error: result.error };
+                // Auto-cancel scheduled checks targeting the completing agent
+                // to prevent stale recurring checks from firing after task completion
+                let cancelledChecks = 0;
+                try {
+                    const checksResult = await client.get(`/schedule?session=${encodeURIComponent(agent)}`);
+                    if (checksResult.success && Array.isArray(checksResult.data)) {
+                        for (const check of checksResult.data) {
+                            if (check.isRecurring) {
+                                await client.delete(`/schedule/${check.id}`);
+                                cancelledChecks++;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Non-fatal: task completion succeeded even if check cleanup fails
+                }
+                if (result.success) {
+                    return { ...result.data, cancelledChecks };
+                }
+                return { error: result.error };
             },
         },
         broadcast: {
@@ -605,15 +943,30 @@ export function createTools(client, sessionName, projectPath, callbacks) {
             },
         },
         read_file: {
-            description: 'Read the contents of a file. Returns the file content as a string.',
+            description: 'Read the contents of a file. Returns text content with line numbers, or base64-encoded image data for image files (png/jpg/gif/webp/svg). Image files are returned as multimodal content parts for AI SDK.',
             inputSchema: z.object({
                 file_path: z.string().describe('Absolute path to the file to read'),
-                offset: z.number().optional().describe('Line number to start reading from (1-based)'),
-                limit: z.number().optional().describe('Maximum number of lines to read'),
+                offset: z.number().optional().describe('Line number to start reading from (1-based, text files only)'),
+                limit: z.number().optional().describe('Maximum number of lines to read (text files only)'),
             }),
             execute: async ({ file_path, offset, limit }) => {
                 const fp = expandPath(file_path);
                 try {
+                    // Check if this is an image file
+                    const ext = fp.split('.').pop()?.toLowerCase() || '';
+                    if (IMAGE_EXTENSIONS.has(ext)) {
+                        const buffer = await fsPromises.readFile(fp);
+                        const base64 = buffer.toString('base64');
+                        const mimeType = IMAGE_MIME_TYPES[ext] || 'application/octet-stream';
+                        return {
+                            success: true,
+                            type: 'image',
+                            mimeType,
+                            data: base64,
+                            file: fp,
+                            sizeBytes: buffer.length,
+                        };
+                    }
                     const content = await fsPromises.readFile(fp, 'utf8');
                     const lines = content.split('\n');
                     if (offset || limit) {
@@ -686,20 +1039,39 @@ export function createTools(client, sessionName, projectPath, callbacks) {
             },
         },
         report_status: {
-            description: 'Report task status to the orchestrator.',
+            description: 'Report task status to the orchestrator. sessionName and role are auto-injected from the current session context.',
             inputSchema: z.object({
                 status: z.enum(['in_progress', 'done', 'blocked', 'error']).describe('Current status'),
                 summary: z.string().describe('Brief status summary'),
             }),
             execute: async ({ status, summary }) => {
-                const body = {
-                    sessionName,
-                    status,
-                    summary,
+                // Build status message matching the bash report-status format
+                const statusUpper = status.toUpperCase();
+                const message = `[${statusUpper}] Agent ${sessionName}: ${summary}`;
+                // Send to orchestrator via chat API (matches bash skill behavior)
+                const chatBody = {
+                    content: message,
+                    senderName: sessionName,
+                    senderType: 'agent',
                 };
-                if (projectPath)
-                    body.projectPath = projectPath;
-                const result = await client.post('/teams/members/register', body);
+                if (conversationId) {
+                    chatBody.conversationId = conversationId;
+                }
+                const result = await client.post('/chat/agent-response', chatBody);
+                // Auto-complete tracked tasks when status is done
+                if (status === 'done') {
+                    await client.post('/task-management/complete-by-session', { sessionName }).catch(() => { });
+                }
+                // Auto-persist key findings as project knowledge when done (#127)
+                if (status === 'done' && summary && projectPath) {
+                    await client.post('/memory/remember', {
+                        agentId: sessionName,
+                        content: `Task completed by ${sessionName}: ${summary}`,
+                        category: 'pattern',
+                        scope: 'project',
+                        projectPath,
+                    }).catch(() => { });
+                }
                 return result.success ? result.data : { error: result.error };
             },
         },
@@ -719,6 +1091,18 @@ export function createTools(client, sessionName, projectPath, callbacks) {
                 };
             },
         },
+        get_context_budget: {
+            description: 'Check current context window token budget usage. Returns total tokens used, context window size, usage percentage, and warning level (normal/warning/critical). Use proactively to decide when to compact or wrap up work.',
+            inputSchema: z.object({}),
+            sensitivity: 'safe',
+            execute: async () => {
+                if (!callbacks?.onGetContextBudget) {
+                    return { success: false, error: 'Context budget tracking not available — no runner callback configured' };
+                }
+                const budget = callbacks.onGetContextBudget();
+                return { success: true, ...budget };
+            },
+        },
         // ===== Security Audit Tool =====
         get_audit_log: {
             description: 'Retrieve the security audit trail of recent tool invocations. Shows tool name, sensitivity classification, success/failure, duration, and sanitized arguments. Use for security review, debugging, or compliance.',
@@ -729,16 +1113,237 @@ export function createTools(client, sessionName, projectPath, callbacks) {
             }),
             sensitivity: 'safe',
             execute: async ({ limit, sensitivity: filterSensitivity, toolName: filterTool }) => {
-                // Audit log is maintained by the runner via callbacks
-                // This tool returns a formatted view — actual data comes from the runner
+                if (!callbacks?.onGetAuditLog) {
+                    return {
+                        success: false,
+                        error: 'Audit log not available — no runner callback configured',
+                    };
+                }
+                const filters = {
+                    limit: limit || 50,
+                    sensitivity: filterSensitivity,
+                    toolName: filterTool,
+                };
+                const entries = callbacks.onGetAuditLog(filters);
                 return {
                     success: true,
-                    note: 'Audit log is maintained in the agent runner. Use the runner getAuditLog() method for programmatic access.',
+                    totalEntries: entries.length,
                     filters: {
-                        limit: limit || 50,
-                        sensitivity: filterSensitivity || 'all',
-                        toolName: filterTool || 'all',
+                        limit: filters.limit,
+                        sensitivity: filters.sensitivity || 'all',
+                        toolName: filters.toolName || 'all',
                     },
+                    entries,
+                };
+            },
+        },
+        // ===================================================================
+        // Shell Execution (#176)
+        // ===================================================================
+        bash_exec: {
+            description: 'Execute a shell command and return stdout/stderr. Commands run with a timeout (default 30s, max 120s). Use for build, test, lint, and system operations. Some commands (kill, reboot, rm -rf /, etc.) are blocked by security policy.',
+            inputSchema: z.object({
+                command: z.string().describe('Shell command to execute'),
+                cwd: z.string().optional().describe('Working directory (defaults to project path)'),
+                timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000, max: 120000)'),
+            }),
+            sensitivity: 'destructive',
+            execute: async ({ command, cwd, timeout }) => {
+                const cmd = command;
+                // Check command against blocklist before execution
+                const blockReason = validateBashCommand(cmd);
+                if (blockReason) {
+                    return {
+                        success: false,
+                        exitCode: 126,
+                        stdout: '',
+                        stderr: blockReason,
+                        error: blockReason,
+                    };
+                }
+                // Check if command requires explicit approval (git push, rm, docker, network, etc.)
+                const approvalLabel = checkBashApprovalRequired(cmd);
+                if (approvalLabel && callbacks?.onEnqueueApproval) {
+                    const sanitizedArgs = sanitizeArgs({ command: cmd, cwd, timeout });
+                    const enqueued = callbacks.onEnqueueApproval('bash_exec', 'destructive', sanitizedArgs);
+                    return {
+                        success: false,
+                        requiresApproval: true,
+                        approvalId: enqueued.approvalId,
+                        reason: `Command requires approval: ${approvalLabel}`,
+                        error: `Approval required for: ${approvalLabel}. Approval ID: ${enqueued.approvalId}`,
+                    };
+                }
+                const workDir = expandPath(cwd || projectPath || process.cwd());
+                const timeoutMs = Math.min(timeout || 30000, 120000);
+                // Run in isolated process group to prevent signal propagation
+                const result = execIsolated(cmd, workDir, timeoutMs);
+                if (result.exitCode === 0) {
+                    const truncated = result.stdout.length > 10000;
+                    return {
+                        success: true,
+                        exitCode: 0,
+                        stdout: truncated ? result.stdout.slice(-10000) + '\n...(truncated)' : result.stdout,
+                        truncated,
+                    };
+                }
+                return {
+                    success: false,
+                    exitCode: result.exitCode,
+                    stdout: (result.stdout || '').slice(-5000),
+                    stderr: (result.stderr || '').slice(-5000),
+                    error: result.stderr ? result.stderr.slice(0, 500) : `Process exited with code ${result.exitCode}`,
+                };
+            },
+        },
+        // ===================================================================
+        // Git Tools (#176)
+        // ===================================================================
+        git_status: {
+            description: 'Get the git status of a project directory. Returns current branch, staged files, unstaged changes, and untracked files.',
+            inputSchema: z.object({
+                projectPath: z.string().describe('Absolute path to the git repository'),
+            }),
+            execute: async ({ projectPath }) => {
+                const cwd = expandPath(projectPath);
+                try {
+                    const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd, encoding: 'utf8' }).trim();
+                    const statusOutput = execSync('git status --porcelain', { cwd, encoding: 'utf8' });
+                    const staged = [];
+                    const unstaged = [];
+                    const untracked = [];
+                    for (const line of statusOutput.split('\n')) {
+                        if (!line.trim())
+                            continue;
+                        const x = line[0]; // index status
+                        const y = line[1]; // working tree status
+                        const file = line.slice(3);
+                        if (x === '?' && y === '?') {
+                            untracked.push(file);
+                        }
+                        else {
+                            if (x !== ' ' && x !== '?')
+                                staged.push(file);
+                            if (y !== ' ' && y !== '?')
+                                unstaged.push(file);
+                        }
+                    }
+                    return { success: true, branch, staged, unstaged, untracked };
+                }
+                catch (error) {
+                    return { success: false, error: error instanceof Error ? error.message : String(error) };
+                }
+            },
+        },
+        git_diff: {
+            description: 'Get the git diff output for a project directory. Shows unstaged changes by default, or staged changes when staged=true. Output truncated to 5000 characters.',
+            inputSchema: z.object({
+                projectPath: z.string().describe('Absolute path to the git repository'),
+                staged: z.boolean().default(false).describe('Show staged (cached) changes instead of unstaged'),
+            }),
+            execute: async ({ projectPath, staged }) => {
+                const cwd = expandPath(projectPath);
+                try {
+                    const cmd = staged ? 'git diff --cached' : 'git diff';
+                    const diff = execSync(cmd, { cwd, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+                    const truncated = diff.length > GIT_DIFF_MAX_CHARS;
+                    const output = truncated ? diff.slice(0, GIT_DIFF_MAX_CHARS) + '\n... (truncated)' : diff;
+                    return { success: true, diff: output, truncated, totalLength: diff.length };
+                }
+                catch (error) {
+                    return { success: false, error: error instanceof Error ? error.message : String(error) };
+                }
+            },
+        },
+        git_commit: {
+            description: 'Stage files and create a git commit. If files are provided, stages only those files. Otherwise stages all changes (git add -A). Returns the new commit hash.',
+            inputSchema: z.object({
+                projectPath: z.string().describe('Absolute path to the git repository'),
+                message: z.string().describe('Commit message'),
+                files: z.array(z.string()).optional().describe('Specific files to stage (omit for git add -A)'),
+            }),
+            sensitivity: 'sensitive',
+            execute: async ({ projectPath, message, files }) => {
+                const cwd = expandPath(projectPath);
+                try {
+                    // Stage files
+                    if (files && files.length > 0) {
+                        for (const file of files) {
+                            execSync(`git add -- ${JSON.stringify(file)}`, { cwd, encoding: 'utf8' });
+                        }
+                    }
+                    else {
+                        execSync('git add -A', { cwd, encoding: 'utf8' });
+                    }
+                    // Commit
+                    execSync(`git commit -m ${JSON.stringify(message)}`, { cwd, encoding: 'utf8' });
+                    // Get the commit hash
+                    const hash = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8' }).trim();
+                    return { success: true, commitHash: hash, message: message };
+                }
+                catch (error) {
+                    return { success: false, error: error instanceof Error ? error.message : String(error) };
+                }
+            },
+        },
+        // ===================================================================
+        // Task Handoff (F12)
+        // ===================================================================
+        handoff_task: {
+            description: 'Hand off an in-progress task to another agent with full context (progress, findings, blockers). Unlike delegate_task which assigns NEW work, handoff transfers ONGOING work so the receiving agent can continue where you left off.',
+            inputSchema: z.object({
+                to: z.string().describe('Target agent session name to hand off to'),
+                reason: z.string().describe('Why you are handing off (blocked, expertise needed, etc.)'),
+                progress: z.string().optional().describe('Current progress summary (what is done so far)'),
+                findings: z.string().optional().describe('Key findings and decisions made'),
+                blockers: z.string().optional().describe('Current blockers or notes for the receiving agent'),
+                taskPath: z.string().optional().describe('Path to the task markdown file'),
+            }),
+            sensitivity: 'sensitive',
+            execute: async ({ to, reason, progress, findings, blockers, taskPath }) => {
+                const target = to;
+                const handoffReason = reason;
+                // Build handoff context message
+                let message = `[TASK HANDOFF] from ${sessionName}\n\n## Reason\n${handoffReason}\n`;
+                if (progress)
+                    message += `\n## Progress\n${progress}\n`;
+                if (findings)
+                    message += `\n## Key Findings\n${findings}\n`;
+                if (blockers)
+                    message += `\n## Blockers / Notes\n${blockers}\n`;
+                if (taskPath)
+                    message += `\n## Task File\n${taskPath}\n`;
+                if (projectPath) {
+                    message += `\n---\nWhen done, report back using: bash config/skills/agent/core/report-status/execute.sh '{"sessionName":"${target}","status":"done","summary":"<brief summary>","projectPath":"${projectPath}"}'`;
+                }
+                // Deliver to target agent
+                const deliverResult = await client.post(`/terminal/${target}/deliver`, {
+                    message,
+                    waitForReady: true,
+                    waitTimeout: 15000,
+                }).catch(async () => {
+                    // Retry with force
+                    return client.post(`/terminal/${target}/deliver`, { message, force: true });
+                });
+                // Record handoff via task management
+                const handoffRecord = await client.post('/task-management/handoff', {
+                    from: sessionName,
+                    to: target,
+                    taskPath: taskPath || '',
+                    reason: handoffReason,
+                    progress: progress || '',
+                    projectPath: projectPath || '',
+                }).catch(() => ({ success: false, error: 'handoff tracking not available' }));
+                return {
+                    success: deliverResult?.success ?? false,
+                    handoff: {
+                        from: sessionName,
+                        to: target,
+                        reason: handoffReason,
+                        timestamp: new Date().toISOString(),
+                    },
+                    delivery: deliverResult?.success ? 'delivered' : (deliverResult?.error || 'failed'),
+                    tracking: handoffRecord?.success ? 'tracked' : 'not tracked',
                 };
             },
         },
@@ -752,6 +1357,15 @@ export function createTools(client, sessionName, projectPath, callbacks) {
             execute: wrapWithAudit(name, tool.execute, callbacks),
         };
     }
+    // Merge MCP-sourced tools with audit wrapping
+    if (mcpTools) {
+        for (const [name, tool] of Object.entries(mcpTools)) {
+            tools[name] = {
+                ...tool,
+                execute: wrapWithAudit(name, tool.execute, callbacks),
+            };
+        }
+    }
     return tools;
 }
 /**
@@ -782,11 +1396,12 @@ export function getToolNames() {
     return [
         'delegate_task', 'send_message', 'get_agent_status', 'get_team_status',
         'get_agent_logs', 'reply_slack', 'schedule_check', 'cancel_schedule',
-        'start_agent', 'stop_agent', 'subscribe_event', 'recall_memory',
-        'remember', 'heartbeat', 'get_tasks', 'complete_task', 'broadcast',
-        'handle_agent_failure', 'edit_file', 'read_file', 'write_file',
+        'get_scheduled_checks', 'start_agent', 'stop_agent', 'subscribe_event',
+        'recall_memory', 'remember', 'heartbeat', 'get_tasks', 'complete_task',
+        'broadcast', 'handle_agent_failure', 'edit_file', 'read_file', 'write_file',
         'register_self', 'get_project_overview', 'report_status',
         'compact_memory', 'get_audit_log',
+        'git_status', 'git_diff', 'git_commit',
     ];
 }
 //# sourceMappingURL=tool-registry.js.map