@polderlabs/bizar 10.7.2 → 10.10.0

package/.claude/commands/tailscale-serve.md

@@ -1,100 +1,14 @@
 ---
-description: Authenticate Tailscale Serve and expose a local port on your tailnet
-allowed-tools: Read, Bash
+description: Expose an explicitly selected local service through Tailscale Serve with confirmation.
 ---
 
-# Tailscale Serve Command
+# Tailscale Serve
 
-Authenticate and configure Tailscale Serve to expose a local service on your
-tailnet. Auto-detects whether Serve is enabled on the tailnet and either
-provisions HTTPS automatically or surfaces the admin-enable URL clearly.
+This command is generic and does not start any Bizar service.
 
-## Usage
-
-```
-/tailscale-serve                 # expose port 8765 (the BizarHarness dashboard default)
-/tailscale-serve 3000            # expose port 3000
-/tailscale-serve --status        # show current serve config, no changes
-/tailscale-serve --reset         # remove the current serve config
-```
-
-The full arguments are available as `$ARGUMENTS` (and `$1` for the port).
-Parse them and route to the matching step below.
-
-## Steps
-
-1. **Parse the argument**: first arg is the port (default `8765`). If `--status`, run step 3 only. If `--reset`, run step 6 only.
-
-2. **Verify the local port is listening**:
-   ```bash
-   ss -lntp 2>/dev/null | grep -E ":${PORT}\b" || curl -sS -o /dev/null -w "HTTP %{http_code}\n" --max-time 2 http://127.0.0.1:${PORT}/
-   ```
-   If the port is not open, tell the user clearly which command starts the
-   service (e.g. `npm run host:start` for the BizarHarness demo, or
-   `python3 -m http.server 8765` for a pam static server). Do not proceed
-   without an upstream.
-
-3. **Check current Tailscale Serve status**:
-   ```bash
-   tailscale serve status
-   tailscale status --json | jq -r '.Self.DNSName, .Self.TailscaleIPs[0]'
-   ```
-   Capture the MagicDNS name and the Tailscale IP. The DNS name will look
-   like `devbox.tail2cdf4d.ts.net` (trim the trailing dot).
-
-4. **If already configured** (status shows `https://`):
-   - Print the current config
-   - Print the existing endpoints
-   - **Stop** — do not re-configure
-
-5. **Try to enable Serve** (with a hard timeout — it may try to open a browser):
-   ```bash
-   timeout 5 tailscale serve --bg --https=443 "http://127.0.0.1:${PORT}" 2>&1
-   ```
-   - **On success**: print the new config, print the `https://<dnsname>/` endpoint.
-   - **If the output contains "Serve is not enabled"**:
-     - Parse the admin-enable URL from the output (it's the
-       `https://login.tailscale.com/f/serve?node=...` line).
-     - Print it prominently with a clear message:
-       > **Tailscale Serve is not enabled on this tailnet.**
-       > An admin must visit this URL once to enable it:
-       > **<URL>**
-       > Then re-run `/tailscale-serve ${PORT}`.
-     - Do not fall back to plain HTTP automatically — the user asked for
-       authentication, not a workaround. They can run the demo's
-       `host:start` script for the HTTP fallback.
-   - **On any other error**: print the full error, suggest
-     `tailscale serve status` and `sudo tailscale up` as debug steps.
-
-6. **For `--reset`**:
-   ```bash
-   tailscale serve reset
-   ```
-   Confirm the reset succeeded by re-running `tailscale serve status`.
-
-7. **Final output** — always end with a clear status block:
-
-   ```
-   === Tailscale Serve ===
-   config:    <status>
-   upstream:  http://127.0.0.1:<port>
-   endpoints:
-     - https://<dnsname>/         (HTTPS, only if Serve is enabled)
-     - http://<dnsname>:<port>/   (HTTP fallback, only if upstream binds 0.0.0.0)
-
-   To remove: /tailscale-serve --reset
-   ```
-
-## Notes
-
-- `tailscale serve` requires a one-time tailnet admin enable. There is no
-  per-device flag — only the admin can authorize it. The command surfaces
-  the admin URL and stops rather than silently falling back.
-- This command does not start the upstream service. It assumes the service
-  is already running and only wires the HTTPS proxy.
-- For the BizarHarness Demo Dashboard, the typical flow is:
-  ```
-  /tailscale-serve --status       # see current state
-  npm run host:start              # upstream on port 8765
-  /tailscale-serve                # expose it on the tailnet
-  ```
+1. Require the user to provide the local port or socket to expose.
+2. Verify the target is listening locally.
+3. Show the exact `tailscale serve` command and exposure scope.
+4. Ask before changing the machine's Tailscale Serve configuration.
+5. After approval, run the command and verify `tailscale serve status`.
+6. Report the public/private URL and the reversal command: `tailscale serve reset`.

