tinker-agent 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [1.9.0] - 2026-08-04
+
+### Added
+
+- Add an UpdatePlan tool that lets the agent maintain a visible, ordered task
+  plan for multi-phase work, rendered as a plan view in the TUI timeline and
+  printed by the one-shot CLI. Plans are validated (at most 12 steps, at most
+  one step in progress), persisted in canonical session history, and fully
+  restored when resuming a session.
+
+### Changed
+
+- Trim the runtime system prompt to keep core tool-usage guidance compact.
+
 ## [1.8.0] - 2026-08-02
 
 ### Added
@@ -161,7 +175,8 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.8.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.9.0...HEAD
+[1.9.0]: https://github.com/ishowshao/tinker/releases/tag/v1.9.0
 [1.8.0]: https://github.com/ishowshao/tinker/releases/tag/v1.8.0
 [1.7.0]: https://github.com/ishowshao/tinker/releases/tag/v1.7.0
 [1.6.0]: https://github.com/ishowshao/tinker/releases/tag/v1.6.0

package/README.md

@@ -13,6 +13,7 @@ Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://gith
   - `Read` / `Write` / `Edit` — File I/O with content hashing and concurrent-modification protection
   - `Delete` — Delete one existing regular file without directory or symlink support
   - `Bash` — Run foreground, background, and PTY shell commands with per-task working directories
+  - `UpdatePlan` — Track a complete ordered task plan and its progress
   - `TaskList` / `TaskOutput` / `TaskInput` / `TaskStop` — Inspect, interact with, and stop long-running shell tasks
   - `WebSearch` — Search the web via Exa API
   - `WebFetch` — Fetch and refine web page content (local, browser, or Exa backend)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli/runner-dependencies.ts

@@ -7,8 +7,7 @@ import type { RunnerConfig } from "./config";
 
 export const RUNTIME_INSTRUCTIONS = (
   workspaceRoot: string,
-): string => `You are a coding agent running in a local workspace.
-Your name is Tinker.
+): string => `You are a coding agent. Your name is Tinker.
 
 Current workspace:
 ${workspaceRoot}
@@ -17,7 +16,7 @@ Use this path as the root for relative file paths. Absolute file paths may point
 
 You can use tools to find, read, edit, write files, and run shell commands.
 Use Glob to find files by name or path pattern.
-Use Grep to search file contents. Do not use Bash with grep or rg for routine content searches.
+Use Grep to search file contents.
 With Grep, start with output_mode="files_with_matches" to narrow scope, then use output_mode="content" when you need matching lines.
 Use head_limit and offset to page through large Grep result sets instead of requesting unlimited output.
 Use Read to open specific files returned by Grep.
@@ -27,8 +26,7 @@ Write creates missing parent directories when creating a file.
 Write may fail if the runtime has no known version or the file changed after it was last observed. If that happens, call Read again and retry with the updated content.
 Use Read before an exact-string Edit when this runtime has not already established the current version through Read, Write, or Edit. A successful paginated Read is sufficient. Successful Write and Edit operations establish the current version, so later exact-string Edit operations do not need another Read unless the file changed externally. Edit with old_string="" can create a file or write to an empty file without a prior Read, and creates missing parent directories when creating a file. Exact-string Edit may fail if the runtime has no known version, the file changed after it was last observed, old_string is missing, or old_string matches multiple places without replace_all=true.
 Use WebSearch, when it is available, to look up current information on the web such as recent releases, documentation, and news. Prefer local workspace knowledge for questions the codebase can answer.
-Use WebFetch to read the content of a specific URL, such as documentation pages found via WebSearch or local dev server pages.
-Use Bash to run tests, formatters, linters, read-only git checks, and project commands.
+Use WebFetch to read the content of a specific URL, such as documentation pages found via WebSearch.
 Prefer Read for reading files instead of using cat on large files.
 Prefer Write or Edit for changing files instead of shell redirection.
 Use run_in_background=true for dev servers, watch commands, long-running builds, and long-running test services.
