tinker-agent 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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
+
+- Add `tinker update` for manually upgrading a direct npm global installation to
+  the latest stable release from the official npm registry.
+
+### Fixed
+
+- Wait for completed background-task output to finish flushing before returning
+  it through `TaskOutput`.
+
 ## [1.7.0] - 2026-08-01
 
 ### Added
@@ -149,7 +175,9 @@ 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.7.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
 [1.5.1]: https://github.com/ishowshao/tinker/releases/tag/v1.5.1

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)
@@ -80,11 +81,17 @@ The installed package exposes this public CLI:
 | `tinker run [--profile <profile-name>] [--yolo] <prompt>` | Submit one shell-quoted prompt argument. |
 | `tinker run [--profile <profile-name>] [--yolo] --stdin` | Read the prompt from standard input until EOF. |
 | `tinker run [--profile <profile-name>] [--yolo] --file <path>` | Read the prompt from a UTF-8 text file. |
+| `tinker update` | Update the global npm installation from the official npm registry. |
 | `tinker --help` | Show top-level CLI help. |
 | `tinker help run` | Show one-shot command help. |
+| `tinker help update` | Show update command help. |
 | `tinker --version` | Print the installed package version. |
 <!-- END GENERATED: PUBLIC CLI COMMANDS -->
 
+`tinker update` is available only to direct npm global installations. It checks
+the `latest` stable version on the official npm registry, updates that same global
+prefix, and exits without loading model configuration or starting a session.
+
 Repository development commands are separate from the installed CLI:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -59,6 +59,7 @@
     "chrome:diagnose": "bun packages/tinker-chrome/src/cli.ts diagnose",
     "chrome:install-host": "bun packages/tinker-chrome/src/cli.ts install-host",
     "chrome:mcp": "bun packages/tinker-chrome/src/cli.ts mcp",
+    "chrome:smoke": "bun packages/tinker-chrome/scripts/live-smoke.ts",
     "docs:generate": "bun scripts/render-public-contract-docs.ts --write",
     "docs:check": "bun scripts/render-public-contract-docs.ts --check",
     "tinker": "bun src/cli/index.ts",
@@ -93,6 +94,7 @@
     "markdansi": "0.3.2",
     "marked": "^18.0.5",
     "openai": "^7.1.0",
+    "puppeteer-core": "25.4.0",
     "react": "^19.2.7",
     "sharp": "^0.35.3",
     "shiki": "^4.3.1",

package/src/agent/runtime-session.ts

@@ -635,6 +635,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       if (mcpConfig !== undefined) {
         session.mcpManager = await dependencies.createMcpManager({
           config: mcpConfig,
+          workspaceRoot: input.workspaceRoot,
           runtimeSession: session.context,
           timeoutMs: input.toolingConfig?.mcpTimeoutMs,
           maxObservationChars: input.toolingConfig?.mcpMaxObservationChars,

package/src/cli/command-line.ts

@@ -5,6 +5,7 @@ import { CliUsageError, type CliCommandScope } from "./output";
 
 export type CliCommand =
   | { readonly type: "tui"; readonly profileName?: string }
+  | { readonly type: "update" }
   | {
       readonly type: "run";
       readonly profileName?: string;
@@ -129,6 +130,17 @@ export async function parseCommandLine(
       },
     );
 
+  program
+    .command(contract.update.command)
+    .description(contract.update.description)
+    .showHelpAfterError('Run "tinker update --help" for usage.')
+    .showSuggestionAfterError(false)
+    .allowExcessArguments(false)
+    .exitOverride()
+    .action(() => {
+      selectedCommand = Object.freeze({ type: "update" });
+    });
+
   try {
     await program.parseAsync([...args], { from: "user" });
   } catch (error) {
@@ -154,6 +166,12 @@ export async function parseCommandLine(
       "run",
     );
   }
+  if (selectedCommand.type === "update" && topLevelProfile !== undefined) {
+    throw new CliUsageError(
+      "The top-level --profile option only applies to the TUI.",
+      "update",
+    );
+  }
   return Object.freeze({ type: "command", command: selectedCommand });
 }
 
@@ -173,7 +191,7 @@ function preflightArgv(args: readonly string[]): CliCommandScope {
 
     if (
       (!rootBlocked && scope === "root" && isRootTerminalOption(token)) ||
-      (scope === "run" && isRunTerminalOption(token))
+      (scope !== "root" && isSubcommandTerminalOption(token))
     ) {
       return scope;
     }
@@ -202,6 +220,10 @@ function preflightArgv(args: readonly string[]): CliCommandScope {
         scope = "run";
         continue;
       }
+      if (token === "update") {
+        scope = "update";
+        continue;
+      }
       if (token === "help") {
         return "root";
       }
@@ -290,7 +312,7 @@ function isRootTerminalOption(token: string): boolean {
   );
 }
 
-function isRunTerminalOption(token: string): boolean {
+function isSubcommandTerminalOption(token: string): boolean {
   return token === "--help" || token === "-h";
 }
 

package/src/cli/main.ts

@@ -67,6 +67,14 @@ type OneShotRunner = {
   ) => Promise<number>;
 };
 
+type UpdateRunner = {
+  readonly runUpdate: (options: {
+    readonly metadata: PackageMetadata;
+    readonly stdout: CliOutputWriter;
+    readonly env: NodeJS.ProcessEnv;
+  }) => Promise<number>;
+};
+
 export type MainDependencies = {
   readonly loadPackageMetadata: () => Promise<PackageMetadata>;
   readonly parseCommandLine: (
@@ -81,6 +89,7 @@ export type MainDependencies = {
   ) => Promise<ResolvedPrompt>;
   readonly loadTuiRunner: () => Promise<TuiRunner>;
   readonly loadOneShotRunner: () => Promise<OneShotRunner>;
+  readonly loadUpdateRunner: () => Promise<UpdateRunner>;
 };
 
 const DEFAULT_DEPENDENCIES: MainDependencies = {
@@ -91,6 +100,7 @@ const DEFAULT_DEPENDENCIES: MainDependencies = {
   resolvePromptSource,
   loadTuiRunner: () => import("./tui-runner"),
   loadOneShotRunner: () => import("./run-runner"),
+  loadUpdateRunner: () => import("./update-runner"),
 };
 
 export async function main(
@@ -133,6 +143,22 @@ export async function main(
       return finish(0);
     }
 
+    if (parsed.command.type === "update") {
+      try {
+        const runner = await dependencies.loadUpdateRunner();
+        return finish(
+          await runner.runUpdate({
+            metadata,
+            stdout: input.stdout,
+            env,
+          }),
+        );
+      } catch (error) {
+        await writeCliOutput(input.stderr, renderCliFailure("Update failed", error));
+        return finish(1);
+      }
+    }
+
     let configBoundary: ConfigBoundary;
     let publicConfig: ResolvedPublicConfig;
     let runnerConfig: RunnerConfig;

package/src/cli/output.ts

@@ -4,7 +4,7 @@ const TRUNCATION_MARKER = "...[truncated]";
 const ESCAPE = String.fromCharCode(27);
 const ANSI_CSI_PATTERN = new RegExp(`${ESCAPE}\\[[0-?]*[ -/]*[@-~]`, "g");
 
-export type CliCommandScope = "root" | "run";
+export type CliCommandScope = "root" | "run" | "update";
 
 export interface CliOutputWriter {
   write(chunk: string): boolean | void;
@@ -24,9 +24,9 @@ export class CliUsageError extends Error {
 
 export function renderUsageError(error: CliUsageError): string {
   const hint =
-    error.scope === "run"
-      ? 'Run "tinker run --help" for usage.'
-      : 'Run "tinker --help" for usage.';
+    error.scope === "root"
+      ? 'Run "tinker --help" for usage.'
+      : `Run "tinker ${error.scope} --help" for usage.`;
   return `error: ${sanitizeDiagnosticDetail(error.message)}\n${hint}\n`;
 }
 

package/src/cli/public-cli-contract.ts

@@ -68,6 +68,10 @@ export const PUBLIC_CLI_CONTRACT = Object.freeze({
     helpAfter:
       "Use exactly one prompt source. For complex or sensitive prompts, prefer --stdin or --file.",
   }),
+  update: Object.freeze({
+    command: "update",
+    description: "Update the global npm installation from the official npm registry.",
+  }),
 });
 
 export type PublicCliContract = typeof PUBLIC_CLI_CONTRACT;

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/cli/update-runner.ts

@@ -0,0 +1,308 @@
+import { spawn } from "node:child_process";
+import { lstat, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadPackageMetadata, type PackageMetadata } from "./package-metadata";
+import { writeCliOutput, type CliOutputWriter } from "./output";
+
+export const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
+
+const OFFICIAL_PACKAGE_NAME = "tinker-agent";
+const MAX_NPM_OUTPUT_CHARACTERS = 32_768;
+
+type NpmCommandResult = {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+type NpmCommandInput = {
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+export type UpdateRunnerDependencies = {
+  readonly packageRoot: string;
+  readonly npmCwd: string;
+  readonly runNpm: (input: NpmCommandInput) => Promise<NpmCommandResult>;
+  readonly canonicalizePath: (filePath: string) => Promise<string>;
+  readonly isSymbolicLink: (filePath: string) => Promise<boolean>;
+  readonly readPackageMetadata: (packageJsonPath: string) => Promise<PackageMetadata>;
+  readonly compareVersions: (left: string, right: string) => -1 | 0 | 1;
+};
+
+type UpdateInput = {
+  readonly metadata: PackageMetadata;
+  readonly stdout: CliOutputWriter;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+const DEFAULT_DEPENDENCIES: UpdateRunnerDependencies = {
+  packageRoot: path.resolve(fileURLToPath(new URL("../../", import.meta.url))),
+  npmCwd: tmpdir(),
+  runNpm,
+  canonicalizePath: realpath,
+  isSymbolicLink: async (filePath) => (await lstat(filePath)).isSymbolicLink(),
+  readPackageMetadata: (packageJsonPath) =>
+    loadPackageMetadata(pathToFileURL(packageJsonPath)),
+  compareVersions: (left, right) => Bun.semver.order(left, right),
+};
+
+export async function runUpdate(
+  input: UpdateInput,
+  injected: Partial<UpdateRunnerDependencies> = {},
+): Promise<number> {
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...injected };
+  if (input.metadata.name !== OFFICIAL_PACKAGE_NAME) {
+    throw new Error("The installed package is not tinker-agent.");
+  }
+
+  await writeCliOutput(input.stdout, `Current version: ${input.metadata.version}\n`);
+  await writeCliOutput(
+    input.stdout,
+    "Checking npm official registry for the latest version...\n",
+  );
+
+  const globalRoot = await readGlobalPath(
+    dependencies,
+    input.env,
+    ["root", "--global"],
+    "npm global package root",
+  );
+  const globalPrefix = await readGlobalPath(
+    dependencies,
+    input.env,
+    ["prefix", "--global"],
+    "npm global prefix",
+  );
+  const installedRoot = path.join(globalRoot, input.metadata.name);
+  await assertGlobalInstallation(dependencies, installedRoot);
+
+  const latestResult = await runNpmChecked(
+    dependencies,
+    {
+      args: [
+        "view",
+        `${input.metadata.name}@latest`,
+        "version",
+        "--json",
+        "--registry",
+        OFFICIAL_NPM_REGISTRY,
+        "--prefer-online",
+      ],
+      cwd: dependencies.npmCwd,
+      env: input.env,
+    },
+    "Could not query the npm official registry",
+  );
+  const latestVersion = parseLatestVersion(latestResult.stdout);
+  const order = compareVersions(dependencies, input.metadata.version, latestVersion);
+
+  if (order === 0) {
+    await writeCliOutput(
+      input.stdout,
+      `Already up to date: ${input.metadata.version}\n`,
+    );
+    return 0;
+  }
+  if (order > 0) {
+    await writeCliOutput(
+      input.stdout,
+      `Installed version ${input.metadata.version} is newer than npm latest ${latestVersion}; no changes made.\n`,
+    );
+    return 0;
+  }
+
+  await writeCliOutput(input.stdout, `Updating to ${latestVersion}...\n`);
+  await runNpmChecked(
+    dependencies,
+    {
+      args: [
+        "install",
+        "--global",
+        "--prefix",
+        globalPrefix,
+        `${input.metadata.name}@${latestVersion}`,
+        "--registry",
+        OFFICIAL_NPM_REGISTRY,
+        "--prefer-online",
+        "--no-audit",
+        "--no-fund",
+        "--loglevel",
+        "error",
+      ],
+      cwd: dependencies.npmCwd,
+      env: input.env,
+    },
+    `npm could not install ${input.metadata.name}@${latestVersion}`,
+  );
+
+  let installedMetadata: PackageMetadata;
+  try {
+    installedMetadata = await dependencies.readPackageMetadata(
+      path.join(installedRoot, "package.json"),
+    );
+  } catch {
+    throw new Error("The updated package metadata could not be verified.");
+  }
+  if (
+    installedMetadata.name !== input.metadata.name ||
+    installedMetadata.version !== latestVersion
+  ) {
+    throw new Error(
+      `npm completed, but the active global installation is not version ${latestVersion}.`,
+    );
+  }
+
+  await writeCliOutput(
+    input.stdout,
+    `Successfully updated from ${input.metadata.version} to version ${latestVersion}\n`,
+  );
+  return 0;
+}
+
+async function readGlobalPath(
+  dependencies: UpdateRunnerDependencies,
+  env: NodeJS.ProcessEnv,
+  args: readonly string[],
+  label: string,
+): Promise<string> {
+  const result = await runNpmChecked(
+    dependencies,
+    { args, cwd: dependencies.npmCwd, env },
+    `Could not resolve the ${label}`,
+  );
+  const value = result.stdout.trim();
+  if (value === "" || !path.isAbsolute(value)) {
+    throw new Error(`npm returned an invalid ${label}.`);
+  }
+  return value;
+}
+
+async function assertGlobalInstallation(
+  dependencies: UpdateRunnerDependencies,
+  installedRoot: string,
+): Promise<void> {
+  try {
+    const [packageRoot, expectedRoot, linked] = await Promise.all([
+      dependencies.canonicalizePath(dependencies.packageRoot),
+      dependencies.canonicalizePath(installedRoot),
+      dependencies.isSymbolicLink(installedRoot),
+    ]);
+    if (linked || packageRoot !== expectedRoot) {
+      throw new Error("not a direct global installation");
+    }
+  } catch {
+    throw new Error(
+      "This Tinker installation is not managed by the active npm global prefix.",
+    );
+  }
+}
+
+function parseLatestVersion(stdout: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error("npm returned invalid update metadata.");
+  }
+  if (typeof parsed !== "string" || parsed.trim() === "") {
+    throw new Error("npm returned invalid update metadata.");
+  }
+  return parsed.trim();
+}
+
+function compareVersions(
+  dependencies: UpdateRunnerDependencies,
+  currentVersion: string,
+  latestVersion: string,
+): -1 | 0 | 1 {
+  try {
+    return dependencies.compareVersions(currentVersion, latestVersion);
+  } catch {
+    throw new Error("Tinker or npm returned an invalid semantic version.");
+  }
+}
+
+async function runNpmChecked(
+  dependencies: UpdateRunnerDependencies,
+  input: NpmCommandInput,
+  failureMessage: string,
+): Promise<NpmCommandResult> {
+  const result = await dependencies.runNpm(input);
+  if (result.exitCode === 0) {
+    return result;
+  }
+  const diagnostic = result.stderr.trim() || result.stdout.trim();
+  const status =
+    result.signal === null
+      ? `npm exited with code ${String(result.exitCode)}`
+      : `npm exited after ${result.signal}`;
+  throw new Error(
+    diagnostic === ""
+      ? `${failureMessage}: ${status}.`
+      : `${failureMessage}: ${diagnostic}`,
+  );
+}
+
+function runNpm(input: NpmCommandInput): Promise<NpmCommandResult> {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn("npm", [...input.args], {
+        cwd: input.cwd,
+        env: {
+          ...input.env,
+          NPM_CONFIG_UPDATE_NOTIFIER: "false",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      reject(new Error("npm could not be started."));
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout = appendBounded(stdout, chunk);
+    });
+    child.stderr.on("data", (chunk: string) => {
+      stderr = appendBounded(stderr, chunk);
+    });
+    child.once("error", (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const code = (error as NodeJS.ErrnoException).code;
+      reject(
+        new Error(
+          code === "ENOENT"
+            ? "npm was not found on PATH."
+            : "npm could not be started.",
+        ),
+      );
+    });
+    child.once("close", (exitCode, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve({ exitCode, signal, stdout, stderr });
+    });
+  });
+}
+
+function appendBounded(current: string, chunk: string): string {
+  if (current.length >= MAX_NPM_OUTPUT_CHARACTERS) {
+    return current;
+  }
+  return (current + chunk).slice(0, MAX_NPM_OUTPUT_CHARACTERS);
+}

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/mcp/mcp-manager.ts

@@ -1,15 +1,24 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
 import {
   StdioClientTransport,
   getDefaultEnvironment,
 } from "@modelcontextprotocol/sdk/client/stdio.js";
 import type { RuntimeSessionContext } from "../agent/runtime-session";
+import { ListRootsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import type { ToolExecutor } from "../tools/types";
 import type { McpConfig, McpServerConfig } from "./mcp-config";
 import { createMcpToolExecutor } from "./mcp-tool-executor";
 
 const STDERR_TAIL_MAX_CHARS = 2_000;
 
+function temporaryDirectoryEnvironment(): Record<string, string> {
+  return process.platform === "win32" ? { TEMP: tmpdir() } : { TMPDIR: tmpdir() };
+}
+
 export type McpClientConnection = {
   client: Client;
   close(): Promise<void>;
@@ -18,6 +27,7 @@ export type McpClientConnection = {
 export type McpClientFactory = (
   serverName: string,
   serverConfig: McpServerConfig,
+  workspaceRoot: string,
 ) => Promise<McpClientConnection>;
 
 export type McpManager = {
@@ -37,6 +47,7 @@ export type McpServerInventory = {
 
 export type CreateMcpManagerOptions = {
   config: McpConfig;
+  workspaceRoot: string;
   runtimeSession: RuntimeSessionContext;
   clientFactory?: McpClientFactory;
   timeoutMs?: number;
@@ -70,7 +81,11 @@ export async function createMcpManager(
       let tools;
 
       try {
-        connection = await clientFactory(serverName, serverConfig);
+        connection = await clientFactory(
+          serverName,
+          serverConfig,
+          options.workspaceRoot,
+        );
       } catch (error) {
         await options.runtimeSession.append({
           type: "mcp.server.failed",
@@ -227,11 +242,16 @@ async function closeConnections(
 async function stdioClientFactory(
   serverName: string,
   serverConfig: McpServerConfig,
+  workspaceRoot: string,
 ): Promise<McpClientConnection> {
   const transport = new StdioClientTransport({
     command: serverConfig.command,
     args: serverConfig.args,
-    env: { ...getDefaultEnvironment(), ...serverConfig.env },
+    env: {
+      ...getDefaultEnvironment(),
+      ...temporaryDirectoryEnvironment(),
+      ...serverConfig.env,
+    },
     cwd: serverConfig.cwd,
     stderr: "pipe",
   });
@@ -241,7 +261,18 @@ async function stdioClientFactory(
     stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_MAX_CHARS);
   });
 
-  const client = new Client({ name: "tinker", version: "0.1.0" });
+  const client = new Client(
+    { name: "tinker", version: "0.1.0" },
+    { capabilities: { roots: { listChanged: false } } },
+  );
+  client.setRequestHandler(ListRootsRequestSchema, () => ({
+    roots: [
+      {
+        uri: pathToFileURL(workspaceRoot).href,
+        name: path.basename(workspaceRoot),
+      },
+    ],
+  }));
 
   try {
     await client.connect(transport);

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/bash-task.ts

@@ -264,11 +264,7 @@ export class ShellTaskManager {
     }
 
     this.synchronizeTerminalState(task);
-    if (
-      task.mode === "pty" &&
-      isTerminalStatus(task.status) &&
-      task.finalScreen === undefined
-    ) {
+    if (isTerminalStatus(task.status)) {
       await task.completion;
     } else {
       await task.terminalScreen?.flush();

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,