gentle-pi v4.7.0 — Gentle AI v4.4.0, Full Delegation Profiles and Tighter Execution Guards

Gentle Shell v4.7.0 is a feature release. It pins Gentle AI v4.4.0; profiles can choose an orchestrator workflow mode, organic or full delegation, that changes on the next turn; the fullscreen chrome gains header placements, a transparent surface by default, card-style rail sections and mouse controls in every modal; guarded commands can be allowed once, for the session or always; and sessions publish a universal agent-status file any terminal tool can read. Reviews gain an opt-in coordinator, frozen request intent, reviewer execution evidence and actionable blocker diagnoses. Execution got tighter: delegation can no longer escape to an external pane, the sensitive-path guard now covers shell commands, and qualifying child agents get the background job tools they declare. Windows session transport re-arms once after a failed start, pi.cmd shims launch without a shell, and a read-only STATUS that times out on the host offers a rerun instead of a dead end. Twenty-three community authors contributed to this release. The npm package remains gentle-pi.

Provenance

• Previous stable: v4.6.0 → 1f74e9e24473e7e121a96b1680444ae0196d3009
• Release target: v4.7.0 → 8e11f0e2fb19af2a28233d1774848f7a3a33bbf1
• Release validation: run 42401297004 passed package verification, published gentle-pi@4.7.0 to npm with provenance, and built, verified and attached the installers.
• Pinned Gentle AI: v4.4.0 (55240af); the review provider contract remains unchanged at 1.4.0, and the negotiated capability identity is unchanged.

What's new

Gentle AI v4.4.0 pin

The bundled runtime moves from Gentle AI v4.3.1 to v4.4.0, which brings Antigravity 1.4 parity, faster gentle-shell/gs launches, gs on Windows, and safer Windows restores. See Pinned runtime.

Included work: #3000 (issue #2999).

Profiles choose who writes

A profile now carries an orchestrator workflow mode. organic lets the orchestrator implement inline and delegate when a delegation trigger fires; full-delegation never implements and sends every authorized change to a bounded writer with its code, tests and docs together, while the orchestrator keeps authorizing, routing, deciding, asking, tracking, committing, verifying and reporting. Neither mode is presented as the better one. In /gentle:profiles, w toggles the mode as a draft that is saved with the routing, and the Orchestrator row reads ◎ organic or ⇄ full delegation. The rules follow the active profile on the next turn in both directions, with no restart. The mode is stored under a separate workflow key in profiles.json, so profiles that stay organic serialize exactly as before, and every degraded case falls back to the organic rules.

In full delegation mode the organic routing rules are removed from the orchestrator's context rather than annotated, which shrinks the always-on core from 9,146 B to 5,611 B. Writer admission follows the same mode, so a small task no longer deadlocks between a prompt that forbids inline edits and a runtime that refused a generic writer; the edit-surface guard still runs first. The reply language also stays with the human after an English subagent result.

Included work: #2976, #2987.

Header placements, a transparent surface and card-style rail

Header › top draws the whole header row (model and effort, context, cost, usage) above the conversation, and the previous IDE chrome stays available as Header › split. Every placement at 140 columns or more now uses one bar design: branch, permission mode with its icon (🔥 YOLO, 💥 SUPER-YOLO), model and effort with the agent profile beside it, context, cost and usage, with the titled-rule editor under it. Layout › Surface offers tinted or transparent; transparent is now the default, so a terminal background image shows through the rail, bars and /gentle:panel, and rail sections draw as cards in the active card style. Minimal cards are the default, float cards stay apart in every density, a click anywhere on a card's title row folds its section, and titles take the hover color. The Todos header shows its collapse key, Stats opens with the profile, and the mobile chrome is aligned with the full-width layout.

Fullscreen Customize, Commands and Jobs now accept the mouse, and every actionable control and question label shares one orange hover; hovering never selects, applies, answers or stops anything. Every installation also shows the end-of-run TPS notification by default, with input, output, cache and total tokens and the elapsed time.

Included work: #2896 (issue #2890), #2897, #2904, #2908, #2876 (issue #2875), #2918 (issue #2916).

Scoped command confirmations and RDD controls

A guarded command in Normal mode now offers Allow once, Allow for this session (the exact command), Always allow (saved in the user-level guardrails config) and Deny. Recognized data-loss commands never offer Always allow, hosts without a select dialog keep the plain yes/no confirm, and a malformed guardrails config is refused instead of rewritten. /gentle:rdd and a Customize entry switch RDD through one native mode owner with explicit repository or machine-wide choices, the existing normal, auto, YOLO and super-YOLO session modes are offered from the same place, and native assessment-only work is skipped when RDD is freshly validated off.

Included work: #2931 (issue #2929), #2902.

