@sayansr26/agent-os 0.6.0 → 0.6.2

package/.claude-plugin/marketplace.json

@@ -22,6 +22,29 @@
         "orchestration",
         "codebase-navigation"
       ]
+    },
+    {
+      "name": "auto-route",
+      "source": "./plugins/auto-route",
+      "description": "Picks the model and effort level for each turn from what the prompt asks for. /route pins a tier or turns routing off.",
+      "category": "productivity",
+      "keywords": [
+        "model-routing",
+        "effort",
+        "mod"
+      ]
+    },
+    {
+      "name": "auto-handoff",
+      "source": "./plugins/auto-handoff",
+      "description": "Hands a long session off to a fresh one instead of auto-compacting: Haiku writes a structured brief, the mod runs /clear and seeds the new session with it. Vendored from alexknowshtml/claude-auto-handoff (MIT).",
+      "category": "productivity",
+      "keywords": [
+        "context",
+        "handoff",
+        "compaction",
+        "mod"
+      ]
     }
   ]
 }

package/CHANGELOG.md

@@ -5,7 +5,45 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.6.0] — 2026-09-25
+## [0.6.2] — 2026-10-22
+
+agent-os plugin unchanged (0.5.0), auto-route unchanged (0.1.0). New plugin
+auto-handoff 0.8.6 in the same marketplace.
+
+### Added
+- **auto-handoff, a third plugin in the `sayan-plugins` marketplace**, vendored
+  from [alexknowshtml/claude-auto-handoff](https://github.com/alexknowshtml/claude-auto-handoff)
+  by Alex Hillman (MIT, commit `8d762ce`). In place of auto-compact, Haiku
+  writes a structured brief, the mod runs `/clear`, and the fresh session is
+  seeded with a pointer to the brief. `/plugin install auto-handoff@sayan-plugins`.
+  The brief viewer server is **off** by default here (upstream serves on the
+  Tailscale IP); `plugins/auto-handoff/UPSTREAM.md` lists every local change.
+- **`agent-os init` installs and updates auto-handoff** with the other two;
+  `--no-auto-handoff` leaves it out.
+
+### Changed
+- `scripts/validate-plugin.mjs` lets a mod carry a listing `icon.png`, as the
+  agent-os plugin now does.
+
+## [0.6.1] — 2026-10-21
+
+agent-os plugin unchanged (0.5.0). New plugin auto-route 0.1.0 in the same
+marketplace. 0.7.0 stays reserved for the move to Rulegate.
+
+### Added
+- **auto-route, a second plugin in the `sayan-plugins` marketplace.** A Claude
+  Code mod (a TypeScript hooks module) that picks the model and effort for each
+  turn from what the prompt asks for: lookups to Haiku, regular coding to
+  Sonnet, design and debugging to Opus, "ultrathink" and security work to Opus
+  at max effort. Subagents keep their own model. `/route` shows the route,
+  `/route light|standard|deep|max` pins a tier, `/route off` and `/route auto`
+  switch it off and on. `/plugin install auto-route@sayan-plugins`.
+- **`agent-os init` installs and updates auto-route** at project scope next to
+  agent-os, adding or refreshing the marketplace once. `--no-auto-route` leaves
+  it out; `--no-plugin` still skips both.
+- `scripts/validate-plugin.mjs` checks every other marketplace plugin built
+  from hook modules: manifest, name against its marketplace entry, the types
+  contract and each module it names.
 
 Plugin 0.5.0. Found by running 0.4.1 in a real project: the plugin passed its
 own audit while Claude ignored it — a whole feature was built without the

package/README.md

@@ -140,6 +140,38 @@ Feature directories default to the first of `src/features`, `src/modules`, `app/
 { "targets": ["claude-code"], "claude": { "features": ["src/features/*", "apps/*"], "cartographerReminder": true } }
 ```
 
+### auto-route
+
+A second, independent plugin in the same marketplace: a Claude Code mod (a TypeScript hooks module) that picks the model and effort for each turn from what the prompt asks for — lookups go to Haiku, regular coding to Sonnet, design and debugging to Opus, "ultrathink" and security work to Opus at max effort. Subagents keep their own model.
+
+```
+/plugin install auto-route@sayan-plugins
+```
+
+`agent-os init` installs and updates it alongside agent-os, at project scope; `--no-auto-route` leaves it out.
+
+`/route` shows the current route; `/route light|standard|deep|max` pins a tier, `/route off` hands control back to the session's own model, `/route auto` resumes routing. The tier table and the prompt rules sit at the top of `plugins/auto-route/hooks/register.ts`.
+
+Working on it:
+
+```sh
+claude --plugin-dir plugins/auto-route     # run a session with the working copy, hot-reloaded
+claude plugin validate plugins/auto-route  # what the engine would refuse
+claude plugin test plugins/auto-route      # tests/route.test.ts
+```
+
+Once the engine loads it, it writes `.claude-plugin/types/` (git-ignored) for the editor; `tsc -p plugins/auto-route` type-checks it after that. Bump `version` in its `plugin.json` when shipping a change so installs update.
+
+### auto-handoff
+
+A third plugin, vendored from [alexknowshtml/claude-auto-handoff](https://github.com/alexknowshtml/claude-auto-handoff) by Alex Hillman (MIT). Instead of auto-compacting at the context limit, it has Haiku write a structured brief, runs `/clear`, and seeds the fresh session with a pointer to the brief, so work carries on with a clean context. Settings (threshold, templates, ignored files) are rows in `/config`.
+
+```
+/plugin install auto-handoff@sayan-plugins
+```
+
+`agent-os init` installs it too; `--no-auto-handoff` leaves it out. One change from upstream: the brief viewer server is **off** by default here (upstream serves pages on your Tailscale IP); set `viewer` in `/config` to turn it on. `plugins/auto-handoff/UPSTREAM.md` records the upstream commit, the local changes and how to sync. Develop it the same way as auto-route: `claude --plugin-dir plugins/auto-handoff`, `claude plugin validate|test plugins/auto-handoff`.
+
 ---
 
 ## Design rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayansr26/agent-os",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "One source of truth for AI coding agent config. Write your rules once; compile them to Claude Code, Cursor, Cline, Windsurf, Antigravity, Gemini CLI, OpenCode and Kilo.",
   "keywords": [
     "ai",
@@ -46,4 +46,4 @@
     "test": "node scripts/validate-plugin.mjs && node src/selftest.mjs",
     "prepublishOnly": "npm test"
   }
-}
+}