package/.claude/commands/team.md

@@ -1,132 +1,36 @@
 ---
-description: Spawn a Claude Code agent team — coordinate Thor (M2.7), Tyr (M3), Mimir (research), and Hermod (git) to complete a complex mission end-to-end.
-allowed-tools: Read, Bash, Agent
+description: Coordinate a Claude Code agent team with disjoint ownership, explicit gates, and leader verification.
+allowed-tools: Read, Bash, Agent, SendMessage
 ---
 
-# Team — Spawn a Claude Code Agent Team
+# Team — Coordinated Claude Code Agents
 
-The `/team` command spawns a **coordinated agent team** for a complex,
-multi-step mission. The lead agent coordinates teammates; each teammate
-owns a disjoint scope; results are synthesized and committed.
+Use `/team` only when parallel, independent scopes materially improve delivery.
 
-The full mission is available as `$ARGUMENTS` (or composed from `$1`).
+## Protocol
 
-## When to Use `/team`
+1. Read repository instructions, `PROGRESS.md`, and `feature_list.json` when present.
+2. Define the target result, constraints, validation evidence, and stop condition.
+3. Decompose into disjoint file/responsibility scopes. Assign shared root files to one owner only.
+4. Create and claim durable `bizar task` records for editing lanes. Code-writing
+   agents run with `isolation: worktree`; their claimed path scopes remain
+   authoritative even though the checkouts are physically separate.
+5. Launch bounded agents through Claude Code's Agent tool. Every prompt names ownership, deliverable, validation, and the rule not to revert sibling work.
+6. Submit verified task commits to `bizar task integrate enqueue`. The designated
+   integrator serializes application of completed work and records pass/failure.
+7. The leader runs the final repository gates and owns the completion claim.
+8. Use `SendMessage` for coordination; stop or reassign stalled work rather than duplicating edits.
 
-Use `/team` for any non-trivial mission that benefits from **parallel
-work + explicit coordination**. Examples:
+## Human approval gates
 
-- **Refactor** — split a module across Thor (M2.7) and Tyr (M3) in parallel.
-- **Multi-feature build** — new feature A (Thor) + new feature B (Tyr) + tests (Heimdall).
-- **Research + implementation** — Mimir researches, Thor implements, Forseti audits.
-- **Migration / upgrade** — Hermod handles the git/PR lifecycle while Thor/Tyr write code.
-- **Bug hunt** — Mimir traces the data flow while Tyr writes the fix and tests.
+Team agents may inspect, edit, build, and test locally without approval. They must not push, publish, deploy, merge, alter credentials/access, or perform destructive operations unless the user explicitly approved that exact action. A git specialist may prepare commits or PR text, but external publication remains gated.
 
-Do NOT use `/team` for trivial single-file edits or single-question
-clarifications. Use `@brenda` directly for those.
+## Checklist
 
