@polymorphism-tech/morph-spec 8.37.1 → 8.38.0

package/framework/evals/rubrics/code-quality.md

@@ -11,6 +11,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - **Nada do que foi criado aqui já existia no projeto**: os conceitos novos batem com o veredito do `reuse-map.md`, e cada `CRIAR` tem justificativa que se sustenta.
 - Segue os padrões do stack conforme os standards do projeto (ex: Result pattern para .NET, hooks pattern para React).
 - Sem "dead code" — sem variáveis não usadas, sem blocos comentados, sem imports desnecessários.
+- Comentário só com o porquê que o código não mostra (`architecture-code-comments`): nenhum conta história de task, UC, ADR, Gate ou avaliador.
 
 ## Score 7-8 — Bom
 
@@ -20,6 +21,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - No máximo um conceito recriado que já existia no codebase, com impacto pequeno e localizado.
 - Segue padrões do stack com desvios isolados e justificáveis.
 - Sem dead code significativo.
+- Um ou outro comentário que repete o código; nenhum narra o processo.
 
 ## Score 5-6 — Aceitável com ressalvas
 
@@ -29,6 +31,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - Um ou dois tipos/componentes recriados que já existiam em outro arquivo do projeto.
 - Desvios dos padrões do stack sem justificativa.
 - Dead code pontual.
+- Comentário de processo (UC, ADR, `T{n}`, Gate, `spec.md`, mockup) ou comentário afirmando comportamento que nenhum teste cobra.
 
 ## Score 3-4 — Problemático
 
@@ -37,6 +40,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - Duplicação significativa: mesma lógica em múltiplos lugares.
 - Conceito central do domínio redeclarado na MESMA feature (o caso `SimpleBuilding`: cinco cópias na mesma pasta, uma já divergindo do resto).
 - Não segue os padrões do stack — código parece escrito para outro contexto.
+- Blocos longos de comentário contando a história da implementação, em vários arquivos.
 
 ## Score 1-2 — Reprovado
 
@@ -91,3 +95,4 @@ chave `obs` no `**Proof-Scores:**`, também não há teto a aplicar.
 3b. **O que foi criado aqui já existia no projeto?** Confira os tipos, componentes, hooks e serviços novos contra o `reuse-map.md` e contra o grafo — e diga no relatório o que você conferiu.
 4. O código segue os padrões definidos nos standards do projeto?
 5. Há variáveis não usadas, imports desnecessários ou blocos comentados?
+6. Algum comentário conta história de processo, repete o código ou passa de ~3 linhas sem justificar? O validador `code-budget` do nó `validators` já conta, nas linhas adicionadas, os comentários que citam processo; leia os citados antes de pontuar.

package/framework/evals/rubrics/condensed.md

@@ -30,8 +30,8 @@ Se o diff toca endpoint minimal API ou fetch cross-camada, independente do resto
 |---|---|---|---|---|
 | **Arquitetura** | Ignora a arquitetura do spec.md; sem feature folder; deps circulares; ou violação mecânica acima | Pastas corretas, responsabilidades se misturam; deps cross-feature sem justificativa; domain acoplado a infra | Desvios menores justificados; deps cross-feature via abstração; impurezas de infra pontuais | Feature folder rigoroso; zero deps cross-feature diretas; domain isolado; DI onde exige |
 | **Contratos** | Sem tipos ou `any` generalizado; zero validação; sem tratamento de erro; naming arbitrário | `any`/genérico visível; validação parcial; mix exceptions/Result; naming inconsistente | Tipos bem definidos, `any` raro e justificado; validação na maioria; erro consistente | Zero `any`; validação em todos endpoints; Result pattern/discriminated union; naming consistente |
-| **Qualidade** | Nomes arbitrários; god objects; duplicação massiva; recria o que o `reuse-map` mandou REUSAR; fora do padrão do stack | Nomes genéricos (`data`,`temp`); funções >30 linhas; duplicação perceptível; conceito da MESMA feature redeclarado | Nomes claros, raras exceções; bem dimensionado; duplicação mínima; no máximo um conceito recriado | Nomes comunicam intenção; funções ≤20-25 linhas, 1 responsabilidade; zero duplicação/dead code; nada criado que já existia no projeto |
-| **Testes** | Sem testes ou sem asserts reais; zero edge case; nomes genéricos | Happy path OK, edge cases parciais; erros só óbvios; testes interdependentes; teste de texto de arquivo sem substituto em runtime | Happy path completo; maioria dos edge cases; erros nos fluxos principais | Toda pós-condição do `usecase` tem teste; A1/A2 cobertos; edge+erro cobertos; isolados |
+| **Qualidade** | Nomes arbitrários; god objects; duplicação massiva; recria o que o `reuse-map` mandou REUSAR; fora do padrão do stack | Nomes genéricos (`data`,`temp`); funções >30 linhas; duplicação perceptível; conceito da MESMA feature redeclarado; comentário que narra task/UC/ADR | Nomes claros, raras exceções; bem dimensionado; duplicação mínima; no máximo um conceito recriado | Nomes comunicam intenção; funções ≤20-25 linhas, 1 responsabilidade; zero duplicação/dead code; nada criado que já existia no projeto; comentário só com o porquê |
+| **Testes** | Sem testes ou sem asserts reais; zero edge case; nomes genéricos | Happy path OK, edge cases parciais; erros só óbvios; testes interdependentes; teste de texto de arquivo sem substituto em runtime; cópias em vez de tabela ou excesso sem justificativa | Happy path completo; maioria dos edge cases; erros nos fluxos principais | Toda pós-condição do `usecase` tem teste; A1/A2 cobertos; edge+erro cobertos, em tabela; isolados; dentro do orçamento |
 
 > **Qualidade olha o CODEBASE, não só o diff.** Símbolo novo cujo nome já existe no projeto não aparece no diff — é preciso perguntar de fora dele. O nó `validators` do `morph-spec verify` já traz os achados do validador `reuse`; o `2-plan/reuse-map.md` diz o que o plano decidiu por conceito.
 