A universal agent-status file

Interactive top-level sessions publish their status as one documented JSON file per session (gentle-shell.agent-status/v1: agent, session, pid, cwd, working/blocked/idle state, task title and update time) under <config home>/agent-status/, so Herdr or any other terminal tool can show it without a socket. The file is replaced atomically, refreshed at least every 10 seconds, removed on shutdown, and stale records left by a crash are swept at the next session start. Layout › Task summary: on / off in /gentle:customize hides or shows task titles in both this file and the Herdr summary.

Included work: #2949 by @MarsSall, #2947 by @MarsSall, #2958 (issue #2392).

Review: request intent, an opt-in coordinator and clearer blockers

A fresh ordinary START accepts an explicit request file and keeps that intent through native preflight, untracked selection and consent, when the runtime advertises the capability; .envrc and .netrc join the shared sensitive-path policy. A default-off gentle_review_run coordinator follows native transition offers through the existing facade and stops for authored input, a native stop, a failure or maintenance that needs authorization. Reviewer execution facts (effective model and provider, phase, durations, and SDK-reported usage and cost) now survive through relay, facade and coordinator results; a blocked step names its category, actor and next step; optional host relay phase timings can be observed; and an empty candidate range after acknowledgement explains how to ask for the committed range instead.

Included work: #2883 by @dnlrsls, #2884 by @dnlrsls, #2966 by @dnlrsls, #2973 by @dnlrsls, #2975 by @dnlrsls, #2982 by @dnlrsls.

Updates follow the latest Pi and its companions

The managed Pi self-update now selects the latest stable Pi, a Shell upgrade keeps a newer Pi in place, and global installer actions resolve an exact validated latest-stable Pi while frozen release distributions keep their pins. The managed gentle-engram registration no longer carries an exact version ceiling, so Pi's own startup update notice and update --extensions reach it; Gentle Shell installs gentle-engram from npm latest (gentle-engram 0.7.0 (npm latest), paired with engram v3.7.0).

Included work: #2892 (issue #2891).

Pasted images on disk, on request

GENTLE_PI_IMAGES_DISK_CACHE=session writes each pasted image chip to ${XDG_CACHE_HOME:-~/.cache}/gentle-shell/images/<session>/ (directory 0700, files 0600), so local vision models, OCR and other tools have a real path to read. /gentle:images lists the paths for chips the draft still references, the submitted payload stays base64, the session directory is removed on shutdown, and the cache is off by default.

Included work: #2889 by @ipproyectosysoluciones (issue #2678).

Background jobs for child agents

A child agent that declared bash_background never had the tool registered, because the child branch returned before the background job tools were added, so it reported the tool as missing. Qualifying children now get the background job tools they declare.

Included work: #2968 (issue #2266).

Design skills and smaller additions

gentle-ui-design ships project-neutral product interface guidance, and design requests now pair it with gentle-design: gentle-design owns the artboards and canvas, gentle-ui-design owns UX quality, with a UX self-check before delivery. A slow package-local Gentle AI download now draws a progress bar on a terminal (npm and CI logs are unchanged), bash command protections are evaluated through an ordered policy list ready for future policy modules, and pure helpers find and remove stale routing keys ahead of a cleanup action.

Included work: #2856 (issue #2855), #2873 (issue #2872), #2255 by @jals1212, #915 by @danielgap, #2630 by @aiorellana502.

What was fixed

Delegation could escape the managed runtime

A tool call that set openProjectPaneIfMissing could fall back to an external pane outside the managed runtime, and the delegation reference allowed "another available delegation mechanism". A guard now classifies the call by that input property, never by tool name, and blocks true or any non-boolean value in every mode and in child sessions, before any UI or execution, with a four-field reason (gentle-ai.execution-surface.external-fallback-prohibited). The prompt and docs now delegate only through subagent_* or the native Agent.

Included work: #2993 (issue #379).

Shell commands could read sensitive paths

The sensitive-path deny list covered file tools but not shell commands. bash, bash_background and monitor now evaluate the same patterns over the command string with quote-, escape- and control-operator-aware matching, so cat .env is blocked in every spelling the pattern can reach. Globs, $VAR indirection and nested interpreters such as bash -c 'cat .env' remain documented fail-open limits. A guarded phrase inside a grep, cat or echo argument no longer triggers a confirmation just because a read-only git/gh segment shares the line, YOLO's standing permission no longer hesitates over destructive text that is only quoted or read outside the workspace, and reading the task's resolved skill files no longer asks once per file.

Included work: #2969 (issue #2349), #2772 by @MataM15, #2932 (issue #2930), #2936 (issue #2935).

Reviewer lenses refused configured models

With no binding, pin or frozen profile, the reviewer snapshot did not read the effective routing the models panel and subagent launches use, so a lens the panel showed as configured was refused with reviewer-config-invalid. It now reads the same global effective routing, resolved from the session's working directory so a reviewed repository or worktree can never choose its own reviewer through planted project agents; explicit bindings, repository pins and frozen profiles keep their fail-closed snapshot, and a refusal names its routing source and whether the lens entry is missing or has no model. Reviewers are also gated on session profile authority, startup orchestrators route the refuter and validator, /gentle:profiles clear says when a session is already on its startup state, a legacy project models.json is merged with the global config, and a profile snapshot no longer invents saved routing when no model config exists.

Included work: #2989 (refs #2163), #2863 by @matraket, #2864 by @matraket, #2477 by @aiorellana502, #2940.

A read-only STATUS timeout was a dead end

When the host's 30-second timeout fired on a read-only STATUS or INSPECT with no mutation, INSPECT ended in require-complete-native-authority-inventory and STATUS in resolve-native-operation-failure. Both now return native-status-timed-out with next_action: "rerun-native-status" and the read-only remediation command. Timeouts behind recover, repair or start, and corrupt authority, are unchanged.

Included work: #2992 (issue #213).

Review tools cost too much context

The five review-family tool declarations were the only always-on surface without a byte budget and had grown to about 21.3 KB per session. Their prose is trimmed to invariants and routing, with the mirrored runtime contract as the lifecycle authority, saving about 4.8 KB per session under a pinned budget test. A later blocker guidance repeated on three tools pushed it over budget; it is now declared once, at 17,179 B under the 17,300 B cap.

Included work: #2944 by @decode2 (refs #2213), #2994.

Review host

START continuations keep explicit lenses, focus, reason and policy path through intended-untracked selection, and STATUS accepts JSON object inputs; reviewer authentication and completion share one host deadline; an explicitly frozen empty policy is accepted in targeted validation; literal candidate-tree symlink scans are cached with fresh ref checks; START intent and failure facts are shared instead of rebuilt; every reviewer model is validated before materialization; committed approval acknowledgement is covered across restarts; the check that refused an intended-untracked selection is named; START mode is validated before lineage prerequisites; abandon accepts object input; and review authorization dialogs mark a Herdr pane as blocked. On Windows, ACL observations are batched into one probe per boundary, enforcement takes its identity from that probe, and the real-ACL boundary tests run in CI.

Included work: #2962 by @dnlrsls, #2963 by @dnlrsls, #2965 by @dnlrsls, #2964 by @dnlrsls, #2971 by @dnlrsls, #2972 by @dnlrsls, #2974 by @dnlrsls, #2980 by @dnlrsls, #942 by @L4XB, #1183 by @mvanhorn, #2659 by @pujitha24, #2395 by @jals1212 (issue #1203), #2882 by @dnlrsls, #2898, #2899.

Windows

A failed session transport start silently stayed down; it now re-arms exactly once on the next agent_start or turn_end, and startup, presence and bootstrap failures surface as sanitized warnings. When Pi is upgraded mid-session, pi.cmd and other npm or pnpm shims resolve to their JavaScript entry point and launch through node.exe without a shell. A Git scan that times out kills its whole process tree, including when the spawn throws synchronously; deep pnpm paths can stage the installer; dictation keeps capturing after a buffer underrun or overrun, and under WSL it captures through node-cpal's PulseAudio backend.

Included work: #2988 (issue #2166), #2341 by @dnlrsls, #2941 by @twotnguyen (issue #2887), #2394 by @LuisAlbertoMK, #1691 by @dnlrsls, #1541 by @NicolasIppoliti, #2733 by @orshih6 (issue #2603), #2771 by @MataM15.

Agents and orchestration

Incoming session messages go through the prompt-lifecycle router, held content is released after /tree, and an idle wake no longer races a starting prompt. A running subagent task is persisted at launch and reconciled after an abrupt exit, Herdr shows busy while owned background subagents run, and the recipient picker names peers instead of listing bare ids. Workers can recover through an explicit, bounded continuation after failures, the verifier is given a guard-compatible scratch copy without .git, the strict Risk: item N grammar and post-denial disposition are documented, and every agent package publishes the same codegraph tool contract.

Included work: #1639 and #1640 by @BGamboa13 (issue #1638), #1774 by @carlosmoradev (issue #1741), #1812 by @WarisGG (issue #626), #2729 by @ivvanare, #2919 (issue #2699), #2925 (issue #2818), #2948 (issue #2478), #2970 (issue #2888).

Launcher, installer and shell

Setup that failed now still runs post-install cleanup, so a later launch no longer defers silently to the published package. Bundled launches skip a redundant pi --version spawn, the Gentle AI download honors HTTPS_PROXY, HTTP_PROXY and NO_PROXY, and Pi's bash tool gets GIT_EDITOR=true and GIT_SEQUENCE_EDITOR=true unless the user set them, so git rebase --continue no longer hangs on a hidden editor. Switching tabs in /gentle:profiles no longer spawns several Git processes, the startup banner no longer flickers, freezes or damages the editor after /reload, the skill registry mirrors the skills Pi actually loaded, retired SDD references are gone from the shipped skills, the design canvas no longer selects text while panning, and the install guides agree on pi install npm:gentle-pi.

Included work: #1665 by @carlosmoradev (issue #1647), #2208 by @aiorellana502 (issue #2096), #2614 by @andreuSignes, #2677 by @orshih6 (issue #2448), #2942 by @twotnguyen (issue #2922), #355 by @AlejandroTatum, #1320 by @danielgap (issue #369), #2312 by @jonasotoaguilar (issue #2311), #2871 (issue #2828), #2399 by @danielgap (issue #299).

CI and tests

The suite isolates its environment and aligns SDK fixtures, pnpm run no longer triggers an implicit install that broke linked worktrees, and tests pin that setting and the workflow install order. Test scratch stays in the system temp directory, session-profile resets are exception-safe, the render cache harness runs on the declared Pi version, load-sensitive tests get CI-sized deadlines, the CodeGraph timeout test keeps Node 22's event loop alive, and a job test waits for settlement instead of a fixed budget.

Included work: #2917, #2927 (issue #2926), #2928, #2934 (issue #2933), #1803 by @carlosmoradev (issue #1768), #2422 by @LuisAlbertoMK (issue #2411), #2706 by @pujitha24 (issue #2428), #2727 by @pujitha24 (issue #2438), #2938.

Pinned runtime

The pinned Gentle AI runtime moves to github.com/gentleman-programming/gentle-ai/v3 v4.4.0 (tag commit 55240afb100ad6d2ef5fbe16f7be33a7693f77ad): signed release archives on Darwin and Linux, pinned by archive and extracted-binary SHA-256, and a SumDB-verified source build on Windows (h1:cAQAzIsbocYcQfOzA1CmgGpGgiCivUNcPjdfJE8RJ6g=). The binary still advertises gentle-ai.review-integration.capabilities/v2.6 and the review provider contract remains 1.4.0, so no capabilities/vN identity was added; the new 4.4.0 NATIVE_CLI_CONTRACTS row repeats the 4.3.1 row.

Breaking changes

None. Existing ODD, SDD, review, and package interfaces remain compatible.

Upgrade

pi install npm:gentle-pi@4.7.0

Restart Pi, then run gentle-ai sync so the managed orchestrator assets match the pinned runtime. Bundled installs run gentle-shell upgrade. The fullscreen chrome now defaults to the transparent surface and minimal cards; pick Layout › Surface: tinted in /gentle:customize to keep the previous look. Going back to an earlier version: it rejects a visual-customization.json that stores the split header or the transparent surface and falls back to the defaults.

Numbers

167 non-merge commits, 92 merged pull requests, and 24 unique GitHub PR authors since v4.6.0.

Thanks to the community authors of this release: @AlejandroTatum, @aiorellana502, @andreuSignes, @BGamboa13, @carlosmoradev, @danielgap, @decode2, @dnlrsls, @ipproyectosysoluciones, @ivvanare, @jals1212, @jonasotoaguilar, @L4XB, @LuisAlbertoMK, @MarsSall, @MataM15, @matraket, @mvanhorn, @NicolasIppoliti, @orshih6, @pujitha24, @twotnguyen and @WarisGG.

Verification

• Full suite on the head of #2994: 9219 pass, 0 fail, 93 skipped; type checking reports only the 11 known baselines.
• Pin bump #3000: focused suites 159 pass, 0 fail, and gentle-ai-binary 12 of 12 with the real v4.4.0 binary installed; package verification lists 248 files and 69 exact byte-pinned contract artifacts for v4.4.0; node scripts/test-packed-runner.mjs against the published release assets reports packed package E2E passed (gentle-pi 4.6.0; Gentle AI 4.4.0).
• Windows: the real-ACL boundary tests added to CI by #2899 ran 7 of 7 on their first real Windows run, and #2988 passes the Windows session transport suite 32 of 32.
• Safety: #2969 was verified adversarially with a 29-probe sweep and no blockers, and #2993 blocks every non-false openProjectPaneIfMissing value in normal, YOLO, super-YOLO and child sessions.

Install

pi install npm:gentle-pi@4.7.0

Package: https://www.npmjs.com/package/gentle-pi

Full changelog: v4.6.0...v4.7.0