pi-usereq 0.51.0 → 0.56.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.51.0)
+# PI-useReq/pi-usereq (0.56.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -9,19 +9,22 @@
 </p>
 
 <p align="center">
-<strong>TODO: complete with one line project descrition.</strong><br>
-TODO: complete with complete molti-line project descrition.<br>
-This allows them to be run both as a Python package (installed as <b>req</b>, <b>usereq</b>, or <b>use-req</b>) and directly using <b>uvx</b>.
+<strong>pi-usereq is a pi extension that runs a requirements-first development workflow.</strong><br>
+It turns a User Request into a living <em>Software Requirements Specification</em> (SRS), implements the corresponding
+source code, and keeps the project documentation (<code>WORKFLOW.md</code>, <code>REFERENCES.md</code>, <code>FLOWCHART.md</code>, <code>README.md</code>)
+in sync with the repository. All capabilities are exposed as slash commands and agent tools inside
+<a href="https://pi.dev"><strong>pi</strong></a> (<code>pi-coding-agent</code> 0.80.4+).
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> |
+  <a href="#requirements">Requirements</a> |
   <a href="#feature-highlights">Feature Highlights</a> |
   <a href="#prompts-and-agents">Prompts and Agents</a> |
   <a href="#default-workflow">Default Workflow</a> |
-  <a href="#supported-clis-agents-and-extensions">Supported CLIs, Agents, and Extensions</a> |
-  <a href="#known-issues">Known Issues</a> |
-  <a href="#legacy-mode">Legacy Mode</a>
+  <a href="#install-uninstall">Install/Uninstall</a> |
+  <a href="#extension-usage">Extension Usage</a> |
+  <a href="#note-on-git-usage">Note on Git usage</a>
 </p>
 <p align="center">
 <br>
