@aefree/pi-plastic 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+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.4.0] - 2026-08-01
+
+### Added
+
+- Added bounded portable `plastic_diffFile`/`plastic_diffRevisions` output metadata, explicit binary results, temporary historical-content cleanup, Unity-YAML-as-text coverage, revision validation, and Windows GNU `diff` regression coverage.
+
+- Added session-scoped generic repository-search policy. The policy safely discovers bounded `ignore.conf`/`cloaked.conf` chains.
+- Added actual package-root/version owner discovery at the extension boundary and packed-copy owner-conflict coverage.
+- Added direct mutation execution coverage proving one exact `cm` process attempt with no approval context and no implicit retry.
+
+- Added a composable `plastic-branch` footer status with nearest-workspace discovery, selector fallback, bounded `cm` confirmation, and debounced same-workspace refresh.
+- Added credential-free workspace, selector/status parser, footer composition, and lifecycle cleanup coverage using sanitized fixtures.
+- Added an opt-in, local-only branch-creation test for contributor-authenticated disposable Plastic repositories.
+
+### Changed
+
+- Made `@aefree/pi-repo-search` an optional peer: Plastic ignore/cloak policy registration is enabled when the package is installed, while core Plastic tools and skills load normally without it.
+
+- Made `plastic_diffFile(path=...)` default to the workspace Plastic base, route changed-file questions to `plastic_status`, and document supported advanced revision forms without agent-authored `cm cat` temporary-file recipes.
+
+- Updated the Pi development baseline to 0.83.0.
+
+- Removed the `vcs.plastic` workflow provider, its marker/readiness/preflight/guidance integration, and the unused optional `@aefree/pi-workflow` dependency. Repository-search policy remains independently registered and Plastic tools retain operation-specific validation.
+- Stopped registering or dynamically advertising `plastic_workspaceCreate` until workspace creation has a paired, safe cleanup capability.
+- Plastic repository policy outputs now declare the canonical marker-owned `policyOwnedRoot` boundary used by repo-search physical ignore-file containment.
+- Canonical contract packages are normal semver dependencies rather than bundled local links, preventing sibling/`node_modules` path leakage in packed tarballs.
+- Shared Plastic status branch parsing with `plastic_currentBranch` while preserving its `cm`-authoritative source policy.
+- Made `plastic_branchCreate` support an explicit parent branch independent of the loaded workspace branch, default relative names to the current branch when omitted, and reject accidental top-level branches unless `allowRootBranch=true` is explicitly supplied.
+- Removed package-owned token and UI-confirmation approval from Plastic mutations. Direct calls now proceed through the existing command, workspace-readiness, exact-target, path-containment, and process-safety checks to one `cm` process attempt without implicit retry.
+
+## [0.3.0] - 2026-07-25
+
+### Added
+
+- Added `plastic_tool_search`, a bounded package-owned dynamic loader with explicit Plastic aliases, tags, and selected-tool safety guidance.
+- Added balanced, loader-only, and all-active initial tool-loading modes through `PI_PLASTIC_TOOL_LOADING_MODE`, plus active-branch restoration of valid historical loader additions.
+- Added harness coverage for dynamic tool composition, search, additive activation, restoration, and deferred prompt-metadata behavior.
+- Added a package-local dynamic tool-loading behavioral eval with fresh Pi JSON subprocesses, bounded configured cases, implicit discovery coverage, exact smallest-sufficient activation checks, preflight-only mutation guarding, sandbox attestations, provider-schema capture hygiene, and ignored sanitized result summaries.
+- Added an opt-in, read-only live smoke test for dedicated Plastic sandbox workspaces.
+- Added a compatibility audit that prevents JSON-schema constrained sampling from being enabled on schemas that OpenAI strict tools would reject.
+- Added cross-platform Windows, macOS, and Linux validation plus a manually dispatched, tag-verified GitHub Release workflow.
+- Added Dependabot configuration, contribution and security policies, and repository-wide text/ignore conventions.
+
+### Changed
+
+- Declared Pi 0.82 and TypeBox development dependencies so the expanded test suite installs reproducibly while keeping runtime peers optional.
+- Declared the supported Node.js engine, expanded package metadata, added an explicit tarball allowlist and reproducible development lockfile, and documented pinned HTTPS and SSH installs.
+
+### Fixed
+
+- Allow eval validation on compatible Pi 0.82 patch releases instead of rejecting every version except 0.82.0.
+- Resolve relative Pi extension provenance paths against their canonical extension base directory so standard relative `--extension` loading retains dynamic activation.
+- Fail safe when canonical Pi `sourceInfo` provenance or effective loader ownership is unavailable: preserve the active set exactly and never activate or defer an unproven `plastic_*` name.
+- Fixed full-path branch existence checks by querying Plastic's leaf-name field and validating the returned full branch path.
+
+## [0.2.4] - 2026-07-24
+
+### Changed
+
+- Marked Pi-bundled core dependencies as optional peers so Pi git installs do not create redundant per-package `node_modules` directories.
+
+## [0.2.3] - 2026-07-10
+
+### Changed
+
+- Migrated Pi extension imports and peer dependencies to the `@earendil-works` package scope, and removed the unused `pi-ai` peer dependency.
+
+### Fixed
+
+- Normalize Windows-style absolute and relative checkin paths with Windows path semantics even when validation runs on another operating system.
+
+## [0.2.2] - 2026-07-09
+
+### Fixed
+
+- Preserve case distinctions on case-sensitive Darwin/APFS volumes while still matching paths case-insensitively on detected case-insensitive volumes and Windows, without inferring a mounted volume's policy from its parent filesystem.
+- Make spawned Plastic command cancellation escalate based on terminal process settlement, with prompt listener and timer cleanup.
+- Report actionable diagnostics when the Plastic or Git executable cannot be launched.
+
+### Added
+
+- Support `PI_PLASTIC_CM_EXECUTABLE` and `PI_PLASTIC_GIT_EXECUTABLE` executable-path overrides.
+- Add macOS CI coverage for tests and package validation.
+
+## [0.2.1] - 2026-06-27
+
+### Changed
+
+- Changed `plastic_mergeToBranch` so an omitted target resolves to the source branch's Plastic parent branch instead of assuming `/dev`.
+
+## [0.2.0] - 2026-06-27
+
+### Added
+
+- Added `plastic_mergeToBranch`, a safe closeout helper that switches to a target branch, optionally updates, merges a source branch non-interactively, verifies merge state, and checks in the merge result.
+- Documented the closeout merge helper in the README and `using-plastic` skill.
+
+## [0.1.0] - 2026-04-27
+
+### Added
+
+- Initial Plastic SCM / Unity Version Control package with status, branch, merge, checkin, shelveset, patch, diff-safe, and code-review tools.

