@cdoing/core 0.1.0

package/src/tools/sub-agent.ts

@@ -0,0 +1,162 @@
+/**
+ * Sub-Agent Tool — allows the agent to spawn child agents for parallel research.
+ *
+ * The sub-agent gets its own conversation context and the same tools,
+ * but cannot spawn further sub-agents (prevents infinite recursion).
+ *
+ * Security:
+ *  - Sub-agents inherit the parent's PermissionManager — all tool calls
+ *    inside the child go through the same deny/ask/allow rules.
+ *  - Task descriptions are screened for destructive intent patterns.
+ *  - Permission prompt shows a ⚠ warning for destructive tasks.
+ *
+ * Features:
+ *  - Custom timeout (useful for long-running tasks like npm install)
+ *  - Background mode (returns agent ID immediately, check status later)
+ *  - Foreground mode (waits for completion, default)
+ */
+
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { SubAgentManager } from "./sub-agent-manager";
+
+// ── Destructive task detection ──────────────────────────────────────────────
+
+/**
+ * Patterns in task descriptions that indicate destructive intent.
+ * These trigger an elevated permission prompt (⚠ DESTRUCTIVE) so the
+ * user is clearly warned before the sub-agent is spawned.
+ */
+const DESTRUCTIVE_TASK_PATTERNS = [
+  // File deletion
+  /\bdelete\b.*\bfiles?\b/i, /\bremove\b.*\bfiles?\b/i, /\brm\s+-rf\b/i,
+  /\bwipe\b/i, /\bpurge\b/i, /\bclean\s*up\b/i, /\bnuke\b/i,
+  // Git destructive
+  /\bforce\s*push\b/i, /\bgit\s+reset\s+--hard\b/i, /\bgit\s+clean\b/i,
+  /\brewrite\s+history\b/i, /\bdelete\b.*\bbranch/i,
+  // Database
+  /\bdrop\b.*\b(table|database|collection)\b/i, /\btruncate\b/i,
+  // System
+  /\bkill\b.*\bprocess/i, /\bshutdown\b/i, /\brestart\b.*\bserver/i,
+  /\bformat\b.*\bdisk\b/i,
+  // Destructive ops
+  /\boverwrite\b/i, /\bdestroy\b/i, /\buninstall\b/i,
+  /\bdrop\b.*\bpermission/i, /\brevoke\b/i,
+];
+
+/**
+ * Factory function signature for creating sub-agent runners.
+ * Now accepts an AbortSignal so the parent can cancel child agents.
+ */
+export interface SubAgentRunnerFactory {
+  (prompt: string, signal?: AbortSignal): Promise<string>;
+}
+
+export class SubAgentTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "sub_agent",
+    description:
+      "Spawn a sub-agent to handle a specific task. The sub-agent has access to the same file and search tools but runs in its own context. Use this for independent tasks like 'find all usages of X', 'read and summarize file Y', or long-running commands like 'npm install'. Supports custom timeout and background mode. The sub-agent cannot spawn further sub-agents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: "A clear, specific task for the sub-agent to perform",
+        },
+        timeout: {
+          type: "number",
+          description:
+            "Custom timeout in milliseconds. Use for long-running tasks (e.g., 300000 for 5 minutes). Default: no timeout (runs until completion).",
+        },
+        background: {
+          type: "boolean",
+          description:
+            "If true, returns immediately with an agent ID. Use sub_agent_status to check progress and sub_agent_terminate to stop it. Default: false (waits for completion).",
+        },
+      },
+      required: ["task"],
+    },
+    requiresPermission: true,
+    permissionMessage: (input) => {
+      const task = String(input.task || "").slice(0, 200);
+      if (DESTRUCTIVE_TASK_PATTERNS.some((p) => p.test(task))) {
+        return `⚠ DESTRUCTIVE sub-agent task: ${task}`;
+      }
+      return `Spawn sub-agent: ${task}`;
+    },
+  };
+
+  private runnerFactory: SubAgentRunnerFactory;
+  private manager: SubAgentManager;
+
+  constructor(runnerFactory: SubAgentRunnerFactory, manager: SubAgentManager) {
+    this.runnerFactory = runnerFactory;
+    this.manager = manager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const task = input.task as string;
+    const timeout = input.timeout as number | undefined;
+    const background = input.background as boolean | undefined;
+
+    if (!task || task.trim().length === 0) {
+      return { success: false, output: "", error: "Task cannot be empty" };
+    }
+
+    // Prepend a safety instruction if the task looks destructive.
+    // The sub-agent inherits the parent's PermissionManager so each tool call
+    // will still go through deny/ask/allow checks, but this extra context
+    // makes the LLM aware it should proceed cautiously.
+    const isDestructive = DESTRUCTIVE_TASK_PATTERNS.some((p) => p.test(task));
+    const safeTask = isDestructive
+      ? `[CAUTION: This task involves potentially destructive operations. ` +
+        `You MUST ask for explicit user confirmation before executing any ` +
+        `destructive commands (rm, delete, drop, force push, reset --hard, etc.). ` +
+        `Prefer safe alternatives when possible.]\n\n${task}`
+      : task;
+
+    const runnerFn = (signal: AbortSignal) => this.runnerFactory(safeTask, signal);
+
+    if (background) {
+      // Background mode: return immediately with agent ID
+      const agentId = this.manager.spawn(task, runnerFn, timeout);
+      return {
+        success: true,
+        output: JSON.stringify({
+          agent_id: agentId,
+          status: "running",
+          message: `Sub-agent spawned in background. Use sub_agent_status with agent_id "${agentId}" to check progress, or sub_agent_terminate to stop it.`,
+        }),
+      };
+    }
+
+    // Foreground mode: wait for completion
+    try {
+      const entry = await this.manager.spawnAndWait(task, runnerFn, timeout);
+
+      if (entry.status === "completed") {
+        return {
+          success: true,
+          output: entry.output || "(sub-agent returned no output)",
+        };
+      }
+
+      if (entry.status === "timed_out") {
+        return {
+          success: false,
+          output: entry.output || "",
+          error: `Sub-agent timed out after ${timeout}ms. Partial output (if any) is included. You can retry with a longer timeout or run in background mode.`,
+        };
+      }
+
+      return {
+        success: false,
+        output: entry.output || "",
+        error: `Sub-agent ${entry.status}: ${entry.error || "unknown error"}`,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { success: false, output: "", error: `Sub-agent failed: ${message}` };
+    }
+  }
+}