-## Default Team Composition
-
-If the user does not specify a team composition, spawn this default:
-
-| Role          | Agent   | Model             | Job                                   |
-|---------------|---------|-------------------|---------------------------------------|
-| Lead          | @mike   | minimax/MiniMax-M3   | Coordinate, synthesize, gate quality  |
-| Implementer 1 | @todd   | minimax/MiniMax-M2.7 | Moderate-complexity implementation   |
-| Implementer 2 | @karen    | minimax/MiniMax-M3   | Complex / cross-cutting work         |
-| Researcher    | @greg  | bizar/MiniMax-M3 | Codebase research, pattern discovery  |
-| Git ops       | @steve | minimax/MiniMax-M2.7 | Branch, commit, push, PR             |
-| Reviewer      | @linda| minimax/MiniMax-M3   | Audit plan + final output            |
-
-You can swap or remove any of these — but always keep at least one
-implementer and a reviewer.
-
-## Protocol (How Odin Runs a `/team` Invocation)
-
-1. **Read `.bizar/PROJECT.md`** if it exists. Factor the project
-   description into the team mission.
-2. **Read `bizar memory status`**. If the vault is reachable, run
-   `bizar memory search "<topic>"` for prior context on the mission.
-3. **Decompose** the mission into disjoint work items. Each item
-   names:
-   - The agent that owns it
-   - The file scope (paths/globs)
-   - The deliverable (a function, a test, a commit, a doc)
-   - The exit signal ("done when X is committed")
-4. **Launch in parallel** — use the **Agent tool** in a **single
-   message** with multiple `Agent` calls so all teammates run
-   concurrently. Each call's prompt names the Bizar agent
-   (`todd`, `karen`, `greg`, `steve`, `linda`) so the audit
-   trail stays readable. For long-running work, pass
-   `run_in_background: true`.
-5. **Monitor** — while the team runs, return control to the user.
-   The team runs asynchronously. Check teammate progress only
-   when the user asks (use `SendMessage` to the named agent).
-6. **Synthesize** — when teammates report back, gate through @linda
-   (audit) and @steve (commit/push). Then report the final outcome
-   to the user with file:line references.
-
-## Pre-Dispatch Checklist (MANDATORY)
-
-- [ ] Each teammate has a **disjoint file scope** — no two agents
-      edit the same file or directory
-- [ ] Lockfiles, `package.json`, root configs, `tsconfig.json`,
-      `vite.config.*`, `Dockerfile`, CI configs are assigned to ONE
-      agent or marked READ-ONLY for everyone else
-- [ ] No subagent has both `bash: allow` AND a write-level git task
-      in the same batch — Hermod is the only git writer
-- [ ] Each teammate's scope is named in plain English
-- [ ] You have prepended a one-paragraph sibling-awareness block to
-      every prompt (Odin baseline, "Parallel Dispatch Coordination")
-- [ ] You have called `bizar memory status` and confirmed the vault
-      is reachable
-
-## Example Mission Strings
-
-**Refactor a module:**
-```
-Refactor src/api/auth.ts into a clean module: extract JWT validation
-into src/auth/jwt.ts, rate-limiting into src/auth/rate-limit.ts, and
-keep the public surface stable. Add tests for each new module. Update
-docs/architecture.md with the new module map. Do not change the HTTP
-route handlers.
-```
-
-**Multi-feature build:**
-```
-Add a kanban board: (1) Thor — backend API at /api/tasks with CRUD
-endpoints and SQLite persistence. (2) Tyr — frontend React component
-in src/components/Kanban.tsx with 5 columns. (3) Heimdall — write
-the OpenAPI spec at docs/api/tasks.yaml. (4) Hermod — open a PR
-named feat/kanban-board.
-```
-
-**Bug hunt:**
-```
-Mimir — trace the data flow from POST /api/checkout through to the
-Stripe webhook handler; find any place where the order status is
-written before the payment is confirmed. Tyr — write a regression
-test that reproduces the race. Thor — fix the bug. Forseti —
-audit the fix for completeness. Hermod — commit + push.
-```
-
-## Tool Reference (Claude Code)
-
-- **Agent tool** — spawn one subagent per call. Use multiple
-  `Agent` calls in a single message for parallelism.
-- `run_in_background: true` on the Agent tool — for tasks that
-  span more than a few minutes.
-- `SendMessage` — talk to a running background agent by name.
-
-## Failure Modes
-
-- **Two agents write the same file** — STOP, revert one branch, reassign.
-- **One agent stalls** — use `TaskStop` to terminate, route the
-  remaining scope to another agent.
-- **Tests fail after team work** — dispatch `todd` to investigate;
-  do not paper over the failure.
-- **Git conflict** — route to `steve` for `git rebase` / merge
-  resolution.
-- **A teammate goes silent** — send a `SendMessage` to the named
-  agent for a status report; if dead, kill and re-spawn with a
-  fresh prompt.
+- [ ] Parallelism is justified; a direct lane would be slower or less reliable.
+- [ ] File scopes are disjoint.
+- [ ] Every editing lane has a claimed task/worktree and path scope.
+- [ ] Lockfiles and root configuration have one owner.
+- [ ] Each agent has an explicit exit condition and proving test.
+- [ ] A reviewer/verifier is separate from the main implementation owner.
+- [ ] The leader will run repository-wide required gates after integration.