package/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thanks for improving Pi Plastic.
+
+## Prerequisites
+
+- Node.js 22.19.0 or newer
+- npm
+- Plastic SCM / Unity Version Control CLI for opt-in live validation
+- Git for the text-only diff tools
+
+## Setup
+
+```bash
+npm ci --ignore-scripts --no-audit --no-fund
+npm test
+```
+
+The default suite is credential-free. Keep it that way. Tests that require Plastic access must remain explicitly opt-in and target a dedicated disposable workspace.
+
+## Making changes
+
+- Keep public tool names and output shapes stable unless the change intentionally documents a breaking release.
+- Preserve built-in and foreign-extension tools when changing active-tool composition.
+- Do not weaken confirmation, preflight, path, process, or mutation safeguards.
+- Add focused regression coverage for behavior changes.
+- Update README documentation when user-facing behavior changes.
+- Keep unreleased user-visible changes under `## Unreleased` in `CHANGELOG.md` during ordinary development.
+- Do not bump the package version for every implementation commit. Convert the accumulated Unreleased section into one dated SemVer release only when preparing a release.
+
+## Validation
+
+Run:
+
+```bash
+npm test
+npm run eval:tool-loading -- --dry-run
+npm pack --dry-run
+```
+
+Review the tarball list for machine-specific paths, credentials, raw provider payloads, generated results, and unrelated files.
+
+Plastic live tests are intentionally local-only. This project has no shared Plastic Cloud account or CI credentials, and contributors must authenticate `cm` with their own account and use a repository they are authorized to modify. Never add Plastic credentials, tokens, cloud organization details, or private repository data to tests, fixtures, logs, pull requests, or GitHub Actions.
+
+For an opt-in read-only Plastic smoke test:
+
+```bash
+PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/dedicated/sandbox npm run test:live
+```
+
+For branch-creation behavior, use the opt-in mutation test only against a clean, dedicated disposable repository:
+
+```bash
+PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/dedicated/sandbox \
+PI_PLASTIC_ALLOW_MUTATION_TESTS=true \
+npm run test:live:branch-create
+```
+
+The mutation test creates uniquely named hierarchical branches, verifies explicit-parent behavior and the top-level guard, does not switch the workspace, and removes temporary branches in cleanup.
+
+### Behavior completion gate
+
+When a change modifies how a `plastic_*` tool invokes or interprets real Plastic behavior:
+
+1. Add or update credential-free regression coverage for policy, parsing, and command construction.
+2. Locally run the narrowest relevant opt-in live test in a clean disposable Plastic repository using the contributor's own authenticated account.
+3. Verify the workspace state and temporary-resource cleanup afterward.
+4. Report the exact live test and that an authenticated disposable repository was used, without exposing account, organization, server, credential, or private repository details.
+
+GitHub Actions is not expected to run Plastic live tests. If local authenticated validation is unavailable, describe the work as implemented with live validation pending; do not claim the behavior is done or verified. Documentation-only and purely internal changes may mark live validation as not applicable with a reason.
+
+Follow `evals/tool-loading/README.md` before any live model evaluation. Never use an ordinary production workspace for mutation testing.
+
+## Pull requests
+
+Keep pull requests focused. Describe:
+
+- the behavior changed;
+- safety or compatibility considerations;
+- tests and environments actually run;
+- checks intentionally skipped;
+- relevant before/after metadata or latency measurements for loader changes.
+
+Do not include secrets, account data, private repository content, or raw provider captures.
+
+## Security reports
+
+Follow [SECURITY.md](SECURITY.md) instead of opening a public issue for vulnerabilities.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Freedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# Pi Plastic
+
+Pi tools, footer status, and skill guidance for Plastic SCM / Unity Version Control workflows.
+
+## Plastic branch footer status
+
+When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace`, reads the local selector as a fast credential-free fallback, and confirms the branch with a bounded `cm status` call. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
+
+The extension owns only the `plastic-branch` status key. It does not replace Pi's footer or suppress Pi's Git branch display, so Git and Plastic information can appear together in nested workspaces. If the Plastic marker exists but neither the selector nor `cm` yields a branch, the footer shows `Plastic branch unavailable`. Non-Plastic directories show no Plastic status.
+
+## Repository-search policy
+
+When `@aefree/pi-repo-search` is also installed, Pi session startup registers the independent `plastic.ignore-files` repository-search policy. The marker-based policy discovers readable `ignore.conf` and `cloaked.conf` only from the nearest Plastic workspace to each requested root, then adds them as ripgrep ignore files without replacing native ripgrep/Git-ignore behavior. The integration is optional: without `pi-repo-search`, all Plastic tools and skills still load and only this policy registration is omitted. It does not register workflow guidance or perform Plastic CLI readiness checks; owning `plastic_*` tools validate their own workspace and CLI requirements.
+
+
+## Mutation execution
+
+Directly invoked mutating `plastic_*` tools do not require approval tokens or package-owned UI confirmation. After the tool's existing argument, command, workspace-readiness, exact-target, and path-containment checks pass, each command attempt proceeds to its intended `cm` spawn. The process layer makes one attempt and does not retry implicitly; inspect Plastic status before manually retrying an ambiguous side-effecting failure.
+
+Removing the approval layer does not relax Plastic safety guards. Command allowlists, exact mutation targets, workspace/path containment, non-interactive process selection, blocked `cm diff`, safe merge flags, and operation-specific preflight behavior remain authoritative. Compound tools may intentionally execute multiple validated command steps.
+
+## Tools
+
+- `plastic_tool_search` (dynamic capability search and loader)
+- `plastic_status`
+- `plastic_update`
+- `plastic_add`
+- `plastic_checkin`
+- `plastic_undo`
+- `plastic_resolveDeleteChangeConflict`
+- `plastic_diff`
+- `plastic_patch`
+- `plastic_diffRevisions`
+- `plastic_diffFile`
+- `plastic_branchCreate`
+- `plastic_switchBranch`
+- `plastic_merge`
+- `plastic_mergeToBranch`
+- `plastic_finalizeMerge`
+- `plastic_currentBranch`
+- `plastic_branchList`
+- `plastic_branchExists`
+- `plastic_branchDelete`
+- `plastic_shelvesetCreate`
+- `plastic_shelvesetApply`
+- `plastic_shelvesetDelete`
+- `plastic_shelvesetList`
+- `plastic_codeReviewCreate`
+- `plastic_codeReviewUpdate`
+- `plastic_codeReviewDelete`
+- `plastic_codeReviewFind`
+- `plastic_workspaceList`
+
+## Dynamic tool loading
+
+The package exposes 28 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
+
+The default **balanced** session set keeps `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch` active. The other Plastic tools remain registered but inactive until selected; built-in and other-extension tools are not removed. Previous loader additions on the active session branch are restored on startup, resume, fork, and reload.
+
+For controlled comparisons, set `PI_PLASTIC_TOOL_LOADING_MODE` before starting Pi:
+
+```bash
+PI_PLASTIC_TOOL_LOADING_MODE=balanced    # default production candidate
+PI_PLASTIC_TOOL_LOADING_MODE=loader-only # maximum initial schema reduction
+PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 28 currently exposed tools; loader omitted
+```
+
+Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package's effective tools before deferring, restoring, or activating them. If canonical provenance or ownership of the effective loader cannot be proven, `pi-plastic` fails safe: it preserves the complete current active set exactly, does not defer, remove, or activate any `plastic_*` name, and an effective package loader can only report known tools that are already active rather than activating inactive names. On sourceInfo-capable Pi instances, providers without native deferred definitions still receive the complete current active set after a loader call. Reload or restart Pi after source edits; source files are not watched automatically.
+
+## Safety behavior
+
+- `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_diffFile` or `plastic_diffRevisions` for text-only file diffs.
+- `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`.
+- `plastic_mergeToBranch` performs the common safe closeout flow: resolve the source branch's parent as the default target, switch to the target branch, optionally update, merge a source branch non-interactively, verify merge state, and check in the merge result.
+- `plastic_finalizeMerge` supports reviewed/manual-resolution flows where Plastic still needs merge metadata finalized before checkin.
+
+## Patch generation examples
+
+```text
+plastic_patch(source="<branch-spec>", integration=true)
+plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
+plastic_patch(source="<left-spec>", destination="<right-spec>")
+plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
+```
+
+If `output` is omitted, Plastic prints patch content to stdout. If `output` is provided, Plastic writes a new patch file and refuses to overwrite an existing file. Inspect patches before sharing them because they can contain source code, binary content, local paths, or secrets that were present in the changed files.
+
+## Included skill
+
+- `using-plastic` - PlasticSCM branch, workspace, merge, shelveset, checkin, and code-review workflow guidance
+
+## Install
+
+Install the stable GitHub release over HTTPS:
+
+```bash
+pi install git:github.com/aefreedman/pi-plastic@v0.4.0
+```
+
+Equivalent SSH install:
+
+```bash
+pi install git:git@github.com:aefreedman/pi-plastic@v0.4.0
+```
+
+To intentionally track the moving default branch instead of a release tag:
+
+```bash
+pi install https://github.com/aefreedman/pi-plastic
+```
+
+Local development install:
+
+```bash
+pi install <path-to-pi-plastic>
+```
+
+Project-local install:
+
+```bash
+pi install -l <path-to-pi-plastic>
+```
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.82.0 or newer; the current development and eval baseline is Pi 0.83
+- Plastic SCM / Unity Version Control CLI (`cm`) available on `PATH`, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path
+- A compatible `diff` executable available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path, for text-only diff and patch tools
+- A configured Plastic workspace for workspace-scoped operations
+- `@aefree/pi-repo-search` is an optional peer. When installed, it receives the Plastic ignore/cloak policy; when absent, `pi-plastic` loads without repository-search integration. The tarball does not embed linked sibling workspaces or `node_modules` paths.
+
+## Testing
+
+```bash
+npm test
+```
+
+The default suite is credential-free and covers tool validation, path-resolution regressions, extension registration, OpenAI strict-schema compatibility classification, and bash guard behavior.
+
+Run the opt-in read-only live smoke test against a dedicated clean sandbox workspace:
+
+```bash
+PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/sandbox npm run test:live
+```
+
+The live test requires `/main`, no pending changes, and no merge in progress. It does not mutate the repository. Mutation tools should still be rehearsed manually in a disposable sandbox before relying on them in a new environment.
+
+### Dynamic tool-loading eval
+
+The package-local behavioral eval uses fresh Pi 0.83 JSON subprocesses against an explicitly attested dedicated Plastic sandbox and is not a skill eval. It compares all-active, balanced, and loader-only mode behavior, checks exact smallest-sufficient loader activations, blocks destructive calls unless they are supported `preflight: true` previews, captures tool calls and sanitized provider-schema measurements, and deletes raw provider payload captures by default.
+
+```bash
+npm run eval:tool-loading -- --dry-run
+PI_PLASTIC_EVAL_SANDBOX=/absolute/path/to/sandbox PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox npm run eval:tool-loading -- --model openai-codex/gpt-5.6-luna --condition balanced
+```
+
+See [`evals/tool-loading/README.md`](evals/tool-loading/README.md) for approved model restrictions, cases, measurements, and result hygiene.
+
+## Constrained sampling compatibility
+
+Pi 0.82 introduced provider-side constrained sampling for tools. `pi-plastic` does not currently opt in: every public Plastic schema includes optional fields (at minimum `workdir`), while OpenAI strict function schemas require closed objects and all declared properties to be required. Pi forwards the registered schema without converting those optional fields.
+
+Enabling `strict: "prefer"` now would therefore either produce invalid strict OpenAI requests or require a breaking redesign of the ordinary tool arguments. The test suite audits all registered tools and prevents accidental opt-in until a schema is genuinely strict-compatible. Existing TypeBox validation and Plastic runtime safety checks remain authoritative.
+
+OpenAI Codex models may advertise grammar tools without advertising strict JSON-schema tools. Grammar sampling is not used here because Plastic operations have structured multi-field arguments rather than a single bounded string language.
+
+## Implementation notes
+
+- The core implementation lives in `src/plastic-core.ts`.
+- Shared workspace discovery and branch parsing live in `src/plastic-workspace.ts`.
+- `extensions/plastic-branch-status.ts` owns the additive footer status and its session-scoped refresh lifecycle.
+- `index.ts` is the Pi tool registration layer.
+- Output shapes are intentionally stable for prompt and workflow compatibility.
+
+## License
+
+MIT. See `LICENSE`.

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest tagged release. Upgrade to the newest release before reporting an issue that may already be fixed.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability, credential exposure, or unsafe command-execution path.
+
+Use GitHub's private vulnerability reporting for this repository:
+
+<https://github.com/aefreedman/pi-plastic/security/advisories/new>
+
+Include:
+
+- the affected package version or commit;
+- the Pi, Node.js, Git, and Plastic CLI versions;
+- the operating system;
+- reproduction steps and expected versus observed behavior;
+- the affected tool or extension;
+- impact and any known mitigations;
+- whether credentials, repository content, or remote Plastic objects may have been exposed or changed.
+
+Avoid including real credentials or sensitive repository content. Use a disposable Plastic workspace when a reproduction requires mutation.
+
+You should receive an acknowledgement within seven days. Release timing depends on severity, reproducibility, and coordination needs.
+
+## Scope
+
+Security-sensitive areas include command construction, executable-path overrides, workspace/path targeting, destructive Plastic operations, provider payload capture, dynamic tool ownership, and package-install behavior. General support questions and ordinary bugs belong in the public issue tracker.

package/evals/tool-loading/README.md

@@ -0,0 +1,38 @@
+# Dynamic tool-loading behavioral eval
+
+This package-local eval compares `all-active`, `balanced`, and `loader-only` Plastic tool-loading modes through fresh Pi 0.83 JSON subprocesses. It is intentionally **not** a skill eval: skills, prompt templates, built-in tools, discovered extensions, context files, and sessions are disabled.
+
+## What it measures
+
+- Required Plastic tool calls for status, branch listing, read-only switch/checkin preflight, compound branch list + `/main` verification, no-operation, ambiguous branch discovery, and two implicit contextual discovery prompts (inspect branches; find code reviews) that name neither the loader nor the target public tool.
+- Loader behavior: exactly one `plastic_tool_search` only when a required tool is initially deferred; none for all-active, balanced cases whose target is already active, or the negative case. Whenever a loader is expected, the runner requires its activation result to be exactly the case's smallest sufficient deferred target set.
+- Tool errors, assistant errors, call/output/time bounds, maximum four activation results, and no destructive activation in negative or ambiguous discovery cases. An eval-only extension blocks every destructive Plastic call unless that tool's registered schema supports `preflight` and the call supplies `preflight: true`.
+- JSONL events, assistant usage/cache totals, wall time, initial provider `tools` serialization size, and native `tool_search_call` / `tool_search_output` markers when Pi/provider payloads expose them.
+
+`baseline.json` preserves the legacy 29-tool measurement for comparison. The current all-active mode omits the loader and exposes `28 / 21071` after withholding workspace creation; balanced records `3 / 2133` (89.93% legacy reduction), and loader-only records `1 / 1121` (94.71%). The loader's prompt metadata is 278 characters; the untouched legacy baseline has none.
+
+## Run
+
+A live run requires an explicit approved model and **both** sandbox attestations. `PI_PLASTIC_EVAL_SANDBOX` must resolve to a dedicated workspace containing `.pi-plastic-eval-sandbox` whose complete, exact UTF-8 content is `pi-plastic-eval-sandbox` followed by one LF newline (no other bytes):
+
+```text
+pi-plastic-eval-sandbox
+```
+
+For example, create the marker with `printf 'pi-plastic-eval-sandbox\n' > /absolute/path/to/sandbox/.pi-plastic-eval-sandbox`. Also set `PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox`; this explicit opt-in prevents accidentally targeting an ordinary workspace. Dry runs validate configuration and do **not** require either attestation.
+
+```bash
+PI_PLASTIC_EVAL_SANDBOX=/absolute/path/to/sandbox PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox npm run eval:tool-loading -- --model openai-codex/gpt-5.6-luna
+PI_PLASTIC_EVAL_SANDBOX=/absolute/path/to/sandbox PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox npm run eval:tool-loading -- --model openai-codex/gpt-5.6-terra:medium --condition balanced --cases branch-listing,compound-list-branches-verify-main --trials 2
+```
+
+Only `openai-codex/gpt-5.6-(luna|terra|sol)` with an optional supported thinking level such as `:medium` is accepted. Trials are sequential and bounded to 1–5. Never target an ordinary production workspace.
+
+Validate the configuration without calling a model:
+
+```bash
+npm run eval:tool-loading -- --dry-run
+npm run eval:tool-loading -- --help
+```
+
+Each trial writes provider payloads only to a unique system-temp capture file, never stdout. The runner deletes raw captures by default. Pass `--keep` only when you explicitly need those sensitive raw payloads. Sanitized timestamped summaries are written to ignored `results/`; use `--include-events` to include event type/tool-name crumbs only.

package/evals/tool-loading/RESULTS.md

@@ -0,0 +1,57 @@
+# Dynamic tool-loading pilot results
+
+Date: 2026-07-25  
+Package: `@aefree/pi-plastic`  
+Pi: 0.82.0  
+Model: `openai-codex/gpt-5.6-terra:medium`  
+Sandbox: dedicated `plastic-tool-sandbox` repository
+
+## Decision
+
+The Plastic pilot passes its rollout criteria. Keep the balanced initial set as the production default: `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch`.
+
+- Existing 29 public Plastic tools retain their names and behavior; the loader is additive.
+- Balanced public metadata is 2,117 serialized characters versus the untouched 21,192-character legacy baseline, a 90.01% reduction.
+- Stable live provider payloads contained 1,908 serialized initial tool characters in balanced mode versus 22,120 in the 29-tool legacy all-active mode, a 91.37% reduction.
+- A deferred capability added exactly one loader call/provider round trip and no repeated loader call after activation.
+- Native OpenAI deferred-loading markers (`tool_search_call` and `tool_search_output`) appeared in every deferred GPT-5.6 case and were absent when no loader call was expected.
+- Core outcomes, preflight argument checks, negative controls, and ambiguous branch discovery passed.
+
+## Behavioral evidence
+
+The final expanded diagnostic matrix passed 27/27 trials: nine explicit, implicit, contextual, ambiguous, compound, preflight, and negative cases under all-active, balanced, and loader-only conditions. Five stable status, branch, switch-preflight, checkin-preflight, and compound branch cases passed 45/45 trials over three repetitions per condition. A focused three-trial loader-only regression for contextual branch discovery also passed 3/3 after plural/domain query coverage was added.
+
+Stable-trial measurements:
+
+| Condition | Pass | Initial provider tool chars | Median wall time | Mean wall time | Mean reported total tokens | Mean tool calls |
+|---|---:|---:|---:|---:|---:|---:|
+| all-active | 15/15 | 22,120 | 8.78 s | 9.39 s | 7,180 | 1.20 |
+| balanced | 15/15 | 1,908 | 10.50 s | 10.41 s | 3,295 | 2.00 |
+| loader-only | 15/15 | 832 | 10.23 s | 10.84 s | 3,183 | 2.20 |
+
+The balanced median added about 1.73 seconds (19.7%) in these short cases while reducing initial provider tool serialization by 91.37% and mean reported total tokens by about 54%. Mean provider requests were 2.0 all-active, 2.8 balanced, and 3.0 loader-only; deferred cases account for the accepted first-use loader request, while balanced status remained immediate. Results remain separate because cache reads, input tokens, wall time, and provider requests have different cost/latency implications.
+
+The first diagnostic attempt used a 24,000-character JSONL capture bound and terminated normal Pi event streams before their follow-up tool turn. Raising the bounded capture limit to 2 MiB corrected the harness; no package behavior changed for the passing diagnostic and stable runs. Final live runs also required a sandbox marker, an explicit authorization environment value, and an eval-only guard that blocked mutation-capable tools unless the tool supported and received `preflight: true`.
+
+## Session and compatibility evidence
+
+A persisted loader-only session first called `plastic_tool_search` and `plastic_branchList`. Its tool result stored `addedToolNames: ["plastic_branchList"]`. A fresh Pi process resumed that session, restored `plastic_branchList`, called it directly, and made no second loader call.
+
+Package harness coverage also verifies additive activation without Pi 0.82 `sourceInfo`, representing older/fallback active-list behavior. Pi/provider fallback serialization itself is owned by Pi; this package does not claim a live non-GPT-5.6 provider test.
+
+## Sandbox mutation evidence
+
+The dedicated sandbox was used for real branch, changeset, shelveset, review, merge, conflict-signal, and cleanup operations:
+
+- Created and switched to disposable branch `/dynamic-tool-loading-eval-20260725-1538`.
+- Added a synthetic fixture and created disposable changeset `cs:4`.
+- Created, listed, previewed/applied, undid, and deleted shelveset `sh:2`.
+- Created, found, updated, and deleted code review `21`.
+- Attempted a merge to `/main`; Plastic reported an evil-twin directory conflict before establishing merge state. Explicit source finalization also stopped on that directory conflict, demonstrating the existing safe failure signal rather than silently checking in.
+- Deleted the disposable branch and changeset after the stopped merge.
+
+Final verification found `/main` active, no pending or merge state, and no remaining test branch, shelveset, or review. The private `.pi-plastic-eval-sandbox` attestation marker was removed after the eval; future guarded runs must recreate it deliberately. Workspace creation was not exercised because the package exposes create/list but no paired workspace-delete tool; leaving an account-level test workspace would not improve loader evidence.
+
+## Scope
+
+This result covers the `pi-plastic` pilot only. The recorded seven-case live matrix predates the current two implicit contextual discovery cases, exact smallest-sufficient activation assertion, eval-only preflight mutation guard, and marker/authorization sandbox attestations; no live re-run is implied by those later harness hardenings. Future live runs require `PI_PLASTIC_EVAL_SANDBOX` to contain the documented `.pi-plastic-eval-sandbox` marker and `PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox`. It does not authorize package publishing or version changes, and it does not begin the separate Codecks guidance design or any skill evaluation.

package/evals/tool-loading/baseline.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "measurement": "serializedSchemaChars is JSON.stringify of public registered tool metadata (name, description, parameters, prompt metadata, constrainedSampling); estimated tokens are chars / 4 rounded up. Live provider payload tool serialization is recorded separately by the eval runner.",
+  "legacyBaseline": {
+    "label": "untouched legacy public Plastic tools",
+    "toolCount": 29,
+    "serializedSchemaChars": 21192,
+    "estimatedTokens": 5298,
+    "promptMetadataChars": 0
+  },
+  "implementedConditions": {
+    "all-active": {
+      "toolCount": 28,
+      "serializedSchemaChars": 21071,
+      "estimatedTokens": 5268,
+      "promptMetadataChars": 0,
+      "legacySchemaReductionPercent": 0.57
+    },
+    "balanced": {
+      "toolCount": 3,
+      "serializedSchemaChars": 2133,
+      "estimatedTokens": 534,
+      "promptMetadataChars": 278,
+      "legacySchemaReductionPercent": 89.93
+    },
+    "loader-only": {
+      "toolCount": 1,
+      "serializedSchemaChars": 1121,
+      "estimatedTokens": 281,
+      "promptMetadataChars": 278,
+      "legacySchemaReductionPercent": 94.71
+    }
+  }
+}

package/evals/tool-loading/cases.json

@@ -0,0 +1,70 @@
+{
+  "schemaVersion": 2,
+  "cases": [
+    {
+      "id": "status-inspection",
+      "prompt": "In the dedicated Plastic sandbox, inspect the workspace status now. Call plastic_status exactly once, do not call any other Plastic operation unless plastic_tool_search is required to make plastic_status available, then reply with a one-sentence status summary.",
+      "requiredTools": ["plastic_status"],
+      "minimalActivatedTools": ["plastic_status"],
+      "forbiddenTools": []
+    },
+    {
+      "id": "branch-listing",
+      "prompt": "In the dedicated Plastic sandbox, list the available branches. Call plastic_branchList exactly once. If it is not active, first call plastic_tool_search exactly once and activate only plastic_branchList. Do not mutate the workspace; then give a short result.",
+      "requiredTools": ["plastic_branchList"],
+      "minimalActivatedTools": ["plastic_branchList"],
+      "forbiddenTools": []
+    },
+    {
+      "id": "preflight-branch-switch",
+      "prompt": "Preview, but do not perform, switching the dedicated Plastic sandbox to /main. Call plastic_switchBranch exactly once with branch /main, pendingChanges cancel, preflight true, and the sandbox workdir. If the tool is inactive, first call plastic_tool_search exactly once to activate only plastic_switchBranch. Do not call any other Plastic operation, then summarize the preview.",
+      "requiredTools": ["plastic_switchBranch"],
+      "minimalActivatedTools": ["plastic_switchBranch"],
+      "requiredPreflightTools": ["plastic_switchBranch"],
+      "forbiddenTools": ["plastic_status", "plastic_currentBranch", "plastic_branchCreate", "plastic_merge"]
+    },
+    {
+      "id": "preflight-checkin",
+      "prompt": "Preview, but do not perform, a checkin in the dedicated Plastic sandbox. Call plastic_checkin exactly once with message 'dynamic-loader eval preflight', preflight true, includeAll true, and the sandbox workdir. If the tool is inactive, first call plastic_tool_search exactly once to activate only plastic_checkin. Do not add, undo, or otherwise mutate anything, then summarize the preview.",
+      "requiredTools": ["plastic_checkin"],
+      "minimalActivatedTools": ["plastic_checkin"],
+      "requiredPreflightTools": ["plastic_checkin"],
+      "forbiddenTools": ["plastic_add", "plastic_undo"]
+    },
+    {
+      "id": "compound-list-branches-verify-main",
+      "prompt": "In the dedicated Plastic sandbox, list branches and verify whether /main exists. Call plastic_branchList and plastic_branchExists once each; use /main as the branch-existence argument. If either is inactive, make exactly one plastic_tool_search call that activates both exact tools together. Do not mutate the workspace, then give a short answer.",
+      "requiredTools": ["plastic_branchList", "plastic_branchExists"],
+      "minimalActivatedTools": ["plastic_branchList", "plastic_branchExists"],
+      "forbiddenTools": []
+    },
+    {
+      "id": "negative-no-operation",
+      "prompt": "No Plastic operation is requested. Do not call plastic_tool_search or any plastic_* tool. Reply exactly: NO_OPERATION.",
+      "requiredTools": [],
+      "minimalActivatedTools": [],
+      "forbiddenTools": []
+    },
+    {
+      "id": "ambiguous-branch-discovery",
+      "prompt": "In the dedicated Plastic sandbox, safely discover branch information for a later decision. Prefer a read-only branch listing and call plastic_branchList exactly once. If it is inactive, call plastic_tool_search exactly once with a branch discovery request and activate only read-only branch tools. Do not create, switch, merge, or delete branches; then give a short answer.",
+      "requiredTools": ["plastic_branchList"],
+      "minimalActivatedTools": ["plastic_branchList"],
+      "forbiddenTools": ["plastic_branchCreate", "plastic_switchBranch", "plastic_merge", "plastic_mergeToBranch", "plastic_branchDelete"]
+    },
+    {
+      "id": "contextual-branch-inspection",
+      "prompt": "Before choosing a branch for later work, inspect all available branches in the dedicated sandbox exactly once and give a short read-only summary. Use only the smallest sufficient capability; do not change anything.",
+      "requiredTools": ["plastic_branchList"],
+      "minimalActivatedTools": ["plastic_branchList"],
+      "forbiddenTools": ["plastic_branchCreate", "plastic_switchBranch", "plastic_merge", "plastic_mergeToBranch", "plastic_branchDelete"]
+    },
+    {
+      "id": "contextual-review-discovery",
+      "prompt": "Before planning follow-up work, find the existing code reviews in the dedicated sandbox exactly once and summarize them briefly. Use only the smallest sufficient read-only capability; do not change anything.",
+      "requiredTools": ["plastic_codeReviewFind"],
+      "minimalActivatedTools": ["plastic_codeReviewFind"],
+      "forbiddenTools": ["plastic_codeReviewCreate", "plastic_codeReviewUpdate", "plastic_codeReviewDelete"]
+    }
+  ]
+}