package/src/tools/system-info.ts

@@ -0,0 +1,248 @@
+/**
+ * System Info Tool — gives the LLM runtime awareness of its own
+ * permission mode, settings rules, sandbox config, and available tools.
+ *
+ * This replaces hardcoded permission docs in the system prompt with
+ * a live, queryable tool the agent can call at any time.
+ */
+
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import type { PermissionManager } from "../permissions";
+import type { SandboxManager } from "../sandbox";
+import type { ToolRegistry } from "./registry";
+
+export class SystemInfoTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "system_info",
+    description:
+      "Get information about your current permissions, sandbox restrictions, available tools, and system configuration. Call this when you need to understand what you can or cannot do, or when the user asks about your access level. No arguments required — returns a full status report.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        section: {
+          type: "string",
+          description:
+            "Optional: request a specific section. Values: 'permissions', 'sandbox', 'tools', 'all'. Default: 'all'.",
+        },
+      },
+      required: [],
+    },
+    requiresPermission: false,
+  };
+
+  private permissionManager: PermissionManager;
+  private sandboxManager?: SandboxManager;
+  private toolRegistry: ToolRegistry;
+
+  constructor(
+    permissionManager: PermissionManager,
+    toolRegistry: ToolRegistry,
+    sandboxManager?: SandboxManager,
+  ) {
+    this.permissionManager = permissionManager;
+    this.toolRegistry = toolRegistry;
+    this.sandboxManager = sandboxManager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const section = (input.section as string) || "all";
+    const parts: string[] = [];
+
+    if (section === "all" || section === "permissions") {
+      parts.push(this.buildPermissionsSection());
+    }
+    if (section === "all" || section === "sandbox") {
+      parts.push(this.buildSandboxSection());
+    }
+    if (section === "all" || section === "tools") {
+      parts.push(this.buildToolsSection());
+    }
+
+    return { success: true, output: parts.join("\n\n") };
+  }
+
+  private buildPermissionsSection(): string {
+    const mode = this.permissionManager.getMode();
+    const rules = this.permissionManager.getSettingsRules();
+    const stored = this.permissionManager.getStoredRules();
+
+    const lines: string[] = [
+      "## Permission System Status",
+      "",
+      `**Current Mode:** ${mode}`,
+      this.describeModeEffect(mode),
+      "",
+    ];
+
+    // Settings rules
+    if (rules.deny.length || rules.allow.length || rules.ask.length) {
+      lines.push("### Settings Rules (from .claude/settings.json)");
+      lines.push("Rules are evaluated: deny → ask → allow. Deny always wins.");
+      lines.push("");
+      if (rules.deny.length) {
+        lines.push("**Deny (always blocked):**");
+        for (const r of rules.deny) lines.push(`  - ${r}`);
+      }
+      if (rules.ask.length) {
+        lines.push("**Ask (prompt user, even if allow matches):**");
+        for (const r of rules.ask) lines.push(`  - ${r}`);
+      }
+      if (rules.allow.length) {
+        lines.push("**Allow (auto-approved):**");
+        for (const r of rules.allow) lines.push(`  - ${r}`);
+      }
+      lines.push("");
+    } else {
+      lines.push("No settings-based rules configured. All tool calls fall through to the mode-based behavior.");
+      lines.push("");
+    }
+
+    // Stored rules
+    const globalCount = stored.global.length;
+    const projectCount = stored.project.length;
+    if (globalCount || projectCount) {
+      lines.push("### Previously Approved Rules");
+      if (globalCount) {
+        lines.push(`Global (always): ${globalCount} rule(s)`);
+        for (const r of stored.global) {
+          lines.push(`  - ${r.tool}${r.inputMatch ? ` (${r.inputMatch})` : ""}`);
+        }
+      }
+      if (projectCount) {
+        lines.push(`Project: ${projectCount} rule(s)`);
+        for (const r of stored.project) {
+          lines.push(`  - ${r.tool}${r.inputMatch ? ` (${r.inputMatch})` : ""}`);
+        }
+      }
+      lines.push("");
+    }
+
+    // Decision flow
+    lines.push("### Decision Flow");
+    lines.push("When you call a tool, the system evaluates in this order:");
+    lines.push("1. Bypass mode → allow all");
+    lines.push("2. Tool doesn't require permission (file_read, glob_search, grep_search, system_info) → allow");
+    lines.push("3. Settings deny rule matches → BLOCKED");
+    lines.push("4. Settings ask rule matches → prompt user");
+    lines.push("5. Settings allow rule matches → auto-approve");
+    lines.push("6. Previously approved stored rule → auto-approve");
+    lines.push("7. Mode fallback (plan blocks writes, acceptEdits allows edits, default prompts user)");
+
+    return lines.join("\n");
+  }
+
+  private describeModeEffect(mode: string): string {
+    switch (mode) {
+      case "default":
+        return "Effect: You must get user approval for every write/exec tool call. Read-only tools (file_read, glob_search, grep_search) work freely.";
+      case "acceptEdits":
+        return "Effect: File writes and edits are auto-approved. Shell commands and file_run still require user approval.";
+      case "plan":
+        return "Effect: READ-ONLY mode. file_write, file_edit, shell_exec, and file_run are completely blocked. You can only read files and search code.";
+      case "dontAsk":
+        return "Effect: Everything is denied unless it matches an explicit allow rule in settings. No user prompts are shown.";
+      case "bypassPermissions":
+        return "Effect: All tools are auto-approved without any prompts. The user has opted into this unsafe mode.";
+      default:
+        return `Effect: Unknown mode "${mode}" — behaves like default.`;
+    }
+  }
+
+  private buildSandboxSection(): string {
+    const lines: string[] = ["## Sandbox Status", ""];
+
+    if (!this.sandboxManager || !this.sandboxManager.isEnabled()) {
+      lines.push("**Sandbox: DISABLED**");
+      lines.push("No filesystem or network restrictions are enforced beyond the permission system.");
+      return lines.join("\n");
+    }
+
+    const config = this.sandboxManager.getConfig();
+    lines.push(`**Sandbox: ENABLED (${config.mode} mode)**`);
+    lines.push("");
+
+    // Mode explanation
+    if (config.mode === "auto-allow") {
+      lines.push("Mode: **auto-allow** — Commands that pass sandbox checks are auto-approved without a permission prompt.");
+    } else {
+      lines.push("Mode: **regular** — Sandbox enforces restrictions, but permission prompts are still shown.");
+    }
+    lines.push("");
+
+    // Filesystem
+    lines.push("### Filesystem Restrictions");
+    lines.push("Writes are allowed to: the working directory" +
+      (config.filesystem.allowWrite.length ? ` + ${config.filesystem.allowWrite.join(", ")}` : " (only)"));
+
+    if (config.filesystem.denyWrite.length) {
+      lines.push("Writes DENIED to: " + config.filesystem.denyWrite.join(", "));
+    }
+    if (config.filesystem.denyRead.length) {
+      lines.push("Reads DENIED from: " + config.filesystem.denyRead.join(", "));
+    }
+    if (!config.filesystem.denyWrite.length && !config.filesystem.denyRead.length) {
+      lines.push("No explicit deny rules for filesystem paths.");
+    }
+    lines.push("");
+
+    // Network
+    lines.push("### Network Restrictions");
+    if (config.network.allowedDomains.length) {
+      lines.push("Allowed domains: " + config.network.allowedDomains.join(", "));
+    } else {
+      lines.push("No domains pre-allowed.");
+    }
+    if (config.network.allowManagedDomainsOnly) {
+      lines.push("Policy: **strict** — non-allowed domains are blocked silently (no user prompt).");
+    } else {
+      lines.push("Policy: **prompt** — non-allowed domains trigger a user prompt for approval.");
+    }
+    lines.push("");
+
+    // Excluded commands
+    if (config.excludedCommands.length) {
+      lines.push("### Excluded Commands (bypass sandbox, still need permission)");
+      lines.push(config.excludedCommands.join(", "));
+      lines.push("");
+    }
+
+    // Escape hatch
+    lines.push(`dangerouslyDisableSandbox: ${config.allowUnsandboxedCommands ? "available (user allows)" : "DISABLED (blocked by user)"}`);
+
+    return lines.join("\n");
+  }
+
+  private buildToolsSection(): string {
+    const tools = this.toolRegistry.getAll();
+    const lines: string[] = ["## Available Tools", ""];
+
+    const permissionRequired: string[] = [];
+    const noPermission: string[] = [];
+
+    for (const tool of tools) {
+      const def = tool.definition;
+      const entry = `- **${def.name}**: ${def.description.split(".")[0]}.`;
+      if (def.requiresPermission) {
+        permissionRequired.push(entry);
+      } else {
+        noPermission.push(entry);
+      }
+    }
+
+    if (noPermission.length) {
+      lines.push("### Free to use (no permission needed):");
+      lines.push(...noPermission);
+      lines.push("");
+    }
+
+    if (permissionRequired.length) {
+      lines.push("### Requires permission:");
+      lines.push(...permissionRequired);
+      lines.push("");
+    }
+
+    lines.push(`Total: ${tools.length} tools (${noPermission.length} free, ${permissionRequired.length} permission-required)`);
+
+    return lines.join("\n");
+  }
+}