@@ -39,6 +39,10 @@ Se o diff toca endpoint minimal API ou fetch cross-camada, independente do resto
 
 > Teste que só lê texto de arquivo não cobre pós-condição de comportamento: sem substituto em runtime, ela conta como sem teste (herdado de `test-coverage.md`, pergunta 7).
 
+> Orçamento por task: um teste por pós-condição + um de regressão por bug, cenários do mesmo comportamento numa tabela; teste que só fixa copy é achado (herdado de `test-coverage.md`, pergunta 8). O validador `code-budget` do nó `validators` avisa sobre teste acima de 1,5× a produção e sobre comentário que cita processo.
+
+> Task de UI cuja tela tem `### Checklist de tela` no `1-design/mockups.md`: item divergente sem justificativa em `decisions.md` → teto 8 em Contratos; paginação, ordenação ou filtro que o checklist põe no servidor entregue em memória (ou ausente), ou estado vazio/carregando/erro decidido e ausente → teto 6 (herdado de `contracts.md`, "Contrato de tela").
+
 ## Score composto
 
 ```

package/framework/evals/rubrics/contracts.md

@@ -38,6 +38,25 @@ Avalia a qualidade dos tipos, validações, tratamento de erros e naming dos con
 - Sem tratamento de erro — falhas em runtime sem diagnóstico útil.
 - Naming arbitrário ou genérico (`data`, `obj`, `result` sem qualificador).
 
+## Contrato de tela (feature com UI)
+
+Quando o `1-design/mockups.md` declara telas (`## Tela:`) com `### Checklist de tela`, o checklist é
+um contrato como os tipos da spec: cada item decidido (volume, paginação, ordenação, filtro, os três
+estados, mobile, abas) é conferido contra a tela **entregue** e registrado na seção `## Checklist de
+tela` do `evaluator-report.md` — uma linha por item, com o planejado, o observado e o veredito
+(`cumpre` / `diverge` / `não verificável`, com o motivo).
+
+| Achado | Teto em Contratos |
+|---|---|
+| Item `diverge` sem justificativa registrada em `decisions.md` | 8 |
+| Paginação, ordenação ou filtro que o checklist põe no servidor, entregue em memória no cliente ou ausente | 6 |
+| Estado vazio, carregando ou de erro que o checklist decide e a tela não tem | 6 |
+
+`não verificável` (stack fora do ar) não é divergência: o avaliador lê o código — a query recebe
+página e ordenação? o estado vazio existe? — e diz no veredito por onde conferiu. Itens "não se
+aplica" e a superfície não precisam de linha. Sem a seção, ou com item decidido sem linha, o
+`morph-spec gate-check` pausa o Gate 3 por conta própria, antes de qualquer nota.
+
 ## Perguntas de avaliação
 
 1. Há `any` ou tipos genéricos onde um tipo específico seria possível?
@@ -45,3 +64,4 @@ Avalia a qualidade dos tipos, validações, tratamento de erros e naming dos con
 3. O tratamento de erros segue o padrão do projeto (Result, exceções, etc.)?
 4. Os nomes dos tipos e propriedades comunicam claramente o que representam?
 5. Campos opcionais fazem sentido semântico, ou são opcionais por comodidade?
+6. Em feature com UI: cada item decidido do checklist de tela foi conferido contra a tela entregue, e toda divergência tem justificativa?

package/framework/evals/rubrics/test-coverage.md

@@ -7,7 +7,8 @@ Avalia se os testes cobrem os comportamentos esperados, são isolados e têm nom
 - **Cada pós-condição do use case referenciado tem teste correspondente.** Se a task traz `usecase: "UC-07"`, abra `2-plan/usecases/UC-07-*.md` e percorra as pós-condições (P1, P2…): cada uma precisa de ao menos um teste que a verifique. Pós-condição sem teste **impede a faixa 9-10**, por mais completa que a suíte pareça no resto.
 - Happy path coberto para todos os casos de uso relevantes — "relevantes" são os use cases referenciados pelas tasks da feature, não uma lista implícita.
 - Fluxos alternativos do use case (A1, A2…) cobertos: são os edge cases de **comportamento** e foram declarados justamente para serem testados.