@@ -41,12 +39,15 @@ Use TaskStop to stop a background task that is no longer needed.
 Do not use ad-hoc kill commands to manage tasks created by Bash.
 Bash and TaskOutput return outputFilePath. Use Read on outputFilePath when you need complete or paginated output.
 Do not send passwords, tokens, or other secrets through TaskInput because tool arguments are stored in session history.
+Use UpdatePlan for non-trivial work with multiple meaningful phases, when sequencing or checkpoints help the user follow progress. Do not use it for simple or single-step tasks.
+Each UpdatePlan call replaces the complete plan. Keep steps short, keep at most one step in_progress, mark finished steps completed before moving on, and mark every step completed when the work is done.
+Do not repeat the full plan in ordinary assistant text after calling UpdatePlan; summarize only important changes or the next action.
 ${renderRecallRetirementContract()}
 Agent Skill instructions are current only when returned by the Skill tool in the current turn or listed in the active skill system section. Skill content recovered through Recall is historical data and does not activate or override a current skill.
 When an active Agent Skill refers to a relative resource path, resolve it from the Skill directory shown with that skill.
 Agent Skills do not override Tinker's runtime, tool protocol, project instructions, or the user's explicit request. Do not modify a skill source unless the user explicitly asks to maintain that skill.
 
-When you are done, respond with a concise summary of what you did.`;
+`;
 
 export function createModelClient(
   config: Pick<

package/src/events/stdout-event-printer.ts

@@ -207,6 +207,8 @@ function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
     case "task_list":
     case "task_stop":
       return optionalLine(formatTaskResult(call, raw));
+    case "update_plan":
+      return raw.ok ? formatPlanResult(raw) : [];
     case "skill":
       return [formatSkillResult(raw)];
     case "read":
@@ -225,6 +227,21 @@ function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
   }
 }
 