package/src/tools/todo.ts

@@ -0,0 +1,149 @@
+/**
+ * Todo Tool
+ *
+ * Allows the LLM to create, update, and manage tasks during a session.
+ * This helps users see what the agent is working on and track progress.
+ */
+
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { TodoStore, type TodoStatus } from "../utils/todo";
+
+export class TodoTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "todo",
+    description: `Manage tasks for the current session. Use this to:
+- Create tasks to track what needs to be done
+- Update task status as you work (pending -> in_progress -> completed)
+- Help the user see your progress
+
+Actions:
+- create: Create a new task (returns task ID)
+- update: Update a task's status or details
+- list: Show all tasks
+- delete: Remove a task
+
+Always mark tasks as in_progress when starting work, and completed when done.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["create", "update", "list", "delete"],
+          description: "The action to perform",
+        },
+        subject: {
+          type: "string",
+          description: "Task title (for create)",
+        },
+        description: {
+          type: "string",
+          description: "Task description (for create/update)",
+        },
+        id: {
+          type: "string",
+          description: "Task ID (for update/delete)",
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed", "blocked"],
+          description: "Task status (for update)",
+        },
+      },
+      required: ["action"],
+    },
+    requiresPermission: false,
+  };
+
+  constructor(private todoStore: TodoStore) {}
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const action = input.action as string;
+
+    switch (action) {
+      case "create": {
+        const subject = input.subject as string;
+        if (!subject) {
+          return { success: false, output: "", error: "Subject is required for create" };
+        }
+        const description = input.description as string | undefined;
+        const todo = this.todoStore.create(subject, description);
+        return {
+          success: true,
+          output: `Created task #${todo.id}: ${todo.subject}`,
+        };
+      }
+
+      case "update": {
+        const id = input.id as string;
+        if (!id) {
+          return { success: false, output: "", error: "Task ID is required for update" };
+        }
+        const todo = this.todoStore.get(id);
+        if (!todo) {
+          return { success: false, output: "", error: `Task #${id} not found` };
+        }
+
+        const updates: Partial<{ subject: string; description: string; status: TodoStatus }> = {};
+        if (input.status) updates.status = input.status as TodoStatus;
+        if (input.subject) updates.subject = input.subject as string;
+        if (input.description) updates.description = input.description as string;
+
+        const updated = this.todoStore.update(id, updates);
+        if (!updated) {
+          return { success: false, output: "", error: `Failed to update task #${id}` };
+        }
+
+        const statusIcon = this.getStatusIcon(updated.status);
+        return {
+          success: true,
+          output: `Updated task #${id}: ${statusIcon} ${updated.subject} [${updated.status}]`,
+        };
+      }
+
+      case "list": {
+        const todos = this.todoStore.getAll();
+        if (todos.length === 0) {
+          return { success: true, output: "No tasks" };
+        }
+
+        const lines = todos.map(t => {
+          const icon = this.getStatusIcon(t.status);
+          const desc = t.description ? ` - ${t.description}` : "";
+          return `${icon} #${t.id} [${t.status}] ${t.subject}${desc}`;
+        });
+
+        const summary = this.todoStore.getSummary();
+        lines.push("");
+        lines.push(`Summary: ${summary.completed}/${summary.total} completed`);
+        if (summary.in_progress > 0) lines.push(`  In progress: ${summary.in_progress}`);
+        if (summary.blocked > 0) lines.push(`  Blocked: ${summary.blocked}`);
+
+        return { success: true, output: lines.join("\n") };
+      }
+
+      case "delete": {
+        const id = input.id as string;
+        if (!id) {
+          return { success: false, output: "", error: "Task ID is required for delete" };
+        }
+        const deleted = this.todoStore.delete(id);
+        if (!deleted) {
+          return { success: false, output: "", error: `Task #${id} not found` };
+        }
+        return { success: true, output: `Deleted task #${id}` };
+      }
+
+      default:
+        return { success: false, output: "", error: `Unknown action: ${action}` };
+    }
+  }
+
+  private getStatusIcon(status: TodoStatus): string {
+    switch (status) {
+      case "pending": return "[ ]";
+      case "in_progress": return "[~]";
+      case "completed": return "[x]";
+      case "blocked": return "[!]";
+    }
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,21 @@
+/** Schema for a tool the agent can call */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>; // JSON Schema
+  requiresPermission: boolean;
+  permissionMessage?: (input: Record<string, unknown>) => string;
+}
+
+/** Result returned after executing a tool */
+export interface ToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+}
+
+/** Every tool implements this interface */
+export interface BaseTool {
+  definition: ToolDefinition;
+  execute(input: Record<string, unknown>): Promise<ToolResult>;
+}