-- Edge cases críticos cobertos: null/undefined, string vazia, boundary values, coleção vazia.
+- Edge cases críticos cobertos: null/undefined, string vazia, boundary values, coleção vazia — como linhas da tabela do comportamento (`[Theory]`/`it.each`), não como cópias do mesmo teste.
+- **Dentro do orçamento da task**: um teste por pós-condição, mais um de regressão por bug; o que passa disso tem justificativa escrita na task.
 - Casos de erro cobertos: o que acontece quando a operação falha, quando a dependência retorna erro.
 - Testes completamente isolados — cada teste pode rodar sozinho em qualquer ordem.
 - Nomes de teste descrevem o comportamento esperado: `"deve retornar erro quando email já existe"` (não `"testEmail"`).
@@ -28,6 +29,7 @@ Avalia se os testes cobrem os comportamentos esperados, são isolados e têm nom
 - Alguns testes com dependências entre si (ordem importa).
 - Nomes misturados: alguns descritivos, outros genéricos.
 - Testes que testam implementação (dependentes de detalhes internos).
+- Cenários do mesmo comportamento copiados em N testes em vez de uma tabela, ou testes além do orçamento da task sem justificativa.
 
 ## Score 3-4 — Problemático
 
@@ -35,6 +37,7 @@ Avalia se os testes cobrem os comportamentos esperados, são isolados e têm nom
 - Testes interdependentes ou com estado compartilhado.
 - Nomes que não descrevem o comportamento testado.
 - Cobertura presente mas superficial — testes passam mas não protegem contra regressão.
+- Suíte inflada: a maior parte dos testes novos fixa texto ou repete o mesmo comportamento.
 
 ## Score 1-2 — Reprovado
 
@@ -59,13 +62,21 @@ Avalia se os testes cobrem os comportamentos esperados, são isolados e têm nom
    apareceu no score, porque score não pergunta isso. **Sem resposta a esta pergunta numa correção,
    o teto de Cobertura é 8.**
 7. **Quantos testes desta task asseram sobre TEXTO DE ARQUIVO** (prompt, migration, config,
-   markdown, código-fonte lido como string)? **Cada um tem substituto em runtime** — um teste
-   que exercita o sistema ou, em critério sobre saída de LLM, a evidência em
-   `3-implement/evidencias/{taskId}.md` apontando um eval? Teste de texto prova a VERSÃO do
-   arquivo, não o comportamento: quando é o único teste de uma pós-condição, **a pós-condição
-   conta como sem teste** (pergunta 0 — teto 8). Exceções: pós-condição com
+   markdown, código-fonte lido como string, copy de UI, config de tenant)? **Cada um tem
+   substituto em runtime** — um teste que exercita o sistema ou, em critério sobre saída de LLM,
+   a evidência em `3-implement/evidencias/{taskId}.md` apontando um eval? Teste de texto prova a
+   VERSÃO do arquivo, não o comportamento: quando é o único teste de uma pós-condição, **a
+   pós-condição conta como sem teste** (pergunta 0 — teto 8). Exceções: pós-condição com
    `> [!note] Por que artefato:` e o único teste de estrutura por fonte de prompt
    (`ai-agents-testing-ai`). Medido: 12 suítes, 106 testes sobre versões superadas do prompt.
+   Teste cuja asserção é só a presença ou ausência de uma string de copy é **achado** mesmo quando
+   há teste de runtime ao lado: essa checagem é analyzer, lint ou validação no publish.
+8. **A task cabe no orçamento?** Um teste por pós-condição, mais um de regressão por bug; o
+   excesso tem justificativa na task? Cenários do mesmo comportamento estão numa tabela, e a
+   fixture é a compartilhada, não uma refeita? O validador `code-budget` do nó `validators` avisa
+   quando as linhas de teste adicionadas passam de 1,5× as de produção. Mutante sobrevivente da
+   prova de mutação se fecha apertando asserção ou somando linha de tabela: um teste novo por
+   mutante é excesso, não cobertura.
 
 ## Tetos de prova (Gate 3)
 

package/framework/hooks/README.md

@@ -45,7 +45,7 @@ framework/hooks/
 
 | Event | Hook | Type | Purpose |
 |-------|------|------|---------|
