Propose str_replace / write_file

Author: jahooma

.agents/types/tools.ts

@@ -10,6 +10,8 @@ export type ToolName =
   | 'glob'
   | 'list_directory'
   | 'lookup_agent_info'
+  | 'propose_str_replace'
+  | 'propose_write_file'
   | 'read_docs'
   | 'read_files'
   | 'read_subtree'
@@ -38,6 +40,8 @@ export interface ToolParamsMap {
   glob: GlobParams
   list_directory: ListDirectoryParams
   lookup_agent_info: LookupAgentInfoParams
+  propose_str_replace: ProposeStrReplaceParams
+  propose_write_file: ProposeWriteFileParams
   read_docs: ReadDocsParams
   read_files: ReadFilesParams
   read_subtree: ReadSubtreeParams
@@ -149,6 +153,35 @@ export interface LookupAgentInfoParams {
   agentId: string
 }
 
+/**
+ * Propose string replacements in a file without actually applying them.
+ */
+export interface ProposeStrReplaceParams {
+  /** The path to the file to edit. */
+  path: string
+  /** Array of replacements to make. */
+  replacements: {
+    /** The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation. */
+    old: string
+    /** The string to replace the corresponding old string with. Can be empty to delete. */
+    new: string
+    /** Whether to allow multiple replacements of old string. */
+    allowMultiple?: boolean
+  }[]
+}
+
+/**
+ * Propose creating or editing a file without actually applying the changes.
+ */
+export interface ProposeWriteFileParams {
+  /** Path to the file relative to the **project root** */
+  path: string
+  /** What the change is intended to do in only one sentence. */
+  instructions: string
+  /** Edit snippet to apply to the file. */
+  content: string
+}
+
 /**
  * Fetch up-to-date documentation for libraries and frameworks using Context7 API.
  */

common/src/tools/constants.ts

@@ -31,6 +31,8 @@ export const toolNames = [
   'glob',
   'list_directory',
   'lookup_agent_info',
+  'propose_str_replace',
+  'propose_write_file',
   'read_docs',
   'read_files',
   'read_subtree',

common/src/tools/list.ts

@@ -12,6 +12,8 @@ import { findFilesParams } from './params/tool/find-files'
 import { globParams } from './params/tool/glob'
 import { listDirectoryParams } from './params/tool/list-directory'
 import { lookupAgentInfoParams } from './params/tool/lookup-agent-info'
+import { proposeStrReplaceParams } from './params/tool/propose-str-replace'
+import { proposeWriteFileParams } from './params/tool/propose-write-file'
 import { readDocsParams } from './params/tool/read-docs'
 import { readFilesParams } from './params/tool/read-files'
 import { readSubtreeParams } from './params/tool/read-subtree'
@@ -46,6 +48,8 @@ export const toolParams = {
   glob: globParams,
   list_directory: listDirectoryParams,
   lookup_agent_info: lookupAgentInfoParams,
+  propose_str_replace: proposeStrReplaceParams,
+  propose_write_file: proposeWriteFileParams,
   read_docs: readDocsParams,
   read_files: readFilesParams,
   read_subtree: readSubtreeParams,

common/src/tools/params/tool/propose-str-replace.ts

@@ -0,0 +1,86 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+export const proposeUpdateFileResultSchema = z.union([
+  z.object({
+    file: z.string(),
+    message: z.string(),
+    unifiedDiff: z.string(),
+  }),
+  z.object({
+    file: z.string(),
+    errorMessage: z.string(),
+  }),
+])
+
+const toolName = 'propose_str_replace'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1, 'Path cannot be empty')
+      .describe(`The path to the file to edit.`),
+    replacements: z
+      .array(
+        z
+          .object({
+            old: z
+              .string()
+              .min(1, 'Old cannot be empty')
+              .describe(
+                `The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation.`,
+              ),
+            new: z
+              .string()
+              .describe(
+                `The string to replace the corresponding old string with. Can be empty to delete.`,
+              ),
+            allowMultiple: z
+              .boolean()
+              .optional()
+              .default(false)
+              .describe(
+                'Whether to allow multiple replacements of old string.',
+              ),
+          })
+          .describe('Pair of old and new strings.'),
+      )
+      .min(1, 'Replacements cannot be empty')
+      .describe('Array of replacements to make.'),
+  })
+  .describe(`Propose string replacements in a file without actually applying them.`)
+const description = `
+Propose edits to a file without actually applying them. Use this tool when you want to draft changes that will be reviewed before being applied.
+
+This tool works identically to str_replace but the changes are not written to disk. Instead, it returns the unified diff of what would change. Multiple propose calls on the same file will stack correctly.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'path/to/file',
+    replacements: [
+      { old: 'This is the old string', new: 'This is the new string' },
+      {
+        old: '\nfoo:',
+        new: '\nbar:',
+        allowMultiple: true,
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+    `.trim()
+
+export const proposeStrReplaceParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(proposeUpdateFileResultSchema),
+} satisfies $ToolParams

common/src/tools/params/tool/propose-write-file.ts

@@ -0,0 +1,71 @@
+import z from 'zod/v4'
+
+import { proposeUpdateFileResultSchema } from './propose-str-replace'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'propose_write_file'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1, 'Path cannot be empty')
+      .describe(`Path to the file relative to the **project root**`),
+    instructions: z
+      .string()
+      .describe('What the change is intended to do in only one sentence.'),
+    content: z.string().describe(`Complete file content to write to the file.`),
+  })
+  .describe(
+    `Propose creating or editing a file without actually applying the changes.`,
+  )
+const description = `
+Propose creating or editing a file without actually applying the changes.
+
+This tool works identically to write_file but the changes are not written to disk. Instead, it returns the unified diff of what would change. Each call overwrites the previous call.
+
+Format the \`content\` parameter with the entire content of the file.
+
+This tool is to be used in subagents.
+
+Example - Simple file creation:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'new-file.ts',
+    instructions: 'Prints Hello, world',
+    content: 'console.log("Hello, world!");',
+  },
+  endsAgentStep,
+})}
+
+Example - Overwriting a file:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'foo.ts',
+    instructions: 'Update foo function',
+    content: `function foo() {
+  doSomethingNew();
+}
+  
+function bar() {
+  doSomethingOld();
+}
+`,
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const proposeWriteFileParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(proposeUpdateFileResultSchema),
+} satisfies $ToolParams