package/src/tools/view-diff.ts

@@ -0,0 +1,99 @@
+/**
+ * View Diff Tool — show git diff (working changes, staged, between commits).
+ */
+
+import { exec } from "child_process";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+
+export class ViewDiffTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "view_diff",
+    description:
+      `Show git diff of changes. Supports working changes, staged changes, and diff between commits/branches.
+
+Examples:
+- No args: shows unstaged working changes
+- staged=true: shows staged changes (what would be committed)
+- target="main": diff between current branch and main
+- target="HEAD~3": diff against 3 commits ago
+- file_path="src/app.ts": diff for a specific file only`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        staged: {
+          type: "boolean",
+          description: "Show staged changes instead of working changes. Default: false.",
+        },
+        target: {
+          type: "string",
+          description: "Compare against a branch, commit, or ref. E.g. 'main', 'HEAD~1', 'abc123'.",
+        },
+        file_path: {
+          type: "string",
+          description: "Limit diff to a specific file or directory.",
+        },
+      },
+      required: [],
+    },
+    requiresPermission: false,
+  };
+
+  private workingDir: string;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const staged = (input.staged as boolean) || false;
+    const target = (input.target as string) || "";
+    const filePath = (input.file_path as string) || "";
+
+    // Build git diff command
+    const parts = ["git", "diff"];
+
+    if (staged && !target) {
+      parts.push("--cached");
+    } else if (target) {
+      // Sanitize target — only allow safe git ref characters
+      if (!/^[a-zA-Z0-9_.\/~^@{}\-]+$/.test(target)) {
+        return { success: false, output: "", error: `Invalid git ref: "${target}"` };
+      }
+      parts.push(target);
+    }
+
+    parts.push("--stat", "--patch");
+
+    if (filePath) {
+      parts.push("--", filePath);
+    }
+
+    const command = parts.join(" ");
+
+    return new Promise((resolve) => {
+      exec(command, { cwd: this.workingDir, timeout: 30000, maxBuffer: 5 * 1024 * 1024 },
+        (error, stdout, stderr) => {
+          if (error && !stdout) {
+            const msg = stderr?.trim() || error.message;
+            resolve({ success: false, output: "", error: `git diff failed: ${msg}` });
+            return;
+          }
+
+          const output = stdout.trim();
+          if (!output) {
+            const context = staged ? "staged" : target ? `vs ${target}` : "working";
+            resolve({ success: true, output: `No changes (${context})` });
+            return;
+          }
+
+          // Truncate if too large
+          const maxLen = 50000;
+          const truncated = output.length > maxLen
+            ? output.substring(0, maxLen) + `\n\n... [truncated at ${maxLen} characters]`
+            : output;
+
+          resolve({ success: true, output: truncated });
+        });
+    });
+  }
+}