tulingcode 0.1.0

package/src/tool/lsp.ts

@@ -0,0 +1,91 @@
+import z from "zod"
+import { Effect } from "effect"
+import * as Tool from "./tool"
+import path from "path"
+import { LSP } from "../lsp"
+import DESCRIPTION from "./lsp.txt"
+import { Instance } from "../project/instance"
+import { pathToFileURL } from "url"
+import { assertExternalDirectoryEffect } from "./external-directory"
+import { AppFileSystem } from "@tuling-ai/shared/filesystem"
+
+const operations = [
+  "goToDefinition",
+  "findReferences",
+  "hover",
+  "documentSymbol",
+  "workspaceSymbol",
+  "goToImplementation",
+  "prepareCallHierarchy",
+  "incomingCalls",
+  "outgoingCalls",
+] as const
+
+export const LspTool = Tool.define(
+  "lsp",
+  Effect.gen(function* () {
+    const lsp = yield* LSP.Service
+    const fs = yield* AppFileSystem.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: z.object({
+        operation: z.enum(operations).describe("The LSP operation to perform"),
+        filePath: z.string().describe("The absolute or relative path to the file"),
+        line: z.number().int().min(1).describe("The line number (1-based, as shown in editors)"),
+        character: z.number().int().min(1).describe("The character offset (1-based, as shown in editors)"),
+      }),
+      execute: (
+        args: { operation: (typeof operations)[number]; filePath: string; line: number; character: number },
+        ctx: Tool.Context,
+      ) =>
+        Effect.gen(function* () {
+          const file = path.isAbsolute(args.filePath) ? args.filePath : path.join(Instance.directory, args.filePath)
+          yield* assertExternalDirectoryEffect(ctx, file)
+          yield* ctx.ask({ permission: "lsp", patterns: ["*"], always: ["*"], metadata: {} })
+
+          const uri = pathToFileURL(file).href
+          const position = { file, line: args.line - 1, character: args.character - 1 }
+          const relPath = path.relative(Instance.worktree, file)
+          const title = `${args.operation} ${relPath}:${args.line}:${args.character}`
+
+          const exists = yield* fs.existsSafe(file)
+          if (!exists) throw new Error(`File not found: ${file}`)
+
+          const available = yield* lsp.hasClients(file)
+          if (!available) throw new Error("No LSP server available for this file type.")
+
+          yield* lsp.touchFile(file, true)
+
+          const result: unknown[] = yield* (() => {
+            switch (args.operation) {
+              case "goToDefinition":
+                return lsp.definition(position)
+              case "findReferences":
+                return lsp.references(position)
+              case "hover":
+                return lsp.hover(position)
+              case "documentSymbol":
+                return lsp.documentSymbol(uri)
+              case "workspaceSymbol":
+                return lsp.workspaceSymbol("")
+              case "goToImplementation":
+                return lsp.implementation(position)
+              case "prepareCallHierarchy":
+                return lsp.prepareCallHierarchy(position)
+              case "incomingCalls":
+                return lsp.incomingCalls(position)
+              case "outgoingCalls":
+                return lsp.outgoingCalls(position)
+            }
+          })()
+
+          return {
+            title,
+            metadata: { result },
+            output: result.length === 0 ? `No results found for ${args.operation}` : JSON.stringify(result, null, 2),
+          }
+        }),
+    }
+  }),
+)

package/src/tool/lsp.txt

@@ -0,0 +1,19 @@
+Interact with Language Server Protocol (LSP) servers to get code intelligence features.
+
+Supported operations:
+- goToDefinition: Find where a symbol is defined
+- findReferences: Find all references to a symbol
+- hover: Get hover information (documentation, type info) for a symbol
+- documentSymbol: Get all symbols (functions, classes, variables) in a document
+- workspaceSymbol: Search for symbols across the entire workspace
+- goToImplementation: Find implementations of an interface or abstract method
+- prepareCallHierarchy: Get call hierarchy item at a position (functions/methods)
+- incomingCalls: Find all functions/methods that call the function at a position
+- outgoingCalls: Find all functions/methods called by the function at a position
+
+All operations require:
+- filePath: The file to operate on
+- line: The line number (1-based, as shown in editors)
+- character: The character offset (1-based, as shown in editors)
+
+Note: LSP servers must be configured for the file type. If no server is available, an error will be returned.

package/src/tool/mcp-exa.ts

