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".