@mty-coder/cli 0.1.1

package/src/tool/edit.txt

@@ -0,0 +1,10 @@
+Performs exact string replacements in files. 
+
+Usage:
+- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + colon + space (e.g., `1: `). Everything after that space is the actual file content to match. Never include any part of the line number prefix in the oldString or newString.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if `oldString` is not found in the file with an error "oldString not found in content".
+- The edit will FAIL if `oldString` is found multiple times in the file with an error "Found multiple matches for oldString. Provide more surrounding lines in oldString to identify the correct match." Either provide a larger string with more surrounding context to make it unique or use `replaceAll` to change every instance of `oldString`. 
+- Use `replaceAll` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.

package/src/tool/external-directory.ts

@@ -0,0 +1,132 @@
+import path from "path"
+import { Effect } from "effect"
+import { EffectLogger } from "@/effect"
+import { InstanceState } from "@/effect"
+import { Global } from "@/global"
+import type * as Tool from "./tool"
+import { Instance } from "../project/instance"
+import { ProjectID } from "../project/schema"
+import { assertMemoryWriteAllowed } from "./memory-path-guard"
+import { AppFileSystem } from "@mty-coder/shared/filesystem"
+
+type Kind = "file" | "directory"
+
+type Options = {
+  bypass?: boolean
+  kind?: Kind
+}
+
+export const assertExternalDirectoryEffect = Effect.fn("Tool.assertExternalDirectory")(function* (
+  ctx: Tool.Context,
+  target?: string,
+  options?: Options,
+) {
+  if (!target) return
+
+  if (options?.bypass) return
+
+  const ins = yield* InstanceState.context
+  const full = process.platform === "win32" ? AppFileSystem.normalizePath(target) : target
+  if (Instance.containsPath(full, ins)) return
+
+  // Memory tree has its own finer authority (memory-path-guard), which the write
+  // tools invoke right after this call. Defer to it: asking external_directory here
+  // is redundant and, in headless run mode (no permission replier), deadlocks on a
+  // never-resolved Deferred. memory-path-guard allows a task-bound subagent its own
+  // tasks/<taskId>/*.md and rejects cross-task / wrong-agent writes.
+  if (AppFileSystem.contains(path.join(Global.Path.data, "memory"), full)) return
+
+  const kind = options?.kind ?? "file"
+  const dir = kind === "directory" ? full : path.dirname(full)
+  const glob =
+    process.platform === "win32"
+      ? AppFileSystem.normalizePathPattern(path.join(dir, "*"))
+      : path.join(dir, "*").replaceAll("\\", "/")
+
+  yield* ctx.ask({
+    permission: "external_directory",
+    patterns: [glob],
+    always: [glob],
+    metadata: {
+      filepath: full,
+      parentDir: dir,
+    },
+  })
+})
+
+export async function assertExternalDirectory(ctx: Tool.Context, target?: string, options?: Options) {
+  return Effect.runPromise(assertExternalDirectoryEffect(ctx, target, options).pipe(Effect.provide(EffectLogger.layer)))
+}
+
+/**
+ * The single write-permission gate for file-mutating tools (edit, write,
+ * apply_patch). Runs the two checks every write must pass, in order:
+ *   1. external_directory — asks before touching paths outside the worktree
+ *      (defers the memory subtree to the memory guard; see the early return above).
+ *   2. memory-path-guard — finer authority over the memory tree: a task-bound
+ *      subagent may write its own tasks/<taskId>/*.md, the checkpoint-writer its
+ *      canonical paths, and everything else is rejected.
+ *
+ * Collapsing both into one call removes the per-tool duplication and, more
+ * importantly, makes "call external_directory but forget the memory guard"
+ * unrepresentable — a new write tool that calls this one gate cannot drift into
+ * leaving the memory tree unguarded. Read-only tools (read/grep/glob/lsp) keep
+ * calling assertExternalDirectoryEffect directly; the memory guard is write-only.
+ */
+export const assertWriteAllowed = Effect.fn("Tool.assertWriteAllowed")(function* (
+  ctx: Tool.Context,
+  target?: string,
+  options?: Options,
+) {
+  yield* assertExternalDirectoryEffect(ctx, target, options)
+  if (!target) return
+
+  // Instance.current is a getter that THROWS when no instance is ALS-bound
+  // (detached fibers, tests without a project fixture). The optional chain runs
+  // only after the getter returns, so it cannot save us — the try/catch is
+  // load-bearing, not defensive dead code. Fall back to ProjectID.global so the
+  // guard can still resolve a canonical memory path. Mirrors session/checkpoint.ts.
+  const projectID = (() => {
+    try {
+      return (Instance.current?.project?.id as ProjectID | undefined) ?? ProjectID.global
+    } catch {
+      return ProjectID.global
+    }
+  })()
+
+  assertMemoryWriteAllowed({
+    target,
+    agentName: ctx.agent,
+    memoryRoot: path.join(Global.Path.data, "memory"),
+    projectID,
+    sessionID: ctx.sessionID,
+    taskId: ctx.taskId,
+  })
+})
+
+/**
+ * Perform the per-write `edit` permission ask, EXCEPT for targets under
+ * <data>/memory/. The memory tree's authority is memory-path-guard (invoked by
+ * assertWriteAllowed, which every write tool calls first): it already allows the
+ * checkpoint-writer / task-bound subagent their canonical paths and rejects
+ * everything else. Asking `edit` there is redundant and — for a background fork
+ * inheriting a parent's `edit:ask`/`deny` — would deny/skip the checkpoint write.
+ * Outside the memory tree, ask exactly as the write tools did inline before.
+ *
+ * Mirrors the external_directory memory-region deferral added in the 2026-06-04
+ * poststop-progress-permission-deadlock fix (see assertExternalDirectoryEffect).
+ */
+export const askEditUnlessMemory = Effect.fn("Tool.askEditUnlessMemory")(function* (
+  ctx: Tool.Context,
+  filepath: string,
+  input: { patterns: string[]; diff: string; files?: unknown },
+) {
+  const full = process.platform === "win32" ? AppFileSystem.normalizePath(filepath) : filepath
+  if (AppFileSystem.contains(path.join(Global.Path.data, "memory"), full)) return
+  yield* ctx.ask({
+    permission: "edit",
+    patterns: input.patterns,
+    always: ["*"],
+    metadata: { filepath, diff: input.diff, ...(input.files !== undefined ? { files: input.files } : {}) },
+  })
+})