@@ -0,0 +1,78 @@
+import { Duration, Effect, Schema } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+
+const URL = process.env.EXA_API_KEY
+  ? `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(process.env.EXA_API_KEY)}`
+  : "https://mcp.exa.ai/mcp"
+
+const McpResult = Schema.Struct({
+  result: Schema.Struct({
+    content: Schema.Array(
+      Schema.Struct({
+        type: Schema.String,
+        text: Schema.String,
+      }),
+    ),
+  }),
+})
+
+const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(McpResult))
+
+const parseSse = Effect.fn("McpExa.parseSse")(function* (body: string) {
+  for (const line of body.split("\n")) {
+    if (!line.startsWith("data: ")) continue
+    const data = yield* decode(line.substring(6))
+    if (data.result.content[0]?.text) return data.result.content[0].text
+  }
+  return undefined
+})
+
+export const SearchArgs = Schema.Struct({
+  query: Schema.String,
+  type: Schema.String,
+  numResults: Schema.Number,
+  livecrawl: Schema.String,
+  contextMaxCharacters: Schema.optional(Schema.Number),
+})
+
+export const CodeArgs = Schema.Struct({
+  query: Schema.String,
+  tokensNum: Schema.Number,
+})
+
+const McpRequest = <F extends Schema.Struct.Fields>(args: Schema.Struct<F>) =>
+  Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.Literal(1),
+    method: Schema.Literal("tools/call"),
+    params: Schema.Struct({
+      name: Schema.String,
+      arguments: args,
+    }),
+  })
+
+export const call = <F extends Schema.Struct.Fields>(
+  http: HttpClient.HttpClient,
+  tool: string,
+  args: Schema.Struct<F>,
+  value: Schema.Struct.Type<F>,
+  timeout: Duration.Input,
+) =>
+  Effect.gen(function* () {
+    const request = yield* HttpClientRequest.post(URL).pipe(
+      HttpClientRequest.accept("application/json, text/event-stream"),
+      HttpClientRequest.schemaBodyJson(McpRequest(args))({
+        jsonrpc: "2.0" as const,
+        id: 1 as const,
+        method: "tools/call" as const,
+        params: { name: tool, arguments: value },
+      }),
+    )
+    const response = yield* HttpClient.filterStatusOk(http)
+      .execute(request)
+      .pipe(
+        Effect.timeoutOrElse({ duration: timeout, orElse: () => Effect.die(new Error(`${tool} request timed out`)) }),
+      )
+    const body = yield* response.text
+    return yield* parseSse(body)
+  })

package/src/tool/memory-path-guard.ts

