genshin-mods 0.0.0-stage → 4.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "genshin-mods",
+  "displayName": "Genshin Mods",
+  "description": "Five Claude Code mods under one band above the prompt: waypoints (the next steps, one press each), resin (cache, context, limits and cost, with warm, compact and a one-click handoff), veil (recording mode), commission (a goal's task list and clock) and ward (a question before editing a file another session just changed).",
+  "author": { "name": "Esposter", "url": "https://github.com/Esposter" },
+  "homepage": "https://esposter.com/docs/infra/claude-interface/genshin-mods",
+  "repository": "https://github.com/Esposter/Esposter",
+  "license": "Apache-2.0",
+  "keywords": ["cache", "collision", "genshin", "handoff", "mods", "recording", "tasks"],
+  "types": "./types/index.d.ts"
+}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2020-present Jimmy Chen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# genshin-mods
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Apache-2.0 licensed][badge-license]][url-license]
+[![NPM version][badge-npm-version]][url-npm]
+[![NPM downloads][badge-npm-downloads]][url-npm]
+[![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
+
+A Claude Code plugin of five mods drawn as one band above the prompt, in the session character's colour: the next steps one press away, what the session is spending with a one-press handoff, recording mode, a goal's task list and clock, and a question before editing a file another session just changed.
+
+- **Waypoints** — after each answered turn, up to three next steps the session suggests, each a button that sends it as the next prompt.
+- **Resin** — the prompt cache's time left, the context window, the five-hour and weekly limits and the cost so far, with **Warm**, **Compact** and **Handoff**, and a toast before the cache goes cold.
+- **Veil** — recording mode: emails, amounts, phone numbers and secrets shown as placeholders while the model still reads the real values.
+- **Commission** — a goal meter over the session's task list: the goal, tasks done, the share complete and the minutes since it started.
+- **Ward** — before an edit to a file another session changed in the last half hour, a question: proceed, move to a worktree, or cancel.
+
+## Table of Contents
+
+- 🚀 [Getting Started](#getting-started)
+- 📖 [Documentation](#documentation)
+- ⚖️ [License](#license)
+
+---
+
+## <a name="getting-started">🚀 Getting Started</a>
+
+This repository is a Claude Code plugin marketplace named `esposter`:
+
+```bash
+claude plugin marketplace add Esposter/Esposter
+claude plugin install genshin-mods@esposter
+```
+
+A clone of this repository needs neither command: `.agents/settings.json` enables the plugin at project scope once you trust the repository. With [`genshin-persona`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-persona) installed beside it, the band takes the session character's colour; without it, the game's interface gold.
+
+Developing the plugin from a checkout loads the directory itself, with the installed copy disabled so only one of them answers:
+
+```bash
+claude plugin disable genshin-mods@esposter
+claude --plugin-dir packages/genshin-mods
+```
+
+## <a name="documentation">📖 Documentation</a>
+
+We highly recommend you take a look at the [documentation](https://esposter.com/docs/infra/claude-interface/genshin-mods) to level up.
+
+### Command reference
+
+Each mod is switched by its own slash command; bare, it flips, and the choice is kept across sessions:
+
+| Command                   | What it does                                                        |
+| :------------------------ | :------------------------------------------------------------------ |
+| `/waypoints [on \| off]`  | Suggests the next steps after each answered turn, or stops          |
+| `/resin [on \| off]`      | Shows the cache, context, limits and cost row and its warning toast |
+| `/veil [on \| off]`       | Turns recording mode on or off; off by default                      |
+| `/commission [on \| off]` | Shows the goal meter while a turn works through a task list         |
+| `/ward [on \| off]`       | Asks before an edit to a file another session just changed          |
+
+With the band focused (a click or `ctrl+x tab`), `w`, `c` and `h` warm, compact and hand off, `1` to `3` send a waypoint and `g` opens or closes the whole task list.
+
+### Commands
+
+Run from `packages/genshin-mods/`:
+
+```bash
+pnpm test         # vitest watch mode (coverage is run from the repo root)
+pnpm validate     # claude plugin validate: the engine's own reading of the hooks module
+pnpm lint:fix     # auto-fix lint
+```
+
+## <a name="license">⚖️ License</a>
+
+This project is licensed under the [Apache-2.0 license](https://github.com/Esposter/Esposter/blob/main/LICENSE).
+
+[badge-license]: https://img.shields.io/github/license/Esposter/Esposter.svg?color=blue
+[url-license]: https://github.com/Esposter/Esposter/blob/main/LICENSE
+[badge-npm-version]: https://img.shields.io/npm/v/genshin-mods/latest?color=brightgreen
+[url-npm]: https://www.npmjs.com/package/genshin-mods/v/latest
+[badge-npm-unpacked-size]: https://img.shields.io/npm/unpacked-size/genshin-mods/latest?label=npm
+[badge-npm-downloads]: https://img.shields.io/npm/dm/genshin-mods.svg

package/hooks/hooks.json

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

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "genshin-mods",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "A Claude Code plugin of five mods under one band above the prompt: the next steps, the cache and usage with a one-click handoff, recording mode, a goal's task list and a question before editing a file another session just changed.",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "genshin",
+    "mods"
+  ],
+  "homepage": "https://esposter.com/docs/infra/claude-interface/genshin-mods",
+  "bugs": {
+    "url": "https://github.com/Esposter/Esposter/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Jimmy Chen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Esposter/Esposter.git"
+  },
+  "files": [
+    ".claude-plugin",
+    "hooks",
+    "src",
+    "types",
+    "!**/*.test.ts",
+    "!.claude-plugin/types"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "vitest",
+    "validate": "claude plugin validate ."
+  },
+  "gitHead": "7667bc8c9a2b4e9dcacd6b845ee8cc9951250ae7"
+}

package/src/models/ResinFigure.ts

@@ -0,0 +1,5 @@
+export interface ResinFigure {
+  isWarning: boolean;
+  label: string;
+  text: string;
+}

package/src/models/TaskCall.ts

@@ -0,0 +1,14 @@
+import type { CommissionTask } from "../../types";
+import type { TaskTool } from "./TaskTool";
+
+// One task tool call with what its result says, in the shapes the engine's own tools declare
+export type TaskCall =
+  | {
+      id: string;
+      // oxlint-disable-next-line literal-union/no-string-literal-union -- The engine's own TaskUpdate statuses
+      status?: "deleted" | CommissionTask["status"];
+      subject?: string;
+      tool: TaskTool.TaskUpdate;
+    }
+  | { id: string; subject: string; tool: TaskTool.TaskCreate }
+  | { todos: { content: string; status: CommissionTask["status"] }[]; tool: TaskTool.TodoWrite };

package/src/models/TaskTool.ts

@@ -0,0 +1,5 @@
+export enum TaskTool {
+  TaskCreate = "TaskCreate",
+  TaskUpdate = "TaskUpdate",
+  TodoWrite = "TodoWrite",
+}

package/src/models/WardAnswer.ts

@@ -0,0 +1,8 @@
+export enum WardAnswer {
+  Cancel = "Cancel",
+  Proceed = "Proceed",
+  Worktree = "Move to a worktree",
+}
+
+// In the order the question offers them
+export const WardAnswers: readonly WardAnswer[] = [WardAnswer.Proceed, WardAnswer.Worktree, WardAnswer.Cancel];

package/src/register.ts

@@ -0,0 +1,15 @@
+import type { Register } from "claude-code";
+
+import { registerBand } from "./services/band/registerBand";
+import { registerCommission } from "./services/commission/registerCommission";
+import { registerLifecycle } from "./services/registerLifecycle";
+import { registerVeil } from "./services/veil/registerVeil";
+import { registerWard } from "./services/ward/registerWard";
+
+export const register: Register = (on) => {
+  registerBand(on);
+  registerCommission(on);
+  registerLifecycle(on);
+  registerVeil(on);
+  registerWard(on);
+};

package/src/services/InitialState.ts

@@ -0,0 +1,14 @@
+import type { PluginState } from "claude-code";
+
+// Every state value's initial, read by each file's atoms: the engine traces a state reference only to an atom made in
+// The file that uses it, so each file makes its own and this is the one place their initials are written
+export const InitialState: PluginState["genshin-mods"] = {
+  commission: { goal: "", openedAt: 0, tasks: [] },
+  enabledMods: { commission: true, resin: true, veil: false, ward: true, waypoints: true },
+  isCommissionExpanded: false,
+  isHandingOff: false,
+  lastCacheRequestAt: 0,
+  lastPrompt: "",
+  now: 0,
+  waypoints: [],
+};

package/src/services/ModDescriptionMap.ts

@@ -0,0 +1,12 @@
+import type { EnabledMods } from "../../types";
+
+// Each mod's command, `/<name> [on|off]`, as the menu describes it
+export const ModDescriptionMap: Record<keyof EnabledMods, string> = {
+  commission: "Show a goal's task list, how far it is and how long it has run.",
+  resin: "Show the cache, context, limits and cost, with warm, compact and handoff.",
+  veil: "Recording mode: show emails, amounts, phone numbers and secrets as placeholders.",
+  ward: "Ask before editing a file another session changed in the last half hour.",
+  waypoints: "Suggest the next steps after each answer, one press each.",
+};
+
+export const ModNames = Object.keys(ModDescriptionMap) as (keyof EnabledMods)[];

package/src/services/band/getCommissionSummary.ts

@@ -0,0 +1,21 @@
+import type { Commission } from "../../../types";
+
+import { MINUTE_FORMATTER } from "../constants";
+
+const PERCENT_FORMATTER = new Intl.NumberFormat("en", { style: "percent" });
+
+// `goal · 3 of 4 · 75% · 12m`, the clock counting whole minutes from the commission's opening
+export const getCommissionSummary = ({ goal, openedAt, tasks }: Commission, now: number): string => {
+  const done = tasks.filter(({ status }) => status === "completed").length;
+  const elapsedMinutes = Math.floor(
+    Temporal.Duration.from({ milliseconds: Math.max(0, now - openedAt) }).total("minutes"),
+  );
+  return [
+    goal,
+    `${done} of ${tasks.length}`,
+    PERCENT_FORMATTER.format(done / tasks.length),
+    MINUTE_FORMATTER.format(elapsedMinutes),
+  ]
+    .filter(Boolean)
+    .join(" · ");
+};

package/src/services/band/registerBand.ts

@@ -0,0 +1,215 @@
+import type { EngineInterface, On, RenderElement, RenderInput } from "claude-code";
+
+import { atom, read, update } from "claude-code";
+
+import type { EnabledMods } from "../../../types";
+
+import { ACCENT_COLOR, HANDOFF_QUESTION, MAX_SHOWN_TASKS, WARM_QUESTION } from "../constants";
+import { InitialState } from "../InitialState";
+import { getResinFigures } from "../resin/getResinFigures";
+import { getCommissionSummary } from "./getCommissionSummary";
+
+// The plugin's one band, a row per mod with something to say. `$` is followed only into functions in the file that
+// Hooked it, so each row and each button's action lives here beside the hook
+const commissionAtom = atom({ key: "commission", plugin: "genshin-mods" } as const, InitialState.commission);
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+const isCommissionExpandedAtom = atom(
+  { key: "isCommissionExpanded", plugin: "genshin-mods" } as const,
+  InitialState.isCommissionExpanded,
+);
+const isHandingOffAtom = atom({ key: "isHandingOff", plugin: "genshin-mods" } as const, InitialState.isHandingOff);
+const lastCacheRequestAtAtom = atom(
+  { key: "lastCacheRequestAt", plugin: "genshin-mods" } as const,
+  InitialState.lastCacheRequestAt,
+);
+const nowAtom = atom({ key: "now", plugin: "genshin-mods" } as const, InitialState.now);
+const waypointsAtom = atom({ key: "waypoints", plugin: "genshin-mods" } as const, InitialState.waypoints);
+
+// The engine's press slot takes no promise; every action here resolves each of its outcomes itself
+const press = (action: () => Promise<unknown>) => () => {
+  // oxlint-disable-next-line typescript/no-floating-promises -- The press slot is the engine's and returns nothing
+  action();
+};
+
+const StatusMarkMap = { completed: "✓", in_progress: "▸", pending: "·" } as const;
+
+// A fork re-sends the conversation's prefix, which renews the cache from the moment it is sent, and adds no row to the
+// Transcript
+const warmCache = async ($: EngineInterface) => {
+  const requestedAt = await $.clock.now();
+  const answer = await $.model.fork({ prompt: WARM_QUESTION });
+  if (!answer.isAnswered) {
+    $.ui.toast(`The cache was not warmed: ${answer.reason}.`);
+    return;
+  }
+
+  await update($, lastCacheRequestAtAtom, () => requestedAt);
+  await update($, nowAtom, () => requestedAt);
+};
+
+// The whole relay in one press: the clear waits for the handoff text, so a fork that fails clears nothing
+const relay = async ($: EngineInterface) => {
+  const answer = await $.model.fork({ prompt: HANDOFF_QUESTION });
+  if (answer.isAnswered && answer.text.trim()) {
+    await $.command.run({ command: "clear" });
+    await $.prompt.submit({ text: answer.text });
+  } else $.ui.toast(`The handoff was not written: ${answer.isAnswered ? "it came back empty" : answer.reason}.`);
+};
+
+// The relay is settled rather than awaited, so a clear or submit that rejects still brings the buttons back
+const handOff = async ($: EngineInterface) => {
+  await update($, isHandingOffAtom, () => true);
+  const [outcome] = await Promise.allSettled([relay($)]);
+  await update($, isHandingOffAtom, () => false);
+  if (outcome.status === "rejected") $.ui.toast(`The handoff failed: ${String(outcome.reason)}.`);
+};
+
+// The session character's colour, which the persona publishes, else the game's interface gold
+const readAccent = async ($: EngineInterface) =>
+  (await read($, { key: "character", plugin: "genshin-persona" } as const))?.color || ACCENT_COLOR;
+
+const drawResinRow = async (
+  $: EngineInterface,
+  e: RenderInput<"AbovePrompt">,
+  enabledMods: EnabledMods,
+  accent: string,
+): Promise<RenderElement | undefined> => {
+  const lastCacheRequestAt = await read($, lastCacheRequestAtAtom);
+  if (lastCacheRequestAt === 0 || !enabledMods.resin) return undefined;
+
+  const figures = getResinFigures(await $.session.usage(), lastCacheRequestAt, await read($, nowAtom));
+  const isHandingOff = await read($, isHandingOffAtom);
+  const { Box, Button, Text } = $.ui.resolve(e);
+  return Box({
+    children: [
+      Text({ bold: true, children: "Resin  ", color: accent }),
+      ...figures.map(({ isWarning, label, text }) =>
+        Text({ children: `${label} ${text}  `, color: isWarning ? "yellow" : undefined, dimColor: !isWarning }),
+      ),
+      isHandingOff
+        ? Text({ children: "writing the handoff…", dimColor: true })
+        : Box({
+            children: [
+              Button({ hotkey: "w", key: "resin-warm", label: "Warm", onPress: press(() => warmCache($)) }),
+              Button({
+                hotkey: "c",
+                key: "resin-compact",
+                label: "Compact",
+                onPress: press(() => $.session.compact()),
+              }),
+              Button({
+                hotkey: "h",
+                key: "resin-handoff",
+                label: "Handoff",
+                onPress: press(() => handOff($)),
+                variant: "primary",
+              }),
+            ],
+            flexDirection: "row",
+          }),
+    ],
+    flexDirection: "row",
+    flexWrap: "wrap",
+  });
+};
+
+const drawCommissionRow = async (
+  $: EngineInterface,
+  e: RenderInput<"AbovePrompt">,
+  enabledMods: EnabledMods,
+  accent: string,
+): Promise<RenderElement | undefined> => {
+  const commission = await read($, commissionAtom);
+  if (commission.tasks.length === 0 || !enabledMods.commission) return undefined;
+
+  const isExpanded = await read($, isCommissionExpandedAtom);
+  const shownTasks = isExpanded
+    ? commission.tasks.slice(0, MAX_SHOWN_TASKS)
+    : commission.tasks.filter(({ status }) => status === "in_progress");
+  const { Box, Button, Text } = $.ui.resolve(e);
+  return Box({
+    children: [
+      Box({
+        children: [
+          Text({ bold: true, children: "Commission  ", color: accent }),
+          Text({ children: `${getCommissionSummary(commission, await read($, nowAtom))}  `, wrap: "truncate-end" }),
+          Button({
+            hotkey: "g",
+            key: "commission-expand",
+            label: isExpanded ? "Fewer" : "All tasks",
+            onPress: press(() => update($, isCommissionExpandedAtom, (value) => !value)),
+            plain: true,
+          }),
+        ],
+        flexDirection: "row",
+      }),
+      ...shownTasks.map(({ status, subject }) =>
+        Text({
+          children: `  ${StatusMarkMap[status]} ${subject}`,
+          dimColor: status !== "in_progress",
+          wrap: "truncate-end",
+        }),
+      ),
+    ],
+    flexDirection: "column",
+  });
+};
+
+const drawWaypointsRow = async (
+  $: EngineInterface,
+  e: RenderInput<"AbovePrompt">,
+  enabledMods: EnabledMods,
+  accent: string,
+): Promise<RenderElement | undefined> => {
+  const waypoints = await read($, waypointsAtom);
+  if (waypoints.length === 0 || e.props.isWorking || !enabledMods.waypoints) return undefined;
+
+  const { Box, Button, Text } = $.ui.resolve(e);
+  return Box({
+    children: [
+      Text({ bold: true, children: "Waypoints", color: accent }),
+      ...waypoints.map((waypoint, index) =>
+        Button({
+          hotkey: `${index + 1}`,
+          key: `waypoint-${index}`,
+          label: waypoint,
+          onPress: press(() => $.prompt.submit({ text: waypoint })),
+          plain: true,
+        }),
+      ),
+      Button({
+        key: "waypoints-dismiss",
+        label: "Dismiss",
+        onPress: press(() => update($, waypointsAtom, () => InitialState.waypoints)),
+        plain: true,
+        role: "dismiss",
+      }),
+    ],
+    flexDirection: "column",
+  });
+};
+
+// The veil's marker first, so a recording never runs with it off unnoticed, and the engine's own band whenever no
+// Mod has anything to say
+export const registerBand = (on: On): void => {
+  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
+    if (e.props.hasSurvey) return next(e);
+
+    const enabledMods = await read($, enabledModsAtom);
+    const accent = await readAccent($);
+    const rows = (
+      await Promise.all([
+        drawResinRow($, e, enabledMods, accent),
+        drawCommissionRow($, e, enabledMods, accent),
+        drawWaypointsRow($, e, enabledMods, accent),
+      ])
+    ).filter((row) => row !== undefined);
+    if (rows.length === 0 && !enabledMods.veil) return next(e);
+
+    const { Box, Text } = $.ui.resolve(e);
+    const marker = enabledMods.veil
+      ? [Text({ bold: true, children: "● Veil on: values are hidden on screen", color: "red" })]
+      : [];
+    return Box({ children: [...marker, ...rows], flexDirection: "column" });
+  });
+};

package/src/services/commission/foldTaskCall.ts

@@ -0,0 +1,26 @@
+import type { CommissionTask } from "../../../types";
+import type { TaskCall } from "../../models/TaskCall";
+
+import { TaskTool } from "../../models/TaskTool";
+
+const DELETED_STATUS = "deleted";
+
+export const foldTaskCall = (tasks: CommissionTask[], call: TaskCall): CommissionTask[] => {
+  switch (call.tool) {
+    case TaskTool.TaskCreate:
+      return [...tasks, { id: call.id, status: "pending", subject: call.subject }];
+    case TaskTool.TaskUpdate: {
+      const { id, status, subject } = call;
+      if (status === DELETED_STATUS) return tasks.filter((task) => task.id !== id);
+      else
+        return tasks.map((task) =>
+          task.id === id ? { ...task, status: status ?? task.status, subject: subject ?? task.subject } : task,
+        );
+    }
+    // A todo list carries no ids and is written whole each time, so its place in the list is its id
+    case TaskTool.TodoWrite:
+      return call.todos.map(({ content, status }, index) => ({ id: `${index}`, status, subject: content }));
+    default:
+      return tasks;
+  }
+};

package/src/services/commission/registerCommission.ts

@@ -0,0 +1,48 @@
+import type { EngineInterface, On } from "claude-code";
+
+import { atom, read, update } from "claude-code";
+
+import type { TaskCall } from "../../models/TaskCall";
+
+import { TaskTool } from "../../models/TaskTool";
+import { InitialState } from "../InitialState";
+import { foldTaskCall } from "./foldTaskCall";
+
+const commissionAtom = atom({ key: "commission", plugin: "genshin-mods" } as const, InitialState.commission);
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+const lastPromptAtom = atom({ key: "lastPrompt", plugin: "genshin-mods" } as const, InitialState.lastPrompt);
+
+// A task tool's call folded in once the tool has answered, opening the commission on its first task with the goal
+// Read off the prompt that started the turn
+const fold = async ($: EngineInterface, call: TaskCall) => {
+  if (!(await read($, enabledModsAtom)).commission) return;
+  const now = await $.clock.now();
+  const lastPrompt = await read($, lastPromptAtom);
+  await update($, commissionAtom, (commission) => ({
+    goal: commission.goal || (lastPrompt.split("\n").find(Boolean) ?? "").trim(),
+    openedAt: commission.openedAt || now,
+    tasks: foldTaskCall(commission.tasks, call),
+  }));
+};
+
+export const registerCommission = (on: On): void => {
+  on("tool.call", { tool: "TaskCreate" }, async ($, e, next) => {
+    const result = await next(e);
+    if (!result.deny && !result.isError && result.result)
+      await fold($, { id: result.result.task.id, subject: e.subject, tool: TaskTool.TaskCreate });
+    return result;
+  });
+
+  on("tool.call", { tool: "TaskUpdate" }, async ($, e, next) => {
+    const result = await next(e);
+    if (!result.deny && !result.isError)
+      await fold($, { id: e.taskId, status: e.status, subject: e.subject, tool: TaskTool.TaskUpdate });
+    return result;
+  });
+
+  on("tool.call", { tool: "TodoWrite" }, async ($, e, next) => {
+    const result = await next(e);
+    if (!result.deny && !result.isError) await fold($, { todos: e.todos, tool: TaskTool.TodoWrite });
+    return result;
+  });
+};

package/src/services/constants.ts

@@ -0,0 +1,26 @@
+// The game's own interface gold, the accent wherever the persona publishes no character
+export const ACCENT_COLOR = "#d3bc8e";
+// The prompt cache's lifetime, which the engine chooses and does not report: an hour on a subscription
+export const CACHE_LIFETIME_MS: number = Temporal.Duration.from({ hours: 1 }).total("milliseconds");
+export const CACHE_LOW_MS: number = Temporal.Duration.from({ minutes: 10 }).total("milliseconds");
+export const CACHE_WARNING_MS: number = Temporal.Duration.from({ minutes: 5 }).total("milliseconds");
+export const CLOCK_TICK_MS: number = Temporal.Duration.from({ minutes: 1 }).total("milliseconds");
+export const USAGE_WARNING_PERCENTAGE = 80;
+export const MAX_WAYPOINTS = 3;
+export const MAX_SHOWN_TASKS = 8;
+// Whole minutes as the band writes them, `12m`
+export const MINUTE_FORMATTER: Intl.NumberFormat = new Intl.NumberFormat("en", {
+  style: "unit",
+  unit: "minute",
+  unitDisplay: "narrow",
+});
+export const WARD_WINDOW_MS: number = Temporal.Duration.from({ minutes: 30 }).total("milliseconds");
+export const NO_WAYPOINTS_ANSWER = "NONE";
+// oxlint-disable-next-line typescript/no-inferrable-types -- `isolatedDeclarations` demands the annotation this template literal would otherwise infer
+export const WAYPOINTS_QUESTION: string = `Leave the conversation as it is and answer one side question. List the next steps worth taking from here, at most ${MAX_WAYPOINTS}, most useful first: each one short imperative line the person could send you as their next prompt, with no numbering, no markup and nothing else. When the work is finished or waits on the person, answer ${NO_WAYPOINTS_ANSWER}.`;
+export const WARM_QUESTION = "Answer with the one word OK.";
+export const HANDOFF_QUESTION =
+  "Write a handoff of this session for a fresh conversation that will carry on the work with no other context. Write it as the prompt that conversation starts with: the goal, what is done, what is next in order, the files, commands and decisions that matter with their reasons, and any open question. Be complete but compact, plain markdown, nothing before or after it.";
+export const VEIL_SECTION_ID = "genshin-mods-veil";
+export const VEIL_SYSTEM_SECTION =
+  "Recording mode is on: the screen is being recorded or shared. Never write an email address, a phone number, a money amount, an API key, a token or a password in a reply; write a placeholder such as [email], [phone], [amount] or [secret] instead, even when asked for the value. Tool calls still use the real values.";

package/src/services/registerLifecycle.ts

@@ -0,0 +1,154 @@
+import type { EngineInterface, On } from "claude-code";
+
+import { atom, read, update } from "claude-code";
+
+import type { EnabledMods } from "../../types";
+
+import { CACHE_WARNING_MS, CLOCK_TICK_MS, VEIL_SECTION_ID, VEIL_SYSTEM_SECTION, WAYPOINTS_QUESTION } from "./constants";
+import { InitialState } from "./InitialState";
+import { ModDescriptionMap, ModNames } from "./ModDescriptionMap";
+import { getCacheRemainingMs } from "./resin/getCacheRemainingMs";
+import { parseWaypoints } from "./waypoints/parseWaypoints";
+
+const commissionAtom = atom({ key: "commission", plugin: "genshin-mods" } as const, InitialState.commission);
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+const isCommissionExpandedAtom = atom(
+  { key: "isCommissionExpanded", plugin: "genshin-mods" } as const,
+  InitialState.isCommissionExpanded,
+);
+const lastPromptAtom = atom({ key: "lastPrompt", plugin: "genshin-mods" } as const, InitialState.lastPrompt);
+const lastCacheRequestAtAtom = atom(
+  { key: "lastCacheRequestAt", plugin: "genshin-mods" } as const,
+  InitialState.lastCacheRequestAt,
+);
+const nowAtom = atom({ key: "now", plugin: "genshin-mods" } as const, InitialState.now);
+const waypointsAtom = atom({ key: "waypoints", plugin: "genshin-mods" } as const, InitialState.waypoints);
+
+// The events a plugin may hook once with no matcher, each hooked here for every mod, with the commands that switch
+// The mods. Neither variable is drawn: the expiry already warned about, so each warns once, and whether a turn is
+// Renewing the cache itself, when no warning is owed
+let warnedLastCacheRequestAt = 0;
+let isTurnRunning = false;
+
+const tick = async ($: EngineInterface) => {
+  const now = await $.clock.now();
+  await update($, nowAtom, () => now);
+  const lastCacheRequestAt = await read($, lastCacheRequestAtAtom);
+  const remainingMs = getCacheRemainingMs(lastCacheRequestAt, now);
+  const isWarningDue = lastCacheRequestAt > 0 && remainingMs > 0 && remainingMs <= CACHE_WARNING_MS;
+  if (
+    !isWarningDue ||
+    isTurnRunning ||
+    warnedLastCacheRequestAt === lastCacheRequestAt ||
+    !(await read($, enabledModsAtom)).resin
+  )
+    return;
+
+  warnedLastCacheRequestAt = lastCacheRequestAt;
+  $.ui.toast("The prompt cache goes cold in five minutes: warm it, compact or hand off from the band.");
+};
+
+const suggestWaypoints = async ($: EngineInterface) => {
+  const answer = await $.model.fork({ prompt: WAYPOINTS_QUESTION });
+  if (answer.isAnswered) await update($, waypointsAtom, () => parseWaypoints(answer.text));
+};
+
+const closeCommission = async ($: EngineInterface) => {
+  await update($, commissionAtom, () => InitialState.commission);
+  await update($, isCommissionExpandedAtom, () => InitialState.isCommissionExpanded);
+};
+
+export const registerLifecycle = (on: On): void => {
+  // The bare command flips a mod and an argument sets it, kept in the store so it holds for every later session
+  for (const name of ModNames)
+    on("command.run", { command: name }, async ($, e) => {
+      const argument = e.args.trim().toLowerCase();
+      const enabledMods = await update($, enabledModsAtom, (value) => ({
+        ...value,
+        [name]: argument ? argument === "on" : !value[name],
+      }));
+      await $.store.set(enabledModsAtom.ref.key, enabledMods);
+      return { text: `${name} is ${enabledMods[name] ? "on" : "off"}.` };
+    });
+
+  on("session.start", async ($, e, next) => {
+    const stored = (await $.store.get(enabledModsAtom.ref.key)) as Partial<EnabledMods> | undefined;
+    await update($, enabledModsAtom, (value) => ({ ...value, ...stored }));
+    await Promise.all(
+      ModNames.map((name) =>
+        $.command.register({ argumentHint: "[on|off]", description: ModDescriptionMap[name], name }),
+      ),
+    );
+    // oxlint-disable-next-line unicorn/no-array-method-this-argument -- The engine's clock, not Array.prototype.every
+    $.clock.every(CLOCK_TICK_MS, () => {
+      // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise, and every call in the tick resolves
+      tick($);
+    });
+    return next(e);
+  });
+
+  // A `/clear` or a resume carries on in this process under another conversation, with no `session.start` for it, so
+  // Nothing the old one showed is kept
+  on("session.end", async ($, e, next) => {
+    if (e.reason === "clear" || e.reason === "resume") {
+      await update($, lastCacheRequestAtAtom, () => InitialState.lastCacheRequestAt);
+      await update($, waypointsAtom, () => InitialState.waypoints);
+      await closeCommission($);
+    }
+
+    return next(e);
+  });
+
+  // The prompt is kept as the goal of a commission this turn may open, and a commission whose every task is done has
+  // Shown its finished row since the last turn ended, so it closes as the person moves on
+  on("prompt.submit", async ($, e, next) => {
+    await update($, waypointsAtom, () => InitialState.waypoints);
+    await update($, lastPromptAtom, () => e.text);
+    const { tasks } = await read($, commissionAtom);
+    if (tasks.length > 0 && tasks.every(({ status }) => status === "completed")) await closeCommission($);
+    return next(e);
+  });
+
+  // While the veil is on, the model is told to write placeholders too, so a reply never holds a value to hide
+  on("prompt.compose", async ($, e, next) => {
+    const result = await next(e);
+    if ((await read($, enabledModsAtom)).veil)
+      return { sections: [...result.sections, { id: VEIL_SECTION_ID, scope: "session", text: VEIL_SYSTEM_SECTION }] };
+    else return result;
+  });
+
+  on("turn.start", (_$, e, next) => {
+    isTurnRunning = true;
+    return next(e);
+  });
+
+  // The cache's lifetime runs from the request that read or wrote it, so each of the main conversation's requests
+  // Restarts the countdown as it is sent, not as its reply ends
+  on("turn.step", async function* ($, e, next) {
+    if (e.agentId === undefined) {
+      const now = await $.clock.now();
+      await update($, lastCacheRequestAtAtom, () => now);
+      await update($, nowAtom, () => now);
+    }
+
+    return yield* next(e);
+  });
+
+  // An answer of the main conversation asks for waypoints off the turn's own dispatch, so the fork never holds the
+  // Turn's end or the next prompt behind it
+  on("turn.complete", async ($, e, next) => {
+    const result = await next(e);
+    if (e.agentId !== undefined) return result;
+
+    isTurnRunning = false;
+
+    const now = await $.clock.now();
+    await update($, nowAtom, () => now);
+    if (e.reason === "answer" && (await read($, enabledModsAtom)).waypoints)
+      $.clock.after(0, () => {
+        // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise, and a fork resolves every outcome rather than rejecting
+        suggestWaypoints($);
+      });
+    return result;
+  });
+};

package/src/services/resin/getCacheRemainingMs.ts

@@ -0,0 +1,4 @@
+import { CACHE_LIFETIME_MS } from "../constants";
+
+export const getCacheRemainingMs = (lastCacheRequestAt: number, now: number): number =>
+  Math.max(0, lastCacheRequestAt + CACHE_LIFETIME_MS - now);

package/src/services/resin/getResinFigures.ts

@@ -0,0 +1,44 @@
+import type { SessionUsage } from "claude-code";
+
+import type { ResinFigure } from "../../models/ResinFigure";
+
+import { CACHE_LOW_MS, MINUTE_FORMATTER, USAGE_WARNING_PERCENTAGE } from "../constants";
+import { getCacheRemainingMs } from "./getCacheRemainingMs";
+
+const TOKEN_FORMATTER = new Intl.NumberFormat("en", { maximumFractionDigits: 1, notation: "compact" });
+const USD_CURRENCY_FORMATTER = new Intl.NumberFormat("en", { currency: "USD", style: "currency" });
+const RateLimitLabelMap: Record<string, string> = { five_hour: "5h", seven_day: "7d" };
+
+// The row's figures in the order they are read: the cache only once a request has started its clock, and each other
+// Figure only once the engine has a reading, since a zero it never measured would read as a fact
+export const getResinFigures = (
+  { context, cost, rateLimits }: Pick<SessionUsage, "context" | "cost" | "rateLimits">,
+  lastCacheRequestAt: number,
+  now: number,
+): ResinFigure[] => {
+  const figures: ResinFigure[] = [];
+  if (lastCacheRequestAt > 0) {
+    const remainingMs = getCacheRemainingMs(lastCacheRequestAt, now);
+    const remainingMinutes = Math.ceil(Temporal.Duration.from({ milliseconds: remainingMs }).total("minutes"));
+    const remaining = remainingMs > 0 ? MINUTE_FORMATTER.format(remainingMinutes) : "cold";
+    const resend = context.tokens === undefined ? "" : ` · re-sends ${TOKEN_FORMATTER.format(context.tokens)}`;
+    figures.push({ isWarning: remainingMs < CACHE_LOW_MS, label: "cache", text: `${remaining}${resend}` });
+  }
+
+  if (context.tokens !== undefined)
+    figures.push({
+      isWarning: (context.percent ?? 0) >= USAGE_WARNING_PERCENTAGE,
+      label: "context",
+      text: `${TOKEN_FORMATTER.format(context.tokens)}/${TOKEN_FORMATTER.format(context.window)}`,
+    });
+
+  for (const { kind, percentUsed } of rateLimits)
+    figures.push({
+      isWarning: percentUsed >= USAGE_WARNING_PERCENTAGE,
+      label: RateLimitLabelMap[kind] ?? kind,
+      text: `${Math.round(percentUsed)}%`,
+    });
+
+  if (cost) figures.push({ isWarning: false, label: "cost", text: USD_CURRENCY_FORMATTER.format(cost.usd) });
+  return figures;
+};

package/src/services/veil/registerVeil.ts

@@ -0,0 +1,32 @@
+import type { On } from "claude-code";
+
+import { atom, read } from "claude-code";
+
+import { InitialState } from "../InitialState";
+import { veilText } from "./veilText";
+import { veilValue } from "./veilValue";
+
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+
+// Only the drawing changes: the transcript and what the model reads keep the real values. Each read subscribes the
+// Row, so switching the veil redraws every row already on screen. The instruction the veil adds to the system prompt is
+// An unmatched hook, so it is the lifecycle file's
+export const registerVeil = (on: On): void => {
+  on("ui.render", { component: "AssistantMessage" }, async ($, e, next) =>
+    (await read($, enabledModsAtom)).veil
+      ? next({ ...e, props: { ...e.props, text: veilText(e.props.text) } })
+      : next(e),
+  );
+
+  on("ui.render", { component: "UserMessage" }, async ($, e, next) =>
+    (await read($, enabledModsAtom)).veil
+      ? next({ ...e, props: { ...e.props, text: veilText(e.props.text) } })
+      : next(e),
+  );
+
+  on("ui.render", { component: "ToolResult" }, async ($, e, next) =>
+    (await read($, enabledModsAtom)).veil
+      ? next({ ...e, props: { ...e.props, output: veilValue(e.props.output) } })
+      : next(e),
+  );
+};

package/src/services/veil/veilText.ts

@@ -0,0 +1,25 @@
+// A placeholder holds no digit, at sign or currency sign, so no pattern matches what another wrote and the order they
+// Run in changes nothing. A secret is a known key prefix; a long run mixing letters and digits, read from the run's
+// Start alone so a long run of neither is scanned once rather than again from every position in it; or whatever
+// Follows a password's own label, however short
+const VeilPatternMap = new Map<string, RegExp>([
+  [
+    "[amount]",
+    /[$€£¥₹]\s?\d[\d,]*(?:\.\d+)?(?:\s?[KkMmBb]\b)?|\b(?:USD|EUR|GBP|CAD|AUD|JPY|CNY)\s?\d[\d,]*(?:\.\d+)?|\b\d[\d,]*(?:\.\d+)?\s?(?:USD|EUR|GBP|CAD|AUD|JPY|CNY)\b/gu,
+  ],
+  ["[email]", /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/gu],
+  [
+    "[phone]",
+    /\+\d{1,3}[\s.-]?\(?\d{1,4}\)?(?:[\s.-]?\d{2,4}){2,4}|\(\d{3}\)\s?\d{3}[\s.-]\d{4}|\b\d{3}[\s.-]\d{3}[\s.-]\d{4}\b/gu,
+  ],
+  [
+    "[secret]",
+    /\b(?:sk-[\w-]{16,}|gh[opsu]_\w{16,}|github_pat_\w{16,}|xox[abpr]-[\w-]{10,}|AKIA[0-9A-Z]{16}|eyJ[\w-]+\.[\w-]+\.[\w-]+)|(?<![\w+=-])(?=[\w+=-]*\d)(?=[\w+=-]*[A-Za-z])[\w+=-]{32,}|(?<=\b(?:[Pp]assword|PASSWORD|passwd|pwd)\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|\S+)/gu,
+  ],
+]);
+
+export const veilText = (text: string): string => {
+  let veiled = text;
+  for (const [placeholder, pattern] of VeilPatternMap) veiled = veiled.replaceAll(pattern, placeholder);
+  return veiled;
+};

package/src/services/veil/veilValue.ts

@@ -0,0 +1,11 @@
+import { veilText } from "./veilText";
+
+// A tool's output is whatever the tool recorded, so every string inside it is veiled and its shape is kept, which is
+// What the engine draws the result from
+export const veilValue = (value: unknown): unknown => {
+  if (typeof value === "string") return veilText(value);
+  else if (Array.isArray(value)) return value.map((item) => veilValue(item));
+  else if (value !== null && typeof value === "object")
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, veilValue(item)]));
+  else return value;
+};

