@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/tools/index.js

@@ -0,0 +1,52 @@
+import { ReadTool, WriteTool, EditTool } from './files.js';
+import { makeBashTool, BashOutputTool, KillShellTool } from './bash.js';
+import { GlobTool, GrepTool } from './search.js';
+import { makeWebFetchTool, WebSearchTool } from './web.js';
+import { TodoWriteTool, ExitPlanModeTool, AskUserQuestionTool } from './interaction.js';
+import { makeTaskTool, TaskOutputTool, TaskStopTool } from './task.js';
+import { NotebookEditTool } from './notebook.js';
+import { makeSkillTool } from './skill.js';
+import { RestartTool } from './restart.js';
+import { makeEffortTool } from './effort.js';
+import { ListPeersTool, MessagePeerTool } from './peers.js';
+
+// Build the full tool set for the main agent.
+// `restart`: this session can restart itself (it runs under the supervisor), so it gets the Restart tool.
+// `peers`: an interactive session, which can talk to the other sessions on this machine.
+export function buildTools(config, { agents, skills, mcpTools = [], restart = false, peers = false }) {
+  return [
+    makeTaskTool(agents),
+    ...(skills?.size ? [makeSkillTool(skills)] : []),
+    TaskOutputTool,
+    TaskStopTool,
+    makeBashTool(config),
+    GlobTool,
+    GrepTool,
+    ReadTool,
+    EditTool,
+    WriteTool,
+    NotebookEditTool,
+    makeWebFetchTool(config),
+    WebSearchTool,
+    TodoWriteTool,
+    BashOutputTool,
+    KillShellTool,
+    ExitPlanModeTool,
+    AskUserQuestionTool,
+    makeEffortTool(config),
+    ...(restart ? [RestartTool] : []),
+    ...(peers ? [ListPeersTool, MessagePeerTool] : []),
+    ...mcpTools,
+  ];
+}
+
+// Effort: a sub-agent shares the main agent's settings, so it must not change them.
+const NEVER_FOR_SUBAGENTS = new Set(['TaskOutput', 'TaskStop', 'TodoWrite', 'ExitPlanMode', 'AskUserQuestion', 'Restart', 'Effort', 'ListPeers', 'MessagePeer']);
+
+// Tools for a sub-agent. `allowTask`: it is below the nesting limit, so it may start sub-agents of its own.
+export function toolsForSubagent(allTools, def, { allowTask = false } = {}) {
+  const base = allTools.filter((t) => !NEVER_FOR_SUBAGENTS.has(t.name) && (allowTask || t.name !== 'Task'));
+  if (def.tools === '*' || !def.tools) return base;
+  const wanted = new Set(def.tools);
+  return base.filter((t) => wanted.has(t.name) || [...wanted].some((w) => w.startsWith('mcp__') && t.name.startsWith(w)));
+}

package/src/tools/interaction.js