package/.claude/commands/test.md

@@ -36,7 +36,7 @@ To run a specific Bizar test scope instead, pass arguments to
 `/test`. The arguments are forwarded to the underlying runner and
 are available as `$ARGUMENTS` (or `$1`, `$2`, ...):
 
-- `/test plugins/bizar` — run only the Bizar plugin tests (bun)
+- `/test packages/sdk` — run only the Bizar SDK tests
 - `/test --testPathPattern=auth` — pass a flag to the runner
 
 ## When to Use
@@ -47,7 +47,7 @@ are available as `$ARGUMENTS` (or `$1`, `$2`, ...):
 
 ## Common Patterns
 
-- **Post-implementation gate** — after Thor and Tyr finish their
+- **Post-implementation gate** — after Todd and Karen finish their
   parallel work, dispatch `todd` to run `/test`. If failures, fix
   and re-run.
 - **PR check** — run `/test` in CI before merging.
@@ -59,4 +59,4 @@ are available as `$ARGUMENTS` (or `$1`, `$2`, ...):
 - `bizar test-gate` — the underlying CLI command
 - `bizar doctor` — checks the Bizar install itself (not project tests)
 - `make check` — typecheck + tests (full pipeline, dev only)
-- `make e2e` — Bizar plugin end-to-end (dev only)
+- `make e2e` — Claude Code core-harness end-to-end

package/.claude/commands/use-default.md

@@ -0,0 +1,53 @@
+---
+description: Revert Claude Code to the default tier (bizar/MiniMax-M3). Prints the exact shell command and env vars to unset.
+allowed-tools: Bash
+---
+
+# /use-default — Revert to bizar/MiniMax-M3 (default)
+
+The local model router at `http://localhost:20128/v1` defaults to
+`bizar/MiniMax-M3` for everyday reasoning. Use this when you've
+been running on premium (`cx/gpt-5.6-sol`) and want to drop back to
+the cheaper default.
+
+## Commands
+
+### One-shot launch (recommended)
+
+```bash
+ANTHROPIC_BASE_URL=http://localhost:20128/v1 \
+claude
+```
+
+If `ANTHROPIC_MODEL` is set in your shell, unset it first:
+
+```bash
+unset ANTHROPIC_MODEL
+ANTHROPIC_BASE_URL=http://localhost:20128/v1 \
+claude
+```
+
+### Revert a project-level override
+
+If you added `ANTHROPIC_MODEL` to `.claude/settings.local.json` for
+this project, remove it (or set it back to `bizar/MiniMax-M3`).
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:20128/v1"
+  }
+}
+```
+
+## When default is fine
+
+- Trivial edits, mechanical work, single-file obvious fixes.
+- Read-only Q&A (use `@susan` directly anyway).
+- Research (always use `@greg` on default).
+- Moderate-complexity implementation (route to `@todd`).
+- Most everyday sessions.
+
+The session loop on default is the cheapest path that still
+handles Claude Code's tool surface well. Subagents still pick their
+own tier per the routing table in `.claude/model-router.json`.

package/.claude/commands/use-premium.md

@@ -0,0 +1,74 @@
+---
+description: Launch Claude Code in this project on the premium tier (cx/gpt-5.6-sol). Prints the exact shell command and env vars to set.
+allowed-tools: Bash
+---
+
+# /use-premium — Run this session on cx/gpt-5.6-sol (premium)
+
+The local model router at `http://localhost:20128/v1` exposes
+`cx/gpt-5.6-sol` as the premium-tier reasoning model. Premium is
+expensive — use it intentionally, not by default.
+
+## What it does
+
+Sets `ANTHROPIC_MODEL=cx/gpt-5.6-sol` and `ANTHROPIC_BASE_URL=http://localhost:20128/v1` so the entire session loop runs on the premium model. The model-router is the same one your subagents (`@paul`, `@ria`, `@brad`, `@linda`, `@carl`) already hit.
+
+## Commands
+
+### One-shot launch (recommended)
+
+```bash
+ANTHROPIC_BASE_URL=http://localhost:20128/v1 \
+ANTHROPIC_MODEL=cx/gpt-5.6-sol \
+claude
+```
+
+Or with the explicit `--model` flag (Claude Code forwards it to the
+router as the model id):
+
+```bash
+ANTHROPIC_BASE_URL=http://localhost:20128/v1 \
+claude --model cx/gpt-5.6-sol
+```
+
+### Make it the default for this project
+
+Add to your local override `.claude/settings.local.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:20128/v1",
+    "ANTHROPIC_MODEL": "cx/gpt-5.6-sol"
+  }
+}
+```
+
+Then every Claude Code session in this directory opens on premium.
+
+### Available premium-tier models on the local router
+
+```
+cx/gpt-5.6-sol    — strongest reasoning (planning, debug, design, audit)
+cx/gpt-5.6-terra  — high reasoning at lower cost (complex impl, routing)
+cx/gpt-5.6-luna   — visually-oriented mid-tier (design alt)
+```
+
+See `.claude/model-router.json` for the full tier table.
+
+## When to use premium
+
+- Hard debugging that cheaper models loop on.
+- Architecture-level planning where the cost of a wrong design is high.
+- UI/UX review of a non-trivial surface.
+- Adversarial code review.
+
+## When NOT to use premium
+
+- Routine edits, mechanical work, single-file fixes (use default `bizar/MiniMax-M3`).
+- Research (always use `@greg` on default).
+- Implementation at moderate complexity (use `bizar/MiniMax-M2.7` via `@todd`).
+
+The harness's cost ceiling (`cost_ceiling_per_session_usd: 5.0` in
+`model-router.json`) will downgrade you automatically if the budget is
+exceeded mid-session.