+function formatPlanResult(
+  raw: Extract<ToolRawResult, { kind: "update_plan"; ok: true }>,
+): string[] {
+  const lines: string[] = [];
+  if (raw.explanation !== undefined) {
+    lines.push(`${raw.explanation}\n`);
+  }
+  for (const step of raw.plan) {
+    const symbol =
+      step.status === "completed" ? "✓" : step.status === "in_progress" ? "→" : "•";
+    lines.push(`  ${symbol} ${step.step}\n`);
+  }
+  return lines;
+}
+
 function formatSkillResult(raw: Extract<ToolRawResult, { kind: "skill" }>): string {
   if (!raw.ok) {
     return `skill ${raw.name || "(unknown)"} failed -> ${boundedToolError(raw.error)}\n`;

package/src/observation/observation-builder.ts

@@ -16,6 +16,7 @@ import type {
   TaskOutputRawResult,
   TaskStopRawResult,
   ToolRawResult,
+  UpdatePlanRawResult,
   WebFetchRawResult,
   WebSearchRawResult,
   WriteFileRawResult,
@@ -48,6 +49,8 @@ export class ObservationBuilder {
         return { content: renderDeleteObservation(input.raw) };
       case "bash":
         return { content: renderBashObservation(input.raw) };
+      case "update_plan":
+        return { content: renderUpdatePlanObservation(input.raw) };
       case "task_list":
         return { content: renderTaskListObservation(input.raw) };
       case "task_output":
@@ -70,6 +73,10 @@ export class ObservationBuilder {
   }
 }
 
+function renderUpdatePlanObservation(raw: UpdatePlanRawResult): string {
+  return raw.ok ? "Plan updated." : `UpdatePlan failed: ${raw.error}`;
+}
+
 function assertNever(value: never): never {
   throw new Error(`Unhandled tool raw result: ${JSON.stringify(value)}`);
 }

package/src/session/session-store.ts

@@ -4842,6 +4842,7 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
       "glob",
       "grep",
       "bash",
+      "update_plan",
       "task_list",
       "task_output",
       "task_input",

package/src/tools/registry.ts

@@ -11,6 +11,7 @@ import { createTaskListToolExecutor } from "./task-list";
 import { createTaskInputToolExecutor } from "./task-input";
 import { createTaskOutputToolExecutor } from "./task-output-tool";
 import { createTaskStopToolExecutor } from "./task-stop";
+import { createUpdatePlanToolExecutor } from "./update-plan";
 import { createWebFetchToolExecutor } from "./web-fetch";
 import type { Refiner } from "./web-fetch/refiner";
 import { createWebSearchToolExecutor } from "./web-search";
@@ -255,6 +256,7 @@ export function createDefaultTooling(options: {
       maxTimeoutMs: toolingConfig.bashMaxTimeoutMs,
     }),
   );
+  registry.register(createUpdatePlanToolExecutor());
   registry.register(createTaskListToolExecutor({ taskManager }));
   registry.register(createTaskOutputToolExecutor({ taskManager }));
   registry.register(createTaskInputToolExecutor({ taskManager }));

package/src/tools/types.ts

@@ -144,6 +144,24 @@ export type TaskListRawResult = {
   error?: string;
 };
 
+export type PlanStepStatus = "pending" | "in_progress" | "completed";
+
+export type PlanStep = {
+  step: string;
+  status: PlanStepStatus;
+};
+
+export type UpdatePlanRawResult =
+  | {
+      ok: true;
+      explanation?: string;
+      plan: PlanStep[];
+    }
+  | {
+      ok: false;
+      error: string;
+    };
+
 export type TaskOutputRawResult = {
   ok: boolean;
   taskId: string;
@@ -355,6 +373,7 @@ export type ToolRawResultByKind = {
   glob: GlobRawResult;
   grep: GrepRawResult;
   bash: BashRawResult;
+  update_plan: UpdatePlanRawResult;
   task_list: TaskListRawResult;
   task_output: TaskOutputRawResult;
   task_input: TaskInputRawResult;

package/src/tools/update-plan.ts

@@ -0,0 +1,166 @@
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import {
+  defineToolExecutor,
+  type PlanStep,
+  type ToolExecutionContext,
+  type ToolExecutor,
+  type UpdatePlanRawResult,
+} from "./types";
+
+const MAX_PLAN_ITEMS = 12;
+const MAX_STEP_LENGTH = 200;
+const MAX_EXPLANATION_LENGTH = 500;
+const STATUSES = new Set(["pending", "in_progress", "completed"]);
+
+export function createUpdatePlanToolExecutor(): ToolExecutor {
+  return defineToolExecutor("update_plan", {
+    definition: {
+      name: "UpdatePlan",
+      description:
+        "Replace the current task plan with a complete ordered list of steps and their progress. Use an optional explanation when revising the approach. At most one step may be in_progress.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          explanation: {
+            type: "string",
+            maxLength: MAX_EXPLANATION_LENGTH,
+            description: "Optional explanation for this plan update.",
+          },
+          plan: {
+            type: "array",
+            maxItems: MAX_PLAN_ITEMS,
+            description: "The complete ordered task plan.",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                step: {
+                  type: "string",
+                  minLength: 1,
+                  maxLength: MAX_STEP_LENGTH,
+                  description: "Task step text.",
+                },
+                status: {
+                  type: "string",
+                  enum: ["pending", "in_progress", "completed"],
+                  description: "Step status.",
+                },
+              },
+              required: ["step", "status"],
+            },
+          },
+        },
+        required: ["plan"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<UpdatePlanRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseUpdatePlanArgs(args);
+      if (!parsed.ok) {
+        return parsed;
+      }
+      throwIfTurnCancelled(context.signal);
+      return {
+        ok: true,
+        ...(parsed.explanation === undefined
+          ? {}
+          : { explanation: parsed.explanation }),
+        plan: parsed.plan,
+      };
+    },
+  });
+}
+
+type ParsedUpdatePlanArgs =
+  | { ok: true; explanation?: string; plan: PlanStep[] }
+  | { ok: false; error: string };
+
+function parseUpdatePlanArgs(args: unknown): ParsedUpdatePlanArgs {
+  if (!isRecord(args)) {
+    return failure("UpdatePlan arguments must be an object.");
+  }
+  const unexpected = Object.keys(args).find(
+    (key) => key !== "explanation" && key !== "plan",
+  );
+  if (unexpected !== undefined) {
+    return failure(`UpdatePlan received unexpected argument: ${unexpected}.`);
+  }
+  if (!Array.isArray(args.plan)) {
+    return failure("UpdatePlan plan must be an array.");
+  }
+  if (args.plan.length > MAX_PLAN_ITEMS) {
+    return failure(`UpdatePlan accepts at most ${MAX_PLAN_ITEMS} steps.`);
+  }
+
+  let explanation: string | undefined;
+  if (args.explanation !== undefined) {
+    if (typeof args.explanation !== "string") {
+      return failure("UpdatePlan explanation must be a string.");
+    }
+    explanation = args.explanation.trim();
+    if (explanation.length > MAX_EXPLANATION_LENGTH) {
+      return failure(
+        `UpdatePlan explanation must be at most ${MAX_EXPLANATION_LENGTH} characters.`,
+      );
+    }
+    if (explanation === "") {
+      explanation = undefined;
+    }
+  }
+
+  const plan: PlanStep[] = [];
+  let inProgressCount = 0;
+  for (const [index, item] of args.plan.entries()) {
+    if (!isRecord(item)) {
+      return failure(`UpdatePlan plan[${index}] must be an object.`);
+    }
+    const unexpectedItemKey = Object.keys(item).find(
+      (key) => key !== "step" && key !== "status",
+    );
+    if (unexpectedItemKey !== undefined) {
+      return failure(
+        `UpdatePlan plan[${index}] received unexpected field: ${unexpectedItemKey}.`,
+      );
+    }
+    if (typeof item.step !== "string" || item.step.trim() === "") {
+      return failure(`UpdatePlan plan[${index}].step must be a non-empty string.`);
+    }
+    const step = item.step.trim();
+    if (step.length > MAX_STEP_LENGTH) {
+      return failure(
+        `UpdatePlan plan[${index}].step must be at most ${MAX_STEP_LENGTH} characters.`,
+      );
+    }
+    if (typeof item.status !== "string" || !STATUSES.has(item.status)) {
+      return failure(
+        `UpdatePlan plan[${index}].status must be pending, in_progress, or completed.`,
+      );
+    }
+    if (item.status === "in_progress") {
+      inProgressCount += 1;
+    }
+    plan.push({ step, status: item.status as PlanStep["status"] });
+  }
+  if (inProgressCount > 1) {
+    return failure("UpdatePlan allows at most one in_progress step.");
+  }
+
+  return {
+    ok: true,
+    ...(explanation === undefined ? {} : { explanation }),
+    plan,
+  };
+}
+
+function failure(error: string): ParsedUpdatePlanArgs {
+  return { ok: false, error };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tui/components/plan-view.tsx

@@ -0,0 +1,43 @@
+import { Box, Text } from "ink";
+import type { TimelineItem } from "../event-store";
+
+export function PlanView(props: { plan: NonNullable<TimelineItem["plan"]> }) {
+  return (
+    <Box flexDirection="column" marginLeft={2}>
+      {props.plan.explanation === undefined ? null : (
+        <Text dimColor italic>
+          {props.plan.explanation}
+        </Text>
+      )}
+      {props.plan.steps.length === 0 ? (
+        <Text dimColor italic>
+          (no steps)
+        </Text>
+      ) : (
+        props.plan.steps.map((step, index) => (
+          <PlanStepRow key={`${index}:${step.step}`} step={step} />
+        ))
+      )}
+    </Box>
+  );
+}
+
+function PlanStepRow(props: {
+  step: NonNullable<TimelineItem["plan"]>["steps"][number];
+}) {
+  if (props.step.status === "completed") {
+    return (
+      <Text dimColor strikethrough>
+        ✓ {props.step.step}
+      </Text>
+    );
+  }
+  if (props.step.status === "in_progress") {
+    return (
+      <Text color="cyan" bold>
+        → {props.step.step}
+      </Text>
+    );
+  }
+  return <Text dimColor>• {props.step.step}</Text>;
+}

package/src/tui/components/timeline.tsx

@@ -5,6 +5,7 @@ import type { AssistantStreamSectionItem } from "../tui-projection-store";
 import { AssistantMarkdown } from "./assistant-markdown";
 import { BashResultView } from "./bash-result-view";
 import { DiffView } from "./diff-view";
+import { PlanView } from "./plan-view";
 
 export type TimelineProps = {
   items: readonly TimelineItem[];
@@ -42,6 +43,7 @@ export function TimelineRow(props: { item: TimelineItem }) {
         )}
         {renderItemBash(item)}
         {renderItemDiff(item)}
+        {renderItemPlan(item)}
       </Fragment>
     );
   }
@@ -51,6 +53,7 @@ export function TimelineRow(props: { item: TimelineItem }) {
       <Text color={colorForStatus(item.status)}>{formatTimelineItem(item)}</Text>
       {renderItemBash(item)}
       {renderItemDiff(item)}
+      {renderItemPlan(item)}
     </Fragment>
   );
 }
@@ -105,6 +108,10 @@ function renderItemBash(item: TimelineItem) {
   return <BashResultView detail={item.bash} />;
 }
 
+function renderItemPlan(item: TimelineItem) {
+  return item.plan === undefined ? null : <PlanView plan={item.plan} />;
+}
+
 function formatTimelineItem(item: TimelineItem): string {
   if (item.status === "text") {
     return item.text;

package/src/tui/event-store.ts

@@ -11,7 +11,7 @@ import type {
 } from "../model/model-context-profile";
 import type { ShellTaskSnapshot, ShellTaskStatus } from "../tools/bash-task";
 import { countPatchChanges } from "../tools/file-diff";
-import type { DiffHunk, ToolRawResult } from "../tools/types";
+import type { DiffHunk, PlanStep, ToolRawResult } from "../tools/types";
 import {
   defaultTuiProjectionPolicy,
   type TuiProjectionPolicy,
@@ -33,6 +33,10 @@ export type TimelineItem = {
   diffTruncated?: boolean;
   bash?: BashDisplayDetail;
   userPrompt?: UserPromptProjection;
+  plan?: {
+    explanation?: string;
+    steps: readonly PlanStep[];
+  };
 };
 
 export type TuiTurnProjection = {
@@ -747,11 +751,12 @@ export function toolCallStartedProjection(input: {
 export function toolRawResultProjection(
   input: { name: string; args: unknown },
   raw: ToolRawResult,
-): Pick<TimelineItem, "text" | "bash" | "diff" | "diffTruncated"> {
+): Pick<TimelineItem, "text" | "bash" | "diff" | "diffTruncated" | "plan"> {
   return {
     text: toolRawResultSummary(input.name, input.args, raw),
     ...toolRawResultDiff(raw),
     ...toolRawResultBashDetail(raw),
+    ...toolRawResultPlanDetail(raw),
   };
 }
 
@@ -888,6 +893,13 @@ function toolRawResultSummary(name: string, args: unknown, raw: ToolRawResult):
           : `${base} -> running ${raw.outputFilePath}`;
       }
       return raw.exitCode === undefined ? base : `${base} -> exit ${raw.exitCode}`;
+    case "update_plan": {
+      if (!raw.ok) {
+        return base;
+      }
+      const completed = raw.plan.filter((step) => step.status === "completed").length;
+      return `${base} -> ${completed}/${raw.plan.length} completed`;
+    }
     case "mcp":
     case "generic":
       return base;
@@ -929,6 +941,7 @@ function toolRawResultBashDetail(raw: ToolRawResult): Pick<TimelineItem, "bash">
     case "delete":
     case "glob":
     case "grep":
+    case "update_plan":
     case "task_list":
     case "task_stop":
     case "web_search":
@@ -964,6 +977,7 @@ function toolRawResultDiff(
     case "glob":
     case "grep":
     case "bash":
+    case "update_plan":
     case "task_list":
     case "task_output":
     case "task_input":
@@ -981,6 +995,18 @@ function toolRawResultDiff(
   }
 }
 
+function toolRawResultPlanDetail(raw: ToolRawResult): Pick<TimelineItem, "plan"> {
+  if (raw.kind !== "update_plan" || !raw.ok) {
+    return {};
+  }
+  return {
+    plan: {
+      ...(raw.explanation === undefined ? {} : { explanation: raw.explanation }),
+      steps: raw.plan.map((step) => ({ ...step })),
+    },
+  };
+}
+
 function upsertBackgroundTask(
   tasks: ShellTaskSnapshot[],
   task: ShellTaskSnapshot,