/LifeOSHooks

name: LifeOSHooks
metadata:
  short-description: "Inspect and validate the LifeOS function-hook plugin, banner rendering, type declarations, and core sync. Excludes command-hook edits and Relay diagnostics."
version: 1.0.38
description: "The LifeOS function-hook plugin: check it is armed, explain why a line or banner was or was not drawn, regenerate its types after a Claude Code update, sync pure-core copies, run its probes. USE WHEN function hooks, LifeOSHooks, the plugin, hook-drawn lines, banner missing, memory line missing, plugin types, /plugin-types, plugin validate, is the plugin loaded, hooks module. NOT FOR the command hooks under hooks/ (edit directly), the Pulse dashboard (Pulse), or Relay diagnostics (the relay skill)."

LifeOSHooks

Diagnoses the LifeOS function-hook plugin, the in-process half of the hook system (one hooks module Claude Code's function-hook runtime loads once per interactive session; the command hooks under `hooks/` remain the out-of-process half): whether it is armed, why a line or banner did or did not draw, and keeping its types and pure-core copies current. State of record: `LIFEOS/FUNCTIONHOOKS/ISA.md` (maintainer-side; the ISA does not ship).

Ideal State

• A status answer ("is the plugin loaded and working") says armed or not, on which build, and names its evidence: this session's stamp in `MEMORY/STATE/function-hooks/<session>.json` (the command hooks read it to go quiet on the lines the plugin draws), `hooks/lib/build.ts`, and for a headless check the probe's debug log. A verdict with no evidence fails.
• The check holds the plugin to its standing properties: armed in every interactive session on the declared build, and in a headless session (`-p`, the SDK, Relay) every hook a passthrough with nothing drawn.
• A "why did or didn't this draw" answer names the surface that owns the line (§ References) and the cause it found; a guess is labelled as one.
• After a Claude Code update, `.claude/types/claude-code.d.ts` was written by the running build, `hooks/lib/build.ts` names that build, and the typecheck and tests pass; the answer names the old and the new build.
• `claude plugin validate <plugin dir>` passes; its hooked-events list matches the ISA's closed criteria (`/ic` checks this).
• The pure-core copies under `hooks/lib/` equal their sources (`tests/parity.test.ts`; source tree only, not in the public release payload).

Anti-criteria

• No diagnostic `$.ui.log` line is ever added to the live module, not even for one probe run. In any session that loads the edited module (§ Gotchas, reload), every `$.ui.log` line prints into the principal's transcript: one temporary diagnostic line, printed once per tool call, filled the screen (2026-10-02). Probe in a copy run with `claude --plugin-dir <copy>` and `--debug-file`, or put the diagnostic in `pushEvent`, which only reaches the events log.
• A report never tells the principal a save already reloaded an open session; a check of a change in a live session starts with `/reload-plugins` (2026-10-11: a pane removed on disk kept drawing its old text in open sessions until a reload).

Intent Routing

This skill is its own single intent; its context files:

| File | Read when | |------|-----------| | `References/ModuleGotchas.md` | editing the hooks module, or a draw, repaint or hand-over question the § References list below does not answer: engine API shapes, registration rules, scrollback and repaint behaviour | | `Setup.md` | installing the plugin on a new machine, or filling in this install's loading topology in the USER Config.md |

Tool contract

• Validate: `claude plugin validate <plugin dir>` (lists every hooked event and `$` call).
• Typecheck: `cd <plugin dir> && bunx tsc --noEmit -p tsconfig.json`.
• Tests (source tree only; they are not in the public release payload): `cd <plugin dir> && bun test ./tests`. Running them from the install root hit EMFILE (2026-10-01).
• Sync cores after editing a source: `bun <plugin dir>/scripts/SyncCores.ts`.
• After a Claude Code update: the plugin declarations are Claude Code's own and never ship with the plugin; each install generates its own from the build it runs. `/plugin-types` is gone since 2.1.287, so the source is the running build's `plugin-authoring` skill, which provides that build's declarations when it loads: put them at `.claude/types/claude-code.d.ts` (their first line names the build), set `TYPES_BUILD` in `hooks/lib/build.ts`, typecheck, and run the tests (2026-10-01). The MCP declarations (`.claude/types/claude-code-mcp.d.ts`) copy connector tool descriptions verbatim, and some connectors (Slack) embed the logged-in account's user id in them; replace any such id with `<slack-user-id>` before the file is committed (2026-10-13).
• Headless probe: `claude -p "Reply OK." --plugin-dir <plugin dir> --debug-file <log> --max-turns 1`, then grep the log for `settled` and `failed to load`.
• Host I/O from the module goes only through `LIFEOS/TOOLS/HookBridge.ts <verb>`.

Setup

Needs Claude Code at or above the build named in `hooks/lib/build.ts` (`MIN_BUILD`) and bun. The plugin holds no personal data; its one user setting is `forceBackground` in its plugin manifest (`.claude-plugin/plugin.json`, or the marketplace entry when the install keeps the manifest there), off by default.

1. Load it. Either put this folder under the skills directory, where Claude Code loads it as `LifeOSHooks@skills-dir` and hot-reloads it on every save, or list it in a folder marketplace (`claude plugin marketplace add <folder>`, then `claude plugin install <name>@<marketplace>`) and disable the `skills-dir` copy so only one loads. 2. Record how it loads: with a folder marketplace, fill in `<configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/LifeOSHooks/Config.md` (marketplace, mods loaded from it, disabled `skills-dir` copies, reload consequence); `Setup.md` § Fill in documents every line. Loaded straight from the skills folder, the file is optional. 3.