@@ -31,38 +34,66 @@ This allows them to be run both as a Python package (installed as <b>req</b>, <b
 <p>
 
 
+## Quick Start
 
-## Requirements
-
-- TODO: complete the bulle list with requiremets
+1. **Install the extension** (see [Install](#install)) and restart pi.
+2. **Configure the project** (optional): run `/pi-usereq` to set the documentation directory, unit-tests directory, source directories, static code checkers, enabled tools, git automation, and notifications.
+3. **Write the requirements**: run `/req-write <User Request>` to produce a first SRS draft, or `/req-create` to derive the SRS from the existing source code.
+4. **Implement the source code**: run `/req-implement` to build the source from the requirements, or `/req-cover` to make the minimal changes that cover uncovered requirements.
+5. **Update the documentation**: run `/req-workflow`, `/req-flowchart`, and/or `/req-references` to regenerate the project documentation from the source; `/req-readme` keeps this file aligned with the implementation.
+6. **Iterate**: use `/req-change`, `/req-new`, `/req-fix`, `/req-refactor`, and `/req-check` to evolve requirements and code together.
+7. **Recover** (if a run fails or is interrupted): run `/req-reset` to restore the original base path and remove generated worktrees and branches.
 
 
-## Feature Highlights
-- TODO: complete the bulle list with feature highlights
+## Requirements
 
+- **pi CLI** (`pi.dev`) - the extension runs inside pi; requires `@earendil-works/pi-coding-agent` 0.80.4 or newer (Node.js 22.19+, per the pi CLI requirement).
+- **Git repository** - every `req-*` command runs slash-command-owned git validation: the project must be inside a git work tree, the tracked working tree must be clean, and `HEAD` must resolve (a detached `HEAD` is tolerated; a working branch is recommended because the branch name is embedded in generated worktree names).
+- **Requirements documentation** - the configured `docs-dir` (default `pi-usereq/docs`) must contain the canonical documents required by each command (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`); commands such as `/req-write`, `/req-create`, and `/req-workflow` are the entry points that generate them.
+- **Static code checkers** - the bundled checkers (`pyright`, `ruff`, `eslint`) install automatically through the `postinstall` script; the native C/C++ checkers (`cppcheck`, `clang-format`) require a one-line system install (see [Install](#install)). Default configured languages: C, C++, JavaScript, Python, TypeScript.
 
-## Extension Custom Commands
 
-TODO: complete table with the extension custom commands
+## Feature Highlights
 
-  | Prompt | Description |
-  | --- | --- |
-  | `write` | Produce a *SRS* draft based on the User Request description |
-  | `create` | Write a *Software Requirements Specification* using the project's source code |
-  | `recreate` | Reorganize and update the *Software Requirements Specification* based on source code analysis (preserve requirement IDs) |
-  | `renumber` | Deterministically renumber requirement IDs in the *Software Requirements Specification* without changing requirement text or order |
-  | `analyze` | Produce an analysis report |
-  | `change` | Update the requirements and implement the corresponding changes |
-  | `check` | Run the requirements check |
-  | `cover` | Implement minimal changes to cover uncovered existing requirements |
-  | `fix` | Fix a defect without changing the requirements |
-  | `implement` | Implement source code from requirements (from scratch) |
-  | `new` | Implement a new requirement and the corresponding source code changes |
-  | `refactor` | Perform a refactor without changing the requirements |
-  | `readme` | Write `README.md` from user-visible implementation evidence |
-  | `req-references` | Write a `REFERENCES.md` using the project's source code |
-  | `workflow` | Write a `WORKFLOW.md` using the project's source code |
-  | `flowchart` | Write a `FLOWCHART.md` using the project's source code |
+- **17 slash commands** - 15 prompt-backed `req-*` commands plus the dedicated non-agentic `/req-references` and `/req-reset` commands.
+- **11 built-in agent tools** - token counting, summarization, compression, construct search, and static-check tools for explicit files or for the configured project surface.
+- **Interactive configuration menu** - `/pi-usereq` manages local (`<base-path>/.pi-usereq.json`) and global (`~/.config/pi-usereq/config.json`) configuration with no manual JSON editing required.
+- **Worktree-isolated runs** - prompt-command executions run in an isolated git worktree (created with `<prefix><project>-<branch>-<YYYYMMDDHHMMSS>` names) and are merged back with a stash-assisted fast-forward on success.
+- **Automatic commit guidance** - `AUTO_GIT_COMMIT=enable` (default) injects structured commit instructions (`<TYPE>(<COMPONENT>): <DESCRIPTION> [useReq]`) into every prompt; disabling it forces read-only git behavior and turns worktree orchestration off.
+- **Notifications** - desktop notify command, sound effects (levels `none`/`low`/`mid`/`high`, default `alt+s` toggle) and Pushover push messages on prompt completion, interruption, or failure.
+- **Runtime status bar** - the extension renders its workflow state, current branch, context usage, elapsed time, and sound level in the pi status line.
+- **Debug surface** - config-gated `debug-*` slash commands and a standalone debug harness (`scripts/debug-extension.ts`, `scripts/pi-usereq-debug.sh`) for offline inspection and replay.
+
+
+## Prompts and Agents
+
+Each `req-*` command is invoked as `/req-<name> <User Request>` inside pi. Prompt commands first run git validation and the
+prompt-specific required-document checks, then (when `Auto git commit` and `Git worktree` are enabled) switch the session into an
+isolated worktree, render the bundled prompt with the project context, and on success merge the changes back and leave the
+repository clean. `/req-references` and `/req-reset` are non-agentic: they execute directly without starting an LLM session or
+creating a worktree.
+
+| Command | Description | Required docs |
+| --- | --- | --- |
+| `/req-write` | Produce a *SRS* draft based on the User Request description | none |
+| `/req-create` | Write a *Software Requirements Specification* using the project's source code | none |
+| `/req-recreate` | Reorganize and update the *Software Requirements Specification* based on source code analysis (preserve requirement IDs) | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-renumber` | Deterministically renumber requirement IDs in the *Software Requirements Specification* without changing requirement text or order | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-analyze` | Produce an analysis report | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-change` | Update the requirements and implement the corresponding changes | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-check` | Run the requirements check | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-cover` | Implement minimal changes to cover uncovered existing requirements | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-fix` | Fix a defect without changing the requirements | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-implement` | Implement source code from requirements | `REQUIREMENTS.md` |
+| `/req-new` | Implement a new requirement and the corresponding source code changes | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-refactor` | Perform a refactor without changing the requirements | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-readme` | Write `README.md` from user-visible implementation evidence | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-references` | Write a `REFERENCES.md` using the project's source code (non-agentic, commits the regenerated file) | none |
+| `/req-workflow` | Write a `WORKFLOW.md` using the project's source code | none |
+| `/req-flowchart` | Write a `FLOWCHART.md` using the project's source code | `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md` |
+| `/req-reset` | Reset the req workflow state, restore the base path, and remove generated worktrees and branches (non-agentic) | none |
+
+Bundled prompts substitute project-derived values through `%%` placeholders, including `%%SRC_PATHS%%` (configured source directories), `%%ARGS%%` (command arguments), `%%PROMPT%%` (command name), `%%COMMIT%%` (git commit or read-only instruction), and `%%CONTEXT_FILES%%` (the canonical docs, when the corresponding context-file toggles are enabled in the settings menu).
 
 
 ## Default Workflow
@@ -74,47 +105,48 @@ Click to zoom flowchart image.
 
 ## Project's Documentation
 
-
 ### Project's Tree
 
-TODO: update/rewrite the project tree
-
 ```text
 .
-├── .req/
-│   └── useReq/req files
-├── docs/
-│   ├── FLOWCHART.md
-│   ├── REQUIREMENTS.md
-│   ├── REFERENCES.md
-│   └── WORKFLOW.md
-├── guidelines/
-│   └── User's guidelines
-├── src/
-│   └── Source code
-└── tests/
-    └── Unit tests suite
+├── .pi-usereq.json              # local project configuration (auto-generated)
+├── pi-usereq/                   # configured docs-dir (default)
+│   └── docs/
+│       ├── REQUIREMENTS.md      # Software Requirements Specification (SRS)
+│       ├── WORKFLOW.md          # runtime/execution units and call traces
+│       ├── REFERENCES.md        # symbol index generated from the source
+│       └── FLOWCHART.md         # workflow flowchart (generated on demand)
+├── src/                         # source code
+├── tests/                       # unit tests suite
+├── scripts/                     # debug harness and checker installer
+├── images/                      # project assets (flowchart, logo)
+└── ~/.config/pi-usereq/         # global configuration (outside the repo)
+    └── config.json              # cross-project settings (checkers, git, notifications)
 ```
 
+The documentation directory, unit-tests directory, and source directories are configurable via the
+[settings menu](#extension-usage) (defaults: `pi-usereq/docs`, `tests`, `src`).
+
+
 ## Install/Uninstall
 
 ### Install
 
-Install:
+Install the extension package with the pi CLI:
+
 ```bash
 pi install npm:pi-usereq
 ```
 
-Or via git:
+Or install it directly from the git repository:
+
 ```bash
 pi install git:github.com/Ogekuri/PI-useReq
 ```
 
-Reload Pi.
+Reload pi (restart the session).
 
-Bundled static checkers (`pyright`, `ruff`, `eslint`) install automatically via the
-`postinstall` script. Native checkers (`cppcheck`, `clang-format`) require a one-line
-system install:
+Bundled static checkers (`pyright`, `ruff`, `eslint`) install automatically via the `postinstall` script. Native checkers (`cppcheck`, `clang-format`) require a one-line system install:
 
 - Debian/Ubuntu: `sudo apt install cppcheck clang-format`
 - macOS: `brew install cppcheck clang-format`
@@ -123,33 +155,29 @@ system install:
 
 ### Uninstall
 
-TODO: complete uninstall istructions
+Remove the extension package with the pi CLI (use the same source you installed from):
 
 ```bash
-
+pi remove npm:pi-usereq
 ```
 
-## Quick Start
-
-TODO: complete/reeview with a quick start guide with a complete quick start guide
+Or, if it was installed from git:
 
-1. Install extension, tun pi-dev CLI
-2. Use `/req-write` or `/req-create` to create requirements
-3. Use `/req-implement` to implement source-code from requirements, or `/req-cover` to cover new requirements (documentation).
-4. Use `/req-workflow`, `/req-flowchart`, and/or `/req-references` to update project's documentation.
-5. Start to use `/req-change`, `/req-new`, and `/req-fix`.
+```bash
+pi remove git:github.com/Ogekuri/PI-useReq
+```
 
-## Extension Usage
+Then reload pi. Optionally delete the persisted configuration files: the global `~/.config/pi-usereq/config.json`
+and the project-local `.pi-usereq.json` files.
 
-TODO: document all extension features in details
 
-### Extension Custom Commands
+## Extension Usage
 
-TODO: complete with the extension custom commands full documentation
+> The bulk of the extension capabilities are covered by the [Prompts and Agents](#prompts-and-agents) table; this section documents the tools, the standalone CLI, the settings menu, and the side features.
 
 ### Extension Custom Tools
 
-TODO: complete with the extension custom tools full documentasions
+The extension registers the following agent tools (available to the LLM inside pi). All parameters are exposed through the pi tool-call contract; `FILE` entries may be project-relative or absolute paths. Optional `enableLineNumbers` adds `<n>:` line prefixes to compressed/search output.
 
 - Count tokens and chars for the given files
   `files-tokens FILE [FILE ...]`
@@ -158,54 +186,36 @@ TODO: complete with the extension custom tools full documentasions
   `files-summarize FILE [FILE ...]`
 
 - Generate compressed output for the given files
-  `files-compress FILE [FILE ...]`
+  `files-compress FILE [FILE ...] [enableLineNumbers]`
 
 - Find and extract specific constructs from the given files
-  `files-find TAG PATTERN FILE [FILE ...]`
+  `files-search TAG PATTERN FILE [FILE ...] [enableLineNumbers]`
 
-- Run static analysis on the given files using tools configured in `.req/config.json`
+- Run static analysis on the given files using the checkers configured for their extensions
   `files-static-check FILE [FILE ...]`
 
-- Count tokens and chars for canonical docs files in configured `docs-dir` (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`).
+- Count tokens and chars for the canonical docs in the configured `docs-dir` (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`)
   `tokens`
 
-- Generate LLM summary markdown for source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories.
+- Generate LLM summary markdown for the configured `src-dir` directories
   `summarize`
 
-- Generate compressed output for source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories.  
-  `compress`
-
-- Find and extract specific constructs from source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories.
-  `find TAG PATTERN`
-
-- Run static analysis on source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories (plus configured `tests-dir`, excluding `fixtures/`).
-  `static-check`
-
-- Check repository integrity for the configured git path: clean working tree and valid HEAD.
-  `git-check`
+- Generate `REFERENCES.md` from the configured `src-dir` directories and overwrite `<docs-dir>/REFERENCES.md`
+  `references`
 
-- Check canonical docs presence in configured `docs-dir`: `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`.
-  `docs-check`
+- Generate compressed output for the configured `src-dir` directories
+  `compress [enableLineNumbers]`
 
-- Create an isolated git worktree and branch with the provided name; also copies `.req/`, active provider directories, and `.venv` (when present) into the new worktree context.
-  `git-wt-create WT_NAME`
+- Find and extract specific constructs from the configured `src-dir` directories
+  `search TAG PATTERN [enableLineNumbers]`
 
-- Remove the git worktree and branch identified by name.
-  `git-wt-delete WT_NAME`
-
-- Print the configured `git-path` value from `.req/config.json`; if `.req/config.json` is missing, the command fails with `Error: .req/config.json not found in the project root`.
-  `git-path`
-
-- Print the configured `base-path` value from `.req/config.json`; if `.req/config.json` is missing, the command fails with `Error: .req/config.json not found in the project root`.
-  `get-base-path`
-
-
-- Add `enable-line-numbers` to include `<n>:` prefixes in `files-compress`, `compress`, `files-find`, and `find` output.
+- Run static analysis on the configured `src-dir` plus `tests-dir` selections (excluding `fixtures/`)
+  `static-check`
 
-- Test static check configuration and execution (standalone).
-  `test-static-check {dummy,pylance,ruff,command} [FILES...]`
+The set of startup tools active for a project is configurable through `Enable tools` in the
+[settings menu](#settings-menu-pi-usereq).
 
-#### Supported <TAG> in `find` commands
+#### Supported `<TAG>` in search commands
 
 - **Python**: CLASS, FUNCTION, DECORATOR, IMPORT, VARIABLE
 - **C**: STRUCT, UNION, ENUM, TYPEDEF, MACRO, FUNCTION, IMPORT, VARIABLE
@@ -228,39 +238,89 @@ TODO: complete with the extension custom tools full documentasions
 - **Zig**: FUNCTION, STRUCT, ENUM, UNION, CONSTANT, VARIABLE, IMPORT
 - **Elixir**: MODULE, FUNCTION, PROTOCOL, IMPL, STRUCT, IMPORT
 
+### Standalone CLI
+
+The extension ships a standalone CLI entry point (`src/cli.ts`, runnable with `npm run cli -- <options>`) that mirrors the agent tools for scripting and debugging:
+
+```text
+--files-tokens FILE [FILE ...]
+--files-summarize FILE [FILE ...]
+--files-compress FILE [FILE ...] [--enable-line-numbers] [--verbose]
+--files-find TAG PATTERN FILE [FILE ...] [--enable-line-numbers] [--verbose]
+--files-static-check FILE [FILE ...]
+--summarize [--verbose]
+--compress [--enable-line-numbers] [--verbose]
+--find TAG PATTERN [--enable-line-numbers] [--verbose]
+--tokens
+--static-check
+--test-static-check {dummy,command} [FILES...]
+--enable-static-check LANG=MODULE[,CMD[,PARAM...]]   (repeatable; e.g. --enable-static-check python=command,ruff,check)
+--base <path>        # project base for project-scoped commands
+--here               # use the current directory as project base
+--verbose
+```
+
+Project-scoped commands (`--summarize`, `--compress`, `--tokens`, `--find`, `--static-check`) always target the current project configuration and reject `--base` (use `--here`).
+
+### Settings Menu (`/pi-usereq`)
+
+The interactive configuration menu exposes every user-facing setting; changes are persisted automatically:
+
+- **Documentation directory** — `docs-dir` (default `pi-usereq/docs`) used for the canonical documents.
+- **Unit tests directory** — `tests-dir` (default `tests`).
+- **Source directories** — `src-dir` (default `["src"]`) used by the analysis tools.
+- **Context Files** — toggles to inject `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md` into the prompt context through `%%CONTEXT_FILES%%`.
+- **Auto git commit** — `enable` (default) injects git commit instructions into every prompt; `disable` forces read-only git behavior (`git_read-only.md`) and turns worktree orchestration off.
+- **Git worktree** / **Worktree prefix** — enable/disable prompt-command worktree isolation and set the name prefix (default `PI-useReq-`).
+- **Language static code checkers** — per-language `enable`/`disable` flags and the global `Command`-module checker definitions (view/remove/reset with confirmation).
+- **Enable tools** — the subset of configurable startup tools activated for the project (`files-*` and project tools plus the embedded `read`, `bash`, `edit`, `write` quartet).
+- **Notifications** — command-notify, sound, and Pushover settings with per-event routing (completed/interrupted/failed).
+- **Debug** — local debug logging: log file, log-on-status filter, status-change/workflow-event toggles, enabled tools/prompts, and `Enable debug commands for tools`.
+- **Show local/global configuration** — write the exact config file contents into the editor.
+- **Reset defaults** — restore the default configuration with a confirmation preview.
+
 ### Extension Side Features
 
-TODO: complete with extension side defatures
+#### Sound
 
-#### Sound 
+The extension plays a bundled sound effect when a prompt ends (completed, interrupted, or failed - each event is independently toggleable).
 
-TODO: complete with sound extension feature description
+- Sound levels: `none` → `low` → `mid` → `high`.
+- Default toggle shortcut: `alt+s` (cycles the active runtime level; configurable via `notify-sound-toggle-shortcut`).
+- Each level maps to a configurable shell command; the defaults use `paplay` on the bundled `Soft-high-tech-notification-sound-effect.mp3` with the `%%INSTALLATION_PATH%%` keyword resolved to the installed extension path.
 
-## Note on Git usage
+#### Notifications
 
-TODO: review and rewrite git section according extension features.
+- **Command notify** — a configurable desktop-notification command (`PI_NOTIFY_CMD`) run when the selected prompt-end events occur.
+- **Pushover** — optional Pushover push notifications (`notify-pushover-*`): user key, API token, priority, title, and text template; disabled until both credentials are set.
 
-This section describes the Git behavior when executing the commands provided by the scripts.
+#### Status Bar
 
-- Required state before execution:
-  - Execute commands from a working branch (not in detached HEAD).
-  - Preferably, the working tree should be clean: avoid unintended changes in the repository before starting the scripts.
-  - Save all files and verify that you are in the correct project directory.
-  - **IMPORTANT:** in clude on repository the directory configured in the extension.
-
-- What the scripts do to the repository:
-  - The scripts may modify, create, or remove files in the working tree (files on disk).
-  - They do not modify Git history (HEAD), branches, or tags automatically.
-  - The index (staging area) and history remain unchanged until the user manually performs staging/commit operations.
-
-- How to commit (recommended practice):
-  - Review changes generated by the scripts before including them in a commit.
-  - Manually add files to commit using `git add <file...>`.
-  - Execute the commit with a structured message, for example:
-    `git commit -m "change(<COMPONENT>): <SHORT-DESCRIPTION> [<DATE>]"`.
-  - Staging and commit operations are under the user's control; the scripts do not perform automatic commits or update Git references.
-
-- Practical warnings:
-  - Do not use destructive commands (e.g., `git reset --hard`, `git clean -fd`) to "clean" the repository without verifying the impact.
-  - If you prefer to isolate changes, execute commands in a branch or a copy of the repository.
+The extension renders a status field in the pi status line showing: extension identity, workflow state (`idle`/`checking`/`running`/`merging`/`error`), current branch, context usage, elapsed run time, and the active sound level.
+
+#### Debug
+
+- Config-gated slash commands that run the project tools and write the output into the editor: `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, `debug-tokens`.
+- Standalone debug harness: `scripts/pi-usereq-debug.sh` (bash wrapper) and `scripts/debug-extension.ts` with subcommands `inspect`, `session-start`, `command`, `tool`, and `sdk-smoke`.
+- Debug logging writes to the configured `DEBUG_LOG_FILE`, filtered by prompt/tool name and workflow status.
 
+
+## Note on Git usage
+
+This section describes the Git behavior of the `req-*` commands. The commands own their git workflow: validation happens before dispatch and finalization happens at the end of each run.
+
+- Required state before execution:
+  - The project must be inside a git work tree with a **clean tracked working tree** (`git status --porcelain` empty; the configured debug-log file is ignored by the validation).
+  - `HEAD` must resolve. A working branch is recommended: the current branch name is embedded in the generated worktree names (it falls back to `unknown` on a detached `HEAD`).
+  - All files must be saved and you must be in the correct project directory.
+
+- What the commands do to the repository:
+  - Each `req-*` prompt command runs git validation and the required-document checks, then (when `Auto git commit` and `Git worktree` are enabled) creates an isolated **git worktree and branch** named `<GIT_WORKTREE_PREFIX><project>-<branch>-<YYYYMMDDHHMMSS>` (default prefix `PI-useReq-`), switches the session into it, and executes the prompt there.
+  - On success the extension restores the original `base-path` session, applies a stash-assisted fast-forward merge of the worktree branch, and deletes the worktree and branch.
+  - On failure or interruption the worktree and branch are **kept** and the workflow is parked in the `error` state so the produced artifacts can be inspected or recovered: run `/req-reset` to restore the original base path and force-remove the generated worktrees and branches.
+  - With `Auto git commit = enable` (default), every prompt receives structured commit instructions and commits follow the message template `<TYPE>(<COMPONENT>)<BREAKING>: <DESCRIPTION> [useReq]`. With `Auto git commit = disable`, prompts receive a read-only git restriction and worktree orchestration is forced off.
+  - The extension never rewrites history and never runs destructive cleanup on your behalf.
+
+- Recommended practice:
+  - Review the changes produced by each command before pushing them.
+  - Do not use destructive commands (e.g., `git reset --hard`, `git clean -fd`) to "clean" the repository without verifying the impact; prefer `/req-reset` for worktree cleanup after failed runs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.51.0",
+  "version": "0.56.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"
@@ -32,9 +32,9 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.80.4",
+    "@earendil-works/pi-coding-agent": "^0.80.4",
+    "@earendil-works/pi-tui": "^0.80.4",
     "@sinclair/typebox": "^0.34.49"
   },
   "dependencies": {
@@ -56,6 +56,7 @@
     "protobufjs@7.5.4": true,
     "esbuild": true,
     "koffi": true,
-    "protobufjs": true
+    "protobufjs": true,
+    "@google/genai": true
   }
 }

package/scripts/lib/sdk-smoke.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Implements SDK-parity probing and comparison for the standalone debug harness.
- * @details Dynamically loads the official pi SDK when available, inventories extension-owned commands and tools from the runtime surface, normalizes provenance metadata, and compares the result against the offline recorder snapshot. Runtime is O(c + t) in command and tool counts plus the cost of SDK session creation. Side effects are limited to dynamic module loading, optional SDK-managed filesystem reads, and any extension-owned startup behavior triggered by the official runtime.
+ * @details Dynamically loads the official pi SDK when available, inventories extension-owned commands and tools from the runtime surface, passes the 0.80.4+ `authPath` and `modelsPath` `createAgentSession` options, probes support for the new 0.80.4+ event surface, normalizes provenance metadata, and compares the result against the offline recorder snapshot. Runtime is O(c + t + e) in command, tool, and probed-event counts plus the cost of SDK session creation. Side effects are limited to dynamic module loading, optional SDK-managed filesystem reads, and any extension-owned startup behavior triggered by the official runtime.
  */
 
 import path from "node:path";
@@ -53,6 +53,7 @@ export interface SdkContractSnapshot {
   tools: NormalizedToolRecord[];
   activeTools: string[];
   runtimeShape: string;
+  supportedEvents: string[];
 }
 
 /**
@@ -96,6 +97,60 @@ interface SdkApiLike {
   getActiveTools?: () => string[];
 }
 
+/**
+ * @brief Lists the 0.80.4+ pi event names probed for host support by the SDK parity probe.
+ * @details The probe registers a no-op handler for each new-event name on the extension runtime and treats a returned unsubscribe function as proof that the host emits the event, mirroring the capability contract used by prompt-end finalization. Lookup complexity is O(1).
+ * @satisfies REQ-356
+ */
+const PI_EVENT_SURFACE_PROBE_NAMES = [
+  "agent_settled",
+  "project_trust",
+  "session_info_changed",
+  "session_compact_failed",
+  "before_provider_headers",
+  "after_provider_response",
+  "ui_prompt_start",
+  "ui_prompt_end",
+  "thinking_level_select",
+] as const;
+
+/**
+ * @brief Probes the official SDK runtime for support of the 0.80.4+ pi event surface.
+ * @details Locates an object exposing an `on(...)` registration method on the `extensionsResult.runtime` surface, registers a no-op handler for each new-event name, and records those whose registration returns an unsubscribe function (the 0.80.4+ contract). Handlers are unsubscribed immediately after the probe and unsupported or unavailable surfaces yield an empty list. Runtime is O(e) in probed event count. No external state is mutated.
+ * @param[in] createAgentSessionResult {unknown} Raw `createAgentSession(...)` result.
+ * @return {string[]} Names of supported new pi events, possibly empty.
+ * @satisfies REQ-356
+ */
+function probePiEventSurface(createAgentSessionResult: unknown): string[] {
+  if (!createAgentSessionResult || typeof createAgentSessionResult !== "object") {
+    return [];
+  }
+  const candidateRoot = createAgentSessionResult as Record<string, unknown>;
+  const runtime = (candidateRoot.extensionsResult as Record<string, unknown> | undefined)?.runtime;
+  const host = runtime && typeof runtime === "object" ? runtime as Record<string, unknown> : undefined;
+  const onMethod = host?.on;
+  if (typeof onMethod !== "function") {
+    return [];
+  }
+  const probeHost = host as unknown as {
+    on(event: string, handler: (event: unknown, ctx: unknown) => unknown): unknown;
+  };
+  const supported: string[] = [];
+  for (const eventName of PI_EVENT_SURFACE_PROBE_NAMES) {
+    let unsubscribe: unknown;
+    try {
+      unsubscribe = probeHost.on(eventName, () => undefined);
+    } catch {
+      unsubscribe = undefined;
+    }
+    if (typeof unsubscribe === "function") {
+      supported.push(eventName);
+      (unsubscribe as () => void)();
+    }
+  }
+  return supported;
+}
+
 /**
  * @brief Normalizes one path relative to the requested project root.
  * @details Converts absolute paths under the project root to slash-normalized relative paths and leaves non-project or pseudo-path values unchanged. Runtime is O(p) in path length. No external state is mutated.
@@ -414,18 +469,18 @@ export function buildParityReport(offline: OfflineContractSnapshot, sdk: SdkCont
 
 /**
  * @brief Loads the official pi SDK runtime and extracts the extension-owned command and tool inventories.
- * @details Dynamically imports `@mariozechner/pi-coding-agent`, creates a `DefaultResourceLoader` with the requested extension path, creates an SDK session, extracts inventory methods from the returned runtime surface, and filters to extension-owned commands and tools only. Runtime is dominated by SDK startup. Side effects include SDK-managed resource loading and extension startup behavior.
+ * @details Dynamically imports `@earendil-works/pi-coding-agent`, creates a `DefaultResourceLoader` with the requested extension path, creates an SDK session with the 0.80.4+ `authPath` and `modelsPath` options, extracts inventory methods from the returned runtime surface, probes support for the new 0.80.4+ event surface, and filters to extension-owned commands and tools only. Runtime is dominated by SDK startup. Side effects include SDK-managed resource loading and extension startup behavior.
  * @param[in] cwd {string | undefined} Requested working directory.
  * @param[in] extensionPath {string | undefined} Requested extension entry path.
  * @return {Promise<SdkContractSnapshot>} Normalized SDK inventory snapshot.
  * @throws {ReqError} Throws when the SDK package is unavailable, runtime extraction fails, or session creation fails.
- * @satisfies REQ-050, REQ-056, REQ-058
+ * @satisfies REQ-050, REQ-056, REQ-058, REQ-356
  */
 export async function probeSdkRuntime(cwd?: string, extensionPath?: string): Promise<SdkContractSnapshot> {
   const paths = resolveHarnessPaths(cwd, extensionPath);
   let sdkModule: Record<string, unknown>;
   try {
-    sdkModule = await import("@mariozechner/pi-coding-agent") as Record<string, unknown>;
+    sdkModule = await import("@earendil-works/pi-coding-agent") as Record<string, unknown>;
   } catch (error) {
     throw new ReqError(`Error: SDK parity loading failed: ${error instanceof Error ? error.message : String(error)}`, 1);
   }
@@ -454,6 +509,8 @@ export async function probeSdkRuntime(cwd?: string, extensionPath?: string): Pro
       resourceLoader,
       sessionManager: SessionManager.inMemory(),
       settingsManager: typeof SettingsManager?.inMemory === "function" ? SettingsManager.inMemory({}) : undefined,
+      authPath: path.join(paths.cwd, ".pi-usereq-agent-auth.json"),
+      modelsPath: path.join(paths.cwd, ".pi-usereq-agent-models.json"),
     });
   } catch (error) {
     throw new ReqError(`Error: SDK parity loading failed: ${error instanceof Error ? error.message : String(error)}`, 1);
@@ -485,6 +542,7 @@ export async function probeSdkRuntime(cwd?: string, extensionPath?: string): Pro
     tools,
     activeTools,
     runtimeShape: extracted.runtimeShape,
+    supportedEvents: probePiEventSurface(createAgentSessionResult),
   };
 }
 

