@caupulican/pi-adaptative 0.84.1 → 0.85.3

package/docs/index.md

@@ -49,11 +49,13 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [Tool repair](tool-repair.md) - repaired tool-call arguments, health diagnostics, kill switches, and replay workflow.
 - [Task steps](task-steps.md) - native session checklist, slash commands, persistence, and delegation migration.
 - [Native Python](python.md) - uv-managed bounded Python execution, provisioning, output limits, and cross-platform file guidance.
+- [Managed data tools](managed-data-tools.md) - pinned rg, jq, and Rust jscpd provisioning without project files.
 
 ## Customization
 
 - [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
 - [tmux agent manager](tmux-agent-manager.md) - bundled event-driven external-provider teams with parent wake handoffs.
+- [Task worker profiles](worker-profiles.md) - immutable session-scoped worker profiles with bounded model and tool authority.
 - [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
 - [Resource profiles & library](resources.md) - curate extensions, skills, and agents per project or situation; share a catalog; install and back up.
 - [Self-adaptation](self-adaptation.md) - draft live skills/extensions and run evidence-backed Pi harness improvement loops.
@@ -86,3 +88,4 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 ## Development
 
 - [Development](development.md) - local setup, project structure, and debugging.
+- [Tool boundary performance roadmap](tool-boundary-performance-roadmap-2026-08-02.md) - evidence ledger for preflight, payload ownership, Python coordination, and remaining latency/memory work.

package/docs/managed-data-tools.md

@@ -0,0 +1,15 @@
+# Managed data tools
+
+Pi keeps source filtering and structured-data projection outside the JavaScript heap with managed native tools:
+
+- `rg` for bounded text and file candidate searches.
+- `jq` for selecting only the JSON records and fields needed by the agent.
+- Rust `jscpd` 5.0.14 for production clone evidence.
+
+Pi provisions these binaries under its managed agent `bin` directory and places that directory first on the tool environment `PATH`. Provisioning never runs a project package manager and never writes dependencies, configuration, reports, or caches into the current repository.
+
+The npm package includes the exact jscpd v5 platform package. Standalone releases carry the native binary beside Pi. The first Pi startup, `pi doctor`, or direct `jscpd` wrapper invocation installs the verified binary into managed storage. Concurrent sessions converge on the same exact version; different agent directories remain isolated.
+
+Use `pi doctor` to verify availability. If a managed binary cannot be verified, treat the scan as incomplete and change approach; do not install a fallback into the project.
+
+Ad hoc scanner reports and configuration belong in the OS or Pi transient work directory. A green clone report is evidence only when its production coverage and detection thresholds are also verified.

package/docs/models.md

@@ -237,7 +237,7 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
 | `compat` | No | provider `compat` | Provider compatibility overrides. Merged with provider-level `compat` when both are set. |
 | `textToolCallProtocol` | No | omitted | Set `true` to enable pi's text tool-call protocol fallback for a pure-text model that cannot emit native provider tool calls. |
 
-`textToolCallProtocol` is a per-model opt-in. It is overridden by the emergency global setting `toolRepair.textProtocol` and by the `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` environment kill switch. Native provider tool calls still take precedence when the model emits them; this flag enables only the text-protocol fallback lane. Failed calibration is remembered for the host/model until `/toolprotocol-reset <provider/model>` clears it.
+`textToolCallProtocol` is a per-model fallback opt-in. The `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` kill switch always disables it. A persisted `/toolprobe` native verdict also keeps that exact model on native calls even if the emergency global setting or model metadata enables the text protocol. Without native proof, `toolRepair.textProtocol` overrides the per-model setting. Failed calibration is remembered for the host/model until `/toolprotocol-reset <provider/model>` clears it.
 
 Current behavior:
 - `/model` and `--list-models` list entries by model `id`.

package/docs/quickstart.md

@@ -77,8 +77,8 @@ Summarize this repository and tell me how to run its checks.
 By default, pi gives the model four tools:
 
 - `read` - read files
-- `write` - create or overwrite files
-- `edit` - patch files
+- `write` - preflight and create new files without overwriting existing paths
+- `edit` - preflight and patch existing files with stale-target checks
 - `bash` - run shell commands
 
 Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. Pi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.

package/docs/settings.md

@@ -278,7 +278,7 @@ Worker writes use **review-after-apply** semantics: a grant-authorized direct `w
 
 Deterministic argument repair is built in and has no settings toggle; schema-valid calls still return unchanged without entering the repair layer. `PI_TOOL_REPAIR_DISABLED=1` remains only an emergency diagnostic kill switch.
 
-Text protocol precedence is: `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` kills it, then `toolRepair.textProtocol` force-enables or disables it globally, then per-model `textToolCallProtocol` applies, then a persisted `/toolprobe` text-protocol verdict applies to that exact model. Native provider tool calls still take precedence when the model emits them; the text protocol is the fallback lane for pure-text models. Failed calibration is stored per host/model and can be cleared with `/toolprotocol-reset <provider/model>`.
+Text protocol precedence is: `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` kills it; a persisted `/toolprobe` native verdict then keeps that exact model on native calls; otherwise `toolRepair.textProtocol` force-enables or disables globally, per-model `textToolCallProtocol` applies, and finally a persisted calibrated text-protocol verdict applies. The phone/text protocol is therefore a fallback lane for models without proven native calls, never a replacement for a proven native path. Failed calibration is stored per host/model and can be cleared with `/toolprotocol-reset <provider/model>`.
 
 Environment kill switches override their diagnostic layers: `PI_TOOL_REPAIR_DISABLED=1`, `PI_TOOL_REPAIR_TEACH_DISABLED=1`, and `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1`. See [Tool repair](tool-repair.md) for diagnostics, reset controls, and replay.
 

package/docs/tool-boundary-performance-roadmap-2026-08-02.md

@@ -0,0 +1,166 @@
+# Tool Boundary Performance Roadmap — 2026-08-02
+
+This is the evidence ledger for avoiding wasted model output, repeated large-string work, foreground stalls,
+and cross-session contention at tool boundaries. Findings are classified as fixed, open, rejected, or
+incomplete. A green process exit is not evidence when a relevant payload, race, platform, or memory probe was
+not exercised.
+
+## Required invariants
+
+1. Validate cheap authority, path, identity, availability, and collision facts before asking the model for a
+   large payload.
+2. Keep coordinators, payload handles, mutable queues, and retry state session-owned unless cross-session
+   coordination is the explicit invariant.
+3. Store large bytes once, outside the JavaScript heap where practical. Context and telemetry retain bounded
+   metadata and opaque handles, not duplicate payloads.
+4. Never flatten accumulated text repeatedly. Rendering, loop detection, failure handling, and telemetry use
+   incremental processing or constant-size fingerprints.
+5. A failure that requires a different approach discards its operation arguments. It may expose one bounded
+   reason/directive for the next model turn, then expires.
+6. Every visible tool operation reports elapsed time through the shared TUI timing owner.
+
+## Confirmed and fixed in this cycle
+
+| Boundary | Root cause | Fix | Evidence gate |
+| --- | --- | --- | --- |
+| Write collision | `write` accepted the full content before discovering an occupied destination and could overwrite it. | Two-phase `prepare`/`commit`, path-only collision and parent checks, single-use session intent, and final `wx` no-clobber create. | `test/file-mutation-preflight.test.ts`; `test/file-encoding-policy.test.ts` |
+| Missing/stale edit | `edit` accepted replacement payloads before existence checks and could apply a plan prepared against older bytes. | Path-only preparation records file identity; commit consumes the intent and rejects a missing or changed target. | `test/file-mutation-preflight.test.ts`; `test/file-mutation-queue.test.ts` |
+| Repeated exact content | Copying identical generated content to another destination required retransmitting it. | Successful writes/edits return a session-local `contentRef`; the bounded controller hashes the source and performs exclusive verified copies without retaining bytes on the JS heap. | `test/file-mutation-preflight.test.ts` |
+| Encoding corruption | An unsafe text edit could be remembered as a retryable operation and teach repair/re-read loops. | The central execution-error catalogue classifies `PI_FILE_ENCODING_CORRUPTION` as change-approach, consumes the edit intent, retains no operation arguments, exposes one bounded directive, and expires it after the next assistant response. | `packages/ai/test/tool-execution-error-catalogue.test.ts`; `packages/agent/test/tool-failure-memory.test.ts` |
+| Edit preview flattening | Preview rendering used `JSON.stringify({ path, edits })` during render and result settlement, copying the complete edit payload. | Constant-size request generations fence asynchronous previews; partial renders do not scan accumulated edits. | `test/edit-tool-no-full-redraw.test.ts` |
+| Write preview flattening | Collapsed streamed previews compared the complete prior content prefix, split and highlighted complete snapshots, and retained duplicate full line arrays. | Collapsed rendering inspects at most 8,192 characters, caches by argument-generation identity, and performs one allocation-free final line count; complete text is materialized only on explicit expansion. | `test/tool-execution-component.test.ts` |
+| Loop/failure payload retention | Stall and failure signatures serialized complete tool arguments and stored the normalized string in the loop window. | A streaming structural fingerprint returns 32 hex characters; failure display keeps a bounded structural preview and never serializes the original payload. | `packages/agent/test/tool-failure-memory.test.ts` |
+| Tool timing gaps | Only selected tool implementations exposed duration, so reads and Python appeared to have no timing. | One monotonic component displays live `Elapsed` and terminal `Took` timing for every tool surface, including failures, replayed panels, built-ins, and extensions. | `test/tool-execution-component.test.ts` |
+
+All fixed paths must retain the zero-clone production gate and the focused regression named above.
+
+## P0 — confirmed open work
+
+### P0.1 Persistent Python coordinator per session
+
+Evidence:
+
+- `src/core/tools/python.ts` creates `createLocalPythonOperations()` per tool definition and calls
+  `spawnProcess()` for every execution.
+- `src/core/python-runtime.ts` caches interpreter discovery process-wide, but it is not a command coordinator.
+- `src/core/tools/python.ts` wraps every job in `withExclusiveMutationBarrier()`.
+- `src/core/tools/file-mutation-queue.ts` owns one module-global writer queue, so a long Python job can block
+  unrelated sessions and workspaces.
+
+Required design:
+
+- RuntimeBuilder owns one `PythonCommandCoordinator` per agent session. Never share the command process across
+  sessions or tenants.
+- Start the interpreter/worker once on first use, use framed requests and terminal acknowledgements, and reset
+  the owned process after protocol corruption, timeout, abort, or crash.
+- Completion is event-driven and emits the normal terminal tool signal. Jobs handed to the existing background
+  lane after 15 seconds keep the same session coordinator and notify their owning session only.
+- Replace the process-global exclusive writer with an explicit session/workspace mutation port. Same-file
+  operations remain serialized; unrelated sessions are not globally stopped.
+
+Acceptance evidence:
+
+- Cold start and first dispatch measured separately from warm dispatch on Linux and Windows.
+- Warm no-op harness overhead target: p95 <= 25 ms, excluding Python code runtime.
+- Two concurrent sessions prove distinct worker PIDs/state and no cross-session variables.
+- A 20-second Python job does not delay a read-only call or a mutation in another isolated workspace.
+- Timeout, abort, malformed frame, worker exit, and session disposal each produce one terminal event and bounded
+  handoff.
+
+### P0.2 Python path/runtime preflight before inline code
+
+Evidence: `python` receives up to 200,000 characters of inline code before it checks `cwd`, `scriptPath`, uv, or
+the interpreter. An invalid working directory can therefore waste the entire generated program.
+
+Required design:
+
+- Add a path-only/runtime-only prepare action for inline-code mode and a path/runtime prepare action for script
+  mode.
+- Commit consumes a single-use session intent. Runtime failure or coordinator reset invalidates the intent; the
+  code is not stored as retry memory.
+- Do not add a legacy one-phase fallback.
+
+Acceptance evidence: invalid cwd/runtime tests prove that no `code` field was accepted; stale and cross-session
+intents fail; successful warm preparation meets the same p95 budget as P0.1.
+
+### P0.3 Process-isolate extension smoke tests
+
+Evidence: `src/core/tools/extensionify.ts` writes the complete draft and calls `loadExtension()` in the live Pi
+process. The “isolated runtime” isolates registration state, not CPU, environment, memory, filesystem, or process
+lifetime. A draft can block the event loop or inspect live process state.
+
+Required design:
+
+- Validate name, proposed destination, package JSON shape, size bounds, and policy before accepting factory code.
+- Run the draft in a disposable child process with a bounded environment, output, time, memory, and capability
+  surface. Send back registration metadata only.
+- The child emits one terminal result; cleanup is lease-owned and event-driven.
+- Do not repeat `code`/`packageJson` in tool result details.
+
+Acceptance evidence: infinite loop, allocation bomb, environment read, process exit, malformed package JSON,
+path traversal, and cleanup-failure probes; parent session remains responsive and bounded.
+
+### P0.4 Close edit's external-writer race
+
+Evidence: edit commit verifies identity before `readFile()` and later overwrites by path. A non-Pi writer can
+replace the file after the identity check but before the final write.
+
+Required design: bind read/compare/commit to a file handle or an adapter-owned compare-and-replace primitive;
+fail closed when identity changes. Define Windows replace/share semantics explicitly and preserve BOM/newlines.
+
+Acceptance evidence: deterministic interleavings at every stat/read/write boundary, symlink swaps, same-size
+same-timestamp replacement, Windows sharing violations, abort, and cleanup failure.
+
+## P1 — confirmed, bounded, or dependent work
+
+1. **General payload leases for `skillify`/`extensionify`.** Both tools repeat full draft bodies in result
+   details, while their name/description checks happen only after the payload exists. Introduce a session-owned,
+   disk-backed, byte/count/age-bounded payload store and return opaque handles. Keep security-sensitive payload
+   classes separate even if they share a storage port.
+2. **Streaming skill audit.** `skill-audit.ts` lowercases, regex-replaces, splits, and de-duplicates the complete
+   draft body, then performs pairwise Jaccard comparisons. Add bounded streaming tokenization and an inverted
+   candidate index before exact scoring. Preserve evidence that distinct trust/workflow semantics are not merged.
+3. **Verify custom write adapters before issuing reusable content handles.** Local `wx` writes are authoritative;
+   remote/custom adapters need an adapter-owned verified-create contract so a handle is not returned for altered
+   bytes.
+4. **Reduce bounded toolkit-output copies.** Script capture is capped at 512 KiB per stream, but result assembly
+   trims and joins both strings before artifact packing. Stream directly into the existing output/artifact owner.
+   This is not an OOM path under the present cap, so it follows the unbounded P0 items.
+5. **Bound metadata schemas.** Add evidence-derived character/item limits to `extensionify`, `skillify`, and
+   toolkit identifiers/arguments. Limits must be measured and must not truncate source or reduce correctness.
+6. **Bound renderer-less tool arguments.** `ToolExecutionComponent.formatToolExecution()` currently
+   `JSON.stringify()`s complete arguments for tools without a renderer, and the scrollback component retains
+   that argument object after settlement. Use the shared bounded structural projection for display and release
+   the UI-owned payload after the session transcript has accepted the authoritative call. Preserve explicit
+   expansion through a disk-backed/session-owned handle instead of another heap copy.
+
+## Rejected or low-benefit candidates
+
+- **Ropes/piece tables for provider payloads:** rejected at the network boundary. Providers still require a
+  contiguous JSON/body representation; chunked message ownership, pruning before formatting, and one terminal
+  serialization are the useful controls.
+- **Two-phase preflight for `read`, `grep`, `find`, `ls`, and artifact retrieval:** rejected unless new evidence
+  shows large arguments. Their requests are small, outputs are bounded or artifact-backed, and an extra model
+  round trip would cost more than the local validation.
+- **Replacing native JSON globally:** rejected without per-boundary benchmarks. Several provider transports
+  require JSON text; changing parsers cannot remove serialization and may add copies. Optimize duplicate
+  serialization and retained ownership first.
+- **Raising output/context limits:** rejected as a performance fix. It moves the failure boundary and increases
+  heap exposure without removing repeated work.
+
+## Incomplete probes
+
+- Windows timing distributions for local and SSH-backed prepare/commit.
+- Heap/GC profiles for multi-megabyte skill drafts and extension smoke tests.
+- External-writer race reproduction on NTFS with antivirus/indexer sharing behavior.
+- Provider-specific cost of the extra prepare turn versus rejected-payload tokens across native and text tool
+  protocols.
+- Persistent Python protocol throughput and reset cost; no implementation exists yet, so prior process-spawn
+  timings are not acceptance evidence.
+
+## Release gate for roadmap items
+
+For each item: Detect -> deterministic failing regression and negative control -> fix at the named owner -> run
+the smallest package test -> run adjacent package tests -> `npm run check` -> production clone audit. Run the full
+non-e2e suite only at the pre-release gate. Report fixed findings, rejected candidates, incomplete probes, and
+remaining platform risks separately.

package/docs/tool-repair.md

@@ -2,7 +2,7 @@
 
 Pi validates every model-emitted tool call against its TypeBox schema before execution. Valid calls run unchanged. Invalid calls either pass through a named deterministic repair and then execute with the repaired arguments, or they bounce with schema feedback when no safe repair applies.
 
-Execution failures are not argument repairs. Pi removes their potentially large failed protocol turns from provider context and retains one bounded failure record: stable operation identity, occurrence count, failure code, a cause-bearing diagnostic when available, and `next_action`. A matching successful retry clears the record. Pi uses `repair` only for argument/protocol rejections with a concrete call correction; policy, preflight, abort, and execution failures use `next_action`. It never invents a deterministic repair from an unknown nonzero exit.
+Execution failures are not argument repairs. Pi removes their potentially large failed protocol turns from provider context and normally retains one bounded failure record: constant-size operation fingerprint, bounded operation preview, occurrence count, failure code, a cause-bearing diagnostic when available, and `next_action`. A matching successful retry clears the record. Change-approach classes such as non-UTF-8 text edits are different: Pi discards the complete attempted operation, exposes one bounded reason/directive for the next assistant response, then expires it. Pi uses `repair` only for argument/protocol rejections with a concrete call correction; policy, preflight, abort, and execution failures use `next_action`. It never invents a deterministic repair from an unknown nonzero exit.
 
 ## Runtime behavior
 
@@ -11,7 +11,7 @@ Execution failures are not argument repairs. Pi removes their potentially large
 - Repair is built-in and has no settings toggle. `PI_TOOL_REPAIR_DISABLED=1` is only an emergency diagnostic kill switch; normal configuration should leave repair on.
 - Teaching can be disabled independently with `toolRepair.teach: false` or `PI_TOOL_REPAIR_TEACH_DISABLED=1`. Repairs can still execute; the in-band "Tool argument repair note" is suppressed.
 - Tool-recovery logging can be disabled with `toolRepair.logging: false`. Repairs still run, but Pi does not enqueue recovery records or spawn the background recovery-log worker.
-- Text tool-call protocol calibration can be enabled per model with `textToolCallProtocol: true` in `models.json`. `/toolprobe [provider/model]` can also persist a host-local text-protocol verdict for one model after a live probe. Use `toolRepair.textProtocol` only as a global emergency force/kill switch; `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` always disables it.
+- Text tool-call protocol calibration can be enabled per model with `textToolCallProtocol: true` in `models.json`. `/toolprobe [provider/model]` probes native calls first and can persist a host-local text-protocol verdict only when native calls are absent. A persisted native verdict always keeps that model off the text protocol, including when global or model settings enable it. Use `toolRepair.textProtocol` only as a global emergency force/kill switch for models without native proof; `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` always disables it.
 
 Example project settings:
 
@@ -29,7 +29,7 @@ Example project settings:
 
 - Interactive tool panels show `[repaired arguments]` when execution used repaired arguments.
 - RPC `tool_execution_start`, `tool_execution_update`, and `tool_execution_end` events include a `repair` object when arguments were repaired.
-- `/toolhealth` prints model adaptation records for this host: tool-probe verdicts, calibrated or failed text protocol, learned standing rules, teach statistics, and recovery-log worker counters.
+- `/toolhealth` prints model adaptation records for this host: tool-probe verdicts, calibrated or failed text protocol, learned standing rules, teach statistics, recovery-log worker counters, and execution-failure counts by phase.
 - `/toolrule-remove <provider/model> <mode>` removes one learned standing rule from the host-local adaptation store.
 - `/toolprotocol-reset <provider/model>` removes a stored text protocol calibration or failed-calibration record so the next turn can calibrate again.
 - `/toolprobe [provider/model]` probes the current fleet or one explicit model for native tool calls first, then text-protocol fallback, persists the verdict in the host-local adaptation store, and prints a report table.
@@ -45,7 +45,7 @@ node scripts/tool-repair-replay.mjs ~/.pi/agent/state/failure-corpus.jsonl --jso
 node scripts/tool-repair-replay.mjs ~/.pi/agent/sessions/<session>.jsonl --fixtures /tmp/tool-repair-fixtures.json
 ```
 
-The replay helper reads `tool_validation` corpus records and legacy bounced `tool_argument_validation` session entries. Current recovery telemetry is written by a dedicated `node:worker_threads` worker to `state/tool-recovery-events.jsonl`; bounced records also append sanitized `tool_validation` corpus rows. Records contain shape metadata, failure modes, and error keywords; they do not store full tool arguments.
+The replay helper reads `tool_validation` corpus records and legacy bounced `tool_argument_validation` session entries. Current recovery telemetry is written by a dedicated `node:worker_threads` worker to `state/tool-recovery-events.jsonl`; bounced calls append sanitized `tool_validation` corpus rows, while rejected or failed executions append bounded `tool_execution` rows with phase, failure code, optional redacted diagnostic, and next action. Records do not store full tool arguments.
 
 ## Repair modes
 

package/docs/windows.md

@@ -13,7 +13,7 @@ Pi supports native Windows on x64 and ARM64. The Node.js package runs under Wind
 The model always sees one stable `bash` tool contract. On Windows, a deterministic router classifies every command into one of three tiers instead of parsing the full Bash grammar in one place:
 
 1. **PowerShell floor** (always available): one simple command — a bounded set of builtin translations or a quoted external argv — converted deterministically to PowerShell, exactly as before this tier existed.
-2. **Bundled Python engine** (uv-provisioned Python 3.13, on by default): pipelines, redirection, chaining, quoting, expansion, globs, and the coreutils vocabulary below, plus every state-mutating command (`cd`, `export`, `unset`), which the engine always owns so there is a single mutator.
+2. **Bundled Python engine** (uv-provisioned Python 3.13, on by default): pipelines, redirection, chaining, word-list and arithmetic `for` loops, loop control, quoting, expansion, globs, and the coreutils vocabulary below, plus every state-mutating command (`cd`, `export`, `unset`), which the engine always owns so there is a single mutator.
 
 External programs are not reimplemented. A simple `rg` call runs the installed native `rg.exe` through the persistent PowerShell floor; when a pipeline or chain requires the Python coordinator, it spawns that same `rg.exe` directly without resolving or starting PowerShell. A `.ps1` target in an engine-owned command is adapted through the same selected PowerShell executable as the floor, without starting a nested model-authored shell.
 3. **Named fail-closed refusal**: constructs outside the supported grammar (see below) return an actionable error naming the construct instead of guessing or downgrading silently.
@@ -36,7 +36,9 @@ The PowerShell tier runs with `-NoLogo -NoProfile -NonInteractive -Command` and
 | Sequencing | `a ; b`, newline-separated, `a && b`, `a \|\| b`, `! pipeline` | Left-to-right / short-circuit / negation, bash-standard. |
 | Subshell | `( … )` | Isolated cwd/env copy — inner `cd`/`export` do not leak out. |
 | Brace group | `{ …; }` | Shares state — inner `cd`/`export` persist. |
-| Redirection | `>`, `>>`, `1>`, `1>>`, `<`, `2>`, `2>>`, `2>&1`, `&>`, `>&` | `/dev/null` maps to `os.devnull`. A builtin's stderr is merged into its own stdout (one sink) — an explicit `2>file` on a builtin does not capture its error text; external commands capture normally. |
+| For loop | `for name in words; do …; done`, `for name; do …; done`, `for ((init; condition; update)); do …; done` | Word lists expand once before iteration; the final value remains in the session environment. The omitted-list form iterates shell positional arguments, which Pi does not supply. Arithmetic clauses support integer variables, updates, assignments, comparisons, logical/bitwise operators, and signed 64-bit wrapping. |
+| Loop control | `break [N]`, `continue [N]` | Works across nested word-list and arithmetic loops. An omitted count means one; invalid counts report status 1 without crashing the coordinator. |
+| Redirection | `>`, `>>`, `1>`, `1>>`, `<`, `2>`, `2>>`, `2>&1`, `&>`, `>&` | `/dev/null` maps to `os.devnull`. Unredirected stderr shares Pi's session output; explicit stderr redirection is honored for builtins, state commands, and external programs. |
 | Quoting | `'…'`, `"…"`, `\x`, `$'…'` | Standard single/double/backslash/ANSI-C semantics. |
 | Tilde | `~`, `~/x` | Word-start, unquoted, expands to `$HOME`. `~user` is unsupported (refusal). |
 | Parameter expansion | `$VAR`, `$?`, `${VAR}`, `${V:-w}`, `${V:=w}`, `${V:+w}`, `${V:?w}`, `${#VAR}` | `$?` is the latest foreground pipeline status. POSIX `:`-prefixed (empty-or-unset) semantics only; other `${…}` operators refuse. |
@@ -53,13 +55,13 @@ Builtins: `cd`, `pwd`, `echo [-n -e -E]`, `printf`, `export`, `unset`, `exit [N]
 - `wc`/`uniq -c` column widths reproduce GNU's dynamic field width only for the single-count stdin case; multi-count/file-arg forms use fixed deterministic padding.
 - No shell-variable vs. exported-environment distinction: every `NAME=value` sets engine env.
 - Sorting is always ordinal (`LC_ALL=C`): globs, `ls`, `find`, and default `sort`.
-- A builtin's stderr is merged into its own stdout; only external commands honor an explicit `2>`.
+- Arithmetic loop variables use deterministic signed 64-bit wrapping; invalid shifts, division by zero, negative exponents, and malformed expressions return status 1 with a bounded diagnostic.
 - Globs expand only the final path segment (`dir/*.py` works; `*/x.py` matches the directory part literally).
 - `wc -m` counts UTF-8 characters (bash under `LC_ALL=C` counts bytes).
 
 ### Named unsupported constructs
 
-Each of these fails closed with a named, actionable error instead of an approximation: `job-control` (trailing `&`, `fg`/`bg`/`jobs`/`wait`/`disown`), `process-substitution` (`<(…)`/`>(…)`), `arithmetic-expansion` (`$((…))`, `((…))`, `let`), `brace-expansion` (`{a,b,c}`), `nested-shell` (`bash`/`sh`/`cmd`/`powershell`/`pwsh`/`wsl`/… as a command word), `exec-builtin`, `heredoc`/`here-string` (`<<`, `<<-`, `<<<`), `function-definition`, `control-flow` (`if`/`for`/`while`/`until`/`case`/`select`), `extended-glob` (`@(…)`, `!(…)`, etc.), `unsupported-builtin` (`eval`, `source`/`.`, `alias`, `trap`, `set`, `shopt`, `read`, `declare`, `local`), `unsupported-flag`, `posix-script` (`*.sh`, `/bin/…`), `cwd-missing`, `tilde-user`, `malformed-syntax` (unbalanced quote/paren/brace, empty pipeline element, missing redirect target), `parameter-expansion` (a `${…}` form outside the supported op set).
+Each of these fails closed with a named, actionable error instead of an approximation: `job-control` (trailing `&`, `fg`/`bg`/`jobs`/`wait`/`disown`), `process-substitution` (`<(…)`/`>(…)`), `arithmetic-expansion` (`$((…))`, standalone `((…))`, and `let`; arithmetic `for` headers are supported), `brace-expansion` (`{a,b,c}`), `nested-shell` (`bash`/`sh`/`cmd`/`powershell`/`pwsh`/`wsl`/… as a command word), `exec-builtin`, `heredoc`/`here-string` (`<<`, `<<-`, `<<<`), `function-definition`, `control-flow` (`if`/`while`/`until`/`case`/`select`), `extended-glob` (`@(…)`, `!(…)`, etc.), `unsupported-builtin` (`eval`, `source`/`.`, `alias`, `trap`, `set`, `shopt`, `read`, `declare`, `local`), `unsupported-flag`, `posix-script` (`*.sh`, `/bin/…`), `cwd-missing`, `tilde-user`, `malformed-syntax` (unbalanced quote/paren/brace, empty pipeline element, missing redirect target, malformed `for` loop), `parameter-expansion` (a `${…}` form outside the supported op set).
 
 ### State and session semantics
 
@@ -73,7 +75,7 @@ The Python interpreter and engine imports stay warm in one coordinator process p
 
 `windowsShell.pythonEngine` (default `true`) is the kill switch. Set it to `false` to restore the PowerShell-only contract verbatim: only the simple-command floor is used, and every pipeline/redirection/expansion/chaining form that would have routed to the engine instead returns the same fail-closed error it did before the engine existed.
 
-When the setting is left on but the bundled Python runtime cannot be resolved (uv missing, network failure provisioning Python 3.13, or similar), the engine tier is simply unavailable: simple commands still run on the PowerShell floor exactly as always, and any command that needs the engine returns a named error stating the Python runtime is unavailable, that the simple-command floor still works, and to fix `uv`/network to restore pipelines, redirection, expansion, and chaining. There is no silent approximation — a complex command is never downgraded to a plausible-but-wrong simple execution.
+When the setting is left on but the bundled Python runtime cannot be resolved (uv missing, network failure provisioning Python 3.13, or similar), the engine tier is simply unavailable: simple commands still run on the PowerShell floor exactly as always, and any command that needs the engine returns a named error stating the Python runtime is unavailable, that the simple-command floor still works, and to fix `uv`/network to restore loops, pipelines, redirection, expansion, and chaining. There is no silent approximation — a complex command is never downgraded to a plausible-but-wrong simple execution.
 
 The native `python` tool uses the same contract on Windows and Unix-like systems. Pi provisions a pinned uv executable, resolves or installs Python 3.13 through uv, then spawns the interpreter directly with UTF-8 and bytecode-cache suppression. Python calls default to 30 seconds. See [Native Python](python.md).
 

package/docs/worker-profiles.md

@@ -0,0 +1,16 @@
+# Task worker profiles
+
+`profile_writer` lets the foreground orchestrator create the smallest worker profile needed for one bounded task. It does not edit user or project profile files.
+
+Task profiles are:
+
+- Derived only from an owner-authorized base profile.
+- Immutable and assigned a `task-...` ID by Pi.
+- Stored on the owning session branch, never shared across independent sessions.
+- Limited to 32 profiles per session.
+- Unable to add tools, resources, or budget beyond the base profile.
+- Limited to configured, authenticated, non-exhausted models and a thinking level that model supports.
+
+Use `profile_writer { action: "inspect" }` when the authorized bases or model combinations are unknown. Then call `create` with a concise task and only the fields that need narrowing. Pass the returned profile ID unchanged to `delegate`; never invent one.
+
+Workers cannot invoke `profile_writer`, recursively delegate, or expand their admitted contract. A resumed worker retains the exact profile, model, resources, and transcript admitted for that task.

package/examples/extensions/built-in-tool-renderer.ts

@@ -26,7 +26,13 @@
  */
 
 import type { BashToolDetails, EditToolDetails, ExtensionAPI, ReadToolDetails } from "@caupulican/pi-adaptative";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@caupulican/pi-adaptative";
+import {
+	createBashTool,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	FileMutationIntentController,
+} from "@caupulican/pi-adaptative";
 import { Text } from "@caupulican/pi-tui";
 
 export default function (pi: ExtensionAPI) {
@@ -151,7 +157,8 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Edit tool: show path and diff stats ---
-	const originalEdit = createEditTool(cwd);
+	const fileMutationIntents = new FileMutationIntentController();
+	const originalEdit = createEditTool(cwd, { intentController: fileMutationIntents });
 	pi.registerTool({
 		name: "edit",
 		label: "edit",
@@ -216,7 +223,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Write tool: show path and size ---
-	const originalWrite = createWriteTool(cwd);
+	const originalWrite = createWriteTool(cwd, { intentController: fileMutationIntents });
 	pi.registerTool({
 		name: "write",
 		label: "write",
@@ -230,8 +237,8 @@ export default function (pi: ExtensionAPI) {
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("write "));
 			text += theme.fg("accent", args.path);
-			const lineCount = args.content.split("\n").length;
-			text += theme.fg("dim", ` (${lineCount} lines)`);
+			const writeContent = args.action === "commit" && "content" in args ? args.content : undefined;
+			if (writeContent) text += theme.fg("dim", ` (${writeContent.length} characters)`);
 			return new Text(text, 0, 0);
 		},
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.84.1",
+  "version": "0.85.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.84.1",
+      "version": "0.85.3",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.84.1",
+  "version": "0.85.3",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.84.1",
+  "version": "0.85.3",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/minimal-mode.ts

@@ -25,6 +25,7 @@ import {
 	createLsTool,
 	createReadTool,
 	createWriteTool,
+	FileMutationIntentController,
 } from "@caupulican/pi-adaptative";
 import { Text } from "@caupulican/pi-tui";
 import { homedir } from "os";
@@ -44,11 +45,12 @@ function shortenPath(path: string): string {
 const toolCache = new Map<string, ReturnType<typeof createBuiltInTools>>();
 
 function createBuiltInTools(cwd: string) {
+	const fileMutationIntents = new FileMutationIntentController();
 	return {
 		read: createReadTool(cwd),
 		bash: createBashTool(cwd),
-		edit: createEditTool(cwd),
-		write: createWriteTool(cwd),
+		edit: createEditTool(cwd, { intentController: fileMutationIntents }),
+		write: createWriteTool(cwd, { intentController: fileMutationIntents }),
 		find: createFindTool(cwd),
 		grep: createGrepTool(cwd),
 		ls: createLsTool(cwd),
@@ -167,8 +169,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "write",
 		label: "write",
-		description:
-			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+		description: "Create a new file through path-only preflight. Existing paths are never overwritten.",
 		parameters: getBuiltInTools(process.cwd()).write.parameters,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -179,10 +180,10 @@ export default function (pi: ExtensionAPI) {
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
 			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
-			const lineCount = args.content ? args.content.split("\n").length : 0;
-			const lineInfo = lineCount > 0 ? theme.fg("muted", ` (${lineCount} lines)`) : "";
+			const writeContent = args.action === "commit" && "content" in args ? args.content : undefined;
+			const sizeInfo = writeContent ? theme.fg("muted", ` (${writeContent.length} characters)`) : "";
 
-			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${lineInfo}`, 0, 0);
+			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${sizeInfo}`, 0, 0);
 		},
 
 		renderResult(result, { expanded }, theme, _context) {

package/examples/extensions/prompt-customizer.ts

@@ -37,12 +37,14 @@ function addToolGuidance(options: BuildSystemPromptOptions, basePrompt: string):
 
 	if (hasTool("edit")) {
 		parts.push(
-			"• Use the `edit` tool for precise text replacements in files. Match exact content including whitespace.",
+			"• Use `edit` action=prepare before generating precise replacements, then commit with the returned intent. Match exact content including whitespace.",
 		);
 	}
 
 	if (hasTool("write")) {
-		parts.push("• Use the `write` tool to create new files or overwrite existing ones completely.");
+		parts.push(
+			"• Use `write` action=prepare before generating content; commit creates a new file and never overwrites.",
+		);
 	}
 
 	if (options.skills && options.skills.length > 0) {

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "0.84.1",
+	"version": "0.85.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "0.84.1",
+			"version": "0.85.3",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "0.84.1",
+	"version": "0.85.3",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",