@kkelly-offical/kkcode 0.1.7 → 0.2.3-preview.1

package/src/tool/mutation-guard.mjs

@@ -0,0 +1,54 @@
+import { readFile, stat } from "node:fs/promises"
+import { getFileReadState, extractTrackedView } from "./file-read-state.mjs"
+
+function missingReadMessage(displayPath, operation) {
+  return `error: "${displayPath}" has not been read yet. Read it first before ${operation}.`
+}
+
+function partialReadMessage(displayPath, operation) {
+  return `error: "${displayPath}" was only partially read. Read the full file before ${operation}.`
+}
+
+function staleReadMessage(displayPath, operation) {
+  return `error: "${displayPath}" has changed since it was last read. Read it again before ${operation}.`
+}
+
+function missingFileMessage(displayPath, operation) {
+  return `error: "${displayPath}" no longer exists. Re-read the latest workspace state before ${operation}.`
+}
+
+export async function validateExistingFileMutation({
+  targetPath,
+  displayPath,
+  operation,
+  requireFullRead = false
+}) {
+  const readState = getFileReadState(targetPath)
+  const label = String(displayPath || targetPath)
+  const action = String(operation || "modifying it")
+
+  if (!readState) {
+    return { ok: false, reason: "unread", message: missingReadMessage(label, action) }
+  }
+
+  if (requireFullRead && readState.isPartialView) {
+    return { ok: false, reason: "partial_read", message: partialReadMessage(label, action) }
+  }
+
+  try {
+    const fileStat = await stat(targetPath)
+    const currentTimestamp = Math.floor(fileStat.mtimeMs)
+    const currentContent = await readFile(targetPath, "utf8")
+    const currentTrackedView = extractTrackedView(currentContent, readState)
+    if (currentTrackedView === readState.content) {
+      return { ok: true, readState, currentTimestamp, currentContent }
+    }
+
+    return { ok: false, reason: "stale", message: staleReadMessage(label, action) }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { ok: false, reason: "missing", message: missingFileMessage(label, action) }
+    }
+    throw error
+  }
+}

package/src/tool/prompt/edit.txt

@@ -1,7 +1,7 @@
 Performs exact string replacements in files. Transactional with automatic rollback on failure.
 
 Usage:
-- You must use `read` at least once before editing. This tool will error if you attempt an edit without reading the file.
+- You must use `read` before editing. This tool will reject edits on unread or stale files.
 - When editing text from `read` output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + arrow (→). Everything after that arrow is the actual file content to match. Never include any part of the line number prefix in the `before` or `after` strings.
 - ALWAYS prefer editing existing files. NEVER write new files unless explicitly required.
 - Only use emojis if the user explicitly requests it.
@@ -22,6 +22,6 @@ When to use replace_all:
 Common mistakes and how to avoid them:
 - Editing without reading first → always `read` before `edit`
 - `before` too short, matches multiple locations → include surrounding lines for uniqueness
-- Stale content after failed edit → re-read the file, it may have changed
+- Stale content after failed edit → re-read the file, it may have changed; stale edits are rejected
 - Including line number prefixes in `before` → only use actual file content, not the "     1→" prefix
-- Using `edit` for whole-file replacement → use `write` instead for complete rewrites
+- Using `edit` for whole-file replacement → use `write` instead for complete rewrites

package/src/tool/prompt/multiedit.txt

@@ -16,5 +16,6 @@ Parameters:
 
 Rules:
 - You MUST `read` each file before editing it (same as `edit` tool).
+- Existing files in the batch must be freshly read. If any file is unread or stale, the whole batch is rejected.
 - If any change fails validation (no match, ambiguous match), the entire batch is rejected before any writes.
 - On write failure mid-batch, all previously applied changes are rolled back.

package/src/tool/prompt/notebookedit.txt

@@ -14,8 +14,9 @@ Operations:
 
 IMPORTANT:
 - The notebook must be a valid .ipynb JSON file with a "cells" array.
