Control automatic handoff availability

CHANGELOG.md

@@ -9,8 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Added `handoff.automaticEnabled` raw settings support with JSON boolean values. Missing settings default to automatic handoff enabled; `false` suppresses automatic handoff guidance and blocks direct agent-initiated handoff unless an explicit `/handoff <direction>` request is active in its generated agent turn.
+- Added the extension-owned `/agenticoding-settings` TUI panel for automatic handoff availability. TUI saves are global-only to `~/.pi/agent/settings.json`, preserve unrelated settings keys, persist real booleans, and visibly warn when a project override masks the global value.
+- Manual `/handoff <direction>` remains available even when automatic handoff is disabled: it records a unique operator request, queues the generated handoff prompt, and lets the guarded `handoff` tool compact only after that requested turn becomes active.
+- Successful enabled or manual handoff compaction now always resumes with Pi's fixed post-compaction `Proceed.` continuation; this behavior is not configurable.
 - Spawned child agents now inherit active registered parent tools executable in the child session, including MCP/extension tools such as ChunkHound when active and registered, while still excluding spawn and handoff and preserving child-local notebook tools.
 
+### Fixed
+
+- Queued manual `/handoff` follow-up prompts can no longer be preempted by an older agent turn's automatic handoff call before the generated user turn starts, including repeated same-direction requests with identical user directions.
+- Queued manual `/handoff` status/warnings distinguish pending follow-up delivery from the active generated turn, so the current agent is not told to call a tool that will reject until the generated turn starts.
+- Malformed present `handoff` settings parents such as `{ "handoff": null }` now fail closed instead of falling through to defaults.
+- Unsupported `handoff.automaticEnabled` string diagnostics and TUI display values are JSON-escaped to prevent newline/control-character spoofing.
+- Global `handoff.automaticEnabled` saves now write through a same-directory temporary file and rename over the target, preserve the previous settings file if replacement fails, and keep an existing settings file's mode bits when replacing it.
+
 ## [0.3.0] - 2026-05-23
 
 ### Added
@@ -108,6 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Comprehensive test suite** — 50+ tests covering spawn execution and rendering (concurrency, cancellation, truncation, stale detection, ownership lifecycle, microtask batching), ledger tools (add/get/list, staleness, rehydration, empty states, prompt hints), handoff (tool, command, compaction), watchdog (nudge injection, enforcement), and extension lifecycle.
 - **MIT licensed** — open-source permissive license.
 
+[Unreleased]: https://github.com/agenticoding/pi-agenticoding/compare/v0.3.0...HEAD
 [0.3.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/agenticoding/pi-agenticoding/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/agenticoding/pi-agenticoding/releases/tag/v0.1.0

README.md

@@ -40,7 +40,9 @@ Then disable pi's built-in compaction so handoff stays in control:
 }
 ```
 
-That's it. Your agent now has `spawn`, `notebook_write`, `notebook_read`, `notebook_index`, and `handoff`. The status bar shows context usage and notebook count.
+Optional automatic handoff availability can be changed later with `/agenticoding-settings`.
+
+That's it. Your agent now has `spawn`, `notebook_write`, `notebook_read`, `notebook_index`, `handoff`, and `/agenticoding-settings`. The status bar shows context usage and notebook count.
 
 ---
 
@@ -50,7 +52,8 @@ That's it. Your agent now has `spawn`, `notebook_write`, `notebook_read`, `noteb
 |---------|-------------------|
 | **Context usage %** | `ctx 65%` in status bar — green < 30%, yellow < 50%, orange < 70%, red ≥ 70% |
 | **Notebook count** | 📒 `3` when pages exist, dim `📒 0` when empty |
-| **`/handoff` command** | Instant pivot — agent drafts brief, compacts context, resumes |
+| **`/handoff` command** | Explicit manual pivot — agent drafts brief, compacts context, then Pi sends `Proceed.` in the fresh context |
+| **`/agenticoding-settings` command** | TUI panel for global `handoff.automaticEnabled`, with project override warnings |
 | **`/notebook` command** | Overlay showing all notebook pages with previews |
 | **Auto-rehydration** | Notebook pages survive session restarts |
 | **Spawn transparency** | Watch child agents work in real time in the TUI |
@@ -114,6 +117,20 @@ A sparse pocket notebook the agent curates while working. After discovering some
 
 When context degrades or the job changes, the agent saves reusable state to the notebook, writes a focused brief preserving what's still missing, and restarts clean. The new context starts with the brief front-and-center, all notebook pages accessible, and zero noise.
 
+By default, automatic handoff is enabled: the agent can see the `handoff` tool and may use it at context/job boundaries. After successful handoff compaction, Pi auto-sends `Proceed.` so the fresh context continues immediately; this continuation is fixed, not configurable.
+
+To make handoff human-driven only, set `handoff.automaticEnabled` to `false` in raw Pi settings JSON. Supported persisted values are JSON booleans `true` and `false`; missing settings default to `true`.
+
+```json
+{
+  "handoff": { "automaticEnabled": false }
+}
+```
+
+Settings are read from `~/.pi/agent/settings.json` and `<project>/.pi/settings.json`, with project settings overriding global settings. When automatic handoff is disabled, handoff-call guidance is removed from normal turns and direct `handoff` tool calls are rejected unless they are satisfying an active explicit operator `/handoff <direction>` request in the generated user turn. A queued manual request is only pending delivery; it does not authorize the current turn to call the tool. The tool remains registered; the setting is enforced by runtime guards rather than provider-schema removal.
+
+Run `/agenticoding-settings` to change the global value from the TUI. It saves global-only to `~/.pi/agent/settings.json`, preserves unrelated JSON keys and an existing file's mode bits, shows the effective runtime value separately, and warns when a project override masks the global value. Setting changes affect prompt guidance on future fresh agent turns, while direct handoff tool calls are checked against the effective setting at execution time. Malformed present `handoff` parents such as `{ "handoff": null }` fail closed; edit or remove project overrides manually.
+
 **Rule of thumb:** The notebook holds reusable learned knowledge. Handoff carries the remaining situational context.
 
 ---