package/.claude/commands/validate.md

@@ -1,68 +1,20 @@
 ---
-description: Validate the Bizar install end-to-end — settings.json parses, plugin entry resolves, all agent files are installed, all skills/rules/hooks/commands are in place, provider config is sane, and the 9router gateway is reachable.
-allowed-tools: Read, Bash
+description: Validate the installed Bizar harness, hooks, agents, skills, settings, and retained runtime surfaces.
 ---
 
-# /validate — Validate the Bizar Install
+# Validate Bizar
 
-The `/validate` command runs `bizar doctor` with the full check
-battery. It is the fastest way to confirm the install is healthy
-and Claude Code will see every Bizar component on the next session
-start.
+Run:
 
-## What It Checks
+```bash
+bizar validate
+```
 
-1. **claude-reachable** — `claude --version` exits 0.
-2. **claude-config-valid** — `~/.claude/settings.json` parses as JSON.
-3. **plugin-entry-present** — `settings.json` has a Bizar plugin entry.
-4. **plugin-path-resolves** — the plugin path on disk actually exists.
-5. **agent-files-installed** — all agent files in `~/.claude/agents/`
-   (mike, janet, susan, pam, greg, brenda, steve, todd, brad,
-   karen, carl, linda, oscar, kevin).
-6. **tools-available** — at least one of `semble`, `skills`
-   is on PATH.
-7. **provider-config-sanity** — `provider.9router` has at least
-   one sane model entry.
-8. **9router-reachable** — 9Router gateway responds at
-   `http://localhost:20128/health` (lenient — warn, don't fail).
-9. **slash-commands-installed** — all Bizar slash commands
-   (`/audit`, `/explain`, `/init`, `/learn`, `/plan`, `/plow-through`,
-   `/pr-review`, `/tailscale-serve`, `/visual-plan`, `/bizar`,
-   `/team`, `/test`, `/validate`) are present in `~/.claude/commands/`.
-10. **skills-installed** — every subdir of `config/skills/` is
-    mirrored to `~/.claude/skills/`.
-11. **rules-installed** — every `.md` in `config/rules/` is mirrored
-    to `~/.claude/rules/`.
-12. **hooks-installed** — `.claude/hooks/` scripts are installed
-    with executable permissions.
+Use `bizar validate --json` for machine-readable evidence and
+`bizar validate --strict` when optional integrations must also be reachable.
 
-## How to Use
-
-Invoke `/validate` (no arguments) from anywhere. It is read-only and
-never modifies the system.
-
-If any check fails, the user should run `bizar update` to refresh the
-install, or `bizar repair` to fix common issues.
-
-## Output
-
-Each check prints ✓ or ✗ with a one-line message. The summary line
-shows the total pass/fail count. Exits non-zero if any check fails.
-
-For machine-readable output, the user can run `bizar doctor --json`
-directly.
-
-## When to Use
-
-- After a manual config edit — confirm nothing broke.
-- Before a `/team` mission — confirm the install is healthy so the
-  team has all the tools it needs.
-- After `bizar install` or `bizar update` — the install already
-  calls doctor, but a manual re-run is cheap.
-- When a user asks "why is Claude Code misbehaving?" — start here.
-
-## Related
-
-- `bizar doctor` — the underlying CLI command
-- `bizar update` — refreshes the install (re-runs syncConfigExtras)
-- `bizar repair` — fixes common issues (stale symlinks, version drift)
+The validator checks Claude Code, the Bizar MCP registration, guarded autonomy
+hooks, all 16 uniquely named agent definitions, slash commands, mirrored skills and
+rules, permissions, and local runtime state. Report failures verbatim and repair
+the smallest responsible surface; do not bypass a failed approval or safety
+check.

package/.claude/hooks/README.md

@@ -1,108 +1,24 @@
-# Bizar Harness — Claude Code Hooks
-
-This directory contains the **Claude Code** adapter scripts that back the
-project-scoped hooks defined in `.claude/settings.json`.
-
-They replaced the legacy Cline hooks. The Claude Code
-set is the only supported path on Bizar v6.3.0+; the legacy Cline hooks
-are no longer installed.
-
-## Adapter inventory
-
-| File | Event | Matcher | Behaviour |
-|------|-------|---------|-----------|
-| `pretooluse-editwrite.mjs`   | `PreToolUse`       | `Write\|Edit\|MultiEdit\|Bash` | Blocks `.env`/secrets/lockfiles; warns on `console.log`/`debugger`/`.only()` in `src/`; scans `Bash` against the 36-pattern dangerous-pattern list |
-| `posttooluse-editwrite.mjs`  | `PostToolUse`      | `Edit\|Write\|MultiEdit`        | Logs edit/write latency + size to `~/.config/bizar/hook-logs/` |
-| `sessionstart-prime.mjs`     | `SessionStart`     | (none — branches on `source`)  | Reads PROGRESS.md + feature_list.json + git log + .bizar/PROJECT.md; branches on `startup`/`clear`/`resume`; WIP=1 guard |
-| `thinking-route.mjs`         | `UserPromptSubmit` | (none)                          | Slash-command routing (team/plow-through/test/validate/plan/audit/pr-review) + 35-bucket thinking-* mental-model router |
-| `worker-suggest.mjs`        | `UserPromptSubmit` | (none)                          | Calls `cli/worker-dispatcher.mjs:dispatch()` against `config/trigger-patterns.json` |
-| `sessionend-recall.mjs`      | `SessionEnd`       | (none)                          | Reads `transcript_path`; writes `.bizar/sessions/<date>-<id>.md` + `.bizar/session-state.json` handoff |
-
-## SessionStart ↔ SessionEnd handoff
-
-The two lifecycle hooks form a state machine via the `.bizar/session-state.json`
-file:
-
-```
-SessionEnd (session N)
-  ↓ writes .bizar/session-state.json with {nextStep, blockers, filesTouched}
-SessionStart (session N+1, source: "resume")
-  ↑ reads it; primes the agent with "Last nextStep: …" + blockers
-```
-
-If `.bizar/session-state.json` is missing, the resume branch degrades
-gracefully to "No prior session-state.json found — treating as fresh start."
-
-## I/O contract
-
-Claude Code invokes each hook as a child process, pipes JSON on
-**stdin**, and reads JSON on **stdout**. The five adapters above all
-read using `process.stdin` and write a single JSON object to
-`process.stdout`.
-
-### Stdin (varies by event)
-
-```jsonc
-// PreToolUse
-{
-  "session_id": "...",
-  "transcript_path": "...",
-  "cwd": "/home/drb0rk/Projects/BizarHarness",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Write",
-  "tool_input": { "file_path": "/path", "content": "..." }
-}
-
-// PostToolUse  (adds tool_response)
-// UserPromptSubmit  (uses .user_prompt instead of .tool_name/.tool_input)
-// SessionStart  (uses .source = "startup" | "resume" | "clear")
-// SessionEnd  (uses .reason = "exit" | "clear" | "logout" | "prompt_input_exit")
-```
-
-### Stdout
-
-```jsonc
-// Block (PreToolUse only)
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "..."
-  }
-}
-
-// Inject context for the next turn (all events)
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PostToolUse",   // or PreToolUse / SessionStart / UserPromptSubmit
-    "additionalContext": "..."
-  }
-}
-```
-
-For a non-blocking `PreToolUse`, omitting `permissionDecision` and
-emitting only `additionalContext` is a soft hint to the model — the
-tool call still proceeds.
-
-## Claude Code lifecycle mapping
-
-The legacy Cline plugin used four separate events (PreToolUse,
-PostToolUse, TaskStart, TaskResume, UserPromptSubmit). Claude Code
-collapses "task start" and "task resume" into a single `SessionStart`
-event that branches on `source` (`startup`, `resume`, `clear`). The
-adapter `sessionstart-prime.mjs` reads `source` and applies the
-appropriate priming logic for each branch.
-
-## Disabling an individual hook
-
-Easiest path: comment out the matching `hooks` array entry in
-`.claude/settings.json`. Removing the executable bit
-(`chmod -x …`) also works — Claude Code silently skips hooks it can't
-execute.
-
-## See also
-
-- `cli/provision-claude.mjs` — installs Claude Code hooks to
-  `~/.claude/hooks/` and wires them via `~/.claude/settings.json`.
-- `.claude/settings.json` — the project hook wiring
-- `.bizar/session-state.json` — handoff artifact between SessionEnd and SessionStart
+# Claude Code hooks
+
+All hooks read Claude Code JSON from stdin and emit either no decision, additional context, `deny`, or `ask` using the current event contract.
+
+| Hook | Event | Purpose |
+| --- | --- | --- |
+| `pretooluse-bash.mjs` | PreToolUse Bash | deny/escalate dangerous shell commands; safe calls defer to permissions |
+| `pretooluse-editwrite.mjs` | PreToolUse Write/Edit/MultiEdit | protect secrets and package-managed paths |
+| `git-workflow-guard.mjs` | PreToolUse Bash | Git policy, publication approvals, and visual evidence |
+| `content-style-guard.mjs` | PreToolUse writes/Bash | human-facing prose quality |
+| `simplify-guard.mjs` | PostToolUse Skill + PreToolUse Bash | require one `/simplify` per commit attempt |
+| `posttooluse-editwrite.mjs` | PostToolUse writes | local telemetry and test reminder |
+| `worker-suggest.mjs` | UserPromptSubmit | ranked skill/agent suggestions |
+| `thinking-route.mjs` | UserPromptSubmit | slash and mental-model routing |
+| `telemetry.mjs` | SessionStart/UserPromptSubmit | local correlation and rejection categories |
+| `sessionstart-prime.mjs` | SessionStart | bounded project and handoff context |
+| `sessionend-recall.mjs` | SessionEnd | bounded session record and handoff |
+| `learning-extract.mjs`, `auto-instinct.sh` | lifecycle/tool events | compact learning evidence |
+| `precompact-priorities.sh` | PreCompact | preserve questions, causes, exact evidence, decisions, and approvals |
+| `advisor-context.mjs` | SubagentStart | bounded parent transcript for reviewers/debuggers |
+
+Project hook commands use `$CLAUDE_PROJECT_DIR`. `cli/provision.mjs` writes user-level settings with absolute paths under `~/.claude/hooks`, so the same scripts work outside this checkout.
+
+PreToolUse precedence is intentional: `deny` overrides `ask`, and both override a safe no-decision result. No safe-path hook returns `allow`, because that could suppress the operator's normal permission boundary.