-| **SessionStart** | worktree-context.js | Context inject | Secondary worktree → feature identity (name/branch/phase) + missing-junction warning; primary root → active-feature summary (phase, task stats, pending gates), silent if none |
+| **SessionStart** | worktree-context.js | Context inject | Secondary worktree → feature identity (name/branch/phase) + missing-junction warning; primary root → active-feature summary (phase, task stats, pending gates), silent if none. Also seeds a worktree that has no codebase graph from the root's, and launches the background refresh of the ROOT's graph (`shared/graph-refresh.js`) |
 | **PreToolUse** (Write\|Edit) | _(native permissions.deny)_ | Block | Blocks edits to state.json and .morph/framework/ |
 | **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval; for tasks.json validates the mutable-field diff, the status enum, and requires a `notes` when `outputs` diverge from the plan |
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
@@ -61,6 +61,10 @@ framework/hooks/
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | gate-guard.js | Advisory | Warns (never blocks) when a gate action disagrees with the persisted gateDecisions; logs one `coherent`/`divergent` line per check in `.morph/logs/activity.jsonl` (issue #63) |
 | **PostToolUse** (all tools) | telemetry-log.js | Telemetry | Appends every tool call (skill, sub-agent dispatch + prompt, knowledge-base read, bash/edit) to `.morph/logs/events.jsonl`; silent, fail-open — the NLH execution-path capture read back by `morph-spec telemetry` |
 | **PostToolUse** (all tools) | loop-detect.js | Advisory | Warns when the last 8 actions collapse to ≤2 unique signatures |
+| **PostToolUse** (all tools) | graph-refresh-kick.js | Background | After a Bash or PowerShell command that runs git/gh/morph-spec, launches the DETACHED refresh of the ROOT's codebase graph (`shared/graph-refresh.js`: cwd in the git common dir, never a worktree; one lock per repository; staleness by `shared/graph-freshness.js` — stamp plus the per-tree run record in `<git-common-dir>/morph-spec/graph-refresh-state.json`); never waits, never injects |
+| **PostToolUseFailure** (all tools) | telemetry-log.js | Telemetry | The failed call (a Bash that exits non-zero fires only this event): exit code parsed from the `Exit code N` line, outcome and duration — never the error body |
+| **PostToolBatch** | telemetry-log.js | Telemetry | One `ToolBatch` event per model turn that used tools (the turn counter of `cost --metrics`) |
+| **SubagentStop** | telemetry-log.js | Telemetry | `AgentUsage`: the sub-agent's token usage read from its own transcript, as a delta per agent; never blocks the stop |
 | **UserPromptSubmit** | telemetry-log.js | Telemetry | Appends the user's prompt to the same `events.jsonl` stream; silent, fail-open |
 | **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift (hash-deduped, only re-injects when the warning set changes); dirty-flag-gated build check |
 
@@ -122,9 +126,11 @@ All Claude Code hooks import from `framework/hooks/shared/`:
 | `phase-utils.js` | Phase constants, path extraction, file classification |
 | `hook-response.js` | `block(reason)`, `approve(context)`, `injectContext(text)`, `pass()` |
 | `stdin-reader.js` | `readStdin()` — Promise-based stdin JSON reader |
-| `telemetry-logger.js` | `appendTelemetryEvent()`, `readTelemetryEvents()` — append-only JSONL event stream (`.morph/logs/events.jsonl`) |
+| `telemetry-logger.js` | `appendTelemetryEvent()`, `readTelemetryEvents()` — append-only JSONL event stream (`.morph/logs/events.jsonl`); stamps `schemaVersion`/`eventId` and redacts secrets |
+| `redact-secrets.js` | `redactSecrets()` — pattern redaction of obvious secrets in persisted free text |
+| `transcript-usage.js` | `readTranscriptUsage()`, `usageDelta()` — token usage of a transcript, deduplicated by message id, and the reset-safe delta between samples |
 | `morph-cli.js` | `runMorphSpec(args, { cwd, timeoutMs, env })` — spawns the morph-spec CLI from a hook (`MORPH_SPEC_BIN` → `morph-spec` on PATH → `npx --no-install`); `unavailable: true` when none resolves, never a throw. Hooks may never import from `src/` |
-| `command-tokens.js` | `tokenize(command)` — quote-aware shell tokenizer shared by the Bash guards (a hook must never import a sibling hook: its standalone tail would fire) |
+| `command-tokens.js` | `tokenize(command)` — quote-aware shell tokenizer shared by the Bash guards (a hook must never import a sibling hook: its standalone tail would fire); `exitCodeMasked()`/`producerOf()` — whether a pipe hides the exit code, and the command without its output filter |
 
 `injectContext(text)` is how `worktree-context.js` (and any other SessionStart hook) delivers context: it emits `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": text } }` on stdout. Claude Code only honors additional context nested under `hookSpecificOutput` — a bare top-level field is ignored.
 

package/framework/hooks/claude-code/core/graph-refresh-kick.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: dispara o refresh do grafo de codebase
+ *
+ * Event: PostToolUse | Matcher: none (elo da cadeia de todos os tools)
+ *
+ * Depois de um comando de shell — Bash ou PowerShell, que no Windows é o shell
+ * principal do Claude Code — que chama git, gh ou morph-spec, solta o refresh
+ * do grafo da RAIZ em background (framework/hooks/shared/graph-refresh.js) e
+ * volta na hora. O filtro é largo de propósito: o refresh só roda quando o
+ * grafo da raiz está atrás do HEAD, então um `git status` custa um processo
+ * que sai sem fazer nada — e um comando que move o HEAD sem ser reconhecido é
+ * exatamente como o grafo ficou 85 commits atrás.
+ *
+ * Silencioso e fail-open: nunca injeta contexto, nunca bloqueia.
+ */
+
+import { stateExists } from '../../shared/state-reader.js';
+import { runStandalone } from '../../shared/hook-response.js';
+import { tokenize } from '../../shared/command-tokens.js';
+import { kickGraphRefresh } from '../../shared/graph-refresh.js';
+
+const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);
+const GIT_TOOL = /(^|[\\/])(git|gh|morph-spec)(\.exe|\.cmd)?$/i;
+
+/**
+ * @param {string} command
+ * @returns {boolean} o comando chama git, gh ou morph-spec em algum ponto
+ */
+export function touchesGit(command) {
+  return tokenize(command)
+    .flatMap((t) => t.split(/[;&|()]+/))
+    .some((t) => GIT_TOOL.test(t));
+}
+
+/**
+ * @param {object} payload - PostToolUse stdin payload
+ * @returns {Promise<null>}
+ */
+export async function run(payload) {
+  try {
+    if (!SHELL_TOOLS.has(payload?.tool_name)) return null;
+    if (!touchesGit(payload?.tool_input?.command)) return null;
+    const dir = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    if (!stateExists(dir)) return null;
+    kickGraphRefresh(dir);
+  } catch { /* fail-open */ }
+  return null;
+}
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -3,76 +3,80 @@
 /**
  * Telemetry Hook: harness execution-path capture
  *
- * Events: PostToolUse (all tools) + UserPromptSubmit
+ * Events: PostToolUse + PostToolUseFailure (all tools), PostToolBatch,
+ * SubagentStop, UserPromptSubmit
  *
  * morph-spec is a Natural Language Harness: there is no central runtime to
  * instrument — Claude Code executes the skills and sub-agents. The only
  * vantage points are hooks. This one is the generic capture point: every tool
  * call and every user prompt is appended (one JSON line) to
- * .morph/logs/events.jsonl, from which `morph-spec telemetry` reconstructs the
- * whole path — which skills ran, which personas were dispatched (with their
- * prompts), which standards/knowledge-base files were read.
+ * .morph/logs/events.jsonl, from which `morph-spec telemetry` and
+ * `morph-spec cost` reconstruct the path and measure it.
  *
  * Correlation is by an EXPLICIT key (feature + phase) written into each event,
  * not by ambient span context — hooks fire as separate node processes with no
- * shared trace context (the enrichment lesson from the observability standard:
- * propagate a correlation key, a TraceId does not survive the boundary).
+ * shared trace context. `sessionId` and `agentId` (present only inside a
+ * sub-agent) separate the orchestrator from the sub-agents it dispatched.
+ *
+ * PostToolUse fires only when a tool SUCCEEDS; a Bash command that exits
+ * non-zero fires PostToolUseFailure instead. Only the exit code parsed from
+ * its `error` first line is kept — the rest of `error` is the command's
+ * output, where a secret value can appear with no name beside it.
  *
  * SINK RESOLUTION: the event is appended to the `.morph/` tree that OWNS the
- * tool's target file, not to `process.cwd()`/`CLAUDE_PROJECT_DIR` — same
- * pattern as trace-autogen/state-sync (`resolveMorphRoot`). A session rooted
- * in the primary repo can legitimately touch a feature living in a secondary
- * git worktree; sinking on the session's cwd put those events in the WRONG
- * tree's events.jsonl, the mirror of the trace-autogen worktree defect. Tools
- * that carry no file_path (Bash, Skill, Agent…) have no target to resolve —
- * the session cwd stays the reference for those, same as before.
+ * tool's target file (`resolveMorphRoot`); tools with no file path sink on the
+ * nearest morph tree above the payload's `cwd`, so a sub-agent working in a
+ * worktree logs its Bash calls next to its Reads and Writes.
  *
  * SILENT: never blocks, never injects context — only appends. Fail-open on any
  * error (exit 0). Only active inside a morph project (stateExists gate).
  */
 