+- You MUST read the notebook before editing it. Unread or stale notebook edits are rejected.
 - cell_number is 0-indexed. The first cell is 0, second is 1, etc.
 - For insert mode, cell_type must be specified ("code" or "markdown").
 - Cell outputs are preserved during replace; cleared only if cell_type changes to "markdown".
 - When inserting code cells, outputs default to an empty array.
-- This tool reads the notebook, modifies the cells array, and writes it back atomically.
+- This tool reads the notebook, modifies the cells array, and writes it back atomically.

package/src/tool/prompt/patch.txt

@@ -1,24 +1,25 @@
-Replace a range of lines in a file by line number. Transactional with automatic rollback.
-
-Usage:
-- You MUST `read` the file first — patches on unread files are rejected.
-- Use `read` with offset/limit to view the relevant section, note line numbers, then call `patch`.
-- Lines are 1-based and the range is inclusive (both start_line and end_line are replaced).
-- To delete lines without replacement, pass content as empty string "".
-
-Parameters:
-- path (required): file path
-- start_line (required): first line to replace (1-based, inclusive)
-- end_line (required): last line to replace (1-based, inclusive)
-- content (required): replacement text (replaces the entire line range)
-
-When to use `patch` vs `edit`:
-- You know exact line numbers from a recent `read` → use `patch`
-- You know exact text to match but not line numbers → use `edit`
-- You need to replace many occurrences of a string → use `edit` with replace_all
-- You want to replace a large section (50+ lines) → use `patch` (only needs new content, not old)
-
-Workflow for large file modifications:
-1. `read` the file (or section with offset/limit)
-2. Note the line numbers of the section to change
-3. Call `patch` with start_line, end_line, and new content
+Replace a range of lines in a file by line number. Transactional with automatic rollback.
+
+Usage:
+- You MUST `read` the file first — patches on unread files are rejected.
+- If the file changed after your last read, `patch` will reject until you re-read it.
+- Use `read` with offset/limit to view the relevant section, note line numbers, then call `patch`.
+- Lines are 1-based and the range is inclusive (both start_line and end_line are replaced).
+- To delete lines without replacement, pass content as empty string "".
+
+Parameters:
+- path (required): file path
+- start_line (required): first line to replace (1-based, inclusive)
+- end_line (required): last line to replace (1-based, inclusive)
+- content (required): replacement text (replaces the entire line range)
+
+When to use `patch` vs `edit`:
+- You know exact line numbers from a recent `read` → use `patch`
+- You know exact text to match but not line numbers → use `edit`
+- You need to replace many occurrences of a string → use `edit` with replace_all
+- You want to replace a large section (50+ lines) → use `patch` (only needs new content, not old)
+
+Workflow for large file modifications:
+1. `read` the file (or section with offset/limit)
+2. Note the line numbers of the section to change
+3. Call `patch` with start_line, end_line, and new content

package/src/tool/prompt/read.txt

@@ -18,7 +18,7 @@ Assume this tool is able to read all files on the machine. If the user provides
 ## Critical Rules
 
 - ALWAYS use `read` to view files. NEVER use `bash` with cat/head/tail/type/Get-Content.
-- You MUST read a file before editing it with `edit`. Edits on unread files are rejected.
+- You MUST read an existing file before using `write`, `edit`, `patch`, or `notebookedit` on it. Unread or stale edits are rejected.
 - You can call multiple `read` tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
 - If the user provides a path to a screenshot, ALWAYS use this tool to view the file at that path.
 
@@ -32,9 +32,9 @@ Assume this tool is able to read all files on the machine. If the user provides
 
 ## Tips
 
-- Read the full file first to understand context before editing. Do not provide offset/limit unless necessary.
+- Read the full file first to understand context before editing. Offset/limit reads are treated as partial views and do not authorize whole-file overwrites.
 - For large files (1000+ lines), use offset+limit to read specific sections.
 - After a failed edit, re-read the file — it may have changed since your last read.
 - Line numbers in output help you locate exact positions for edits.
 - When reading multiple related files, read them all in parallel for efficiency.
