@aefree/pi-plastic 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## [0.5.2] - 2026-08-05
+
+### Fixed
+
+- Hardened the Bash GUI-diff guard for Plastic's `differences` alias, quoted subcommands, common CMD and PowerShell wrappers, `call`/`start`, `Start-Process`, CMD caret escaping, and direct `!`/`!!` shell commands; the internal process guard now rejects the alias too.
+- Added runtime-handler coverage and documented that user-scope installation is required to protect delegated Pi processes whose working directory does not load the originating project's package settings.
+
+## [0.5.1] - 2026-08-05
+
+### Changed
+
+- Clarified that preflight is situational rather than routine and that status, focused tests, and direct reads should precede intentional diff output.
+- Reduced agent-facing diff defaults, added caller-controlled body bounds and complete JSON response bounds, required selected paths or explicit `allPending=true` for workspace diffs (including direct-call guards), and limited generic diff discovery to one focused tool.
+
 ## [0.5.0] - 2026-08-05
 
 ### Added

package/README.md

@@ -70,8 +70,11 @@ Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package
 
 ## Safety behavior
 
+The Bash guards run only in Pi processes that actually load this package. A project-local install does not protect a delegated child process whose working directory resolves different project settings. Install `pi-plastic` at user scope (the default `pi install`, without `-l`) when subagents and sessions in arbitrary workspaces must inherit the guards. Restart existing Pi processes after installation or source changes.
+
 - `plastic_branchCreate` supports an explicit parent branch independent of the loaded workspace branch, defaults relative names to the current branch when no parent is supplied, and rejects top-level paths unless `allowRootBranch=true` is explicit.
-- `plastic_diff` remains a disabled alias by design; use `plastic_status` for changed-path listing, `plastic_diffFile` for one file, `plastic_workspaceDiff` for pending review, or `plastic_diffRevisions` for an explicit historical pair.
+- `plastic_diff` remains a disabled alias by design. Use `plastic_status` for changed-path listing; do not diff as routine post-edit validation or checkin preflight. When change-boundary evidence is needed, use `plastic_diffFile` for one exact file, `plastic_workspaceDiff` with selected paths or explicit `allPending=true`, or `plastic_diffRevisions` for an explicit historical pair. Diff responses use small defaults and caller-controlled `maxChars` bounds.
+- Preflight is not routine confirmation. Use it for ambiguous or broad mutation scope, moved/deleted path rewriting, compound operations, or explicit preview requests; otherwise rely on exact targets and the tools' runtime guards.
 - `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply.
 - Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
 - Merge tooling surfaces Plastic `FILE_CONFLICT` records and merge-state metadata from `cm status`.
@@ -95,16 +98,22 @@ If `output` is omitted, Plastic prints patch content to stdout. If `output` is p
 
 ## Install
 
-Install the stable GitHub release over HTTPS:
+Install the latest stable npm release at user scope so the safety guards also load for delegated child processes in other workspaces:
+
+```bash
+pi install npm:@aefree/pi-plastic
+```
+
+Install a pinned GitHub release over HTTPS:
 
 ```bash
-pi install git:github.com/aefreedman/pi-plastic@v0.4.0
+pi install git:github.com/aefreedman/pi-plastic@v0.5.1
 ```
 
 Equivalent SSH install:
 
 ```bash
-pi install git:git@github.com:aefreedman/pi-plastic@v0.4.0
+pi install git:git@github.com:aefreedman/pi-plastic@v0.5.1
 ```
 
 To intentionally track the moving default branch instead of a release tag:
@@ -125,6 +134,8 @@ Project-local install:
 pi install -l <path-to-pi-plastic>
 ```
 
+Project-local installation protects only Pi processes that load those project settings. It is insufficient as a global Bash safety rail when a subagent launches with another working directory.
+
 ## Requirements
 
 - Node.js 22.19.0 or newer

package/extensions/bash-cm-diff-guard.ts

@@ -6,17 +6,26 @@ import {
 } from "./shared/bash-command-guards";
 
 const BLOCK_MESSAGE =
-  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` to list changed paths, `plastic_diffFile` for one file, `plastic_workspaceDiff` for pending review, or `plastic_diffRevisions` for two explicit revisions.";
+  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` when only changed paths are needed. Do not diff routinely; when change-boundary evidence is necessary, use a focused `plastic_diffFile`, explicitly scoped `plastic_workspaceDiff`, or `plastic_diffRevisions`.";
 
-const DIRECT_CM_DIFF = /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:(?:"[^"]*[\\/]cm(?:\.exe)?"|'[^']*[\\/]cm(?:\.exe)?')|(?:[^"'\s]*[\\/])?cm(?:\.exe)?)\s+diff(?:\s|$)/i;
+const CM_EXECUTABLE = String.raw`(?:"(?:[^"]*[\\/])?cm(?:\.exe)?"|'(?:[^']*[\\/])?cm(?:\.exe)?'|(?:[^"'\s]*[\\/])?cm(?:\.exe)?)`;
+const DIFF_SUBCOMMAND = String.raw`(?:diff|differences)`;
+const DIRECT_CM_DIFF = new RegExp(String.raw`^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*${CM_EXECUTABLE}\s+["']?${DIFF_SUBCOMMAND}["']?(?:\s|$)`, "i");
+const POWERSHELL_START_PROCESS_CM_DIFF = new RegExp(String.raw`^(?:start-process|saps|start)\s+(?:-filepath\s+)?${CM_EXECUTABLE}(?=[\s;]|$)[\s\S]*?-argumentlist\s+(?:["'][^"']*${DIFF_SUBCOMMAND}[^"']*["']|${DIFF_SUBCOMMAND}(?:\s|,|$))`, "i");
+const POWERSHELL_INVOKE_EXPRESSION_CM_DIFF = new RegExp(String.raw`^(?:invoke-expression|iex)\s+["'][^"']*${CM_EXECUTABLE}\s+${DIFF_SUBCOMMAND}(?:\s|["'])`, "i");
 
 function isBashToolCall(event: { toolName?: string }): event is { toolName: "bash"; input: { command?: string } } {
   return event.toolName === "bash";
 }
 
 function segmentRunsCmDiff(segment: string): boolean {
-  const stripped = stripLeadingWrappers(stripAssignments(segment));
-  return DIRECT_CM_DIFF.test(stripped);
+  // cmd.exe removes caret escaping before dispatching the command.
+  const normalized = segment.replace(/\^(?=.)/g, "");
+  const stripped = stripLeadingWrappers(stripAssignments(normalized));
+  return DIRECT_CM_DIFF.test(stripped)
+    || POWERSHELL_START_PROCESS_CM_DIFF.test(normalized)
+    || POWERSHELL_START_PROCESS_CM_DIFF.test(stripped)
+    || POWERSHELL_INVOKE_EXPRESSION_CM_DIFF.test(stripped);
 }
 
 function commandRunsCmDiff(command: string): boolean {
@@ -47,4 +56,21 @@ export default function bashCmDiffGuard(pi: ExtensionAPI) {
       reason: BLOCK_MESSAGE,
     };
   });