package/src/services/ward/getCollidingRecord.ts

@@ -0,0 +1,11 @@
+import type { WardRecord } from "../../../types";
+
+import { WARD_WINDOW_MS } from "../constants";
+
+// Another session's edit inside the window is the one record that asks; a session's own edits never do
+export const getCollidingRecord = (
+  record: undefined | WardRecord,
+  sessionId: string,
+  now: number,
+): undefined | WardRecord =>
+  record && record.sessionId !== sessionId && now - record.editedAt < WARD_WINDOW_MS ? record : undefined;

package/src/services/ward/getRecordsWithEdit.ts

@@ -0,0 +1,15 @@
+import type { WardRecord } from "../../../types";
+
+import { WARD_WINDOW_MS } from "../constants";
+
+// The edit recorded and every record past the window dropped, so the file holds the last half hour and no more
+export const getRecordsWithEdit = (
+  records: Record<string, WardRecord>,
+  path: string,
+  record: WardRecord,
+): Record<string, WardRecord> => ({
+  ...Object.fromEntries(
+    Object.entries(records).filter(([, { editedAt }]) => record.editedAt - editedAt < WARD_WINDOW_MS),
+  ),
+  [path]: record,
+});

package/src/services/ward/registerWard.ts

@@ -0,0 +1,82 @@
+import type { EngineInterface, On, ToolCallResult } from "claude-code";
+
+import { atom, read } from "claude-code";
+
+import type { WardRecord } from "../../../types";
+
+import { WardAnswer, WardAnswers } from "../../models/WardAnswer";
+import { InitialState } from "../InitialState";
+import { getCollidingRecord } from "./getCollidingRecord";
+import { getRecordsWithEdit } from "./getRecordsWithEdit";
+
+const enabledModsAtom = atom({ key: "enabledMods", plugin: "genshin-mods" } as const, InitialState.enabledMods);
+const AGE_FORMATTER = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+
+// One file every session on the machine reads afresh, beside the persona's state, so an edit made a moment ago in
+// Another session is always seen
+const readRecordsPath = async ($: EngineInterface) => {
+  const home = (await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")) ?? "";
+  return `${home}/.claude/genshin-mods/ward.json`;
+};
+
+const readRecords = async ($: EngineInterface, path: string): Promise<Record<string, WardRecord>> =>
+  (await $.fs.exists(path))
+    ? // oxlint-disable-next-line no-restricted-properties -- The records hold numbers and ids, no date, and a mod cannot import the shared reviver
+      (JSON.parse(await $.fs.read(path)) as Record<string, WardRecord>)
+    : {};
+
+// Before the edit: the question, when another session's record calls for one. After it: the edit recorded
+const ward = async (
+  $: EngineInterface,
+  path: string,
+  proceed: () => Promise<ToolCallResult>,
+): Promise<ToolCallResult> => {
+  if (!(await read($, enabledModsAtom)).ward) return proceed();
+  const recordsPath = await readRecordsPath($);
+  const sessionId = await $.session.id();
+  const now = await $.clock.now();
+  const collision = getCollidingRecord((await readRecords($, recordsPath))[path], sessionId, now);
+  // A session nobody watches has nobody to ask, and a guard that blocks unattended work is worse than none
+  if (collision && (await $.session.surfaces()).length > 0) {
+    const minutes = -Math.round(Temporal.Duration.from({ milliseconds: now - collision.editedAt }).total("minutes"));
+    const age = AGE_FORMATTER.format(minutes, "minute");
+    const answer = await $.ui.ask(`Another session edited ${path} ${age}. Edit it here too?`, {
+      header: "Ward",
+      options: WardAnswers,
+    });
+    if (answer === WardAnswer.Worktree)
+      return {
+        deny: `The person asked to move this work into a git worktree before editing ${path}: another session changed it ${age}. Enter a worktree, then carry on there.`,
+      };
+    else if (answer === WardAnswer.Cancel)
+      return { deny: `The person stopped this edit: another session changed ${path} ${age}.` };
+    else if (answer !== WardAnswer.Proceed) return { deny: `The person stopped this edit and said: ${answer}` };
+  }
+
+  const result = await proceed();
+  if (!result.deny && !result.isError) {
+    const records = getRecordsWithEdit(await readRecords($, recordsPath), path, {
+      editedAt: await $.clock.now(),
+      sessionId,
+    });
+    await $.fs.write(recordsPath, JSON.stringify(records));
+  }
+
+  return result;
+};
+
+// Any failure lets the edit through, the question dismissed or the record unreadable alike: a guard that blocked on
+// Its own failure would block every edit after it, and Cancel is the person's way to stop one. `next` is replay-safe
+// Here, so an edit the hook had already made is not made twice
+const letEditThrough = <E, R>(_$: EngineInterface, e: E, next: (e: E) => R): R => next(e);
+
+export const registerWard = (on: On): void => {
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on("tool.call", { tool: "Edit" }, ($, e, next) => ward($, e.file_path, () => next(e))).catch(letEditThrough);
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on("tool.call", { tool: "Write" }, ($, e, next) => ward($, e.file_path, () => next(e))).catch(letEditThrough);
+  // eslint-disable-next-line no-restricted-syntax -- The engine's registration handler, run when the hook rejects, not a promise
+  on("tool.call", { tool: "NotebookEdit" }, ($, e, next) => ward($, e.notebook_path, () => next(e))).catch(
+    letEditThrough,
+  );
+};

package/src/services/waypoints/parseWaypoints.ts

@@ -0,0 +1,12 @@
+import { MAX_WAYPOINTS, NO_WAYPOINTS_ANSWER } from "../constants";
+
+const LIST_MARKER_REGEX = /^(?:[-*•]|\d+[.)])\s+/u;
+
+// The fork answers in prose it was asked to keep to lines, so a list marker it added anyway is dropped rather than
+// Sent back as part of the prompt, and an answer of none, or nothing, leaves no step
+export const parseWaypoints = (answer: string): string[] =>
+  answer
+    .split("\n")
+    .map((line) => line.trim().replace(LIST_MARKER_REGEX, "").trim())
+    .filter((line) => line && line !== NO_WAYPOINTS_ANSWER)
+    .slice(0, MAX_WAYPOINTS);

package/types/index.d.ts

@@ -0,0 +1,43 @@
+// The plugin's state contract, the one self-contained file the engine validates the module's `$.state` keys against,
+// So the value types the modules share are declared here too
+export interface Commission {
+  goal: string;
+  openedAt: number;
+  tasks: CommissionTask[];
+}
+
+export interface CommissionTask {
+  id: string;
+  // oxlint-disable-next-line literal-union/no-string-literal-union -- The engine's own task statuses, as its task tools spell them
+  status: "completed" | "in_progress" | "pending";
+  subject: string;
+}
+
+// Which mods are on, each switched by its own command and kept in the store as one record
+export interface EnabledMods {
+  commission: boolean;
+  resin: boolean;
+  veil: boolean;
+  ward: boolean;
+  waypoints: boolean;
+}
+
+export interface WardRecord {
+  editedAt: number;
+  sessionId: string;
+}
+
+declare module "claude-code" {
+  interface PluginState {
+    "genshin-mods": {
+      commission: Commission;
+      enabledMods: EnabledMods;
+      isCommissionExpanded: boolean;
+      isHandingOff: boolean;
+      lastCacheRequestAt: number;
+      lastPrompt: string;
+      now: number;
+      waypoints: string[];
+    };
+  }
+}