-- When editing text from read output, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + →. Everything after that → is the actual file content to match. Never include any part of the line number prefix in edit operations.
+- When editing text from read output, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + →. Everything after that → is the actual file content to match. Never include any part of the line number prefix in edit operations.

package/src/tool/prompt/sysinfo.txt

@@ -0,0 +1,29 @@
+Return structured, read-only system and runtime information for the current machine/workspace.
+
+Use `sysinfo` when the user asks for:
+- system information
+- OS / runtime / shell summary
+- CPU / memory / disk summary
+- current workspace / package-manager / git-repo context
+
+Prefer `sysinfo` over raw `bash` when the goal is a concise environment summary.
+
+Parameters:
+- `sections` (optional): array of section names to return. Supported:
+  - `os`
+  - `runtime`
+  - `workspace`
+  - `cpu`
+  - `memory`
+  - `disk`
+- `path` (optional): workspace path to inspect for `workspace` / `disk` sections
+
+Examples:
+- `sysinfo()`
+- `sysinfo(sections=["os","runtime","workspace"])`
+- `sysinfo(sections=["disk"], path=".")`
+
+Safety:
+- This tool is read-only.
+- It does not dump full environment variables or process lists.
+- Use `bash` only when the user truly needs deeper platform-specific diagnostics.

package/src/tool/prompt/task.txt

@@ -1,6 +1,59 @@
 Launch a subagent to handle complex, multi-step tasks autonomously.
 
-Each task spawns a full, independent LLM session with its own context window. The subagent makes its own tool calls and returns a single result message when done.
+Each task spawns a delegated LLM session that makes its own tool calls and returns a single result message when done.
+
+# Delegation Decision Rules
+
+Stay local when:
+- The next step is a simple read/edit/run action you can do directly
+- Your immediate next action is blocked on the result, and delegation would only add latency
+- The work is tightly coupled to nearby edits you are already making
+- Routing is merely uncertain — do not delegate just to compensate for that uncertainty
+
+Delegate when:
+- The work needs multiple tool calls plus autonomous reasoning
+- The work is self-contained enough to brief clearly
+- The work can proceed in parallel without racing your current critical path
+
+# Fresh Session vs Forked Context vs Continued Session
+
+- New `task` calls start with fresh context by default. The subagent does NOT see your parent conversation unless you summarize it in the prompt.
+- Set `execution_mode="fork_context"` when the delegated task should start from a fork of the current parent session transcript. Use this for sidecar research, audits, or follow-up verification that materially benefits from current context.
+- `fork_context` is reserved for **read-only sidecar work**. If the delegated slice needs implementation or file mutation, prefer `fresh_agent`.
+- Use `session_id` only to continue an existing delegated session that already has the needed context.
+- `fork_context` inherits transcript context, but it does NOT change the parent/child result contract: the parent agent still owns synthesis and must wait for the child result instead of assuming it succeeded.
+- For implementation-heavy work, prefer a fresh task brief with explicit file scope. For follow-up questions or incremental continuation on the same delegated slice, continue the same `session_id`.
+- `isolation="worktree"` creates a **local detached git worktree** for isolated sidecar execution. This MVP is local-only and currently intended for background delegated runs.
+
+# Brief Writing Rules
+
+Every delegated prompt should include:
+- Objective: the concrete outcome to produce
+- Why: the context or decision pressure behind the task
+- Write scope: whether to mutate files or stay read-only
+- Starting points: relevant paths, symbols, tests, or commands
+- Constraints: architectural boundaries, forbidden edits, or safety rules
+- Deliverable: what the subagent should return (summary, patch, review findings, etc.)
+
+Never delegate understanding:
+- Do not hand off the core synthesis step with prompts like “based on your findings, fix it”
+- Parent agent owns synthesis, judgment, and final claims
+- Forked/background delegates report results; they do not authorize the parent to guess
+
+kkcode also accepts structured brief fields for these sections (`objective`, `why`, `write_scope`, `starting_points`, `constraints`, `deliverable`) and will synthesize the directive brief when `prompt` is omitted.
+
+## Execution contract
+
+Whether the brief is handwritten or synthesized, delegated work must follow this contract:
+- Stay local if a direct read/edit/run action would finish the next step faster
+- Do not delegate to compensate for routing uncertainty on a bounded local task
+- Avoid suggesting LongAgent-style escalation unless heavy multi-file evidence is actually present
+- Do not fabricate completion or present unfinished work as done
+- Do not peek at unfinished sibling work and convert guesses into facts
+- Background delegates cannot ask interactive questions; keep them self-contained
+- `isolation="worktree"` is local-only and must not be treated as a remote execution surface
+
+Good delegation briefs are directive and self-contained. The subagent should not need to infer hidden context.
 
 # Available subagent types
 