+
+  pi.on("user_bash", async (event, ctx) => {
+    if (!event.command || !commandRunsCmDiff(event.command)) return;
+
+    if (ctx.hasUI) {
+      ctx.ui.notify("Blocked user shell command invoking cm diff", "warning");
+    }
+
+    return {
+      result: {
+        output: BLOCK_MESSAGE,
+        exitCode: 1,
+        cancelled: false,
+        truncated: false,
+      },
+    };
+  });
 }

package/extensions/shared/bash-command-guards.ts

@@ -1,10 +1,10 @@
 export const WRAPPED_COMMAND_PATTERNS = [
   /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?(?:bash|sh|zsh)(?:\.exe)?\s+-lc\s+(["'])([\s\S]*)\1$/i,
   /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?(?:bash|sh|zsh)(?:\.exe)?\s+-c\s+(["'])([\s\S]*)\1$/i,
-  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?cmd(?:\.exe)?\s+\/[ck]\s+(["'])([\s\S]*)\1$/i,
-  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?cmd(?:\.exe)?\s+\/[ck]\s+()([\s\S]+)$/i,
-  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?(?:pwsh|powershell)(?:\.exe)?\s+-command\s+(["'])([\s\S]*)\1$/i,
-  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?(?:pwsh|powershell)(?:\.exe)?\s+-command\s+()([\s\S]+)$/i,
+  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?cmd(?:\.exe)?(?:\s+\/[dqsvu](?::\S+)*)*\s+\/[ck]\s+(["'])([\s\S]*)\1$/i,
+  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?cmd(?:\.exe)?(?:\s+\/[dqsvu](?::\S+)*)*\s+\/[ck]\s+()([\s\S]+)$/i,
+  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?(?:pwsh|powershell)(?:\.exe)?(?:(?:\s+-(?:noprofile|noninteractive|nologo|sta|mta))|(?:\s+-executionpolicy\s+\S+))*\s+-(?:command|c)\s+(["'])([\s\S]*)\1$/i,
+  /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:["']?[^"'\s]*[\\/])?(?:pwsh|powershell)(?:\.exe)?(?:(?:\s+-(?:noprofile|noninteractive|nologo|sta|mta))|(?:\s+-executionpolicy\s+\S+))*\s+-(?:command|c)\s+()([\s\S]+)$/i,
 ];
 
 export function splitSegments(command: string): string[] {
@@ -25,6 +25,8 @@ export function stripLeadingWrappers(segment: string): string {
     const next = value
       .replace(/^sudo\s+/i, "")
       .replace(/^command\s+/i, "")
+      .replace(/^call\s+/i, "")
+      .replace(/^start\s+(?:["'][^"']*["']\s+)?(?:(?:\/wait|\/b|\/min|\/max|\/i|\/low|\/normal|\/high|\/realtime|\/abovenormal|\/belownormal)\s+)*/i, "")
       .replace(/^time\s+/i, "")
       .replace(/^nice(?:\s+(?:-n\s+)?-?\d+)?\s+/i, "");
 

package/index.ts

@@ -172,6 +172,7 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       normalizeWorkdirAliases(input);
       assignAlias(input, "leftRevision", ["left_revision"]);
       assignAlias(input, "rightRevision", ["right_revision"]);
+      assignAlias(input, "maxChars", ["max_chars"]);
       return input;
     },
   },
@@ -179,6 +180,7 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
     prepareArguments(args) {
       const input = normalizeArgs(args);
       normalizeWorkdirAliases(input);
+      assignAlias(input, "maxChars", ["max_chars"]);
       return input;
     },
   },
@@ -188,8 +190,10 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       normalizeWorkdirAliases(input);
       promoteSinglePath(input);
       assignAlias(input, "paths", ["items", "files"]);
+      assignAlias(input, "allPending", ["all_pending"]);
       assignAlias(input, "includePrivate", ["include_private"]);
       assignAlias(input, "maxFiles", ["max_files"]);
+      assignAlias(input, "maxChars", ["max_chars"]);
       return input;
     },
   },
@@ -708,12 +712,12 @@ export default function plasticTools(pi: ExtensionAPI) {
     description: "Search and enable Plastic SCM / Unity Version Control tools for workspace status and sync, changes and checkins, text-only diffs and patches, branches and merges, shelvesets, code reviews, and workspaces.",
     promptSnippet: "Use plastic_tool_search to find and enable Plastic SCM capabilities that are not active.",
     promptGuidelines: [
-      "Use plastic_tool_search before a Plastic SCM action when an appropriate plastic_* tool is not active. Inspect exact targets and use each tool's preflight and safety options before mutations.",
+      "Use plastic_tool_search before a Plastic SCM action when an appropriate plastic_* tool is not active. Inspect exact mutation targets. Do not preflight routinely: use preflight for ambiguous or broad scope, moved/deleted path rewriting, compound operations, or an explicit preview request.",
     ],
     parameters: Type.Object({
       query: Type.Optional(Type.String({ description: "Capability or workflow to search for." })),
       toolNames: Type.Optional(Type.Array(Type.String({ description: "Exact public Plastic tool name." }), { maxItems: 4, description: "Optional exact tool names to enable." })),
-      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4, description: "Maximum matching tools to enable. Defaults to the single best keyword match, except generic diff loads both safe text-only alternatives; exact toolNames requests may enable up to four." })),
+      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4, description: "Maximum matching tools to enable. Defaults to the single best keyword match; exact toolNames requests may enable up to four." })),
     }),
     async execute(_toolCallId, params) {
       if (isPlasticToolBrowseRequest(params)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"

package/skills/using-plastic/SKILL.md

@@ -16,13 +16,13 @@ Treat `plastic_merge` success as provisional until `plastic_status` confirms the
 
 For the common closeout flow of merging a finished source branch into its parent branch, prefer `plastic_mergeToBranch` when available. When `target` is omitted, it resolves the source branch's Plastic parent branch instead of assuming `/dev`. It switches to the target, optionally updates, runs the safe merge, checks merge state, and checks in the merge result. Pass `target` only when the user explicitly wants a different integration branch.
 
-`plastic_diff` is intentionally disabled. Route changed-path listing to `plastic_status()`, one workspace file to `plastic_diffFile(path="<workspace-path>")`, pending review to `plastic_workspaceDiff()`, and an explicit historical pair to `plastic_diffRevisions`. `plastic_diffFile` uses machine-readable status: added and explicitly selected private/new files compare against an empty base; changed, moved, and deleted items use their reported base revision when available. A `--nodata` base failure means Plastic cannot provide historical bytes; refresh/update the workspace or use two known file-qualified revisions. Explicit `revision` behavior remains a separate historical request. Binary content is reported rather than decoded as text.
+`plastic_diff` is intentionally disabled. Route changed-path listing to `plastic_status()`, one intentional workspace-file comparison to `plastic_diffFile(path="<workspace-path>")`, an explicitly scoped pending review to `plastic_workspaceDiff(paths=[...])`, and an explicit historical pair to `plastic_diffRevisions`. Do not use diffs as routine post-edit validation or checkin preflight. Prefer focused tests, `plastic_status` for pending scope, and direct reads for current file content; diff only when change-boundary evidence is needed. `plastic_diffFile` uses machine-readable status: added and explicitly selected private/new files compare against an empty base; changed, moved, and deleted items use their reported base revision when available. A `--nodata` base failure means Plastic cannot provide historical bytes; refresh/update the workspace or use two known file-qualified revisions. Explicit `revision` behavior remains a separate historical request. Binary content is reported rather than decoded as text.
 
-`plastic_workspaceDiff` runs status once, has intentional file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. It excludes private files by default; select their paths explicitly or pass `includePrivate=true` only when intentional. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise GNU/POSIX `diff` on PATH; paths containing spaces are supported, but Pi does not discover Git Bash paths automatically. Pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
+`plastic_workspaceDiff` requires selected paths or explicit `allPending=true`, runs status once, has small default file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. Selected private paths are included; whole-workspace private review additionally requires `includePrivate=true`. Keep `maxChars` small unless more output is intentional. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise GNU/POSIX `diff` on PATH; paths containing spaces are supported, but Pi does not discover Git Bash paths automatically. Pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
 
 Prefer runtime `plastic_*` tools first. Keep `cm` shell commands as manual fallback.
 
-Directly invoked mutating `plastic_*` tools run without package-owned approval tokens or UI confirmation. Inspect exact targets, use available preflight modes, and rely on the tools' command, workspace, path-containment, and non-interactive process guards. A command process is attempted once without implicit retry; after an ambiguous failure, inspect Plastic status before deciding whether to retry manually.
+Directly invoked mutating `plastic_*` tools run without package-owned approval tokens or UI confirmation. Inspect exact targets and rely on the tools' command, workspace, path-containment, and non-interactive process guards. Do not call preflight and then the same operation as routine ceremony. Use preflight when mutation scope is ambiguous or broad, moved/deleted paths may need rewriting, a compound operation needs preview, or the user explicitly asks for one. A command process is attempted once without implicit retry; after an ambiguous failure, inspect Plastic status before deciding whether to retry manually.
 
 Create normal work branches beneath an intended parent: use `<parent-branch>/<new-branch>`, not `/<new-branch>`. The parent does not need to be the branch loaded in the workspace. Prefer `plastic_branchCreate(branch="<new-branch>", parent="<parent-branch>")`; omitting `parent` uses the current branch only as a convenience. Rare top-level branch creation requires the explicit `allowRootBranch=true` override.
 

package/skills/using-plastic/references/changeset-operations.md

@@ -53,7 +53,7 @@ cm status --all
 
 Safe checklist:
 - Confirm deleted items appear in status output before checkin.
-- Prefer `plastic_checkin(preflight=true, paths=[...])` so the tool can rewrite unstable file scopes (moved/deleted) to stable parent scopes.
+- For path-scoped checkins containing moved/deleted items, use `plastic_checkin(preflight=true, paths=[...])` so the tool can preview rewriting unstable file scopes to stable parent scopes. Do not preflight ordinary exact-scope checkins routinely.
 - `plastic_checkin` now inspects `cm status --machinereadable` and auto-enables `--applychanged` when moved/deleted items are in scope.
 - Re-run `cm status --all` after add/scope changes, then checkin.
 
@@ -71,14 +71,13 @@ cm checkin -c="<commit-message>"
 
 ## Safe Diff Usage
 
-Never run `cm diff` in Pi.
-
-Use one of these safe alternatives:
+Never run `cm diff` in Pi. Do not replace it with a routine safe-diff call: use `plastic_status` for pending scope, focused tests for behavior, and direct reads for current content. Request diff output only when change-boundary evidence is needed.
 
 ```text
 plastic_status(machineReadable=true) # list pending paths/statuses
-plastic_diffFile(path="<workspace-path>") # one workspace file
-plastic_workspaceDiff() # bounded pending review; excludes private unless selected/opted in
+plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped review
+plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```

package/skills/using-plastic/references/integration.md

@@ -4,7 +4,7 @@
 
 - Create feature branch following detected conventions.
 - Use incremental checkins.
-- Never use `cm diff`; use text-only diff tools.
+- Never use `cm diff`. Do not diff routinely; use a text-only diff tool only when review needs change-boundary evidence.
 - Use `plastic_merge` (or `cm merge ... --nointeractiveresolution --mergetype=try`) for autonomous merges.
 
 ## Autonomous Merge Workflow
@@ -34,11 +34,12 @@ plastic_patch(source="<branch-spec>", integration=true)
 plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
 ```
 
-- Inspect specific file content changes with the common workspace-base path first:
+- When change-boundary evidence is needed, inspect specific files first and opt into multi-file output explicitly:
 
 ```text
-plastic_diffFile(path="<workspace-path>") # one workspace file
-plastic_workspaceDiff() # bounded pending review
+plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
+plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```

package/skills/using-plastic/references/quick-reference.md

@@ -18,8 +18,8 @@ Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may d
 | Shelve | `plastic_shelvesetCreate(comment="description")` | `cm shelveset create -c="description"` | Save work temporarily |
 | Patch for review | `plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Focused branch-review patch; inspect before sharing |
 | Changed-file listing | `plastic_status(machineReadable=true)` | `cm status --all` | Lists changed, added, moved, deleted, and private items without GUI diff |
-| Diff (one workspace file) | `plastic_diffFile(path="<workspace-path>")` | None recommended | Uses status base materialization; added/private files use an empty base |
-| Diff (pending review) | `plastic_workspaceDiff()` | None recommended | Runs status once; bounded per-file outcomes; private files excluded unless selected/opted in |
+| Diff (one workspace file) | `plastic_diffFile(path="<workspace-path>", maxChars=4000)` | None recommended | Intentional focused comparison only; not routine validation |
+| Diff (pending review) | `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` | None recommended | Requires selected paths or explicit `allPending=true`; use status for changed-path listing |
 | Diff (workspace vs supported revision) | `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` | None recommended | Also accepts a branch, label, file-qualified, or global revision spec |
 | Diff (revision vs revision) | `plastic_diffRevisions(leftRevision="<left-revspec>", rightRevision="<right-revspec>")` | None recommended | Requires two file-qualified revisions; avoids GUI and package temp-file recipes |
 

package/skills/using-plastic/references/reviewing-changes.md

@@ -21,17 +21,18 @@ plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
 
 ## Text-Only Diff Options
 
-Prefer tool-first:
+Do not use diffs as routine post-edit validation or checkin preflight. Prefer focused tests, `plastic_status` for pending scope, and direct reads for current content. Use a diff only when change-boundary evidence is needed, such as reviewing unfamiliar changes or confirming a specific risky hunk.
 
 ```text
 plastic_status(machineReadable=true) # “what changed?” / changed-path listing
-plastic_diffFile(path="<workspace-path>") # one workspace file
-plastic_workspaceDiff() # bounded pending review; private files excluded by default
+plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
+plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
 plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit historical comparison
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
-The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` returns per-file unavailable outcomes instead of aborting the batch. All tools use bounded GNU/POSIX text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
+The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` requires selected paths or `allPending=true` and returns per-file unavailable outcomes instead of aborting the batch. All tools use bounded GNU/POSIX text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
 
 ## Metadata Listing (No GUI Diff)
 
@@ -50,9 +51,9 @@ Use the Read tool for full context instead of GUI diffs.
 Use the common no-revision path first; `base`, `head`, and `cs:head` are rejected rather than guessed:
 
 ```text
-plastic_diffFile(path="<workspace-path>")
-plastic_diffFile(path="<workspace-path>", revision="br:/<branch>")
-plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+plastic_diffFile(path="<workspace-path>", maxChars=4000)
+plastic_diffFile(path="<workspace-path>", revision="br:/<branch>", maxChars=4000)
+plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>", maxChars=4000)
 ```
 
 ## Pending Changes

package/skills/using-plastic/references/troubleshooting.md

@@ -41,8 +41,9 @@ cm codereview -e <review-id> --reviewer="reviewer-name"
 - `cm diff` is blocked in Pi because it can launch GUI windows and hang the CLI.
 - Use text-only alternatives:
   - `plastic_status(machineReadable=true)` for changed paths/statuses.
-  - `plastic_diffFile(path="<workspace-path>")` for one workspace file.
-  - `plastic_workspaceDiff()` for bounded pending review (private files are excluded unless selected/opted in).
+  - `plastic_diffFile(path="<workspace-path>", maxChars=4000)` when one intentional file comparison is needed.
+  - `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` for an explicitly scoped pending review, or `allPending=true` for an intentional small whole-workspace review.
+  - Use `plastic_status` instead when only pending paths are needed; do not diff routinely.
   - `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` for an explicit supported revision.
   - `plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")` for two historical files.
 
@@ -96,12 +97,12 @@ plastic_resolveDeleteChangeConflict(paths=["<workspace-path>"], keepOnDisk=true)
 
 - Do not use `cm diff --summary`; this form is invalid.
 - Also avoid all other `cm diff` forms in Pi.
-- Use the same text-only alternatives listed above.
+- Use `plastic_status` unless change-boundary evidence is actually needed; then use the focused text-only alternatives above.
 
 ## Deleted Files Missing From Checkin
 
 - Run `cm status --all` and confirm deleted items are listed before checkin.
-- Use `plastic_checkin(preflight=true, paths=[...])` first; the tool can auto-rewrite moved/deleted file scopes to parent directories.
+- For a path-scoped checkin containing moved/deleted items, use `plastic_checkin(preflight=true, paths=[...])`; the tool can preview rewriting unstable file scopes to parent directories. Do not add preflight to unrelated routine checkins.
 - If a path-scoped checkin is rejected as "not changed", rerun with `applyChanged=true` and a parent-directory scope.
 - Re-run `cm status --all` just before checkin to validate scope.
 

package/src/plastic-core.ts

@@ -245,12 +245,12 @@ const spawnAndCollect = async (
     }
 };
 
-const BLOCKED_CM_DIFF_MESSAGE = "`cm diff` is blocked in Pi because it may launch GUI windows and hang the CLI. Use `plastic_status` to list changed paths, `plastic_diffFile` for one file, `plastic_workspaceDiff` for pending review, or `plastic_diffRevisions` for two explicit revision specs.";
+const BLOCKED_CM_DIFF_MESSAGE = "`cm diff` is blocked in Pi because it may launch GUI windows and hang the CLI. Use `plastic_status` when only changed paths are needed. Do not diff routinely; when change-boundary evidence is necessary, use a focused `plastic_diffFile`, explicitly scoped `plastic_workspaceDiff`, or `plastic_diffRevisions`.";
 
 const ensureCmCommandAllowed = (args: string[]): void =>
 {
     const command = (args[0] ?? "").trim().toLowerCase();
-    if (command === "diff")
+    if (command === "diff" || command === "differences")
     {
         throw new Error(BLOCKED_CM_DIFF_MESSAGE);
     }
@@ -1276,7 +1276,14 @@ export const __plasticBranchInternals = {
     resolveBranchCreationTarget,
 };
 
+// Capture enough subprocess output for diagnostics while keeping the default
+// agent-facing response intentionally small. Callers may opt into a larger
+// focused response, but never the full capture bound.
 const DIFF_OUTPUT_MAX_CHARS = 60_000;
+const DIFF_RESPONSE_DEFAULT_MAX_CHARS = 8_000;
+const DIFF_RESPONSE_MAX_CHARS = 20_000;
+const DIFF_RESPONSE_MIN_CHARS = 500;
+const DIFF_RESPONSE_TOTAL_MAX_CHARS = 24_000;
 
 type TextDiffResult = {
     backend: "diff";
@@ -1395,37 +1402,47 @@ const materializeRevision = async (revision: string, destination: string, workdi
     }
 };
 
+const normalizeDiffResponseMaxChars = (value: unknown): number =>
+{
+    if (typeof value !== "number" || !Number.isFinite(value))
+    {
+        return DIFF_RESPONSE_DEFAULT_MAX_CHARS;
+    }
+    return Math.min(DIFF_RESPONSE_MAX_CHARS, Math.max(DIFF_RESPONSE_MIN_CHARS, Math.trunc(value)));
+};
+
 const formatTextDiff = async (
     action: "diffFile" | "diffRevisions",
     format: OutputFormat | undefined,
     comparisonKind: string,
-    result: TextDiffResult,
+    unboundedResult: TextDiffResult,
     workdir: string | undefined,
     comparisonMetadata: Record<string, unknown> = {},
+    maxChars?: number,
 ): Promise<string> =>
 {
+    const result = boundTextDiffResult(unboundedResult, normalizeDiffResponseMaxChars(maxChars));
     const status = result.binary ? (result.changed ? "binary-different" : "unchanged") : (result.changed ? "changed" : "unchanged");
     const text = result.binary
         ? (result.changed ? "Binary content differs; a text diff is unavailable." : "No differences.")
         : (result.changed ? result.output : "No differences.");
-    return toStructuredResult(
-        action,
-        format ?? "text",
-        text,
-        {
-            comparisonKind,
-            ...comparisonMetadata,
-            backend: result.backend,
-            status,
-            changed: result.changed,
-            binary: result.binary,
-            truncated: result.truncated,
-            totalChars: result.totalChars,
-            diff: result.changed && !result.binary ? result.output : undefined,
-        },
-        workdir,
-        result.truncated ? ["Diff output was truncated; use a narrower file or generate a review patch for the complete result."] : undefined,
-    );
+    const data = {
+        comparisonKind,
+        ...comparisonMetadata,
+        backend: result.backend,
+        status,
+        changed: result.changed,
+        binary: result.binary,
+        truncated: result.truncated,
+        totalChars: result.totalChars,
+        diff: result.changed && !result.binary ? result.output : undefined,
+    };
+    const warnings = result.truncated ? ["Diff output was truncated; use a narrower file or generate a review patch for the complete result."] : undefined;
+    if (format === "json")
+    {
+        return toBoundedDiffStructuredResult(action, data, workdir, warnings);
+    }
+    return text;
 };
 
 const isNoDataError = (message: string): boolean =>
@@ -1459,9 +1476,10 @@ const boundTextDiffResult = (result: TextDiffResult, maxChars: number): TextDiff
         return result;
     }
 
+    const suffix = `\n\n[Diff output truncated at the requested ${maxChars}-character response bound.]`;
     return {
         ...result,
-        output: `${result.output.slice(0, maxChars)}\n\n[Per-file diff output truncated at ${maxChars} characters.]`,
+        output: suffix.length >= maxChars ? suffix.slice(0, maxChars) : `${result.output.slice(0, maxChars - suffix.length)}${suffix}`,
         truncated: true,
         totalChars: result.totalChars,
     };
@@ -1469,6 +1487,11 @@ const boundTextDiffResult = (result: TextDiffResult, maxChars: number): TextDiff
 
 export const __plasticDiffInternals = {
     DIFF_OUTPUT_MAX_CHARS,
+    DIFF_RESPONSE_DEFAULT_MAX_CHARS,
+    DIFF_RESPONSE_MAX_CHARS,
+    DIFF_RESPONSE_MIN_CHARS,
+    DIFF_RESPONSE_TOTAL_MAX_CHARS,
+    normalizeDiffResponseMaxChars,
     isBinaryContent,
     stableDiffHeaders,
     boundDiffOutput,
@@ -1730,6 +1753,60 @@ const toStructuredResult = async (
     return `## ${action}\n\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
 };
 
+const toBoundedDiffStructuredResult = async (
+    action: "diffFile" | "diffRevisions",
+    data: Record<string, unknown>,
+    workdir?: string,
+    warnings?: string[],
+): Promise<string> =>
+{
+    const wrap = (payload: Record<string, unknown>): string => `## ${action}\n\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+    const basePayload = {
+        ok: true,
+        action,
+        toolVersion: TOOL_VERSION,
+        cliVersion: (await getCmVersion(workdir)).slice(0, 256),
+    };
+    const initial = wrap({ ...basePayload, data, ...(warnings?.length ? { warnings } : {}) });
+    if (initial.length <= DIFF_RESPONSE_TOTAL_MAX_CHARS)
+    {
+        return initial;
+    }
+
+    const originalDiff = typeof data.diff === "string" ? data.diff : "";
+    const responseWarning = `Diff content was further truncated after JSON escaping to keep the complete response within ${DIFF_RESPONSE_TOTAL_MAX_CHARS} characters.`;
+    const boundedWarnings = [...(warnings ?? []), responseWarning];
+    const suffix = `\n\n[Diff output truncated to keep the complete JSON response within ${DIFF_RESPONSE_TOTAL_MAX_CHARS} characters.]`;
+    const render = (prefixChars: number): string => wrap({
+        ...basePayload,
+        data: {
+            ...data,
+            truncated: true,
+            diff: `${originalDiff.slice(0, prefixChars)}${suffix}`,
+        },
+        warnings: boundedWarnings,
+    });
+
+    let low = 0;
+    let high = originalDiff.length;
+    let best = render(0);
+    while (low <= high)
+    {
+        const middle = Math.floor((low + high) / 2);
+        const candidate = render(middle);
+        if (candidate.length <= DIFF_RESPONSE_TOTAL_MAX_CHARS)
+        {
+            best = candidate;
+            low = middle + 1;
+        }
+        else
+        {
+            high = middle - 1;
+        }
+    }
+    return best;
+};
+
 type MergeConflictStrategy = "auto" | "source" | "destination";
 
 type MergeMachineReadableRecord = {
@@ -2656,6 +2733,7 @@ export const diffRevisions = tool({
     args: {
         leftRevision: tool.schema.string().min(1).describe("Left file-qualified Plastic revision spec for cm cat."),
         rightRevision: tool.schema.string().min(1).describe("Right file-qualified Plastic revision spec for cm cat."),
+        maxChars: tool.schema.number().int().min(DIFF_RESPONSE_MIN_CHARS).max(DIFF_RESPONSE_MAX_CHARS).optional().describe(`Maximum diff-body characters returned (default ${DIFF_RESPONSE_DEFAULT_MAX_CHARS}, maximum ${DIFF_RESPONSE_MAX_CHARS}).`),
         format: outputFormatArg,
         workdir: workdirArg,
     },
@@ -2678,7 +2756,7 @@ export const diffRevisions = tool({
             await materializeRevision(args.leftRevision, leftPath, args.workdir);
             await materializeRevision(args.rightRevision, rightPath, args.workdir);
             const result = await runPortableTextDiff(leftPath, rightPath, cwd, leftLabel, rightLabel);
-            return formatTextDiff("diffRevisions", args.format, "revision-to-revision", result, args.workdir);
+            return formatTextDiff("diffRevisions", args.format, "revision-to-revision", result, args.workdir, {}, args.maxChars);
         }
         finally
         {
@@ -2779,6 +2857,7 @@ export const diffFile = tool({
     args: {
         path: tool.schema.string().min(1).describe("Workspace file path to diff."),
         revision: tool.schema.string().optional().describe("Optional revision: changeset number/cs:<number>, br:/<branch>, lb:<label>, file-qualified '<path>#<selector>', or global revid:/rev:. Omit for the workspace base."),
+        maxChars: tool.schema.number().int().min(DIFF_RESPONSE_MIN_CHARS).max(DIFF_RESPONSE_MAX_CHARS).optional().describe(`Maximum diff-body characters returned (default ${DIFF_RESPONSE_DEFAULT_MAX_CHARS}, maximum ${DIFF_RESPONSE_MAX_CHARS}).`),
         format: outputFormatArg,
         workdir: workdirArg,
     },
@@ -2819,7 +2898,7 @@ export const diffFile = tool({
                     throw error;
                 }
                 const result = await runPortableTextDiff(basePath, workspacePath, cwd, revision.resolved.replace("#", "@"), `${displayPath} (workspace)`);
-                return formatTextDiff("diffFile", args.format, revision.kind, result, args.workdir, { pendingKind: null, isNew: false });
+                return formatTextDiff("diffFile", args.format, revision.kind, result, args.workdir, { pendingKind: null, isNew: false }, args.maxChars);
             }
             finally
             {
@@ -2839,21 +2918,24 @@ export const diffFile = tool({
             compared.result,
             args.workdir,
             { pendingKind: compared.pendingKind, isNew: compared.pendingKind === "private" || compared.pendingKind === "added", statusRevisionId: pendingItem?.revisionId },
+            args.maxChars,
         );
     },
 });
 
-const WORKSPACE_DIFF_DEFAULT_MAX_FILES = 12;
+const WORKSPACE_DIFF_DEFAULT_MAX_FILES = 3;
 const WORKSPACE_DIFF_MAX_FILES = 20;
 const WORKSPACE_DIFF_MAX_PATHS = 20;
 const WORKSPACE_DIFF_PATH_MAX_CHARS = 1_024;
 const WORKSPACE_DIFF_DISPLAY_PATH_MAX_CHARS = 256;
 const WORKSPACE_DIFF_ERROR_MAX_CHARS = 1_024;
-const WORKSPACE_DIFF_PER_FILE_MAX_CHARS = 12_000;
+const WORKSPACE_DIFF_DEFAULT_MAX_CHARS = 3_000;
+const WORKSPACE_DIFF_PER_FILE_MAX_CHARS = 8_000;
+const WORKSPACE_DIFF_MIN_CHARS = 500;
 // This is a response bound, not just a diff-body bound. Reserve space for
 // framing and an omission summary so both text and JSON remain useful.
-const WORKSPACE_DIFF_TOTAL_MAX_CHARS = 60_000;
-const WORKSPACE_DIFF_CONTENT_MAX_CHARS = 48_000;
+const WORKSPACE_DIFF_TOTAL_MAX_CHARS = 20_000;
+const WORKSPACE_DIFF_CONTENT_MAX_CHARS = 16_000;
 
 const boundWorkspaceValue = (value: string, maxChars: number): string =>
 {
@@ -2945,11 +3027,13 @@ const formatWorkspaceDiffResult = async (
 };
 
 export const workspaceDiff = tool({
-    description: "Review bounded pending workspace file diffs in one status pass. Private files are excluded unless explicitly selected or includePrivate=true; unavailable files are reported without aborting the batch.",
+    description: "Review explicitly selected pending workspace file diffs, or opt into a small bounded whole-workspace review with allPending=true. Use plastic_status when only changed paths are needed.",
     args: {
-        paths: tool.schema.array(tool.schema.string().min(1).max(WORKSPACE_DIFF_PATH_MAX_CHARS)).max(WORKSPACE_DIFF_MAX_PATHS).optional().describe(`Optional pending workspace paths to review (maximum ${WORKSPACE_DIFF_MAX_PATHS}, ${WORKSPACE_DIFF_PATH_MAX_CHARS} characters each). Selecting paths includes matching private files.`),
-        includePrivate: tool.schema.boolean().optional().describe("Include private pending files when paths are omitted. Defaults to false."),
-        maxFiles: tool.schema.number().int().min(1).max(WORKSPACE_DIFF_MAX_FILES).optional().describe(`Maximum files to compare (default ${WORKSPACE_DIFF_DEFAULT_MAX_FILES}, maximum ${WORKSPACE_DIFF_MAX_FILES}).`),
+        paths: tool.schema.array(tool.schema.string().min(1).max(WORKSPACE_DIFF_PATH_MAX_CHARS)).max(WORKSPACE_DIFF_MAX_PATHS).optional().describe(`Pending workspace paths to review (maximum ${WORKSPACE_DIFF_MAX_PATHS}, ${WORKSPACE_DIFF_PATH_MAX_CHARS} characters each). Selecting paths includes matching private files.`),
+        allPending: tool.schema.boolean().optional().describe("Explicitly review pending non-private files when paths are omitted. Defaults to false; required for an unscoped workspace diff."),
+        includePrivate: tool.schema.boolean().optional().describe("Include private pending files with allPending=true. Selected private paths do not require this flag."),
+        maxFiles: tool.schema.number().int().min(1).max(WORKSPACE_DIFF_MAX_FILES).optional().describe(`Maximum files to compare for allPending review (default ${WORKSPACE_DIFF_DEFAULT_MAX_FILES}, maximum ${WORKSPACE_DIFF_MAX_FILES}); selected paths are all considered unless this is set.`),
+        maxChars: tool.schema.number().int().min(WORKSPACE_DIFF_MIN_CHARS).max(WORKSPACE_DIFF_PER_FILE_MAX_CHARS).optional().describe(`Maximum diff-body characters returned per file (default ${WORKSPACE_DIFF_DEFAULT_MAX_CHARS}, maximum ${WORKSPACE_DIFF_PER_FILE_MAX_CHARS}).`),
         format: outputFormatArg,
         workdir: workdirArg,
     },
@@ -2957,20 +3041,58 @@ export const workspaceDiff = tool({
     {
         const cwd = args.workdir ?? process.cwd();
         // Runtime guards also cover direct execute() callers that bypass schema validation.
-        const rawPaths = Array.isArray(args.paths) ? args.paths.filter((path): path is string => typeof path === "string") : [];
+        if (args.paths !== undefined && !Array.isArray(args.paths))
+        {
+            throw new Error("paths must be an array of non-blank workspace paths.");
+        }
+        if (args.allPending !== undefined && typeof args.allPending !== "boolean")
+        {
+            throw new Error("allPending must be a boolean; whole-workspace review requires allPending=true explicitly.");
+        }
+        if (args.includePrivate !== undefined && typeof args.includePrivate !== "boolean")
+        {
+            throw new Error("includePrivate must be a boolean and only applies with allPending=true.");
+        }
+        const rawPaths = Array.isArray(args.paths) ? args.paths : [];
+        if (rawPaths.some((path) => typeof path !== "string" || path.trim().length === 0))
+        {
+            throw new Error("paths must contain only non-blank workspace paths.");
+        }
         const selectedPaths = rawPaths.length > 0
             ? rawPaths.slice(0, WORKSPACE_DIFF_MAX_PATHS).map((path) => boundWorkspaceValue(path, WORKSPACE_DIFF_PATH_MAX_CHARS))
             : undefined;
+        const allPending = args.allPending === true;
+        const includePrivate = args.includePrivate === true;
+        const workspaceRoot = toNormalizedAbsolutePath(".", cwd);
+        if (selectedPaths?.some((path) => toPathComparisonKeyFromAbsolutePath(toNormalizedAbsolutePath(path, cwd)) === toPathComparisonKeyFromAbsolutePath(workspaceRoot)))
+        {
+            throw new Error("A workspace-root path is a whole-workspace review; use allPending=true instead of selecting the workspace root.");
+        }
+        if (selectedPaths && allPending)
+        {
+            throw new Error("Choose either explicit paths or allPending=true, not both.");
+        }
+        if (!selectedPaths && !allPending)
+        {
+            throw new Error("plastic_workspaceDiff requires explicit paths or allPending=true. Use plastic_status when only pending paths are needed.");
+        }
+        if (selectedPaths && includePrivate)
+        {
+            throw new Error("includePrivate is only used with allPending=true; explicitly selected private paths are already included.");
+        }
         const ignoredPathInputs = Math.max(0, rawPaths.length - (selectedPaths?.length ?? 0));
         const pendingItems = await getMachineReadablePendingItems(args.workdir); // exactly one status command per batch
         const selectedScopes = selectedPaths?.map((path) => toNormalizedAbsolutePath(path, cwd)) ?? [];
         let candidates = selectedPaths ? filterPendingItemsByScope(pendingItems, selectedScopes) : pendingItems.filter((item) => item.kind !== "private");
-        if (!selectedPaths && args.includePrivate)
+        if (!selectedPaths && includePrivate)
         {
             candidates = pendingItems;
         }
-        const requestedMaxFiles = typeof args.maxFiles === "number" && Number.isFinite(args.maxFiles) ? Math.trunc(args.maxFiles) : WORKSPACE_DIFF_DEFAULT_MAX_FILES;
+        const defaultMaxFiles = selectedPaths ? selectedPaths.length : WORKSPACE_DIFF_DEFAULT_MAX_FILES;
+        const requestedMaxFiles = typeof args.maxFiles === "number" && Number.isFinite(args.maxFiles) ? Math.trunc(args.maxFiles) : defaultMaxFiles;
         const maxFiles = Math.min(WORKSPACE_DIFF_MAX_FILES, Math.max(1, requestedMaxFiles));
+        const requestedMaxChars = typeof args.maxChars === "number" && Number.isFinite(args.maxChars) ? Math.trunc(args.maxChars) : WORKSPACE_DIFF_DEFAULT_MAX_CHARS;
+        const maxChars = Math.min(WORKSPACE_DIFF_PER_FILE_MAX_CHARS, Math.max(WORKSPACE_DIFF_MIN_CHARS, requestedMaxChars));
         const skippedByLimit = Math.max(0, candidates.length - maxFiles);
         candidates = candidates.slice(0, maxFiles);
 
@@ -2999,7 +3121,7 @@ export const workspaceDiff = tool({
             {
                 const compared = await diffPendingWorkspaceFile({ path, workdir: args.workdir }, item);
                 const remaining = Math.max(0, WORKSPACE_DIFF_CONTENT_MAX_CHARS - totalOutputChars);
-                const perFile = boundWorkspaceDiffResult(compared.result, WORKSPACE_DIFF_PER_FILE_MAX_CHARS);
+                const perFile = boundWorkspaceDiffResult(compared.result, maxChars);
                 const bounded = boundWorkspaceDiffResult(perFile, remaining);
                 const status = bounded.binary ? (bounded.changed ? "binary-different" : "unchanged") : (bounded.changed ? "changed" : "unchanged");
                 const diffOutput = bounded.changed && !bounded.binary ? bounded.output : undefined;
@@ -3025,14 +3147,14 @@ export const workspaceDiff = tool({
             ...(skippedByLimit > 0 ? [`Skipped ${skippedByLimit} pending item(s) after the maxFiles bound of ${maxFiles}.`] : []),
             ...(unmatchedPreviews.length > 0 ? [`${unmatchedPreviews.length} selected path(s) had no pending status record: ${unmatchedPreviews.slice(0, 5).join(", ")}${unmatchedPreviews.length > 5 ? `; ${unmatchedPreviews.length - 5} more omitted` : ""}.`] : []),
             ...(ignoredPathInputs > 0 ? [`Ignored ${ignoredPathInputs} path input(s) after the ${WORKSPACE_DIFF_MAX_PATHS}-path bound.`] : []),
-            ...(!selectedPaths && !args.includePrivate && pendingItems.some((item) => item.kind === "private") ? ["Private pending files were excluded; select their paths explicitly or pass includePrivate=true."] : []),
+            ...(!selectedPaths && !includePrivate && pendingItems.some((item) => item.kind === "private") ? ["Private pending files were excluded; select their paths explicitly or pass includePrivate=true."] : []),
         ].map((warning) => boundWorkspaceValue(warning, WORKSPACE_DIFF_ERROR_MAX_CHARS));
         const textPrefix = [
             "## Workspace Diff",
             "",
             `- Status records inspected once: ${pendingItems.length}`,
             `- Files considered: ${candidates.length}`,
-            `- Per-file output bound: ${WORKSPACE_DIFF_PER_FILE_MAX_CHARS} characters; complete response bound: ${WORKSPACE_DIFF_TOTAL_MAX_CHARS} characters.`,
+            `- Per-file output bound: ${maxChars} characters; complete response bound: ${WORKSPACE_DIFF_TOTAL_MAX_CHARS} characters.`,
             ...warnings.map((warning) => `- Warning: ${warning}`),
             ...(textSections.length > 0 ? [] : ["", "No eligible pending files."]),
         ].join("\n");
@@ -3040,9 +3162,10 @@ export const workspaceDiff = tool({
             statusRecords: pendingItems.length,
             selectedPaths: selectedPaths ? workspacePathPreview(selectedPaths) : null,
             selectedPathCount: selectedPaths?.length ?? 0,
-            includePrivate: args.includePrivate ?? false,
+            allPending,
+            includePrivate,
             maxFiles,
-            perFileMaxChars: WORKSPACE_DIFF_PER_FILE_MAX_CHARS,
+            perFileMaxChars: maxChars,
             totalMaxChars: WORKSPACE_DIFF_TOTAL_MAX_CHARS,
             skippedByLimit,
             unmatchedPaths: unmatchedPreviews,

package/src/plastic-tool-loading.ts

@@ -27,8 +27,8 @@ export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
   { name: "plastic_undo", aliases: ["undo changes", "revert changes", "discard changes"], tags: ["changes", "mutation", "destructive"], guidance: ["Confirm the exact paths before discarding pending changes."] },
   { name: "plastic_resolveDeleteChangeConflict", aliases: ["resolve delete conflict", "deleted conflict"], tags: ["merge", "conflict", "resolution"], guidance: ["Inspect the conflict and choose whether files should remain on disk before resolving it."] },
   { name: "plastic_patch", aliases: ["patch", "generate patch", "review patch"], tags: ["diff", "patch", "export"], guidance: ["Inspect generated patches before sharing because they can include source, paths, or secrets."] },
-  { name: "plastic_diffFile", aliases: ["diff", "diff file", "file diff", "compare one file", "compare file"], tags: ["diff", "file", "workspace", "inspect"], guidance: ["For one workspace file, pass path and omit revision; use a documented changeset, branch, label, file-qualified, or global revision only when needed."] },
-  { name: "plastic_workspaceDiff", aliases: ["workspace diff", "pending review", "review pending changes", "review workspace changes", "diff pending files"], tags: ["diff", "workspace", "review", "inspect"], guidance: ["For pending-change review, runs status once and returns bounded per-file outcomes. Private files are excluded unless explicitly selected or includePrivate=true."] },
+  { name: "plastic_diffFile", aliases: ["diff", "diff file", "file diff", "compare one file", "compare file"], tags: ["diff", "file", "workspace", "inspect"], guidance: ["Use only when change-boundary evidence is needed. Pass one exact workspace path, omit revision for its Plastic base, and keep maxChars small unless more output is intentional."] },
+  { name: "plastic_workspaceDiff", aliases: ["workspace diff", "pending review", "review pending changes", "review workspace changes", "diff pending files"], tags: ["diff", "workspace", "review", "inspect"], guidance: ["Use only for an intentional multi-file content review, not routine validation. Select exact paths or pass allPending=true explicitly; use plastic_status when only changed paths are needed."] },
   { name: "plastic_diffRevisions", aliases: ["diff revisions", "compare revisions", "revision diff"], tags: ["diff", "revision", "inspect"], guidance: ["Use this only for two explicit file-qualified revision specifications."] },
   { name: "plastic_branchCreate", aliases: ["create branch", "new branch"], tags: ["branch", "mutation", "workflow"], guidance: ["Create normal work branches beneath an intended parent, which may differ from the loaded branch. Use allowRootBranch only for intentional top-level branches."] },
   { name: "plastic_switchBranch", aliases: ["switch branch", "checkout branch", "change branch"], tags: ["branch", "workspace", "mutation"], guidance: ["Check pending changes and choose how to handle them before switching branches."] },
@@ -168,8 +168,7 @@ function safetyPriority(entry: PlasticSearchCatalogEntry): number {
 export function searchPlasticTools(input: PlasticToolSearchInput, descriptions: ReadonlyMap<string, string> = new Map()): PlasticToolSearchMatch[] {
   const requestedNames = exactRequestedNames(input.toolNames);
   const terms = typeof input.query === "string" ? tokenize(input.query) : [];
-  const normalizedLimit = normalizeLimit(input.limit, requestedNames);
-  const limit = input.limit === undefined && requestedNames.size === 0 && terms.length === 1 && terms[0] === "diff" ? 2 : normalizedLimit;
+  const limit = normalizeLimit(input.limit, requestedNames);
   const domainTerms = terms.filter((term) => SEARCH_DOMAIN_TERMS.has(term));
   const primaryDomainTerm = domainTerms[0];
   const mutationIntent = terms.some((term) => MUTATION_INTENT_TERMS.has(term));