@@ -0,0 +1,157 @@
+// Tools that interact with the session rather than the machine: TodoWrite,
+// ExitPlanMode and AskUserQuestion.
+
+export const TodoWriteTool = {
+  name: 'TodoWrite',
+  readOnly: true,
+  description: `Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+
+## When to Use This Tool
+Use this tool proactively in these scenarios:
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+3. User explicitly requests todo list - When the user directly asks you to use the todo list
+4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+5. After receiving new instructions - Immediately capture user requirements as todos
+6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
+7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+Skip using this tool when:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking it provides no organizational benefit
+3. The task can be completed in less than 3 trivial steps
+4. The task is purely conversational or informational
+
+## Task States and Management
+1. **Task States**:
+   - pending: Task not yet started
+   - in_progress: Currently working on (limit to ONE task at a time)
+   - completed: Task finished successfully
+   **IMPORTANT**: Task descriptions must have two forms:
+   - content: The imperative form describing what needs to be done (e.g., "Run tests")
+   - activeForm: The present continuous form shown during execution (e.g., "Running tests")
+2. **Task Management**:
+   - Update task status in real-time as you work
+   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+   - Exactly ONE task must be in_progress at any time (not less, not more)
+   - Remove tasks that are no longer relevant from the list entirely
+3. **Task Completion Requirements**:
+   - ONLY mark a task as completed when you have FULLY accomplished it
+   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+   - Never mark a task as completed if tests are failing, the implementation is partial, or you hit unresolved errors
+
+When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      todos: {
+        type: 'array',
+        description: 'The updated todo list',
+        items: {
+          type: 'object',
+          properties: {
+            content: { type: 'string', minLength: 1 },
+            status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+            activeForm: { type: 'string', minLength: 1 },
+          },
+          required: ['content', 'status', 'activeForm'],
+        },
+      },
+    },
+    required: ['todos'],
+  },
+  summarize() { return ''; },
+  async call(input, ctx) {
+    const todos = Array.isArray(input.todos) ? input.todos.filter((t) => t && t.content) : [];
+    ctx.agent.todos = todos.every((t) => t.status === 'completed') ? [] : todos;
+    return {
+      content: 'Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable',
+      display: { todos },
+    };
+  },
+};
+
+export const ExitPlanModeTool = {
+  name: 'ExitPlanMode',
+  readOnly: true,
+  description: `Use this tool when you are in plan mode and have finished planning the implementation steps of a task that requires writing code, and are ready to code. This will prompt the user to approve your plan.
+Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      plan: { type: 'string', description: 'The plan you came up with, that you want to run by the user for approval. Supports markdown. The plan should be pretty concise.' },
+    },
+    required: ['plan'],
+  },
+  summarize() { return ''; },
+  async call(input, ctx) {
+    if (ctx.modes.mode !== 'plan') return { isError: true, content: 'You are not in plan mode. Proceed with the task.' };
+    const choice = await ctx.io.approvePlan(input.plan);
+    if (choice === 'full') {
+      ctx.modes.setMode('full');
+      return { content: 'User has approved your plan. You can now start coding. Start with updating your todo list if applicable.', display: { plan: input.plan, approved: true } };
+    }
+    return {
+      content: 'The user wants to keep planning. Do not start implementation. Wait for the user to explain what should change in the plan.',
+      display: { plan: input.plan, approved: false },
+      stopTurn: true,
+    };
+  },
+};
+
+export const AskUserQuestionTool = {
+  name: 'AskUserQuestion',
+  readOnly: true,
+  description: `Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input
+- Use multiSelect: true to allow multiple answers to be selected for a question
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      questions: {
+        type: 'array',
+        minItems: 1,
+        maxItems: 4,
+        items: {
+          type: 'object',
+          properties: {
+            question: { type: 'string', description: 'The complete question to ask the user' },
+            header: { type: 'string', description: 'Very short label (max 12 chars)' },
+            multiSelect: { type: 'boolean' },
+            options: {
+              type: 'array',
+              minItems: 2,
+              maxItems: 4,
+              items: {
+                type: 'object',
+                properties: { label: { type: 'string' }, description: { type: 'string' } },
+                required: ['label', 'description'],
+              },
+            },
+          },
+          required: ['question', 'header', 'options', 'multiSelect'],
+        },
+      },
+    },
+    required: ['questions'],
+  },
+  summarize(input) { return (input.questions || []).map((q) => q.header).join(', '); },
+  async call(input, ctx) {
+    const answers = {};
+    for (const q of input.questions || []) {
+      const a = await ctx.io.askQuestion(q);
+      if (a === null) return { content: 'The user declined to answer the questions.', stopTurn: true, display: { summary: 'Declined' } };
+      answers[q.question] = a;
+    }
+    const text = Object.entries(answers).map(([q, a]) => `"${q}"="${a}"`).join(', ');
+    return { content: `User has answered your questions: ${text}. You can now continue with the user's answers in mind.`, display: { summary: Object.values(answers).join(' · ') } };
+  },
+};

package/src/tools/notebook.js

@@ -0,0 +1,91 @@
+// NotebookEdit: replace, insert or delete a cell of a Jupyter notebook. Like Edit, the
+// notebook must have been read first and unchanged on disk since.
+
+import fs from 'node:fs';
+import { resolvePath, displayPath } from '../utils/paths.js';
+import { checkFreshness, mtime } from './files.js';
+
+// Jupyter stores cell source as an array of lines, each keeping its trailing newline.
+function toSource(text) {
+  const lines = text.split('\n');
+  return lines.map((l, i) => (i < lines.length - 1 ? l + '\n' : l)).filter((l, i, a) => !(i === a.length - 1 && l === ''));
+}
+
+function findCell(nb, id) {
+  const cells = nb.cells || [];
+  const byId = cells.findIndex((c) => c.id === id);
+  if (byId >= 0) return byId;
+  const m = /^cell-(\d+)$/.exec(String(id)) || /^(\d+)$/.exec(String(id));
+  if (m && +m[1] < cells.length) return +m[1];
+  return -1;
+}
+
+export const NotebookEditTool = {
+  name: 'NotebookEdit',
+  editsFiles: true,
+  description: `Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing.
+- notebook_path must be an absolute path, and the notebook must have been read with Read first.
+- cell_id is the id of the cell (or its 0-based index, as in "cell-3"). When inserting, the new cell goes after the cell with this id; omit it to insert at the beginning.
+- edit_mode is "replace" (default), "insert" or "delete". cell_type ("code" or "markdown") is required for insert.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      notebook_path: { type: 'string', description: 'The absolute path to the Jupyter notebook file to edit' },
+      cell_id: { type: 'string', description: 'The ID (or "cell-N" index) of the cell to edit' },
+      new_source: { type: 'string', description: 'The new source for the cell' },
+      cell_type: { type: 'string', enum: ['code', 'markdown'], description: 'The type of the cell (required for insert)' },
+      edit_mode: { type: 'string', enum: ['replace', 'insert', 'delete'], description: 'The type of edit to make (default: replace)' },
+    },
+    required: ['notebook_path', 'new_source'],
+  },
+  summarize(input, ctx) { return displayPath(resolvePath(input.notebook_path, ctx.cwd), ctx.cwd); },
+  filePath(input, ctx) { return resolvePath(input.notebook_path, ctx.cwd); },
+  validate(input, ctx) {
+    const file = resolvePath(input.notebook_path, ctx.cwd);
+    if (!file.endsWith('.ipynb')) return 'File must be a Jupyter notebook (.ipynb file). For other file types, use the Edit tool.';
+    if (!fs.existsSync(file)) return `Notebook does not exist: ${file}`;
+    if ((input.edit_mode || 'replace') === 'insert' && !input.cell_type) return 'cell_type is required when edit_mode is insert.';
+    return checkFreshness(file, ctx);
+  },
+  async call(input, ctx) {
+    const err = this.validate(input, ctx);
+    if (err) return { isError: true, content: err };
+    const file = resolvePath(input.notebook_path, ctx.cwd);
+    let nb;
+    try { nb = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return { isError: true, content: `Could not parse notebook: ${e.message}` }; }
+    nb.cells ||= [];
+    const mode = input.edit_mode || 'replace';
+    let summary;
+    if (mode === 'insert') {
+      let at = 0;
+      if (input.cell_id !== undefined && input.cell_id !== '') {
+        const i = findCell(nb, input.cell_id);
+        if (i < 0) return { isError: true, content: `Cell not found: ${input.cell_id}` };
+        at = i + 1;
+      }
+      const cell = { cell_type: input.cell_type, id: Math.random().toString(36).slice(2, 10), metadata: {}, source: toSource(input.new_source) };
+      if (input.cell_type === 'code') { cell.execution_count = null; cell.outputs = []; }
+      nb.cells.splice(at, 0, cell);
+      summary = `Inserted cell ${cell.id} at position ${at}`;
+    } else {
+      const i = findCell(nb, input.cell_id);
+      if (i < 0) return { isError: true, content: `Cell not found: ${input.cell_id ?? '(no cell_id given)'}` };
+      if (mode === 'delete') {
+        nb.cells.splice(i, 1);
+        summary = `Deleted cell ${input.cell_id}`;
+      } else {
+        const cell = nb.cells[i];
+        cell.source = toSource(input.new_source);
+        if (input.cell_type && input.cell_type !== cell.cell_type) {
+          cell.cell_type = input.cell_type;
+          if (input.cell_type === 'code') { cell.execution_count = null; cell.outputs = []; } else { delete cell.execution_count; delete cell.outputs; }
+        }
+        if (cell.cell_type === 'code') { cell.execution_count = null; cell.outputs = []; }
+        summary = `Updated cell ${input.cell_id}`;
+      }
+    }
+    fs.writeFileSync(file, JSON.stringify(nb, null, 1) + '\n', 'utf8');
+    ctx.fileState.set(file, { mtimeMs: mtime(file) });
+    return { content: summary, display: { summary } };
+  },
+};

package/src/tools/peers.js

@@ -0,0 +1,45 @@
+// ListPeers and MessagePeer: talk to the other claude-pro sessions running on this machine (see peers.js).
+
+const unavailable = { isError: true, content: 'Talking to other sessions is only available in an interactive session.' };
+
+export const ListPeersTool = {
+  name: 'ListPeers',
+  description: 'List the other claude-pro sessions running on this machine (each is an agent with its own conversation, working in its own directory), with the name to send them a message with MessagePeer.',
+  input_schema: { type: 'object', properties: {} },
+  summarize() { return ''; },
+  async call(input, ctx) {
+    const node = ctx.io?.peers;
+    if (!node) return unavailable;
+    const peers = node.peers();
+    const me = `You are "${node.name}" (${node.cwd}).`;
+    if (!peers.length) return { content: `${me}\nNo other session is running.`, display: { summary: 'No other session' } };
+    return {
+      content: `${me}\nOther sessions:\n${peers.map((p) => `- ${p.name}: working in ${p.cwd}`).join('\n')}`,
+      display: { summary: `${peers.length} other session${peers.length === 1 ? '' : 's'}` },
+    };
+  },
+};
+
+export const MessagePeerTool = {
+  name: 'MessagePeer',
+  description: `Send a task or a question to another claude-pro session running on this machine (ListPeers lists them). The other session's agent works on it in its own conversation and directory, and the final text of its answer comes back to you later as a <peer-message kind="reply"> message: you do not wait for it here. Use it to delegate work that belongs to another session's project or context, or to ask it something only it knows. Write the message so that it stands on its own: the other agent has not seen your conversation.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      to: { type: 'string', description: 'The name of the session (as ListPeers shows it)' },
+      message: { type: 'string', description: 'The task or question, self-contained' },
+    },
+    required: ['to', 'message'],
+  },
+  summarize(input) { return `@${input.to}`; },
+  async call(input, ctx) {
+    const node = ctx.io?.peers;
+    if (!node) return unavailable;
+    try {
+      const { peer } = await ctx.io.sendToPeer(input.to, input.message, { byModel: true });
+      return { content: `Sent to ${peer.name}. Its answer will arrive later as a message; carry on meanwhile, or end your turn if you need the answer first.`, display: { summary: `Sent to ${peer.name}` } };
+    } catch (e) {
+      return { isError: true, content: e.message };
+    }
+  },
+};