@@ -0,0 +1,162 @@
+import * as path from "path"
+import type { ProjectID } from "../project/schema"
+import type { SessionID } from "../session/schema"
+
+const VALID_SCOPES = ["global", "projects", "sessions"] as const
+
+const TASK_ID_RE = /^T\d+(\.\d+)*$/
+
+/**
+ * Returns true when the relative path under <root>/memory/ is one of the
+ * precise paths the checkpoint-writer subagent is permitted to write:
+ *   projects/<pid>/memory.md          (or memory-<topic>.md spillover)
+ *   sessions/<sid>/checkpoint.md      (or checkpoint-<topic>.md spillover)
+ *   sessions/<sid>/notes.md
+ *   sessions/<sid>/tasks/<task_id>/*.md
+ *
+ * Rejects anything else. Catches writer drift like
+ * `<pid>/pinned.md` (v4 name) at write time.
+ */
+function isCheckpointWriterAllowed(parts: string[]): boolean {
+  if (parts.length < 3) return false
+
+  if (parts[0] === "projects") {
+    if (parts.length !== 3) return false
+    const file = parts[2]
+    if (!file.endsWith(".md")) return false
+    const lower = file.toLowerCase()
+    return lower === "memory.md" || lower.startsWith("memory-")
+  }
+
+  if (parts[0] === "sessions") {
+    const rest = parts.slice(2)
+    if (rest.length === 1) {
+      const file = rest[0]
+      if (!file.endsWith(".md")) return false
+      return file === "checkpoint.md" || file === "notes.md" || file.startsWith("checkpoint-")
+    }
+    if (rest.length === 3 && rest[0] === "tasks") {
+      return TASK_ID_RE.test(rest[1]) && rest[2].endsWith(".md")
+    }
+    return false
+  }
+
+  return false
+}
+
+/**
+ * Format the multi-line "where to write memory" hint shown to main agent
+ * when it attempts a path with no scope dir or an invalid scope. Both throws
+ * use byte-identical bodies — the corrective action is the same.
+ */
+function formatMainAgentHelp(memoryFile: string, notesFile: string, target: string): string {
+  return (
+    `Memory writes go under <memoryRoot>/<scope>/<scope_id>/<key>.md (scope: global | projects | sessions). You attempted: ${target}.\n` +
+    `\n` +
+    `Canonical main-agent paths (copy verbatim):\n` +
+    `  ${memoryFile}\n` +
+    `    Edit ## Rules / ## Architecture decisions / ## Discovered durable knowledge.\n` +
+    `  ${notesFile}\n` +
+    `    Append \`## [turn N · ISO-Z]\` entries for free-form scratch.\n` +
+    `\n` +
+    `Other free-form <key>.md under a valid scope dir are also allowed.\n` +
+    `checkpoint.md, task progress, and memory-/checkpoint-<topic>.md spillovers are checkpoint-writer's domain.`
+  )
+}
+
+/**
+ * Returns true when the path is reserved-by-pattern for the checkpoint-writer
+ * subagent — main agent must not write it directly.
+ *
+ * In v5 only the writer-managed task directory remains reserved-by-pattern.
+ * Main agent CAN write <pid>/MEMORY.md and <sid>/checkpoint.md (system prompt
+ * teaches it the rules).
+ */
+function isReservedForCheckpointWriter(parts: string[]): boolean {
+  if (parts[0] !== "sessions" || parts.length < 4) return false
+  // Anything under <sid>/tasks/ is writer-managed (use task tool revise action).
+  if (parts[2] === "tasks") return true
+  return false
+}
+
+/**
+ * Throws if the target write would violate memory-scope or reserved-path
+ * rules. Pure function — does not touch the filesystem.
+ *
+ * Two policies:
+ *   - For checkpoint-writer subagent: must be in the precise allowlist above
+ *     (<pid>/MEMORY.md, <sid>/checkpoint.md, <sid>/tasks/<id>/*.md, plus
+ *     memory-/checkpoint- spillover variants).
+ *   - For all other agents: cannot write <sid>/tasks/* — that's
+ *     checkpoint-writer-only.
+ *
+ * Non-memory paths and free keys under valid scopes pass through unmodified.
+ */
+export function assertMemoryWriteAllowed(input: {
+  target: string
+  agentName: string
+  memoryRoot: string
+  projectID: ProjectID
+  sessionID: SessionID
+  taskId?: string
+}): void {
+  const { target, agentName, memoryRoot, projectID, sessionID } = input
+  const memoryFile = path.join(memoryRoot, "projects", projectID, "MEMORY.md")
+  const notesFile = path.join(memoryRoot, "sessions", sessionID, "notes.md")
+  const checkpointFile = path.join(memoryRoot, "sessions", sessionID, "checkpoint.md")
+  const taskMemDir = path.join(memoryRoot, "sessions", sessionID, "tasks")
+  const normalizedRoot = memoryRoot.endsWith(path.sep) ? memoryRoot : memoryRoot + path.sep
+  if (!target.startsWith(normalizedRoot)) return
+
+  const rel = path.relative(memoryRoot, target)
+  const parts = rel.split(path.sep)
+
+  if (parts.length < 2) {
+    throw new Error(formatMainAgentHelp(memoryFile, notesFile, target))
+  }
+  const scope = parts[0]
+  if (!VALID_SCOPES.includes(scope as (typeof VALID_SCOPES)[number])) {
+    throw new Error(formatMainAgentHelp(memoryFile, notesFile, target))
+  }
+
+  if (agentName === "checkpoint-writer") {
+    if (!isCheckpointWriterAllowed(parts)) {
+      throw new Error(
+        `Path '${rel}' is not in the checkpoint-writer allowlist.\n` +
+          `Writer may only write to:\n` +
+          `  ${memoryFile}                           — project memory (or memory-<topic>.md spillover)\n` +
+          `  ${checkpointFile}                       — session checkpoint (or checkpoint-<topic>.md spillover)\n` +
+          `  ${taskMemDir}/<task_id>/*.md            — per-task narratives (any .md filename)\n` +
+          `You attempted: ${target}.`,
+      )
+    }
+    return
+  }
+
+  if (isReservedForCheckpointWriter(parts)) {
+    // Spec ② follow-up: subagent bound to a specific TID may write anywhere
+    // under ITS OWN tasks/<TID>/ subtree. Cross-task writes still rejected.
+    // parts shape under tasks: ["sessions", sid, "tasks", "<TID>", "<file>.md", ...]
+    // NOTE: `parts.length >= 5` is deliberately looser than the checkpoint-writer
+    // path (which requires exactly tasks/<TID>/<file>.md). A subagent may nest
+    // its own workspace (tasks/<TID>/sub/foo.md); the `parts[3] === input.taskId`
+    // guard still confines it to its own task, so the extra depth is safe.
+    if (
+      input.taskId &&
+      parts[2] === "tasks" &&
+      parts[3] === input.taskId &&
+      parts.length >= 5 &&
+      parts[parts.length - 1].endsWith(".md")
+    ) {
+      return
+    }
+    throw new Error(
+      `Path '${rel}' is reserved for the checkpoint-writer subagent.\n` +
+        `Main agent writes to:\n` +
+        `  ${memoryFile}\n` +
+        `  ${notesFile}\n` +
+        `Subagent bound to task <TID> may write to tasks/<TID>/*.md (pass task_id when spawning).\n` +
+        `You attempted: ${target}.`,
+    )
+  }
+}