package/plugins/agent-os/.claude-plugin/plugin.json

@@ -8,6 +8,8 @@
   },
   "homepage": "https://github.com/sayansr26/agent-os",
   "repository": "https://github.com/sayansr26/agent-os",
+  "privacyPolicyUrl": "https://s3techpulse.com/privacy-policy",
+  "supportUrl": "https://s3techpulse.com/support",
   "license": "MIT",
   "keywords": [
     "context-engineering",

package/plugins/auto-handoff/.claude-plugin/plugin.json

@@ -0,0 +1,49 @@
+{
+  "name": "auto-handoff",
+  "version": "0.8.6",
+  "description": "Hands a Claude Code session off to a fresh one before the context fills: a Haiku-written brief, /clear, and a seed that points the new session at the brief.",
+  "author": {
+    "name": "Alex Hillman",
+    "url": "https://github.com/alexknowshtml"
+  },
+  "repository": "https://github.com/alexknowshtml/claude-auto-handoff",
+  "license": "MIT",
+  "userConfig": {
+    "threshold": {
+      "type": "number",
+      "title": "Handoff threshold (tokens)",
+      "description": "Context size that triggers a handoff. AUTO_HANDOFF_TOKENS overrides it for a test run. A seeded session hands off no sooner than 40k past its starting size; the panel above the prompt says so when this is set lower.",
+      "default": 160000
+    },
+    "maxConsecutiveHandoffs": {
+      "type": "number",
+      "title": "Handoffs in a row without a message",
+      "description": "Handoffs allowed before you type a prompt. Past this the mod pauses until you send one.",
+      "default": 2
+    },
+    "briefTemplate": {
+      "type": "string",
+      "title": "Brief template file",
+      "description": "Markdown file that tells Haiku which sections to write. Created with the defaults on first run; edit it to change the brief.",
+      "default": "~/.claude/auto-handoff/brief.md"
+    },
+    "instructionsTemplate": {
+      "type": "string",
+      "title": "Instructions template file",
+      "description": "Markdown file that tells the fresh session how to read the brief. Created with the defaults on first run.",
+      "default": "~/.claude/auto-handoff/instructions.md"
+    },
+    "ignoreFiles": {
+      "type": "string",
+      "title": "Ignored files (regex)",
+      "description": "Edited files matching this pattern are left out of the brief, such as auto-synced state or caches. Leave blank for none.",
+      "default": ""
+    },
+    "viewer": {
+      "type": "string",
+      "title": "Viewer address",
+      "description": "Where the mod serves a readable page for each brief, as host:port, e.g. 127.0.0.1:3846. \"tailscale\" as the host means this machine's Tailscale IP, so only your tailnet can open it; without Tailscale it serves on 127.0.0.1. Blank (the default here) runs no server; the link is then the local file.",
+      "default": ""
+    }
+  }
+}

package/plugins/auto-handoff/LICENSE

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

package/plugins/auto-handoff/README.md

@@ -0,0 +1,131 @@
+# claude-auto-handoff
+
+> Vendored into the `sayan-plugins` marketplace from [alexknowshtml/claude-auto-handoff](https://github.com/alexknowshtml/claude-auto-handoff) (MIT, © 2026 Alex Hillman). See [UPSTREAM.md](UPSTREAM.md) for the commit and what differs here.
+
+A Claude Code mod that hands a long session off to a fresh one before the context fills up. It replaces auto-compact.
+
+At the threshold, Haiku writes a structured handoff brief to disk. Then the mod runs `/clear` and seeds the new session with one line that points at the brief. The fresh session reads the brief and keeps working.
+
+![auto-handoff in a live session: the tool gate stops a read at the threshold, the panel walks through the brief and /clear, and the fresh session picks the work back up](https://raw.githubusercontent.com/alexknowshtml/claude-auto-handoff/8d762ce726c962268e2dbe24c1c60f0889a2fcde/docs/demo.gif)
+
+A live run on Haiku with the threshold at 80k. The mod refuses a read at the threshold, writes the brief, clears, and the fresh session is back at work about 7 seconds later at 31k. ([video](https://github.com/alexknowshtml/claude-auto-handoff/blob/8d762ce726c962268e2dbe24c1c60f0889a2fcde/docs/demo.mp4))
+
+## Why not auto-compact?
+
+Auto-compact summarizes in place, and you can't control what it keeps. A handoff brief has a fixed structure that you can edit. It covers work in progress, decisions, assumptions to verify, dead ends, your last request and whether it was answered, and the next step. The files, commits and issues sections come from the transcript in code, so they don't depend on the model's memory.
+
+## What happens
+
+1. **Threshold.** The mod checks the context size after each turn and before each model request, including tool output that hasn't been measured yet. Once it's past the threshold, the mod refuses new tool calls, so one burst of reads can't overflow the window. Unmeasured tool output is an estimate that can run high, so the real size sometimes comes in under the threshold. A refused call still ends in a handoff, at the next request or the end of the turn.
+2. **Brief.** Haiku writes the brief from the transcript. If Haiku fails, a facts-only brief stands in. Briefs go to `~/.claude/state/auto-handoff/<session-id>.md`.
+3. **Clear and seed.** The mod runs `/clear` and sends the fresh session one line: read the brief and follow its Instructions section. In the transcript, that line's brief path and viewer URL are drawn as links. Claude Code makes them clickable only when it detects a terminal that supports links. Over plain SSH it usually doesn't, so set `FORCE_HYPERLINK=1` if your terminal handles links, or use the status line link below.
+4. **A panel above the prompt.** It shows each step with a braille spinner on the one still running: writing the brief, clearing, starting the fresh session. Once the new session is measured it reads `✓ handed off · 162k → 45k` with an `open brief` link, then collapses after 10 seconds. Failures, the loop-guard pause, a facts-only brief and a too-tight threshold stay up until you press Dismiss. Typing `/clear` yourself closes the panel, including one waiting for Dismiss, unless a handoff is running. The panel steps aside while a survey holds that band. The band is drawn on the terminal and desktop only, so on the mobile app or in VS Code the threshold, the result, and anything that stays up also arrive as a toast.
+5. **Viewer.** Each brief also gets a readable page in `~/.claude/state/auto-handoff/pages/`. The page shows the brief and every handoff in the same run, linked in order. The served link is short, like `http://100.x.y.z:3846/1a2b3c4d`, so it fits on one line on a phone. In this copy the server is off by default and the link is the local file; set `viewer` in `/config` (for example `tailscale:3846`) to serve the pages. With `tailscale:3846` the mod serves them on your Tailscale IP at port 3846, so you can open them from any device on your tailnet. Devices off your tailnet can't reach them. The server starts with the first session that loads the mod and runs while that session is open; if it stops, including when the mod reloads, the next session to finish a turn starts it again. A session that finds the port already taken logs one line and leaves the running server alone, since it serves the same pages. Without Tailscale, the mod serves on `127.0.0.1` instead, so the link opens only on this machine. If Tailscale comes up later, a session already serving on localhost keeps using it; the next new session can serve on the Tailscale IP.
+6. **Status line link (optional).** `statusline/handoff-link.sh` wraps your status line command and adds a `↪ <link>` line when the session came from a handoff. Set it as the `statusLine` command in `~/.claude/settings.json`, with your existing command after it:
+
+   ```json
+   "statusLine": { "type": "command", "command": "~/claude-auto-handoff/statusline/handoff-link.sh ~/.claude/my-statusline.sh" }
+   ```
+
+   It needs `jq`. It finds the link in the previous brief's header, which names this session in `to:` and the page in `viewer:`.
+
+Loop guards stop a fresh session that starts large from handing off again right away. They also cap how many handoffs run in a row before you type something.
+
+## Install
+
+Requires a Claude Code build with mods (function-hook plugins). From the `sayan-plugins` marketplace (`agent-os init` installs it too; `--no-auto-handoff` skips it):
+
+```
+/plugin marketplace add sayansr26/agent-os
+/plugin install auto-handoff@sayan-plugins
+```
+
+Or from upstream, as a plugin folder:
+
+```sh
+git clone https://github.com/alexknowshtml/claude-auto-handoff.git ~/claude-auto-handoff
+claude --plugin-dir ~/claude-auto-handoff
+```
+
+To load it in every session, set `CLAUDE_CODE_PLUGIN_DIRS` to the folder in your shell environment, or in the `env` block of `~/.claude/settings.json`:
+
+```json
+{ "env": { "CLAUDE_CODE_PLUGIN_DIRS": "~/claude-auto-handoff" } }
+```
+
+## Configure
+
+Every setting is a row in `/config` under auto-handoff. They're stored in `~/.claude/settings.json` under `pluginConfigs`.
+
+| Setting | Default | What it does |
+|---|---|---|
+| `threshold` | `160000` | Context tokens that trigger a handoff. Sized for a 200k window: it leaves room for the brief and the turn in flight. A seeded session hands off no sooner than 40k past its own starting size, whatever this says; set it lower than that and the panel tells you where the line actually is |
+| `maxConsecutiveHandoffs` | `2` | Handoffs allowed before you type a prompt; past this, the mod pauses until you do |
+| `briefTemplate` | `~/.claude/auto-handoff/brief.md` | Your copy of the sections Haiku writes |
+| `instructionsTemplate` | `~/.claude/auto-handoff/instructions.md` | Your copy of what the fresh session is told to do |
+| `ignoreFiles` | blank | Regex for edited files to leave out of the brief, such as caches or synced state |
+| `viewer` | blank | Where to serve the brief pages, as `host:port`. `tailscale` as the host means this machine's Tailscale IP, or `127.0.0.1` when Tailscale isn't set up. Leave blank for no server; the link is then the local file |
+
+Environment variables:
+
+- `AUTO_HANDOFF_TOKENS=60000` overrides the threshold for one run, so you can watch a handoff without filling 160k first. It stays set in that shell after the test. Seeded sessions start near 45k, so a value under about 85k leaves them less than 40k of room: the mod then hands off at start + 40k instead and the panel shows `threshold 60k (AUTO_HANDOFF_TOKENS) leaves 15k ...` so you know the override is still live.
+- `AUTO_HANDOFF_DISABLE=1` turns the mod off for one session, viewer server included.
+- `DISABLE_AUTO_COMPACT` also turns it off. When something else manages the context limit, such as a wrapper that pipes the session, `/clear` would break that pipe. The viewer server still runs there.
+
+## Change the brief's structure and rules
+
+The brief is shaped by two markdown files. The defaults live in this repo's [`templates/`](templates/) folder:
+
+- **[`templates/brief.md`](templates/brief.md)** is the prompt Haiku gets after the transcript. Each `## ` heading is a section of the brief.
+- **[`templates/instructions.md`](templates/instructions.md)** goes at the top of the brief and tells the fresh session what to do with it.
+
+On a session's first start, the mod copies both files to `~/.claude/auto-handoff/` if they aren't there yet. Edit those copies, not the ones in the repo, so a `git pull` never overwrites your changes. The next handoff uses your version.
+
+To get the current default back, delete your copy. The next start copies it fresh. To keep your files somewhere else, point `briefTemplate` or `instructionsTemplate` in `/config` at them.
+
+### Editing `brief.md`
+
+Add, remove, rename or reorder `## ` sections. The text under each heading tells Haiku what to put there. A Haiku reply counts as valid if it contains at least one of your headings. Otherwise the mod falls back to a facts-only brief.
+
+Leave out files and commits sections. The mod adds them from the transcript in code.
+
+### Editing `instructions.md`
+
+It has one switch:
+
+```md
+{{#priority}}Shown when the last request is not fully answered.{{/priority}}
+{{^priority}}Shown when it is.{{/priority}}
+```
+
+The switch reads the brief's `## Last Request from the User` section and its `Status:` line. Keep both in `brief.md` if you want it to work.
+
+## Logs
+
+Everything the mod does is logged to `~/.claude/state/auto-handoff/auto-handoff.log`.
+
+## Develop
+
+```sh
+claude plugin validate .
+claude plugin test .
+```
+
+The mod hot-reloads when you save while it's loaded with `--plugin-dir`.
+
+## Changelog
+
+- **0.8.6** On a machine without `sh` (Windows), the brief page is still written, and the link opens it as a local file instead of a server that never started. The viewer no longer shells out to `mkdir`.
+- **0.8.5** Windows support, from [@davidboomcycle](https://github.com/davidboomcycle) (#3). The mod falls back to `USERPROFILE` when `HOME` is unset, so briefs no longer land in `<project>/undefined/`. Where there is no `sh`, the log is written through `$.fs`. The tests pass on Windows. The viewer server still needs a POSIX shell.
+- **0.8.4** Any token figure in Haiku's brief that isn't in Handoff Numbers is marked `[unverified: not in Handoff Numbers]` and logged. The figure is marked, not removed.
+- **0.8.3** The brief gets the real numbers: tokens at handoff, the threshold and where it came from, the session's starting size, and how many handoffs ran with no message from you. Haiku must copy them or write "unknown", so a brief can no longer invent a figure like "burned its 200k budget".
+- **0.8.2** A refused tool call always ends in a handoff, even when the real size measures under the threshold. Your own `/clear` closes the panel. A second session that finds the viewer port taken exits quietly instead of logging a stack trace.
+- **0.8.1** On the mobile app and in VS Code, which don't draw the panel, the threshold, the result and anything that stays up also arrive as toasts.
+- **0.8.0** A panel above the prompt replaces the toasts, with a spinner on each step and an `open brief` link.
+- **0.7.0** A seeded session hands off no sooner than 40k past its starting size. When the threshold is set tighter than that, the panel says so and names the setting. The viewer serves on `127.0.0.1` when Tailscale isn't available.
+- **0.6.0** A viewer page for each brief, served on your Tailscale IP with short links. The pages in a chain link to each other. The seed row's links are clickable, and the status line script adds a handoff link.
+- **0.5.0** First release: a Haiku brief, `/clear` and a seed prompt. It includes the tool gate, the check before each request, auto-compact replaced by a handoff, and the loop guards.
+
+## License
+
+MIT

package/plugins/auto-handoff/UPSTREAM.md

@@ -0,0 +1,22 @@
+# Upstream
+
+This plugin is a vendored copy of [alexknowshtml/claude-auto-handoff](https://github.com/alexknowshtml/claude-auto-handoff)
+by Alex Hillman, MIT licensed (see [LICENSE](LICENSE)); the copyright and author stay his.
+
+- Source commit: `8d762ce726c962268e2dbe24c1c60f0889a2fcde` (upstream version 0.8.6), taken 2026-10-22.
+- Left out: `docs/demo.gif` and `docs/demo.mp4` (1.5 MB); the README links to them upstream.
+
+## Local changes
+
+- `viewer` defaults to blank (no server) in `.claude-plugin/plugin.json` and `hooks/config.ts`.
+  Upstream defaults to `tailscale:3846`, which starts a detached HTTP server that outlives the
+  session. `agent-os init` installs this plugin into projects by default, so it must not start a
+  network listener nobody asked for. Set `viewer` in `/config` to turn it on.
+- Tests that exercise the server name `viewer: 'tailscale:3846'` explicitly.
+- README: provenance note, install from `sayan-plugins`, viewer default.
+
+## Syncing from upstream
+
+Fetch the new commit into a scratch folder, diff it against this folder, re-apply the local
+changes above, update the commit here, and bump `version` in `.claude-plugin/plugin.json` so
+installs update. Run `claude plugin validate` and `claude plugin test` on this folder after.

package/plugins/auto-handoff/hooks/brief.ts

@@ -0,0 +1,190 @@
+import type { SessionMessage } from 'claude-code'
+import { renderTemplate, sectionHeadings } from './templates.ts'
+
+// Brief building.
+// Files, commits, issues and the last real request come from the transcript in code;
+// Haiku only writes the judgment sections. Its reply is checked, and the facts alone
+// stand in when it fails.
+
+const MAX_MESSAGES = 120
+const MAX_MSG_CHARS = 2_000
+const MAX_TRANSCRIPT_CHARS = 150_000
+
+// Harness signals that arrive as user messages but are never the user's words.
+const META_PREFIXES = ['Stop hook feedback', '[Automatic handoff]', '[auto-handoff]', '[Image', '<system-reminder>', '<command-name>', '<local-command']
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit'])
+const GIT_COMMIT_OUTPUT = /^\[[\w./-]+(?: \(root-commit\))? ([0-9a-f]{7,})\] (.+)$/m
+
+export type Facts = {
+  filesModified: string[]
+  commits: string[]
+  issues: string[]
+  lastUserMessage?: string
+  handoffTokens?: number
+  threshold?: number
+  /** Where the base threshold came from: the env override or the /config setting. */
+  thresholdSource?: string
+  seededSessionStartSize?: number
+  /** Handoffs since the user last typed, this one included. */
+  unattendedCount?: number
+  /** Which handoff this is in its chain (1 for the first, 2 for the second, etc.). */
+  depth?: number
+}
+
+/** The user's own words, or undefined for a harness signal or a tool-result-only message. */
+export function userText(m: SessionMessage): string | undefined {
+  if (m.role !== 'user') return undefined
+  const raw = m.text.trim()
+  if (!raw) return undefined
+  return isMeta(raw) ? undefined : raw
+}
+
+function isMeta(text: string): boolean {
+  return META_PREFIXES.some(p => text.startsWith(p))
+}
+
+function commitSubject(command: string): string | undefined {
+  if (!/\bgit\b[^\n|;&]*\bcommit\b/.test(command)) return undefined
+  const heredoc = command.match(/<<\s*'?(\w+)'?\n([\s\S]*?)\n\1/)
+  if (heredoc) return heredoc[2]?.trim().split('\n')[0]
+  return command.match(/-m\s+(["'])(.+?)\1/)?.[2]
+}
+
+/** ignoreFiles: paths that never count as edits (auto-synced state, caches); the ignoreFiles setting. */
+export function extractFacts(messages: readonly SessionMessage[], ignoreFiles?: RegExp): Facts {
+  const files = new Set<string>()
+  const commits: string[] = []
+  const issues = new Set<string>()
+  let lastUserMessage: string | undefined
+  for (const m of messages) {
+    const said = userText(m)
+    if (said) lastUserMessage = said
+    for (const n of `${said ?? (m.role === 'assistant' ? m.text : '')}`.matchAll(/(?<![\w&/])#(\d{2,5})\b/g)) issues.add(`#${n[1]}`)
+    for (const t of m.toolUses) {
+      const path = t.input.file_path ?? t.input.notebook_path
+      if (EDIT_TOOLS.has(t.tool) && typeof path === 'string' && !t.isError && !ignoreFiles?.test(path)) files.add(path)
+      if (t.tool !== 'Bash' || typeof t.input.command !== 'string' || t.isError) continue
+      // git's own "[main abc1234] subject" line is the proof a commit landed; the command is the fallback
+      const out = t.text?.match(GIT_COMMIT_OUTPUT)
+      const subject = out ? `${out[2]} (${out[1]})` : t.text === undefined ? commitSubject(t.input.command) : undefined
+      if (subject && !commits.includes(subject)) commits.push(subject)
+    }
+  }
+  return { filesModified: [...files].slice(-20), commits: commits.slice(-10), issues: [...issues].slice(-15), lastUserMessage }
+}
+
+/** The transcript as Haiku reads it. Harness signals are labelled so they are not taken for the user. */
+export function renderTranscript(messages: readonly SessionMessage[]): string {
+  const lines = messages.slice(-MAX_MESSAGES).map(m => {
+    const role = m.role === 'user' && m.text.trim() && !userText(m) ? 'system signal (not the user)' : m.role
+    const text = m.text.length > MAX_MSG_CHARS ? m.text.slice(0, MAX_MSG_CHARS) + ' [truncated]' : m.text
+    const tools = m.toolUses.map(t => `  [tool ${t.tool}${t.isError ? ' ERROR' : ''}] ${JSON.stringify(t.input).slice(0, 300)}`)
+    return [`### ${role}`, text, ...tools].filter(Boolean).join('\n')
+  })
+  const joined = lines.join('\n\n')
+  return joined.length > MAX_TRANSCRIPT_CHARS ? joined.slice(-MAX_TRANSCRIPT_CHARS) : joined
+}
+
+function list(items: string[], empty: string): string {
+  return items.length ? items.map(i => `- ${i}`).join('\n') : empty
+}
+
+// The only token figures the brief may use. Haiku once wrote "burned its 200k budget" for a
+// session at 93k because the prompt held no numbers at all.
+function handoffNumbersBlock(f: Facts): string {
+  const lines = []
+  if (f.depth !== undefined) lines.push(`- **Handoff depth:** ${f.depth}`)
+  if (f.handoffTokens !== undefined) lines.push(`- **Tokens at handoff:** ${f.handoffTokens} (${k(f.handoffTokens)})`)
+  if (f.threshold !== undefined) lines.push(`- **Threshold:** ${f.threshold} (${k(f.threshold)})${f.thresholdSource ? `, from ${f.thresholdSource}` : ''}`)
+  if (f.seededSessionStartSize !== undefined) lines.push(`- **This session's starting size (seeded from a handoff):** ${f.seededSessionStartSize} (${k(f.seededSessionStartSize)})`)
+  if (f.unattendedCount !== undefined) lines.push(`- **Handoffs in a row with no user message:** ${f.unattendedCount}`)
+  return lines.length ? `## Handoff Numbers\n${lines.join('\n')}\n` : ''
+}
+
+const k = (n: number) => `${Math.round(n / 1000)}k`
+
+export function factsBlock(f: Facts, withLastMessage = true): string {
+  const numbers = handoffNumbersBlock(f)
+  const files = `## Files Modified (from Edit/Write calls)
+${list(f.filesModified, 'None.')}
+
+## Commits This Session
+${list(f.commits, 'None.')}
+
+## GitHub Issues Mentioned
+${f.issues.length ? f.issues.join(', ') : 'None.'}`
+  const all = [numbers, files].filter(Boolean).join('\n')
+  return withLastMessage ? `${all}\n\n## Last Real User Message (verbatim)\n${f.lastUserMessage ?? 'None found.'}` : all
+}
+
+export function briefPrompt(messages: readonly SessionMessage[], facts: Facts, template: string): string {
+  // Data first, instructions last.
+  return `## Extracted Facts\n${factsBlock(facts)}\n\n## Conversation\n${renderTranscript(messages)}\n\n---\n\n${template.trim()}`
+}
+
+/** A reply that holds none of the template's sections is a dialogue fragment, not a brief. */
+export function isValidBrief(text: string, template: string): boolean {
+  return sectionHeadings(template).some(h => text.includes(h))
+}
+
+// Whether the brief's last-request section
+// says the request is not (fully) answered. A chain with no user message is not a real request.
+export function hasUnansweredLastRequest(text: string): boolean {
+  const heading = /##\s*Last Request from the User/i.exec(text)
+  if (!heading) return false
+  const rest = text.slice(heading.index + heading[0].length)
+  const next = /^#{1,6}\s/m.exec(rest)
+  const section = next ? rest.slice(0, next.index) : rest
+  if (/No user message found|^\s*\[auto-handoff\]/i.test(section)) return false
+  return /\bStatus[\s*_`]*:[\s*_`"]*(Not (?:yet |fully )?answered|Partially answered|Unanswered)/i.test(section)
+}
+
+export type BriefContext = {
+  sessionId: string
+  /** The session's transcript file. */
+  transcript: string
+  /** The instructions template, rendered at the top of the brief. */
+  instructions: string
+}
+
+export function assembleBrief(ctx: BriefContext, facts: Facts, haiku: string | undefined): string {
+  const header = `${renderTemplate(ctx.instructions, { priority: haiku ? hasUnansweredLastRequest(haiku) : false })}
+
+## Session Handoff Brief
+
+- **Previous Session:** ${ctx.sessionId}
+- **Transcript:** \`${ctx.transcript}\`
+
+## How to Use This Brief
+${haiku ? 'Haiku wrote the judgment sections from conversation text with tool output abbreviated. The facts sections came from tool calls in code.' : 'Haiku did not return a usable brief, so this holds only facts extracted in code. Read the transcript for the rest.'} Treat every line as a starting point, not a fact. Before acting on anything here, spawn a subagent to verify: run git status, gh pr view, or Read the file directly. If a fact is missing, grep the transcript before asking the user.`
+  // A valid Haiku brief already quotes the last request in its own section.
+  return [header, haiku?.trim(), factsBlock(facts, !haiku)].filter(Boolean).join('\n\n')
+}
+
+// A token figure: "93k", "93.1k", "93,105 tokens", "93105 tokens".
+const TOKEN_FIGURE = /\b(\d{1,4}(?:\.\d+)?)k\b|\b(\d{1,3}(?:,\d{3})+|\d{4,7})(?= tokens\b)/gi
+
+const figureValue = (k?: string, whole?: string) => k !== undefined ? Number(k) * 1000 : Number(whole!.replace(/,/g, ''))
+
+/**
+ * Marks every token figure in Haiku's text that the Handoff Numbers block does not hold, within
+ * rounding to the nearest thousand. The template asks Haiku to copy those numbers; this makes it a
+ * rule. Figures are marked, not removed, so the next session sees what was claimed and that it is
+ * unchecked. With no numbers block, every figure is marked.
+ */
+export function markUnverifiedFigures(text: string, f: Facts): { text: string; flagged: string[] } {
+  const block = handoffNumbersBlock(f)
+  const allowed = [
+    ...[...block.matchAll(/\b(\d{1,4}(?:\.\d+)?)k\b/g)].map(m => figureValue(m[1])),
+    ...[...block.matchAll(/\b\d{4,7}\b/g)].map(m => Number(m[0])),
+  ]
+  const flagged: string[] = []
+  const marked = text.replace(TOKEN_FIGURE, (match: string, k?: string, whole?: string) => {
+    const value = figureValue(k, whole)
+    if (allowed.some(a => Math.abs(a - value) < 1000)) return match
+    flagged.push(match)
+    return `${match} [unverified: not in Handoff Numbers]`
+  })
+  return { text: marked, flagged }
+}

package/plugins/auto-handoff/hooks/config.ts

@@ -0,0 +1,64 @@
+// Settings from /config and the constants built on them. Engine-free: the host follows $ only
+// into functions declared in register.tsx, so anything taking $ stays there.
+
+export const BRIEF_DIR = '.claude/state/auto-handoff'
+// The two numbers are userConfig fields (plugin.json), set in /config. Defaults match the manifest.
+// threshold: matches HANDOFF_ARM_TOKENS in context-warning.ts.
+// MIN_HEADROOM and maxUnattended are loop guards. A seeded session must grow MIN_HEADROOM past its
+// first-turn size (its floor) before it can hand off again, and at most maxUnattended handoffs may
+// run before the user types a prompt. MIN_HEADROOM is fixed: seeded sessions start near 45k, so at
+// the default threshold it never moves the line; it only matters when the threshold is set low.
+// 40k is the empirical line where a seeded session can read its brief and still do real work. The
+// 2026-10-03 live run (threshold 20k, seeded sessions start at ~31k) chained six times with no
+// guard; the 2026-10-04 run (AUTO_HANDOFF_TOKENS=80000 left in a shell, floor ~45k) chained eight
+// times with a guard of a quarter of the threshold, because max(80k, 45k + 20k) is still 80k, and
+// 35k of room goes in reading the brief. Progress, not time: a 15-minute chain cap could block a
+// real session that fills fast.
+// The rest shape the brief: two template files and a pattern for files
+// that never count as edits.
+// viewer: where the mod serves the brief pages, "host:port"; "tailscale" as the host means this
+// machine's Tailscale IP, or 127.0.0.1 without Tailscale. Blank: no server, and the link is the local file.
+// sayan-plugins ships it blank (upstream: 'tailscale:3846'), so installing the mod starts no server.
+export type Config = { threshold: number; maxUnattended: number; briefTemplate: string; instructionsTemplate: string; ignoreFiles?: RegExp; viewer: string }
+export const DEFAULTS: Config = { threshold: 160_000, maxUnattended: 2, briefTemplate: '~/.claude/auto-handoff/brief.md', instructionsTemplate: '~/.claude/auto-handoff/instructions.md', viewer: '' }
+export const MIN_HEADROOM = 40_000
+// Each template's default, a file in the mod's templates/ folder.
+export const TEMPLATES = [['briefTemplate', 'brief.md'], ['instructionsTemplate', 'instructions.md']] as const
+export type TemplateKey = typeof TEMPLATES[number][0]
+// Used only when the shipped default is unreadable too, so the fresh session still knows what to do.
+export const LAST_RESORT_INSTRUCTIONS = '## Instructions\n\nThis turn was triggered by the system, not by a user. Read this brief and continue the work it describes.'
+
+export const k = (n: number) => `${Math.round(n / 1000)}k`
+export const short = (sessionId: string) => sessionId.slice(0, 8)
+export const expand = (path: string, home: string) => path.replace(/^~(?=\/|$)/, home)
+
+// A non-positive or non-numeric value falls back to the default rather than handing off at 0.
+const num = (v: unknown, fallback: number) => typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fallback
+const str = (v: unknown, fallback: string) => typeof v === 'string' && v.trim() ? v.trim() : fallback
+// A bad pattern is dropped, not fatal: a typo in /config should not stop handoffs.
+function pattern(v: unknown): RegExp | undefined {
+  if (typeof v !== 'string' || !v.trim()) return undefined
+  try { return new RegExp(v) } catch { return undefined }
+}
+
+/** The /config values, each checked, with the manifest's defaults for anything missing or bad. */
+export function parseConfig(options: Record<string, unknown>): Config {
+  return {
+  threshold: num(options.threshold, DEFAULTS.threshold),
+  maxUnattended: num(options.maxConsecutiveHandoffs, DEFAULTS.maxUnattended),
+  briefTemplate: str(options.briefTemplate, DEFAULTS.briefTemplate),
+  instructionsTemplate: str(options.instructionsTemplate, DEFAULTS.instructionsTemplate),
+  ignoreFiles: pattern(options.ignoreFiles),
+  viewer: typeof options.viewer === 'string' ? options.viewer.trim() : DEFAULTS.viewer,
+  }
+}
+
+// The seed prompt's first characters; the render hook knows the seed row by them.
+export const SEED_PREFIX = '[auto-handoff] ↪ Handoff from session'
+// The seed text with its brief path and viewer URL as markdown links. The path becomes a
+// file: link labelled by its file name; the URL links to itself. Exported for the test.
+export function linkify(text: string): string {
+  return text
+    .replace(/(?<=\bat )(\/\S+\.md)(?=[\s)]|$)/, (p) => `[${p.slice(p.lastIndexOf('/') + 1)}](file://${p})`)
+    .replace(/(https?:\/\/[^\s)]+)/, (u) => `[${u}](${u})`)
+}

package/plugins/auto-handoff/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }