roafacturare/docs/s0_context_hook.md

# S0 - Prototip context/handoff: fix SubagentStop, -StareFile, compactare mai devreme

Executat 17.09.2026, pe masina curenta (fara UI, conform plan_qa_factura_aviz.md sectiunea S0).

## Ce am gasit

- Hook-ul `SubagentStop` din `C:\Users\mmari\.claude\settings.json` (era la cheia
  `hooks.SubagentStop[0].hooks[0].command`) era un simplu `echo '{"hookSpecificOutput":...}'`
  static, executat de fiecare data cand un subagent se opreste, fara sa citeasca deloc stdin-ul
  hook-ului. Nu bloca explicit (nu avea `decision:block`/exit 2), dar reinjecta acelasi
  `additionalContext` la fiecare `SubagentStop`, inclusiv la reincercarile in acelasi ciclu de
  stop - de aici bucla observata (patru agenti raportand cicluri repetate in aceeasi sesiune).
  Cauza + fix documentate in `docs/qa_factura_hooks_ref.md` sectiunea 4 ("stop_hook_active si
  bucla"): campul `stop_hook_active` trebuie citit de pe stdin, iar la `true` hook-ul trebuie sa
  iasa imediat cu 0, fara iesire.
- `context_watch.ps1` e in `D:\ROA\ROAGEST\COMUN\utile\context_watch.ps1`. Verificat: acel `COMUN`
  e checkout separat al aceluiasi repo `git@gitea.romfast.ro:romfast/comun.git` ca si
  `D:\ROA\ROAFACTURARE\COMUN` (acelasi `origin`, ramuri `main`) - deci e intr-adevar biblioteca
  partajata, doar clonata separat per produs. Nu l-am mutat: mutarea in `COMUN` (punctul 4 din
  planul S0) nu a fost in cele trei sarcini primite de la team lead pentru aceasta sesiune, ramane
  neacoperit (vezi mai jos).
- Scriptul deja avea parametrii `-Stdout` (UserPromptSubmit) si `-OSinguraData` (PostToolUse,
  dedup prin fisier marcaj in `%TEMP%`); nu avea niciun mecanism de scriere pe disc a starii.
- `env` in `settings.json` nu exista `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`.

## Ce am schimbat

### 1. Garda `stop_hook_active` pe hook-ul SubagentStop

`C:\Users\mmari\.claude\settings.json`, cheia `hooks.SubagentStop[0].hooks[0].command`
(inainte de orice modificare am facut copie de siguranta la
`C:\Users\mmari\.claude\settings.json.bak_20260917`, verificata pe disc):

Inainte:
```
echo '{"hookSpecificOutput":{"hookEventName":"SubagentStop","additionalContext":"..."}}'
```

Dupa:
```
grep -q '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && exit 0; echo '{"hookSpecificOutput":{"hookEventName":"SubagentStop","additionalContext":"..."}}'
```

Mesajul `additionalContext` a ramas identic (neschimbat), doar prefixat cu garda. `grep -q`
citeste stdin-ul hook-ului (JSON-ul cu `stop_hook_active`) fara dependenta de `jq` (nu e instalat
pe masina - verificat). Daca patternul gaseste `"stop_hook_active":true` (cu sau fara spatiu dupa
`:`), hook-ul iese cu 0 fara sa emita nimic; altfel continua la `echo` ca inainte.

### 2. `-StareFile` in `context_watch.ps1`

`D:\ROA\ROAGEST\COMUN\utile\context_watch.ps1`:
- linia 20: parametru nou `[string]$StareFile`.
- liniile 23-36: functia noua `Scrie-AntetStare` - daca fisierul exista si primul rand se
  potriveste cu `^<!-- context_watch:`, il inlocuieste; altfel adauga antetul ca prim rand
  (fisier nou sau fisier existent fara antet). Restul continutului ramane neschimbat.
- linia 92: apel `if ($StareFile) { Scrie-AntetStare -cale $StareFile -tokeni $total -nivel $nivel }`
  in blocul `if ($mesaj)`, deci se declanseaza exact cand pragul de avertisment sau max e atins
  (acelasi punct unde se decide mesajul), indiferent de `-Stdout`/`-OSinguraData`.
- Comportamentul fara `-StareFile` e neschimbat: parametrul e opt, iar apelul e conditionat de
  prezenta lui.

### 3. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` in settings

`C:\Users\mmari\.claude\settings.json`, cheia `env` (exista deja, avea doar
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`): adaugat `"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70"`.
Nicio alta setare atinsa.

## Rezultatul probelor cerute

1. **`settings.json` e JSON valid** dupa modificare:
   `Get-Content ... -Raw | ConvertFrom-Json` -> a rulat fara eroare, a scris `JSON_VALID`.
2. **`context_watch.ps1 -StareFile` pe transcript de test** (usage sintetic la 260000 tokeni,
   peste pragul implicit de 250000):
   - rulare 1: fisier inexistent -> creat, un singur rand:
     `<!-- context_watch: 17.09.2026 21:57 | tokeni: 260000 | nivel: avertisment -->`.
   - am adaugat manual un rand "text scris de model" dupa antet (simuland continutul modelului).
   - rulare 2 (o secunda mai tarziu): antetul de pe primul rand a fost INLOCUIT (ora actualizata),
     randul "text scris de model" a ramas neatins, nu s-a adaugat un al doilea antet
     (verificat cu citire BOM-aware: 2 linii total, 1 linie cu prefixul antetului).
3. **`context_watch.ps1` fara `-StareFile`**: acelasi transcript de test -> acelasi mesaj de
   avertisment pe stderr, exit code 2, identic cu comportamentul dinaintea modificarii (nimic
   scris pe disc).
4. **Hook-ul `SubagentStop`**: comanda extrasa din `settings.json` dupa modificare, rulata direct:
   - stdin `{"stop_hook_active":true}` -> nicio iesire, exit 0.
   - stdin `{"stop_hook_active":false}` -> a scos exact `additionalContext`-ul de dinainte, exit 0.

## Ce a ramas neacoperit

- Punctul 4 din S0 al planului ("se muta in COMUN ca sa fie refolosibil de toate produsele ROA")
  NU a fost facut - nu a fost in lista de 3 sarcini primite de la team lead pentru aceasta rulare.
  Scriptul ramane in `D:\ROA\ROAGEST\COMUN\utile\context_watch.ps1`, neschimbat ca locatie.
- Proba "ciclu real cu subagent care se termina, o singura rulare a hook-ului" (mentionata in
  plan la finalul sectiunii S0) nu a fost reprodusa printr-un subagent real - probele de mai sus
  au testat garda si scrierea de stare direct, in izolare, nu printr-o rulare completa
  Claude Code cu un subagent viu. Nu am lansat subagenti (interdictie explicita in sarcina).
- Nu am facut niciun commit (interdictie explicita); `settings.json` nu e sub control de versiuni
  in acest repo, deci nu exista diff de revizuit acolo - doar backup-ul
  `C:\Users\mmari\.claude\settings.json.bak_20260917`. `context_watch.ps1` e in repo-ul `COMUN`
  (git) - diff-ul ramane de revizuit acolo inainte de commit, conform regulii "fara commit fara
  review".