package/src/tool/memory.ts

@@ -0,0 +1,81 @@
+import { Effect } from "effect"
+import z from "zod"
+import { Memory } from "@/memory"
+import DESCRIPTION from "./memory.txt"
+import * as Tool from "./tool"
+
+const parameters = z.object({
+  operation: z.enum(["search"]).default("search").describe("Memory operation to perform"),
+  query: z.string().describe("Search query (BM25 over markdown bodies)"),
+  scope: z.enum(["global", "projects", "sessions", "cc"]).optional().describe("Filter by memory scope"),
+  scope_id: z
+    .string()
+    .optional()
+    .describe("Filter by scope id (e.g., session id, task id, project id hash)"),
+  type: z
+    .string()
+    .optional()
+    .describe("Filter by memory type (pinned, snapshot, learning, progress, free, ...)"),
+  limit: z.number().optional().describe("Max results (default 10)"),
+})
+
+export const MemoryTool = Tool.define(
+  "memory",
+  Effect.gen(function* () {
+    const memory = yield* Memory.Service
+    return {
+      description: DESCRIPTION,
+      parameters,
+      execute: (args: z.infer<typeof parameters>) =>
+        Effect.gen(function* () {
+          const results = yield* memory.search({
+            query: args.query,
+            scope: args.scope,
+            scope_id: args.scope_id,
+            type: args.type,
+            limit: args.limit,
+          })
+          if (results.length === 0) {
+            return {
+              title: `Memory search: 0 results`,
+              output: [
+                `No matches for "${args.query}".`,
+                ``,
+                `0 results does NOT mean it was never recorded. Escalate before giving up:`,
+                `1. Retry with FEWER / more distinctive terms — queries are OR-joined and`,
+                `   ranked, so 1-2 rare words (an exact ID, function name, flag) beat a long`,
+                `   descriptive phrase. Drop generic words ("config", "params", "database").`,
+                `2. For a LITERAL string the tokenizer splits (URLs like postgres://…, ports`,
+                `   like 5433, paths) — Grep the memory dir directly; FTS can't see it.`,
+                `3. For VERBATIM recall of something a summary may have glossed over (exact`,
+                `   command, the user's precise wording) — use the history tool (raw`,
+                `   conversation), which keeps original messages.`,
+                `Widen scope progressively: session → project → global → history.`,
+              ].join("\n"),
+              metadata: { count: 0 },
+            }
+          }
+          const lines = [
+            `Found ${results.length} match${results.length === 1 ? "" : "es"} (BM25-ranked, best first).`,
+            `A hit here is authoritative — use it even if a parallel/sibling query returned nothing.`,
+            `If you need the FULL body (snippets are truncated), Read the path.`,
+            `If you need an EXACT literal (a connection string, port, token, full command line, path) and the snippet/body only paraphrases or partially shows it, the curated memory may have dropped the precise form — query the history tool for the original message, which holds it verbatim.`,
+            ``,
+          ]
+          for (const r of results) {
+            lines.push(`### ${r.path}`)
+            lines.push(
+              `Scope: ${r.scope}${r.scope_id ? `/${r.scope_id}` : ""}, Type: ${r.type}, Score: ${r.score.toFixed(3)}`,
+            )
+            lines.push(r.snippet)
+            lines.push("")
+          }
+          return {
+            title: `Memory search: ${results.length} result${results.length === 1 ? "" : "s"}`,
+            output: lines.join("\n"),
+            metadata: { count: results.length },
+          }
+        }),
+    }
+  }),
+)