-import { statSync } from 'fs';
+import { statSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
 import { stateExists, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 import { runStandalone } from '../../shared/hook-response.js';
 import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
+import { redactSecrets } from '../../shared/redact-secrets.js';
+import { exitCodeMasked } from '../../shared/command-tokens.js';
+import { readTranscriptUsage, usageDelta } from '../../shared/transcript-usage.js';
 
 function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
-// events.jsonl grows forever across a project's lifetime (R2 rotation caps
-// the FILE, not any single line) — a multi-KB sub-agent prompt or a long
-// Bash command written verbatim on every dispatch/call is the dominant per-
-// line cost. Capped AT THE WRITE SITE (not in the shared logger, so every
-// OTHER event type stays exactly as-is) to `MAX_FIELD_CHARS`, with the
-// ORIGINAL length preserved in a sibling `<field>Chars` key — `morph-spec
-// cost` sums prompt chars for its dispatch-cost view, and must prefer that
-// field over `prompt.length` once it's present (a truncated string's own
-// length would silently undercount every dispatch over the cap). This shape
-// is a CONTRACT with the telemetry reader — do not rename either half.
+// A multi-KB prompt or command written verbatim on every call dominates the
+// per-line cost. The ORIGINAL length travels in a sibling `<field>Chars` key,
+// which `morph-spec cost` prefers over the truncated string's own length —
+// a contract with the telemetry reader: do not rename either half.
 const MAX_FIELD_CHARS = 2000;
 const TRUNCATE_SUFFIX = '…[truncado]';
 
+// Read returns this many lines when the call passes no `limit`.
+const DEFAULT_READ_LINES = 2000;
+// Above this, measuring the slice would cost more than the hook budget allows.
+const MAX_SLICE_BYTES = 10 * 1024 * 1024;
+const BINARY_READ = /\.(png|jpe?g|gif|webp|bmp|ico|pdf)$/i;
+
 /**
- * Cap a free-text field (prompt/command) at MAX_FIELD_CHARS, always
- * reporting the field's true original length alongside it.
+ * Redact, then cap a free-text field, reporting its original length. Redacting
+ * first keeps a token cut at the cap from surviving as a recognizable prefix.
  *
  * @param {string} value
  * @returns {{ value: string, chars: number }}
  */
 function capField(value) {
   const str = typeof value === 'string' ? value : '';
-  if (str.length <= MAX_FIELD_CHARS) return { value: str, chars: str.length };
-  return { value: str.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
+  const clean = redactSecrets(str);
+  if (clean.length <= MAX_FIELD_CHARS) return { value: clean, chars: str.length };
+  return { value: clean.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
 }
 
 /**
  * Classify a Read target into the telemetry `kind` taxonomy — a contract with
- * the observability side (src/lib/telemetry/telemetry-reader.js), so these
- * values are pinned, not free-form. Order matters: check the specific
- * categories before falling back to 'code'. Case-insensitive; `/` and `\`
- * both normalize to `/` upstream via `normalize()`.
+ * src/lib/telemetry/telemetry-reader.js, so these values are pinned. Specific
+ * categories first, 'code' last.
  */
 function classifyReadKind(target) {
   const t = (target || '').toLowerCase();
@@ -82,9 +86,6 @@ function classifyReadKind(target) {
   if (t.endsWith('skill.md') || t.includes('/skills/')) return 'skill';
   if (t.split('/').pop() === 'agents.json') return 'agents';
 
-  // Inside a feature folder AND one of the named plan artifacts (or under a
-  // usecases/ or reports/ subfolder) — everything else in a feature folder
-  // (source files a task produced, say) is 'code'.
   const inFeature = t.match(/\.morph\/features\/[^/]+\/(.+)$/);
   if (inFeature) {
     const rel = inFeature[1];
@@ -101,60 +102,118 @@ function classifyReadKind(target) {
   return 'code';
 }
 
+/** Nearest directory at or above `dir` that is a morph project; `fallback` when none. */
+function morphRootAbove(dir, fallback) {
+  if (!dir) return fallback;
+  let current = normalize(dir);
+  for (let i = 0; i < 32; i++) {
+    if (stateExists(current)) return current;
+    const parent = normalize(dirname(current));
+    if (parent === current) break;
+    current = parent;
+  }
+  return fallback;
+}
+
+function featureFromPath(target) {
+  const m = /\/\.morph\/features\/([^/]+)\//.exec(`/${normalize(target)}`);
+  return m ? m[1] : null;
+}
+
 /**
- * @param {object} payload - parsed PostToolUse (any tool) or UserPromptSubmit payload
- * @returns {Promise<null>} always null — this hook is pure side-effect
- *   (appends to events.jsonl + claim heartbeat), never prints/injects context.
+ * What a Read actually put in context: the requested line window, not the
+ * whole file. Binary reads (images, PDFs) go in whole.
+ */
+function readSliceBytes(absPath, input, size) {
+  if (BINARY_READ.test(absPath)) return size;
+  if (size > MAX_SLICE_BYTES) return undefined;
+  const offset = Number.isInteger(input.offset) && input.offset > 1 ? input.offset : 1;
+  const limit = Number.isInteger(input.limit) && input.limit > 0 ? input.limit : DEFAULT_READ_LINES;
+  const lines = readFileSync(absPath, 'utf-8').split('\n');
+  if (offset === 1 && limit >= lines.length) return size;
+  return Buffer.byteLength(lines.slice(offset - 1, offset - 1 + limit).join('\n'), 'utf-8');
+}
+
+/** Exit code and outcome of a finished tool call, without keeping its output. */
+function outcomeOf(payload, input) {
+  if (payload.hook_event_name === 'PostToolUseFailure') {
+    const firstLine = String(payload.error ?? '').split('\n', 1)[0];
+    const code = /^exit code (\d+)/i.exec(firstLine);
+    const outcome = payload.is_interrupt === true ? 'interrupted'
+      : /timed? ?out/i.test(firstLine) ? 'timeout'
+        : 'error';
+    return { outcome, exitCode: code ? Number(code[1]) : null };
+  }
+  if (input.run_in_background === true) return { outcome: 'background', exitCode: null };
+  if (payload.tool_response?.interrupted === true) return { outcome: 'interrupted', exitCode: null };
+  return { outcome: 'ok', exitCode: 0 };
+}
+
+function countByName(calls) {
+  const out = {};
+  for (const call of calls) {
+    const name = call?.tool_name || 'unknown';
+    out[name] = (out[name] || 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * Sub-agent tokens live in their own transcript; each stop emits the delta.
+ * One file per agent: two sub-agents stopping together never share a
+ * read-modify-write, and one agent never stops twice at once.
+ */
+function agentUsageEvent(payload, cwd) {
+  const usage = readTranscriptUsage(payload.agent_transcript_path);
+  if (!usage || !payload.agent_id) return null;
+  const dir = join(cwd, '.morph', 'memory', 'agent-usage');
+  const storePath = join(dir, `${String(payload.agent_id).replace(/[^A-Za-z0-9_-]/g, '_')}.json`);
+  let previous = null;
+  try {
+    if (existsSync(storePath)) previous = JSON.parse(readFileSync(storePath, 'utf-8'));
+  } catch { previous = null; }
+  const { delta, changed } = usageDelta(previous, usage);
+  if (!changed) return null;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(storePath, JSON.stringify(usage), 'utf-8');
+  } catch { /* the event still carries the delta */ }
+  return { event: 'AgentUsage', ...usage, delta };
+}
+
+/**
+ * @param {object} payload - parsed hook payload (PostToolUse, PostToolUseFailure,
+ *   PostToolBatch, SubagentStop or UserPromptSubmit)
+ * @returns {Promise<null>} always null — pure side effect (append + claim heartbeat)
  */
 export async function run(payload) {
   try {
     if (!payload) return null;
 
-    // Resolve the sink tree from the tool's target file (when it has one)
-    // BEFORE the stateExists gate below — otherwise a root session writing
-    // into a worktree would be gated on the ROOT's state instead of the
-    // worktree's.
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
     const targetFilePath = getFilePath(payload);
-    const cwd = targetFilePath ? resolveMorphRoot(targetFilePath, projectDir) : projectDir;
+    const cwd = targetFilePath
+      ? resolveMorphRoot(targetFilePath, projectDir)
+      : morphRootAbove(payload.cwd, projectDir);
 
     if (!stateExists(cwd)) return null;
 
-    // Correlation key: active feature + its phase (explicit, not ambient).
-    // NOTE (perf): getActiveFeature → loadState hydrates every .morph/features/*/
-    // feature.json, so enrichment is O(active-feature-count) per tool call. That
-    // is fine for realistic projects (archive removes finished features, so the
-    // dir holds only the few in-flight ones) but would grow on a project that
-    // keeps many un-archived features. If that ever bites, resolve the active
-    // feature from the thin state.json index alone. Kept accurate-over-cheap for
-    // now because phase is not stored in feature.json — it needs derivation.
+    // getActiveFeature → loadState hydrates every feature.json: O(active
+    // features) per call, fine while archive keeps that set small.
     let feature = null;
     let phase = null;
     try {
       const active = getActiveFeature(cwd);
-      if (active) {
-        feature = active.name;
-        phase = active.feature?.phase || derivePhaseForFeature(active.name, cwd);
-      }
+      feature = active?.name ?? featureFromPath(targetFilePath);
+      if (feature) phase = active?.feature?.phase || derivePhaseForFeature(feature, cwd);
     } catch {
       // enrichment is best-effort — a missing feature never blocks capture
     }
 
-    // Claim heartbeat (B1): this hook already fires on EVERY tool call, so it is
-    // the natural proof-of-life for the advisory feature claim — no extra hook,
-    // no discipline asked of the operator. Two throttles guard the cost:
-    //   1. shouldHeartbeat() — a LOCAL, git-independent pre-check (see its own
-    //      doc in claim-registry.js) that answers "is a heartbeat even due"
-    //      from a marker beside this project's own `.morph/logs/`. On ~99% of
-    //      calls it says no and NOTHING git-related happens — not even the
-    //      pure-FS walk below, let alone a subprocess.
-    //   2. Only when (1) says yes do we resolve the git common dir — via
-    //      git-paths.js, pure filesystem, no `git` subprocess spawn (this used
-    //      to be `execSync('git rev-parse --git-common-dir')`, ~34ms wasted on
-    //      ~99% of calls because the write below was ALREADY throttled) — and
-    //      call heartbeatClaim(), which has its own authoritative throttle
-    //      keyed to claims.json's stored heartbeatAt.
-    // Silent and fail-open, like everything else here.
+    // Claim heartbeat: this hook fires on every tool call, so it is the proof
+    // of life for the advisory feature claim. shouldHeartbeat() is a local,
+    // git-free pre-check that says no on ~99% of calls; only then is the git
+    // common dir resolved (pure filesystem, no subprocess).
     if (feature && payload.session_id) {
       try {
         const { shouldHeartbeat, heartbeatClaim } = await import('../../shared/claim-registry.js');
@@ -166,51 +225,77 @@ export async function run(payload) {
       } catch { /* fail-open — a missed heartbeat only shortens a claim's life */ }
     }
 
+    const hookEvent = payload.hook_event_name;
     let event;
 
-    // UserPromptSubmit carries the user's prompt and no tool_name.
-    if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
+    if (hookEvent === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string' && !hookEvent)) {
       const userPrompt = capField(payload.prompt || '');
       event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: userPrompt.value, promptChars: userPrompt.chars };
+    } else if (hookEvent === 'PostToolBatch') {
+      const calls = Array.isArray(payload.tool_calls) ? payload.tool_calls : [];
+      event = { event: 'ToolBatch', size: calls.length, tools: countByName(calls) };
+    } else if (hookEvent === 'SubagentStop') {
+      event = agentUsageEvent(payload, cwd);
+      if (!event) return null;
     } else {
       const tool = payload.tool_name;
       if (!tool) return null;
       const input = payload.tool_input || {};
-      event = { event: 'PostToolUse', tool };
+      event = { event: hookEvent === 'PostToolUseFailure' ? 'PostToolUseFailure' : 'PostToolUse', tool };
 
       if (tool === 'Skill') {
         event.skill = input.skill || '';
       } else if (tool === 'Agent' || tool === 'Task') {
         event.persona = input.subagent_type || '';
-        if (input.description) event.desc = input.description;
+        if (input.description) event.desc = redactSecrets(input.description);
         const dispatchPrompt = capField(input.prompt || '');
         event.prompt = dispatchPrompt.value;
         event.promptChars = dispatchPrompt.chars;
+      } else if (tool === 'SendMessage') {
+        if (input.to) event.target = String(input.to);
+        event.messageChars = typeof input.message === 'string' ? input.message.length : 0;
       } else if (tool === 'Read') {
         event.target = targetFilePath || normalize(input.file_path || input.path);
         event.kind = classifyReadKind(event.target);
-        // bytes is best-effort: statSync races a file that got deleted/moved
-        // between the Read and this hook firing, or lacks permission — omit
-        // the field rather than fail the whole (silent, fail-open) capture.
-        try {
-          event.bytes = statSync(resolveTargetPath(event.target, cwd)).size;
-        } catch {
-          // omit bytes
+        if (Number.isInteger(input.offset)) event.offset = input.offset;
+        if (Number.isInteger(input.limit)) event.limit = input.limit;
+        // A failed Read ingested nothing. A stat/read race with a file deleted
+        // between the Read and this hook omits the numbers rather than fail.
+        if (hookEvent !== 'PostToolUseFailure') {
+          try {
+            const abs = resolveTargetPath(event.target, cwd);
+            event.bytes = statSync(abs).size;
+            const read = readSliceBytes(abs, input, event.bytes);
+            if (read !== undefined) event.bytesRead = read;
+          } catch {
+            // omit bytes
+          }
         }
-      } else if (tool === 'Bash') {
-        const bashCommand = capField(input.command || '');
-        event.command = bashCommand.value;
-        event.commandChars = bashCommand.chars;
+      } else if (tool === 'Bash' || tool === 'PowerShell') {
+        const command = capField(input.command || '');
+        event.command = command.value;
+        event.commandChars = command.chars;
+        Object.assign(event, outcomeOf(payload, input));
+        if (exitCodeMasked(input.command)) event.exitMasked = true;
       } else if (tool === 'Write' || tool === 'Edit') {
         event.target = normalize(input.file_path || input.path);
       } else {
-        // Every other tool still counts toward "the whole path" — record a
-        // compact target so Grep/Glob/WebFetch bursts remain distinguishable.
+        // Every other tool still counts toward "the whole path" — a compact
+        // target keeps Grep/Glob/WebFetch bursts distinguishable.
         const target = input.file_path || input.path || input.pattern || input.query || input.url || '';
         if (target) event.target = normalize(String(target));
       }
+
+      if (hookEvent === 'PostToolUseFailure' && event.outcome === undefined) event.outcome = 'error';
+      if (payload.tool_use_id) event.toolUseId = payload.tool_use_id;
+      if (Number.isFinite(payload.duration_ms)) event.durationMs = payload.duration_ms;
     }
 
+    if (payload.session_id) event.sessionId = payload.session_id;
+    if (payload.prompt_id) event.promptId = payload.prompt_id;
+    if (payload.agent_id) event.agentId = payload.agent_id;
+    if (payload.agent_type) event.agentType = payload.agent_type;
+    if (payload.cwd) event.cwd = normalize(payload.cwd);
     event.feature = feature;
     event.phase = phase;