package/src/core/extension-status.ts

@@ -12,7 +12,7 @@ import type {
   ContextUsage,
   ExtensionContext,
   ThemeColor,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
 import type { PiNotifyOutcome, PiNotifySoundLevel } from "./pi-notify.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
@@ -126,6 +126,7 @@ export interface PiUsereqStatusState {
   pendingPromptRequest: PiUsereqPromptRequest | undefined;
   activePromptRequest: PiUsereqPromptRequest | undefined;
   pendingFinalizationOutcome: PiNotifyOutcome | undefined;
+  agentSettledEventSupported: boolean | undefined;
 }
 
 /**
@@ -683,6 +684,7 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
       pendingPromptRequest: undefined,
       activePromptRequest: undefined,
       pendingFinalizationOutcome: undefined,
+      agentSettledEventSupported: undefined,
     },
     tickHandle: undefined,
   };

package/src/core/pi-notify.ts

@@ -8,7 +8,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import * as https from "node:https";
-import type { AgentEndEvent } from "@mariozechner/pi-coding-agent";
+import type { AgentEndEvent } from "@earendil-works/pi-coding-agent";
 import { getInstallationPath, normalizePathSlashes } from "./path-context.js";
 import type { UseReqConfig } from "./config.js";
 

package/src/core/prompt-command-runtime.ts

@@ -28,7 +28,7 @@ import {
   setRuntimeGitPath,
   setRuntimeWorktreePathState,
 } from "./path-context.js";
-import { SessionManager } from "@mariozechner/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
 import {
   clearPersistedPromptCommandSessionContext,
@@ -1945,11 +1945,11 @@ export async function finalizePromptCommandExecution(
 /**
  * @brief Maps one `agent_end` payload into the canonical prompt-worktree finalization outcome.
  * @details Delegates to the shared notification outcome classifier so worktree merge and fork-session retention decisions stay aligned with prompt-end notification routing. Runtime is O(m) in assistant message count. No external state is mutated.
- * @param[in] event {Pick<import("@mariozechner/pi-coding-agent").AgentEndEvent, "messages">} Agent-end payload subset.
+ * @param[in] event {Pick<import("@earendil-works/pi-coding-agent").AgentEndEvent, "messages">} Agent-end payload subset.
  * @return {PiNotifyOutcome} Canonical prompt-end outcome.
  */
 export function classifyPromptCommandOutcome(
-  event: Pick<import("@mariozechner/pi-coding-agent").AgentEndEvent, "messages">,
+  event: Pick<import("@earendil-works/pi-coding-agent").AgentEndEvent, "messages">,
 ): PiNotifyOutcome {
   return classifyPiNotifyOutcome(event);
 }

package/src/core/prompts.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Renders bundled pi-usereq prompts for the current project context.
- * @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for manifest checks and bundled prompt loading.
+ * @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for the coding-agent-docs directory check and bundled prompt loading.
  */
 
 import fs from "node:fs";
@@ -61,8 +61,8 @@ const PI_DEV_AWARE_PROMPT_NAMES = new Set<string>([
   "refactor",
 ]);
 /**
- * @brief Stores the repository-relative pi.dev manifest path used in prompt guidance.
- * @details The constant lets rendered prompts cite the authoritative documentation manifest with a deterministic path. Lookup complexity is O(1).
+ * @brief Stores the repository-relative optional pi.dev manifest path used in prompt guidance.
+ * @details The constant lets rendered prompts cite the authoritative documentation manifest when present with a deterministic path. The governance block is not gated on this file; it is an optional contract source. Lookup complexity is O(1).
  */
 const PI_DEV_MANIFEST_PROMPT_PATH = "docs/pi.dev/agent-document-manifest.json";
 /**
@@ -82,37 +82,36 @@ const PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH = `${PI_DEV_DOCS_PROMPT_PATH}/coding-
 const PI_DEV_SOURCE_PROMPT_PATH = "pi.dev-src/pi-mono";
 /**
  * @brief Defines the injected pi.dev governance guidance block.
- * @details The block requires read-only handling for documentation and pi client sources, manifest-first review, coding-agent-document compliance, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
+ * @details The block requires read-only handling for documentation and pi client sources, coding-agent-document review, coding-agent-document compliance, optional manifest-referenced document handling, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
  * @satisfies REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
 const PI_DEV_CONFORMANCE_BLOCK = [
   "- Treat every path under `docs/` as read-only; do NOT modify "
-    + `\`${PI_DEV_MANIFEST_PROMPT_PATH}\` or any other documentation file.`,
+    + "any documentation file, including those under `docs/pi.dev/`.",
   "- Treat every path under `pi.dev-src/` as read-only; do NOT modify "
     + `\`${PI_DEV_SOURCE_PROMPT_PATH}\` or any other pi client source.`,
   "- If the task creates or modifies software that interfaces with the "
-    + `pi.dev CLI, read \`${PI_DEV_MANIFEST_PROMPT_PATH}\` and every `
-    + "document path it references before analysis, implementation, "
-    + "verification, or bug fixing.",
-  `- Treat \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` and documents `
-    + `referenced by \`${PI_DEV_MANIFEST_PROMPT_PATH}\` as the `
+    + `pi.dev CLI, review \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` `
+    + "before analysis, implementation, verification, or bug fixing.",
+  `- Treat \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` as the `
     + "authoritative read-only interface contract; new or modified "
     + "pi.dev CLI integrations MUST comply with the APIs they describe.",
-  `- Treat manifest document paths as relative to \`${PI_DEV_DOCS_PROMPT_PATH}/\`.`,
-  "- If manifest or "
-    + `\`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` guidance is `
+  `- If \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` guidance is `
     + "ambiguous for extension-to-pi-client interface behavior, validate "
     + `the produced source code by analyzing \`${PI_DEV_SOURCE_PROMPT_PATH}\`.`,
   "- For bug fixes or problem resolution influenced by extension-to-pi-client "
     + "interface implementations, validate the produced source code by "
     + `analyzing \`${PI_DEV_SOURCE_PROMPT_PATH}\`.`,
+  `- If \`${PI_DEV_MANIFEST_PROMPT_PATH}\` exists under \`${PI_DEV_DOCS_PROMPT_PATH}/\`, `
+    + "treat every document path it references as part of the read-only "
+    + "interface contract.",
 ].join("\n");
 
 /**
  * @brief Builds the conditional pi.dev governance block for one rendered prompt.
- * @details Emits the manifest-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the pi.dev manifest. Time complexity O(1). No filesystem writes.
+ * @details Emits the coding-agent-document-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the `docs/pi.dev/coding-agent-docs/` directory; the manifest file is optional and its absence does not suppress the block. Time complexity O(1). No filesystem writes.
  * @param[in] promptName {string} Bundled prompt identifier.
- * @param[in] projectBase {string} Absolute project root used for manifest existence checks.
+ * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Markdown bullet block or the empty string when injection is not applicable.
  * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
@@ -120,8 +119,8 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
   if (!PI_DEV_AWARE_PROMPT_NAMES.has(promptName)) {
     return "";
   }
-  const manifestPath = path.join(projectBase, PI_DEV_MANIFEST_PROMPT_PATH);
-  if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
+  const codingAgentDocsPath = path.join(projectBase, PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH);
+  if (!fs.existsSync(codingAgentDocsPath) || !fs.statSync(codingAgentDocsPath).isDirectory()) {
     return "";
   }
   return PI_DEV_CONFORMANCE_BLOCK;
@@ -132,7 +131,7 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
  * @details Inserts the block immediately after the `## Behavior` heading so downstream agents evaluate the rule before workflow steps. Leaves prompts unchanged when no behavior section exists or the block is already present. Time complexity O(n).
  * @param[in] text {string} Prompt markdown after placeholder replacement.
  * @param[in] promptName {string} Bundled prompt identifier.
- * @param[in] projectBase {string} Absolute project root used for manifest existence checks.
+ * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Prompt markdown with zero or one injected conformance block.
  * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */

package/src/core/req-references-command.ts

@@ -116,6 +116,47 @@ function getGitAddTargetPath(gitRoot: string, absolutePath: string): string {
   return relativePath.split(path.sep).join("/");
 }
 
+/**
+ * @brief Detects whether the git index holds staged differences for the given target paths.
+ * @details Executes `git diff --cached --quiet -- <paths>`; exit code `1` signals at least one staged difference, exit code `0` signals no staged difference for the target paths, and any other status or spawn failure is converted into a deterministic `ReqError`. Runtime is dominated by one git subprocess. Side effects include subprocess creation. No index or worktree mutation occurs.
+ * @param[in] gitRoot {string} Absolute git root path.
+ * @param[in] targetPaths {string[]} Git-add target paths inspected in the cached index.
+ * @return {boolean} `true` when at least one staged difference exists for the target paths.
+ * @throws {ReqError} Throws when staged-difference inspection fails.
+ * @satisfies REQ-357
+ */
+function hasStagedChangesForPaths(gitRoot: string, targetPaths: string[]): boolean {
+  const diffResult = runCapture(["git", "diff", "--cached", "--quiet", "--", ...targetPaths], gitRoot);
+  if (diffResult.error || diffResult.status === null || diffResult.status < 0 || diffResult.status > 1) {
+    throw new ReqError("ERROR: Unable to inspect staged changes before git commit.", 1);
+  }
+  return diffResult.status === 1;
+}
+
+/**
+ * @brief Executes one guarded `git commit` invocation for the staged target paths.
+ * @details Runs a staged-changes precheck against the cached index and returns without creating a commit when no staged difference exists for the target paths, preventing empty-commit failures such as `nothing to commit, working tree clean`. When a staged difference exists, delegates to `git commit -m <commitMessage>` and converts any non-zero result into a deterministic `ReqError`. Runtime is dominated by up to two git subprocesses. Side effects include subprocess creation and conditional commit creation.
+ * @param[in] gitRoot {string} Absolute git root path.
+ * @param[in] targetPaths {string[]} Git-add target paths inspected by the staged-changes precheck.
+ * @param[in] commitMessage {string} Commit message used when a staged difference exists.
+ * @return {void} No return value.
+ * @throws {ReqError} Throws when staged-difference inspection or commit creation fails.
+ * @satisfies REQ-357, REQ-358
+ */
+function runGuardedGitCommit(gitRoot: string, targetPaths: string[], commitMessage: string): void {
+  if (!hasStagedChangesForPaths(gitRoot, targetPaths)) {
+    return;
+  }
+  const commitResult = runCapture(["git", "commit", "-m", commitMessage], gitRoot);
+  if (commitResult.error || commitResult.status !== 0) {
+    const diagnostic = commitResult.stderr.trim()
+      || commitResult.stdout.trim()
+      || commitResult.error?.message
+      || "unknown error";
+    throw new ReqError(`ERROR: git commit failed: ${diagnostic}`, 1);
+  }
+}
+
 /**
  * @brief Prepares the specialized `req-references` execution plan.
  * @details Reuses slash-command-owned git validation, resolves the configured references document path, and returns the fixed commit metadata consumed by the direct-write workflow. Runtime is dominated by git validation subprocesses. Side effects include subprocess creation delegated through `validatePromptGitState(...)`.
@@ -142,12 +183,12 @@ export function prepareReqReferencesCommandExecution(
 
 /**
  * @brief Executes the specialized `req-references` direct-write workflow.
- * @details Regenerates `REFERENCES.md` through the same source-summary path used by the `references` tool, stages only the target file, creates the fixed-message commit, and verifies that no residual git-status rows remain after ignored extension-owned debug artifacts are filtered out. Runtime is dominated by summary generation plus three git subprocesses. Side effects include documentation writes, index mutation, commit creation, and subprocess creation.
+ * @details Regenerates `REFERENCES.md` through the same source-summary path used by the `references` tool, stages only the target file, creates the fixed-message commit through the guarded commit helper whenever a staged difference exists, and verifies that no residual git-status rows remain after ignored extension-owned debug artifacts are filtered out. Runtime is dominated by summary generation plus two to four git subprocesses. Side effects include documentation writes, index mutation, conditional commit creation, and subprocess creation.
  * @param[in] plan {ReqReferencesCommandPlan} Prepared direct-write execution plan.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {void} No return value.
- * @throws {ReqError} Throws when reference generation, staging, commit creation, or cleanliness verification fails.
- * @satisfies REQ-300, REQ-301, REQ-302, REQ-303
+ * @throws {ReqError} Throws when reference generation, staging, guarded commit creation, or cleanliness verification fails.
+ * @satisfies REQ-300, REQ-301, REQ-302, REQ-303, REQ-357, REQ-358
  */
 export function executeReqReferencesCommandExecution(
   plan: ReqReferencesCommandPlan,
@@ -160,14 +201,7 @@ export function executeReqReferencesCommandExecution(
     const diagnostic = addResult.stderr.trim() || addResult.error?.message || "unknown error";
     throw new ReqError(`ERROR: git add failed for ${addTargetPath}: ${diagnostic}`, 1);
   }
-  const commitResult = runCapture(["git", "commit", "-m", plan.commitMessage], plan.gitPath);
-  if (commitResult.error || commitResult.status !== 0) {
-    const diagnostic = commitResult.stderr.trim()
-      || commitResult.stdout.trim()
-      || commitResult.error?.message
-      || "unknown error";
-    throw new ReqError(`ERROR: git commit failed: ${diagnostic}`, 1);
-  }
+  runGuardedGitCommit(plan.gitPath, [addTargetPath], plan.commitMessage);
   const residualStatusLines = listResidualGitStatusLines(plan.basePath, plan.gitPath, config);
   if (residualStatusLines.length > 0) {
     throw new ReqError("ERROR: Git repository is not clean after req-references commit.", 1);

package/src/core/settings-menu.ts

@@ -4,8 +4,8 @@
  * @details Wraps `SettingsList` in one extension-command helper that exposes right-aligned current values, built-in circular scrolling, bottom-line descriptions, and a deterministic bridge for offline test harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
  */
 
-import { getSettingsListTheme, type ThemeColor, type ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import { Container, SettingsList, Text, type Component, type SettingItem, type SettingsListTheme } from "@mariozechner/pi-tui";
+import { getSettingsListTheme, type ThemeColor, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Text, type Component, type SettingItem, type SettingsListTheme } from "@earendil-works/pi-tui";
 
 /**
  * @brief Describes one selectable pi-usereq settings-menu choice.

package/src/index.ts

@@ -18,8 +18,8 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
   ToolInfo,
-} from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import {
   buildMonolithicToolExecuteResult,
@@ -153,6 +153,7 @@ import {
   setPiUsereqWorkflowState,
   shouldPreservePromptCommandStateOnShutdown,
   updateExtensionStatus,
+  type PiUsereqPromptRequest,
   type PiUsereqStatusController,
   type PiUsereqStatusHookName,
 } from "./core/extension-status.js";
@@ -1247,9 +1248,138 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
   pi.setActiveTools(allTools.map((tool) => tool.name).filter((toolName) => nextActive.has(toolName)));
 }
 
+/**
+ * @brief Probes whether the running pi host emits the `agent_settled` event and caches the result on the status controller state.
+ * @details The 0.80.4+ `ExtensionAPI.on(...)` contract returns an unsubscribe function, and `agent_settled` is introduced in that same release; therefore a registration that returns a callable proves the host supports the event, while a `void` registration means a legacy host that never emits it. The probe registers a no-op handler once per status controller, unsubscribes it when the new contract returns a function, and caches the boolean so all later lookups are O(1). No external state is retained beyond the controller-scoped cached boolean.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller that caches the probed capability.
+ * @param[in] pi {ExtensionAPI} Active extension API instance used to probe event registration.
+ * @return {boolean} `true` when the host emits `agent_settled`, `false` on legacy hosts.
+ * @satisfies REQ-354, REQ-355
+ */
+function isPiAgentSettledEventSupported(
+  statusController: PiUsereqStatusController,
+  pi: ExtensionAPI,
+): boolean {
+  if (statusController.state.agentSettledEventSupported !== undefined) {
+    return statusController.state.agentSettledEventSupported;
+  }
+  const probeHost = pi as ExtensionAPI & {
+    on(event: string, handler: (event: unknown, ctx: unknown) => unknown): unknown;
+  };
+  const registration = probeHost.on("agent_settled", () => undefined);
+  const supported = typeof registration === "function";
+  if (supported) {
+    (registration as () => void)();
+  }
+  statusController.state.agentSettledEventSupported = supported;
+  return supported;
+}
+
+/**
+ * @brief Finalizes a matched successful worktree-backed prompt at the current lifecycle point.
+ * @details Executes the deferred stash-assisted merge, transcript preservation, base-path restore, and worktree plus branch deletion through `finalizePromptCommandExecution(...)`, surfaces `error` or warning-only notifications, clears the pending finalization outcome plus prompt state, and transitions workflow state through `merging` to `idle`. Reused by the `agent_settled` handler on 0.80.4+ hosts and directly by the `agent_end` fallback on legacy hosts that never emit `agent_settled`. Runtime is dominated by git finalization. Side effects include branch merges, worktree deletion, notifications, and workflow-state transitions.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller whose pending and active prompt state is cleared.
+ * @param[in] promptRequest {PiUsereqPromptRequest} Matched successful worktree-backed prompt execution plan.
+ * @param[in] ctx {ExtensionContext} Active extension context used for finalization and notifications.
+ * @return {Promise<void>} Promise resolved when finalization and state transitions complete.
+ * @satisfies REQ-208, REQ-228, REQ-229, REQ-230, REQ-282, REQ-291, REQ-292, REQ-354, REQ-355
+ */
+async function finalizeMatchedPromptSuccess(
+  statusController: PiUsereqStatusController,
+  promptRequest: PiUsereqPromptRequest,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const debugConfig = statusController.config;
+  let promptContext = ctx;
+  let finalization:
+    | {
+      mergeAttempted: boolean;
+      mergeSucceeded: boolean;
+      cleanupSucceeded: boolean;
+      errorMessage?: string;
+      warningMessage?: string;
+      activeContext?: unknown;
+    }
+    | undefined;
+  try {
+    finalization = await finalizePromptCommandExecution(
+      promptRequest,
+      promptContext,
+      debugConfig
+        ? { config: debugConfig, workflowState: statusController.state.workflowState }
+        : undefined,
+    );
+    promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
+  } catch (error) {
+    promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
+    let errorMessage = error instanceof Error ? error.message : String(error);
+    let cleanupSucceeded = false;
+    try {
+      promptContext = (await restorePromptCommandExecution(
+        promptRequest,
+        promptContext,
+        debugConfig
+          ? { config: debugConfig, workflowState: statusController.state.workflowState }
+          : undefined,
+      ) ?? promptContext) as typeof ctx;
+      cleanupSucceeded = true;
+    } catch (restoreError) {
+      promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
+      errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
+    }
+    finalization = {
+      mergeAttempted: false,
+      mergeSucceeded: false,
+      cleanupSucceeded,
+      errorMessage,
+    };
+  }
+  if (
+    finalization.errorMessage
+    && (!finalization.cleanupSucceeded || !finalization.mergeSucceeded)
+  ) {
+    if (debugConfig) {
+      transitionPromptWorkflowState(
+        statusController,
+        promptContext,
+        promptRequest.basePath,
+        debugConfig,
+        promptRequest.promptName,
+        "error",
+      );
+    } else {
+      setPiUsereqWorkflowState(statusController, "error", promptContext);
+    }
+    notifyContextSafely(promptContext, finalization.errorMessage, "error");
+  }
+  if (
+    finalization.warningMessage
+    && finalization.cleanupSucceeded
+    && finalization.mergeSucceeded
+    && !finalization.errorMessage
+  ) {
+    notifyContextSafely(promptContext, finalization.warningMessage, "info");
+  }
+  statusController.state.pendingFinalizationOutcome = undefined;
+  statusController.state.pendingPromptRequest = undefined;
+  statusController.state.activePromptRequest = undefined;
+  if (debugConfig) {
+    transitionPromptWorkflowState(
+      statusController,
+      promptContext,
+      promptRequest.basePath,
+      debugConfig,
+      promptRequest.promptName,
+      "idle",
+    );
+  } else {
+    setPiUsereqWorkflowState(statusController, "idle", promptContext);
+  }
+}
+
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` because the pi 0.67.1+ `switchSession` implementation awaits the active agent run to become idle and would deadlock inside `agent_end`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_settled` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful closure handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
@@ -1373,24 +1503,36 @@ async function handleExtensionStatusEvent(
         );
       }
       if (shouldFinalizeMatchedSuccess) {
-        // Defer the restore switch, merge, and worktree deletion to
-        // `agent_settled`. The pi 0.67.1+ `switchSession` implementation
-        // awaits the active agent run to become idle before replacing the
-        // session, and that idle transition only happens at `agent_settled`.
-        // Calling `switchSession` here would deadlock the `agent_end` handler
-        // and leave the workflow parked in `merging` forever.
-        statusController.state.pendingFinalizationOutcome = outcome;
-        if (debugConfig) {
-          transitionPromptWorkflowState(
+        if (isPiAgentSettledEventSupported(statusController, pi)) {
+          // Defer the restore switch, merge, and worktree deletion to
+          // `agent_settled`. The pi 0.80.4+ `switchSession` implementation
+          // awaits the active agent run to become idle before replacing the
+          // session, and that idle transition only happens at `agent_settled`.
+          // Calling `switchSession` here would deadlock the `agent_end` handler
+          // and leave the workflow parked in `merging` forever.
+          statusController.state.pendingFinalizationOutcome = outcome;
+          if (debugConfig) {
+            transitionPromptWorkflowState(
+              statusController,
+              promptContext,
+              activePromptRequest.basePath,
+              debugConfig,
+              activePromptRequest.promptName,
+              "merging",
+            );
+          } else {
+            setPiUsereqWorkflowState(statusController, "merging", promptContext);
+          }
+        } else {
+          // Legacy hosts never emit `agent_settled`, so no idle-waiting
+          // `switchSession` deadlock exists; finalize the matched success
+          // directly at `agent_end` to avoid parking in `merging` forever.
+          statusController.state.pendingFinalizationOutcome = outcome;
+          await finalizeMatchedPromptSuccess(
             statusController,
+            activePromptRequest,
             promptContext,
-            activePromptRequest.basePath,
-            debugConfig,
-            activePromptRequest.promptName,
-            "merging",
           );
-        } else {
-          setPiUsereqWorkflowState(statusController, "merging", promptContext);
         }
       } else if (closureFailureMessage !== undefined) {
         // Worktree-backed run that ended interrupted, failed, aborted, or
@@ -1464,92 +1606,7 @@ async function handleExtensionStatusEvent(
       && settledPromptRequest.worktreeDir !== undefined
       && pendingOutcome === "completed"
     ) {
-      const debugConfig = statusController.config;
-      let promptContext = ctx;
-      let finalization:
-        | {
-          mergeAttempted: boolean;
-          mergeSucceeded: boolean;
-          cleanupSucceeded: boolean;
-          errorMessage?: string;
-          warningMessage?: string;
-          activeContext?: unknown;
-        }
-        | undefined;
-      try {
-        finalization = await finalizePromptCommandExecution(
-          settledPromptRequest,
-          promptContext,
-          debugConfig
-            ? { config: debugConfig, workflowState: statusController.state.workflowState }
-            : undefined,
-        );
-        promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
-      } catch (error) {
-        promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
-        let errorMessage = error instanceof Error ? error.message : String(error);
-        let cleanupSucceeded = false;
-        try {
-          promptContext = (await restorePromptCommandExecution(
-            settledPromptRequest,
-            promptContext,
-            debugConfig
-              ? { config: debugConfig, workflowState: statusController.state.workflowState }
-              : undefined,
-          ) ?? promptContext) as typeof ctx;
-          cleanupSucceeded = true;
-        } catch (restoreError) {
-          promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
-          errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
-        }
-        finalization = {
-          mergeAttempted: false,
-          mergeSucceeded: false,
-          cleanupSucceeded,
-          errorMessage,
-        };
-      }
-      if (
-        finalization.errorMessage
-        && (!finalization.cleanupSucceeded || !finalization.mergeSucceeded)
-      ) {
-        if (debugConfig) {
-          transitionPromptWorkflowState(
-            statusController,
-            promptContext,
-            settledPromptRequest.basePath,
-            debugConfig,
-            settledPromptRequest.promptName,
-            "error",
-          );
-        } else {
-          setPiUsereqWorkflowState(statusController, "error", promptContext);
-        }
-        notifyContextSafely(promptContext, finalization.errorMessage, "error");
-      }
-      if (
-        finalization.warningMessage
-        && finalization.cleanupSucceeded
-        && finalization.mergeSucceeded
-        && !finalization.errorMessage
-      ) {
-        notifyContextSafely(promptContext, finalization.warningMessage, "info");
-      }
-      statusController.state.pendingFinalizationOutcome = undefined;
-      statusController.state.pendingPromptRequest = undefined;
-      statusController.state.activePromptRequest = undefined;
-      if (debugConfig) {
-        transitionPromptWorkflowState(
-          statusController,
-          promptContext,
-          settledPromptRequest.basePath,
-          debugConfig,
-          settledPromptRequest.promptName,
-          "idle",
-        );
-      } else {
-        setPiUsereqWorkflowState(statusController, "idle", promptContext);
-      }
+      await finalizeMatchedPromptSuccess(statusController, settledPromptRequest, ctx);
     }
   }
   if (hookName === "session_shutdown") {