package/src/tool/memory.txt

@@ -0,0 +1,69 @@
+Search session/project/global memory using BM25 over markdown
+bodies. Use this to recall content the agent or writer subagent
+persisted previously: project memory, session checkpoints, task
+narratives (under sessions/<sid>/tasks/), project notes, global
+preferences.
+
+Memory layout: <data>/memory/<scope>/<scope_id>/<key>.md
+Scopes: global | projects | sessions | cc (opt-in, see below)
+
+QUERY GUIDELINES:
+- Queries are OR'd and BM25-ranked: a document matches if it contains
+  ANY query word, ordered by relevance (how many / how rare the matched
+  words are). Low-relevance common-word-only matches are dropped by a
+  score floor.
+- Prefer 1–3 distinctive terms (function name, task ID, exact phrase
+  from a directive, a rare word from the snippet you want). Long lists
+  of generic words ("config params database connection") just add noise
+  and bury the real hit — pick the rarest, most specific word.
+- "T5.3 closure" works. So does "permission deadlock". Avoid padding
+  with generic descriptors.
+- Punctuation (`.`, `-`, `/`, `:`) is stripped during tokenization.
+  Both query and indexed body see only alphanumeric runs, so `T5.3`
+  matches `T5.3`, `T5_3`, or `T5 3`. A literal like `postgres://host:5433`
+  is indexed as tokens `postgres`, `host`, `5433` — search one of those,
+  not the full URL.
+
+A HIT IS AUTHORITATIVE. If search returns a result, trust it — even
+when a different/sibling query you ran returned nothing. Do not conclude
+"I never recorded this" because one phrasing missed.
+
+PARTIAL HIT, EXACT LITERAL NEEDED. A hit may give the gist but have
+dropped the precise form of a connection string, port, token, full
+command line, or path (curation paraphrases). If you need the literal
+byte-for-byte and the result only approximates it, query the history
+tool — the original message holds it verbatim. Don't reconstruct or
+guess the exact value from a paraphrase.
+
+WHEN SEARCH RETURNS 0 (escalate, do not give up):
+1. Retry with fewer / rarer terms (see guidelines above).
+2. For a literal string the tokenizer splits (URL, port, path) — Grep
+   the memory dir directly; FTS can't match the punctuation form.
+3. For verbatim recall a summary may have glossed over — use the
+   history tool (raw conversation messages).
+Widen scope progressively: session → project → global → history.
+
+Actions:
+- search: OR-joined BM25 query, optional scope/scope_id/type filters
+
+After search returns paths, use Read on the most relevant ones to
+load full content (snippets are truncated). Use Glob on
+`<data>/memory/**/*.md` to inspect the tree if you need to find files
+by name pattern instead of body.
+
+CC SCOPE:
+When memory.cc_index is enabled in config, Claude Code memory at
+~/.claude/projects/<slug>/memory/*.md is also indexed under
+scope="cc". scope_id is the CC project slug (a path-derived identifier
+like "-home-user-projects-app"). Frontmatter metadata.type
+(feedback / project / reference / user) populates the type column,
+so e.g. type="feedback" filters CC feedback memories. CC memory is
+read-only from this tool.
+
+Privacy note: CC's `type: user` and `type: feedback` categories may
+hold personal context (the user's role, preferences, prior guidance)
+that CC originally wrote for its own future sessions. With cc_index on,
+they become recallable from any tulingcode agent — including subagents
+that may be exposed to prompt-injected content. If that's not desired,
+keep cc_index disabled or filter `type` at search time to exclude
+the more sensitive categories.

package/src/tool/multiedit.ts

@@ -0,0 +1,61 @@
+import z from "zod"
+import { Effect } from "effect"
+import * as Tool from "./tool"
+import { EditTool } from "./edit"
+import DESCRIPTION from "./multiedit.txt"
+import path from "path"
+import { Instance } from "../project/instance"
+
+export const MultiEditTool = Tool.define(
+  "multiedit",
+  Effect.gen(function* () {
+    const editInfo = yield* EditTool
+    const edit = yield* editInfo.init()
+
+    return {
+      description: DESCRIPTION,
+      parameters: z.object({
+        filePath: z.string().describe("The absolute path to the file to modify"),
+        edits: z
+          .array(
+            z.object({
+              filePath: z.string().describe("The absolute path to the file to modify"),
+              oldString: z.string().describe("The text to replace"),
+              newString: z.string().describe("The text to replace it with (must be different from oldString)"),
+              replaceAll: z.boolean().optional().describe("Replace all occurrences of oldString (default false)"),
+            }),
+          )
+          .describe("Array of edit operations to perform sequentially on the file"),
+      }),
+      execute: (
+        params: {
+          filePath: string
+          edits: Array<{ filePath: string; oldString: string; newString: string; replaceAll?: boolean }>
+        },
+        ctx: Tool.Context,
+      ) =>
+        Effect.gen(function* () {
+          const results = []
+          for (const [, entry] of params.edits.entries()) {
+            const result = yield* edit.execute(
+              {
+                filePath: params.filePath,
+                oldString: entry.oldString,
+                newString: entry.newString,
+                replaceAll: entry.replaceAll,
+              },
+              ctx,
+            )
+            results.push(result)
+          }
+          return {
+            title: path.relative(Instance.worktree, params.filePath),
+            metadata: {
+              results: results.map((r) => r.metadata),
+            },
+            output: results.at(-1)!.output,
+          }
+        }),
+    }
+  }),
+)

package/src/tool/multiedit.txt

@@ -0,0 +1,41 @@
+This is a tool for making multiple edits to a single file in one operation. It is built on top of the Edit tool and allows you to perform multiple find-and-replace operations efficiently. Prefer this tool over the Edit tool when you need to make multiple edits to the same file.
+
+Before using this tool:
+
+1. Use the Read tool to understand the file's contents and context
+2. Verify the directory path is correct
+
+To make multiple file edits, provide the following:
+1. file_path: The absolute path to the file to modify (must be absolute, not relative)
+2. edits: An array of edit operations to perform, where each edit contains:
+   - oldString: The text to replace (must match the file contents exactly, including all whitespace and indentation)
+   - newString: The edited text to replace the oldString
+   - replaceAll: Replace all occurrences of oldString. This parameter is optional and defaults to false.
+
+IMPORTANT:
+- All edits are applied in sequence, in the order they are provided
+- Each edit operates on the result of the previous edit
+- All edits must be valid for the operation to succeed - if any edit fails, none will be applied
+- This tool is ideal when you need to make several changes to different parts of the same file
+
+CRITICAL REQUIREMENTS:
+1. All edits follow the same requirements as the single Edit tool
+2. The edits are atomic - either all succeed or none are applied
+3. Plan your edits carefully to avoid conflicts between sequential operations
+
+WARNING:
+- The tool will fail if edits.oldString doesn't match the file contents exactly (including whitespace)
+- The tool will fail if edits.oldString and edits.newString are the same
+- Since edits are applied in sequence, ensure that earlier edits don't affect the text that later edits are trying to find
+
+When making edits:
+- Ensure all edits result in idiomatic, correct code
+- Do not leave the code in a broken state
+- Always use absolute file paths (starting with /)
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- Use replaceAll for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+
+If you want to create a new file, use:
+- A new file path, including dir name if needed
+- First edit: empty oldString and the new file's contents as newString
+- Subsequent edits: normal edit operations on the created content

package/src/tool/plan-enter.txt

@@ -0,0 +1,14 @@
+Use this tool to suggest switching to plan agent when the user's request would benefit from planning before implementation.
+
+If they explicitly mention wanting to create a plan ALWAYS call this tool first.
+
+This tool will ask the user if they want to switch to plan agent.
+
+Call this tool when:
+- The user's request is complex and would benefit from planning first
+- You want to research and design before making changes
+- The task involves multiple files or significant architectural decisions
+
+Do NOT call this tool:
+- For simple, straightforward tasks
+- When the user explicitly wants immediate implementation

package/src/tool/plan-exit.txt

@@ -0,0 +1,13 @@
+Use this tool when you have completed the planning phase and are ready to exit plan agent.
+
+This tool will ask the user if they want to switch to build agent to start implementing the plan.
+
+Call this tool:
+- After you have written a complete plan to the plan file
+- After you have clarified any questions with the user
+- When you are confident the plan is ready for implementation
+
+Do NOT call this tool:
+- Before you have created or finalized the plan
+- If you still have unanswered questions about the implementation
+- If the user has indicated they want to continue planning