package/src/tool/glob.ts

@@ -0,0 +1,100 @@
+import path from "path"
+import z from "zod"
+import { Effect, Option } from "effect"
+import * as Stream from "effect/Stream"
+import { InstanceState } from "@/effect"
+import { AppFileSystem } from "@mty-coder/shared/filesystem"
+import { Ripgrep } from "../file/ripgrep"
+import { assertExternalDirectoryEffect } from "./external-directory"
+import { SessionCwd } from "./session-cwd"
+import DESCRIPTION from "./glob.txt"
+import * as Tool from "./tool"
+
+export const GlobTool = Tool.define(
+  "glob",
+  Effect.gen(function* () {
+    const rg = yield* Ripgrep.Service
+    const fs = yield* AppFileSystem.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: z.object({
+        pattern: z.string().describe("The glob pattern to match files against"),
+        path: z
+          .string()
+          .optional()
+          .describe(
+            `The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.`,
+          ),
+      }),
+      execute: (params: { pattern: string; path?: string }, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const ins = yield* InstanceState.context
+          yield* ctx.ask({
+            permission: "glob",
+            patterns: [params.pattern],
+            always: ["*"],
+            metadata: {
+              pattern: params.pattern,
+              path: params.path,
+            },
+          })
+
+          let search = params.path ?? SessionCwd.get(ctx.sessionID)
+          search = path.isAbsolute(search) ? search : path.resolve(SessionCwd.get(ctx.sessionID), search)
+          const info = yield* fs.stat(search).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          if (info?.type === "File") {
+            throw new Error(`glob path must be a directory: ${search}`)
+          }
+          yield* assertExternalDirectoryEffect(ctx, search, { kind: "directory" })
+
+          const limit = 100
+          let truncated = false
+          const files = yield* rg.files({ cwd: search, glob: [params.pattern], signal: ctx.abort }).pipe(
+            Stream.mapEffect((file) =>
+              Effect.gen(function* () {
+                const full = path.resolve(search, file)
+                const info = yield* fs.stat(full).pipe(Effect.catch(() => Effect.succeed(undefined)))
+                const mtime =
+                  info?.mtime.pipe(
+                    Option.map((date) => date.getTime()),
+                    Option.getOrElse(() => 0),
+                  ) ?? 0
+                return { path: full, mtime }
+              }),
+            ),
+            Stream.take(limit + 1),
+            Stream.runCollect,
+            Effect.map((chunk) => [...chunk]),
+          )
+
+          if (files.length > limit) {
+            truncated = true
+            files.length = limit
+          }
+          files.sort((a, b) => b.mtime - a.mtime)
+
+          const output = []
+          if (files.length === 0) output.push("No files found")
+          if (files.length > 0) {
+            output.push(...files.map((file) => file.path))
+            if (truncated) {
+              output.push("")
+              output.push(
+                `(Results are truncated: showing first ${limit} results. Consider using a more specific path or pattern.)`,
+              )
+            }
+          }
+
+          return {
+            title: path.relative(ins.worktree, search),
+            metadata: {
+              count: files.length,
+              truncated,
+            },
+            output: output.join("\n"),
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/glob.txt

@@ -0,0 +1,6 @@
+- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns
+- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the actor tool instead
+- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches as a batch that are potentially useful.

package/src/tool/grep.ts

@@ -0,0 +1,145 @@
+import path from "path"
+import z from "zod"
+import { Effect, Option } from "effect"
+import { AppFileSystem } from "@mty-coder/shared/filesystem"
+import { Ripgrep } from "../file/ripgrep"
+import { assertExternalDirectoryEffect } from "./external-directory"
+import { SessionCwd } from "./session-cwd"
+import DESCRIPTION from "./grep.txt"
+import * as Tool from "./tool"
+
+const MAX_LINE_LENGTH = 2000
+
+export const GrepTool = Tool.define(
+  "grep",
+  Effect.gen(function* () {
+    const fs = yield* AppFileSystem.Service
+    const rg = yield* Ripgrep.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: z.object({
+        pattern: z.string().describe("The regex pattern to search for in file contents"),
+        path: z.string().optional().describe("The directory to search in. Defaults to the current working directory."),
+        include: z.string().optional().describe('File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")'),
+      }),
+      execute: (params: { pattern: string; path?: string; include?: string }, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const empty = {
+            title: params.pattern,
+            metadata: { matches: 0, truncated: false },
+            output: "No files found",
+          }
+          if (!params.pattern) {
+            throw new Error("pattern is required")
+          }
+
+          yield* ctx.ask({
+            permission: "grep",
+            patterns: [params.pattern],
+            always: ["*"],
+            metadata: {
+              pattern: params.pattern,
+              path: params.path,
+              include: params.include,
+            },
+          })
+
+          const effectiveCwd = SessionCwd.get(ctx.sessionID)
+          const search = AppFileSystem.resolve(
+            path.isAbsolute(params.path ?? effectiveCwd)
+              ? (params.path ?? effectiveCwd)
+              : path.join(effectiveCwd, params.path ?? "."),
+          )
+          const info = yield* fs.stat(search).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          const cwd = info?.type === "Directory" ? search : path.dirname(search)
+          const file = info?.type === "Directory" ? undefined : [path.relative(cwd, search)]
+          yield* assertExternalDirectoryEffect(ctx, search, {
+            kind: info?.type === "Directory" ? "directory" : "file",
+          })
+
+          const result = yield* rg.search({
+            cwd,
+            pattern: params.pattern,
+            glob: params.include ? [params.include] : undefined,
+            file,
+            signal: ctx.abort,
+          })
+          if (result.items.length === 0) return empty
+
+          const rows = result.items.map((item) => ({
+            path: AppFileSystem.resolve(
+              path.isAbsolute(item.path.text) ? item.path.text : path.join(cwd, item.path.text),
+            ),
+            line: item.line_number,
+            text: item.lines.text,
+          }))
+          const times = new Map(
+            (yield* Effect.forEach(
+              [...new Set(rows.map((row) => row.path))],
+              Effect.fnUntraced(function* (file) {
+                const info = yield* fs.stat(file).pipe(Effect.catch(() => Effect.succeed(undefined)))
+                if (!info || info.type === "Directory") return undefined
+                return [
+                  file,
+                  info.mtime.pipe(
+                    Option.map((time) => time.getTime()),
+                    Option.getOrElse(() => 0),
+                  ) ?? 0,
+                ] as const
+              }),
+              { concurrency: 16 },
+            )).filter((entry): entry is readonly [string, number] => Boolean(entry)),
+          )
+          const matches = rows.flatMap((row) => {
+            const mtime = times.get(row.path)
+            if (mtime === undefined) return []
+            return [{ ...row, mtime }]
+          })
+
+          matches.sort((a, b) => b.mtime - a.mtime)
+
+          const limit = 100
+          const truncated = matches.length > limit
+          const final = truncated ? matches.slice(0, limit) : matches
+          if (final.length === 0) return empty
+
+          const total = matches.length
+          const output = [`Found ${total} matches${truncated ? ` (showing first ${limit})` : ""}`]
+
+          let current = ""
+          for (const match of final) {
+            if (current !== match.path) {
+              if (current !== "") output.push("")
+              current = match.path
+              output.push(`${match.path}:`)
+            }
+            const text =
+              match.text.length > MAX_LINE_LENGTH ? match.text.substring(0, MAX_LINE_LENGTH) + "..." : match.text
+            output.push(`  Line ${match.line}: ${text}`)
+          }
+
+          if (truncated) {
+            output.push("")
+            output.push(
+              `(Results truncated: showing ${limit} of ${total} matches (${total - limit} hidden). Consider using a more specific path or pattern.)`,
+            )
+          }
+
+          if (result.partial) {
+            output.push("")
+            output.push("(Some paths were inaccessible and skipped)")
+          }
+
+          return {
+            title: params.pattern,
+            metadata: {
+              matches: total,
+              truncated,
+            },
+            output: output.join("\n"),
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/grep.txt

@@ -0,0 +1,8 @@
+- Fast content search tool that works with any codebase size
+- Searches file contents using regular expressions
+- Supports full regex syntax (eg. "log.*Error", "function\s+\w+", etc.)
+- Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
+- Returns file paths and line numbers with at least one match sorted by modification time
+- Use this tool when you need to find files containing specific patterns
+- If you need to identify/count the number of matches within files, use the Bash tool with `rg` (ripgrep) directly. Do NOT use `grep`.
+- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the actor tool instead

package/src/tool/history.ts

@@ -0,0 +1,146 @@
+import { Effect } from "effect"
+import z from "zod"
+import { History } from "@/history"
+import DESCRIPTION from "./history.txt"
+import * as Tool from "./tool"
+import * as Truncate from "./truncate"
+import { Agent } from "@/agent/agent"
+
+const KIND = z.enum([
+  "user_text",
+  "assistant_text",
+  "tool_input",
+  "tool_error",
+  "reasoning",
+  "tool_output",
+])
+
+// around() output can easily be tens of KB (multi-message contexts with full
+// part bodies including reasoning/tool blocks). Capping below the global
+// MAX_BYTES nudges agents toward "search → message_id → targeted Read" instead
+// of one giant inline dump. Only history.around uses this; other tools keep
+// the framework default.
+const AROUND_MAX_BYTES = 20 * 1024
+
+const parameters = z.object({
+  operation: z.enum(["search", "around"]).describe("search: FTS BM25; around: pull message context"),
+  // search params
+  query: z.string().optional().describe("FTS query (BM25 over text/tool bodies). Required for operation=search."),
+  scope: z.enum(["project", "global"]).optional().describe("Default project."),
+  session_id: z.string().optional(),
+  kind: z.array(KIND).optional(),
+  tool_name: z.string().optional().describe("Filter to a specific tool (e.g. Bash, Read)"),
+  time_after: z.number().optional().describe("Unix ms"),
+  time_before: z.number().optional(),
+  limit: z.number().optional().describe("Max 50, default 10"),
+  // around params
+  message_id: z.string().optional().describe("Anchor message id. Required for operation=around."),
+  before: z.number().optional().describe("Default 5"),
+  after: z.number().optional().describe("Default 5"),
+})
+
+export const HistoryTool = Tool.define(
+  "history",
+  Effect.gen(function* () {
+    const history = yield* History.Service
+    const truncate = yield* Truncate.Service
+    const agents = yield* Agent.Service
+    return {
+      description: DESCRIPTION,
+      parameters,
+      execute: (args: z.infer<typeof parameters>, ctx) =>
+        Effect.gen(function* () {
+          if (args.operation === "search") {
+            if (!args.query) {
+              return {
+                title: "History search: missing query",
+                output: "operation=search requires a `query` argument.",
+                metadata: { count: 0 },
+              }
+            }
+            const hits = yield* history.search({
+              query: args.query,
+              scope: args.scope,
+              session_id: args.session_id,
+              kind: args.kind,
+              tool_name: args.tool_name,
+              time_after: args.time_after,
+              time_before: args.time_before,
+              limit: args.limit,
+            })
+            if (hits.length === 0) {
+              return {
+                title: "History search: 0 matches",
+                output: `0 matches for "${args.query}". Try memory search if you haven't, or broaden the query.`,
+                metadata: { count: 0 },
+              }
+            }
+            const lines = [`Found ${hits.length} match${hits.length === 1 ? "" : "es"}:`, ""]
+            for (const h of hits) {
+              const kindLabel = h.tool_name ? `${h.kind} · ${h.tool_name}` : h.kind
+              lines.push(`### ${h.session_id} ${h.message_id}  (${kindLabel})`)
+              lines.push(`Time: ${new Date(h.time_created).toISOString()}, Score: ${h.score.toFixed(3)}`)
+              lines.push(h.snippet)
+              lines.push("")
+            }
+            return {
+              title: `History search: ${hits.length} match${hits.length === 1 ? "" : "es"}`,
+              output: lines.join("\n"),
+              metadata: { count: hits.length },
+            }
+          }
+
+          // operation=around
+          if (!args.message_id) {
+            return {
+              title: "History around: missing message_id",
+              output: "operation=around requires a `message_id` argument.",
+              metadata: { count: 0 },
+            }
+          }
+          const around = yield* history.around({
+            message_id: args.message_id,
+            before: args.before,
+            after: args.after,
+          })
+          if (around.messages.length === 0) {
+            return {
+              title: "History around: anchor not found",
+              output: `No message with id ${args.message_id}.`,
+              metadata: { count: 0 },
+            }
+          }
+          const lines = [
+            `Session ${around.session_id}, ${around.messages.length} messages (anchor ${args.message_id}):`,
+            "",
+          ]
+          for (const m of around.messages) {
+            const prefix = m.matched ? ">>>" : "---"
+            lines.push(`${prefix} ${m.message_id} (${new Date(m.time_created).toISOString()})`)
+            for (const p of m.parts) {
+              const head = p.tool_name ? `${p.type} (${p.tool_name})` : p.type
+              lines.push(`  ${p.role} · ${head}:`)
+              lines.push(p.text.split("\n").map((l) => `    ${l}`).join("\n"))
+            }
+            lines.push("")
+          }
+          const rawOutput = lines.join("\n")
+          // around() output is naturally large; cap below the framework default
+          // and let the truncation file fallback handle the overflow. The
+          // metadata.truncated set here also opts us out of tool.ts wrap's
+          // global truncate call (see tool.ts:110).
+          const agent = yield* agents.get(ctx.agent)
+          const truncated = yield* truncate.output(rawOutput, { maxBytes: AROUND_MAX_BYTES }, agent)
+          return {
+            title: `History around ${args.message_id}`,
+            output: truncated.content,
+            metadata: {
+              count: around.messages.length,
+              truncated: truncated.truncated,
+              ...(truncated.truncated && { outputPath: truncated.outputPath }),
+            },
+          }
+        }),
+    }
+  }),
+)

package/src/tool/history.txt

@@ -0,0 +1,17 @@
+Search RAW conversation trajectory: prior user/assistant messages, tool inputs, tool errors.
+
+USE ONLY WHEN MEMORY SEARCH RETURNS NOTHING USEFUL.
+
+memory is your curated notebook — small, fast, semantically organized. ALWAYS try `memory` first.
+history is the unindexed firehose of your past sessions: bigger, noisier, slower, and tool result
+cap will likely truncate `around` output forcing a follow-up Grep/Read. Reach for it as a last
+resort, e.g.:
+  - memory had no entry, but you suspect this came up in a prior session
+  - you need verbatim recall of something the memory summary glossed over
+  - debugging "did I already try X" across the project
+
+Two operations:
+  - search: FTS BM25 over text/tool kinds (returns snippets + message_ids)
+  - around: given a search hit's message_id, pull ±N surrounding messages from the raw store
+
+Default scope is current project; pass scope="global" to search every project on this machine.

package/src/tool/index.ts

@@ -0,0 +1,4 @@
+export * as Truncate from "./truncate"
+export * as ToolRegistry from "./registry"
+export * as Tool from "./tool"
+export * as BashInteractive from "./bash-interactive"

package/src/tool/invalid.ts

@@ -0,0 +1,20 @@
+import z from "zod"
+import { Effect } from "effect"
+import * as Tool from "./tool"
+
+export const InvalidTool = Tool.define(
+  "invalid",
+  Effect.succeed({
+    description: "Do not use",
+    parameters: z.object({
+      tool: z.string(),
+      error: z.string(),
+    }),
+    execute: (params: { tool: string; error: string }) =>
+      Effect.succeed({
+        title: "Invalid Tool",
+        output: `The arguments provided to the tool are invalid: ${params.error}`,
+        metadata: {},
+      }),
+  }),
+)

package/src/tool/invocation-style.ts

@@ -0,0 +1,17 @@
+export type InvocationStyle = "json" | "shell"
+
+// Shape of the `tool` config block (config.ts: cfg.tool). Kept structural so the
+// helper has no dependency on the Config service — it's a pure decision function.
+export interface ToolStyleConfig {
+  invocation_style?: InvocationStyle
+  invocation_style_by_tool?: Record<string, InvocationStyle>
+}
+
+// Single source of truth for "which invocation style is tool <toolId> in".
+// Per-tool override wins; otherwise the global default; otherwise "json".
+// NOTE: this resolves the *configured* style. A tool with no `shell` field still
+// falls back to JSON at the registry (tool.shell !== undefined guard) — callers
+// that care about the rendered form must also know whether the tool has a shell.
+export function resolveInvocationStyle(cfg: ToolStyleConfig | undefined, toolId: string): InvocationStyle {
+  return cfg?.invocation_style_by_tool?.[toolId] ?? cfg?.invocation_style ?? "json"
+}