@@ -21,6 +74,7 @@ Use `task` when the work:
 - Benefits from an independent context window (protects main conversation from result noise)
 - Involves code review, deep research, or broad codebase exploration
 - Can be parallelized — launch multiple independent tasks simultaneously
+- Is safe to hand off without racing another agent on the same files
 
 <example>
 User: "Please investigate how authentication works in this project"
@@ -63,7 +117,7 @@ GOOD: glob(pattern="**/*.test.js")
 
 # Parameters
 
-- **prompt** (required): Detailed task description with ALL necessary context. The subagent starts fresh — it cannot see your conversation history. Include:
+- **prompt** (required unless `objective` is provided for a new run): Detailed task description with ALL necessary context. The subagent starts fresh — it cannot see your conversation history. Include:
   - What to do (specific instructions)
   - Why (context for decision-making)
   - Whether to write code or just research
@@ -71,7 +125,11 @@ GOOD: glob(pattern="**/*.test.js")
 
 - **subagent_type** (optional): One of "explore", "architect", "reviewer", "researcher", or omit for default build agent.
 
-- **run_in_background** (optional): Set to true to run as a background worker. Returns a task_id immediately — use `background_output` to check results later.
+- **session_id** (optional): Continue an existing delegated session when you need follow-up work on the same slice. Do NOT use this as a substitute for briefing a new task.
+- **execution_mode** (optional): `fresh_agent` (default) or `fork_context`. Use `fork_context` only when inheriting the parent transcript is genuinely useful and the delegated slice stays read-only.
+- **isolation** (optional): `default` (normal workspace) or `worktree` (local detached git worktree). `worktree` is currently meant for isolated background sidecar execution only.
+
+- **run_in_background** (optional): Set to true only for sidecar work that can continue while you do other things. Returns a task_id immediately — use `background_output` to check results later. Background delegates must be self-contained and cannot use `question`.
 
 # Important Behaviors
 
@@ -80,4 +138,8 @@ GOOD: glob(pattern="**/*.test.js")
 - You can launch multiple tasks in parallel for independent work — this is a key advantage.
 - Avoid duplicating work that subagents are already doing. If you delegated research, don't also search yourself.
 - Provide clear, self-contained prompts. The subagent has no access to your conversation context.
-- Clearly state whether you expect the agent to write code or just do research, since it cannot infer your intent.
+- Clearly state whether you expect the agent to write code or just do research, since it cannot infer your intent.
+- Do NOT launch overlapping delegates on the same file set unless coordination is explicit.
+- Do NOT "peek" at unfinished delegated work and present it as done. Wait for the result, then summarize it accurately.
+- Do NOT fabricate completion. If a background delegate is still running or blocked, report that truthfully.
+- If you launch background work, keep moving on non-overlapping tasks and report progress when the delegate finishes or blocks.

package/src/tool/prompt/write.txt

@@ -2,7 +2,7 @@ Writes a file to the local filesystem. Creates parent directories automatically.
 
 Usage:
 - This tool will overwrite the existing file if there is one at the provided path.