package/src/tools/restart.js

@@ -0,0 +1,50 @@
+// Restart: the model restarts this program after changing the program's own source code, so that the change
+// takes effect and the conversation goes on in the new process.
+
+import { APP_NAME, INSTALL_DIR } from '../config.js';
+import { canRestart, runSelfCheck, MAX_RESTARTS } from '../restart.js';
+
+export const RestartTool = {
+  name: 'Restart',
+  description: `Restart this program (${APP_NAME}) so that changes you made to its own source code take effect, and carry on in the new process. Its source is in ${INSTALL_DIR} (src/ and bin/). Editing those files does not change the process you are running in: it keeps the old code until it restarts.
+
+Use it after you have changed the program's own code, to fix a bug you ran into or to add something you need. Do not use it for anything else.
+
+How it works:
+- First the new code is started in a separate throwaway process (every module loads, the interface comes up, the tools and the system prompt are well formed). If that fails, nothing is restarted and the error is returned to you: fix it and call Restart again.
+- Then the restart happens as soon as your current turn ends, so finish the turn with a short message to the user. The conversation, your todo list, the model and effort settings, queued messages and whatever the user was typing carry over, and you get a message saying the new code is loaded.
+- Use \`then\` to say what to do right after the restart (typically: check that the change works). Without it you simply carry on.
+- Background agents and background shells are killed by a restart, so the tool refuses while any are running unless you pass force.
+- Restarting more than ${MAX_RESTARTS} times within five minutes is refused: that is a loop. Stop and tell the user.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      reason: { type: 'string', description: 'What changed, in a few words. Shown to the user.' },
+      then: { type: 'string', description: 'What to do right after the restart, for example how to check the change.' },
+      force: { type: 'boolean', description: 'Restart even though background agents or shells are running (they are killed).' },
+    },
+    required: ['reason'],
+  },
+  summarize(input) { return input.reason || ''; },
+  async call(input, ctx) {
+    const io = ctx.io;
+    if (!canRestart() || typeof io?.requestRestart !== 'function') {
+      return { isError: true, content: `Restart is not available here: it needs an interactive session started with \`${APP_NAME}\` (not -p, and not with CLAUDE_PRO_NO_SUPERVISOR set). Ask the user to restart the program themselves.` };
+    }
+    const blockers = io.restartBlockers?.() || [];
+    if (blockers.length && !input.force) {
+      return { isError: true, content: `A restart would kill what is still running: ${blockers.join('; ')}. Wait for it to finish (TaskOutput / BashOutput), stop it (TaskStop / KillShell), or call Restart again with force: true.` };
+    }
+    const check = await runSelfCheck({ signal: ctx.signal });
+    if (!check.ok) {
+      return { isError: true, content: `Not restarting: the new code does not start.\n\n${check.output}\n\nFix this and call Restart again.`, display: { summary: 'The new code does not start' } };
+    }
+    const res = io.requestRestart({ reason: input.reason, then: input.then, continueTurn: true, force: true });
+    if (!res.ok) return { isError: true, content: res.message };
+    const secs = Math.max(1, Math.round(check.ms / 1000));
+    return {
+      content: `The new code starts fine (checked in ${secs}s). ${APP_NAME} restarts as soon as this turn ends and the conversation continues in the new process${input.then ? ` with your note: "${input.then}"` : ''}. Finish this turn now with a short message to the user; do not change anything more and do not call Restart again.`,
+      display: { summary: `Restarting when this turn ends: ${input.reason}` },
+    };
+  },
+};