-- If this is an existing file, you MUST use the `read` tool first to read the file's contents.
+- If this is an existing file, you MUST use the `read` tool first to read the full file. Partial reads do not authorize whole-file writes.
 - ALWAYS prefer editing existing files with `edit`. NEVER write new files unless explicitly required.
 - NEVER proactively create documentation files (*.md) or README files. Only create documentation if explicitly requested by the user.
 - Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
@@ -35,4 +35,4 @@ When to use `write` vs `edit` vs `patch`:
 - Adding content to end of file → `write` with mode="append"
 - Changing a few lines in an existing file → `edit`
 - Renaming a variable across a file → `edit` with replace_all
-- Replacing a large section by line numbers → `patch`
+- Replacing a large section by line numbers → `patch`

package/src/tool/question-prompt.mjs

@@ -1,93 +1,99 @@
-import { stdin as input, stdout as output } from "node:process"
-import { createInterface } from "node:readline/promises"
-
-let customPromptHandler = null
-
-export function setQuestionPromptHandler(handler) {
-  customPromptHandler = typeof handler === "function" ? handler : null
-}
-
-export async function askQuestionInteractive({ questions }) {
-  if (!Array.isArray(questions) || questions.length === 0) {
-    return {}
-  }
-
-  // 1. TUI handler (registered by repl.mjs)
-  if (customPromptHandler) {
-    const answers = await customPromptHandler({ questions })
-    if (answers && typeof answers === "object") return answers
-  }
-
-  // 2. Non-TTY: return empty answers
-  if (!process.stdout.isTTY || !process.stdin.isTTY) {
-    return Object.fromEntries(questions.map((q) => [q.id, ""]))
-  }
-
-  // 3. TTY fallback: readline sequential Q&A
-  const rl = createInterface({ input, output })
-  const answers = {}
-  try {
-    for (const q of questions) {
-      console.log("")
-      console.log(`  ${q.text}`)
-      if (q.description) console.log(`  ${q.description}`)
-      const options = Array.isArray(q.options) ? q.options : []
-      if (options.length) {
-        for (let i = 0; i < options.length; i++) {
-          const opt = options[i]
-          console.log(`    ${i + 1}. ${opt.label}`)
-          if (opt.description) console.log(`       ${opt.description}`)
-        }
-        if (q.allowCustom !== false) {
-          console.log(`    ${options.length + 1}. Custom...`)
-        }
-      }
-      const raw = (await rl.question("  > ")).trim()
-      if (options.length) {
-        const idx = parseInt(raw, 10)
-        if (idx >= 1 && idx <= options.length) {
-          const chosen = options[idx - 1]
-          answers[q.id] = chosen.value || chosen.label
-        } else {
-          answers[q.id] = raw
-        }
-      } else {
-        answers[q.id] = raw
-      }
-    }
-  } finally {
-    rl.close()
-  }
-  return answers
-}
-
-export async function askPlanApproval({ plan, files = [] }) {
-  const fileList = files.length ? `\nFiles to modify:\n${files.map(f => `  - ${f}`).join("\n")}` : ""
-  const questions = [
-    {
-      id: "plan_approval",
-      text: `Plan Review`,
-      description: `${plan}${fileList}`,
-      options: [
-        { label: "Approve", value: "approve", description: "Proceed with this plan" },
-        { label: "Request Changes", value: "changes", description: "Revise and resubmit with feedback" },
-        { label: "Reject", value: "reject", description: "Cancel this plan entirely" }
-      ],
-      multi: false,
-      allowCustom: true
-    }
-  ]
-  const answers = await askQuestionInteractive({ questions })
-  const answer = String(answers.plan_approval || "").trim().toLowerCase()
-  if (answer === "approve" || answer === "1") {
-    return { approved: true, requestChanges: false, feedback: "" }
-  }
-  if (answer === "changes" || answer === "2") {
-    return { approved: false, requestChanges: true, feedback: "" }
-  }
-  if (answer === "reject" || answer === "3") {
-    return { approved: false, requestChanges: false, feedback: "" }
-  }
-  // Custom text input: treat as "request changes" with the text as feedback
-  return { approved: false, requestChanges: true, feedback: answer }
-}
+import { stdin as input, stdout as output } from "node:process"
+import { createInterface } from "node:readline/promises"
+
+let customPromptHandler = null
+
+export function setQuestionPromptHandler(handler) {
+  customPromptHandler = typeof handler === "function" ? handler : null
+}
+
+export async function askQuestionInteractive({ questions }) {
+  if (!Array.isArray(questions) || questions.length === 0) {
+    return {}
+  }
+
+  // 1. TUI handler (registered by repl.mjs)
+  if (customPromptHandler) {
+    const answers = await customPromptHandler({ questions })
+    if (answers && typeof answers === "object") return answers
+  }
+
+  // 2. Non-TTY: return empty answers
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    return Object.fromEntries(questions.map((q) => [q.id, ""]))
+  }
+
+  // 3. TTY fallback: readline sequential Q&A
+  const rl = createInterface({ input, output })
+  const answers = {}
+  try {
+    for (const q of questions) {
+      console.log("")
+      console.log(`  ${q.text}`)
+      if (q.description) console.log(`  ${q.description}`)
+      const options = Array.isArray(q.options) ? q.options : []
+      if (options.length) {
+        for (let i = 0; i < options.length; i++) {
+          const opt = options[i]
+          console.log(`    ${i + 1}. ${opt.label}`)
+          if (opt.description) console.log(`       ${opt.description}`)
+        }
+        if (q.allowCustom !== false) {
+          console.log(`    ${options.length + 1}. Custom...`)
+        }
+      }
+      const raw = (await rl.question("  > ")).trim()
+      if (options.length) {
+        const idx = parseInt(raw, 10)
+        if (idx >= 1 && idx <= options.length) {
+          const chosen = options[idx - 1]
+          answers[q.id] = chosen.value || chosen.label
+        } else {
+          answers[q.id] = raw
+        }
+      } else {
+        answers[q.id] = raw
+      }
+    }
+  } finally {
+    rl.close()
+  }
+  return answers
+}
+
+export async function askPlanApproval({ plan, files = [] }) {
+  const fileList = files.length ? `\nFiles to modify:\n${files.map(f => `  - ${f}`).join("\n")}` : ""
+  const questions = [
+    {
+      id: "plan_approval",
+      text: `Plan Review`,
+      description: `${plan}${fileList}`,
+      options: [
+        { label: "Approve", value: "approve", description: "Proceed with this plan" },
+        { label: "Request Changes", value: "changes", description: "Revise and resubmit with feedback" },
+        { label: "Reject", value: "reject", description: "Cancel this plan entirely" }
+      ],
+      multi: false,
+      allowCustom: true
+    }
+  ]
+  const answers = await askQuestionInteractive({ questions })
+  const answer = String(answers.plan_approval || "").trim().toLowerCase()
+  if (answer === "approve" || answer === "1") {
+    return { approved: true, requestChanges: false, feedback: "" }
+  }
+  if (answer === "changes" || answer === "2") {
+    const rl2 = createInterface({ input, output })
+    let changeFeedback = ""
+    try { changeFeedback = (await rl2.question("  Feedback> ")).trim() } catch {} finally { rl2.close() }
+    return { approved: false, requestChanges: true, feedback: changeFeedback }
+  }
+  if (answer === "reject" || answer === "3") {
+    const rl3 = createInterface({ input, output })
+    let rejectFeedback = ""
+    try { rejectFeedback = (await rl3.question("  Reason> ")).trim() } catch {} finally { rl3.close() }
+    return { approved: false, requestChanges: false, feedback: rejectFeedback }
+  }
+  // Custom text input: treat as "request changes" with the text as feedback
+  return { approved: false, requestChanges: true, feedback: answer }
+}