v3.10.0 — Sync from Claude Code v2.1.144→v2.1.152 (features)

Builds on the v3.9.1 security patch. 14 upstream feature/UX practices from the same release window.

Highlights

• MessageDisplay hook event (v2.1.152) — first display-time event. Catalogue 32+ → 34+, four lifecycle cadences now. Use for PII/secret redaction or markdown post-processing.
• SessionStart hook expansion (v2.1.152) — reloadSkills: true re-scans skills in same session; sessionTitle extends to startup/resume (was UserPromptSubmit-only).
• Stop / SubagentStop receive background_tasks + session_crons (v2.1.145). template/hooks/session-report.sh consumes them.
• disallowed-tools frontmatter (v2.1.152) — companion to allowed-tools. Pattern for read-only analytical skills.
• autoMode.hard_deny opt-in consent removed (v2.1.152) — auto mode activates directly.
• /code-review (rename + --fix + --comment, v2.1.147/.152). Independent from dotforge's code-reviewer subagent.
• /reload-skills (v2.1.152), /model per-session by default (v2.1.144), /extra-usage → /usage-credits (v2.1.144).
• claude agents --json (v2.1.145) for scripting.
• ANTHROPIC_WORKSPACE_ID (v2.1.141) for multi-workspace SAML/OIDC federation.
• OTEL claude_code.tool spans carry agent_id (v2.1.145); trace parenting fixed.

Practices

14 new in active/ (4 monitoring + 10 informational). 92 practices tracked.

Full diff

v3.9.1...v3.10.0

v3.9.1 — Upstream security fixes propagated (v2.1.145→v2.1.149)

Patch release dedicated to five upstream security/permission fixes from the v2.1.145–v2.1.149 hardening pass. Documentation-only — no code changes.

Fixed bypasses

1. PowerShell cd built-ins (v2.1.149): cd.., cd\, cd~, X: changed working dir undetected, letting later commands escape the workspace.
2. Sandbox worktree allowlist scope (v2.1.149): write allowlist covered entire main repo root instead of shared .git subset.
3. forceLoginOrgUUID / forceLoginMethod (v2.1.147): enforced only against Claude.ai sessions — 3rd-party-provider + API-key sessions silently bypassed.
4. Bare env var assignments (v2.1.145): FOO=bar cmd with non-allowlisted FOO was auto-approved.
5. PowerShell execution policy (v2.1.143+ behavior): -ExecutionPolicy Bypass default. Opt-out via CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1.

Action recommended

Re-audit any project with worktree patterns, Windows + PowerShell tool, or enterprise forceLogin* managed settings. Pre-v2.1.149 audits may have a false sense of coverage.

Full diff

v3.9.0...v3.9.1

v3.9.0 — Sync from Claude Code v2.1.141-143

Sync from Claude Code v2.1.141-143

Procesados 13 items del inbox (acumulado 2026-05-18 a 2026-05-19). 8 incorporados a domain rules + skill + best-practices. 3 rechazados (1 informational sin acción, 2 auto-stubs de session-changes sin proyecto identificable). 2 diferidos (powershell-execution-policy con tag needs-windows-user; workspace-id-federation con tag needs-enterprise-federation).

Domain rules

• domain/hook-events.md — nueva sección "Hook JSON output fields (universal)" con continue, stopReason, suppressOutput, systemMessage, y el nuevo terminalSequence (v2.1.141+) para desktop notifications / window titles / terminal bell desde hooks sin TTY. Nueva sección "Stop hook contract (v2.1.143+)" con el cap de 8 bloqueos consecutivos y CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.
• domain/hook-architecture.md — sección "Stop hook convergence contract (v2.1.143+)": cap de 8 blocks, patrones de convergencia (contadores en .claude/session/, systemMessage en vez de block).
• domain/model-ids.md — nueva sección "Fast mode (Opus toggle)" con default flippeado a Opus 4.7 (v2.1.142) y CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 para pin a 4.6.
• domain/cli-flags.md — claude agents ahora documentado como launcher con los 9 flags (--cwd, --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort, --dangerously-skip-permissions). Nuevas env vars: CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.
• domain/parallel-sessions.md — nueva sección "Disabling bg session worktree isolation" con worktree.bgIsolation: "auto"|"none" y los trade-offs (Bazel/codegen vs concurrent-clobber risk). Nueva sección "Configuring sessions dispatched from claude agents" documenta los flags-as-launcher y la persistencia en detach a /bg (v2.1.143).
• domain/compaction-strategy.md — tabla extendida con cuarta modalidad: rewind + "Summarize up to here" (v2.1.141), sexta opción del rewind menu. Comprime desde session start hasta un checkpoint elegido, deja turnos posteriores intactos.

Skills

• skills/plugin-generator/SKILL.md — documenta dos shapes:
  • Flat (single-skill, v2.1.142+): SKILL.md en root sin skills/ directory
  • Structured (default): cuando hay ≥2 skills u otros componentes
  • Plus: plugin.json ahora incluye dependencies: [] con guía sobre el enforcement de v2.1.143 (claude plugin disable rechaza si otros plugins dependen; enable force-enables transitive deps).

Docs

• docs/best-practices.md — nueva subsección "Recent additions (v2.1.141-143)" con 6 entries: Stop hook anti-pattern, plugin disable-chain, hook terminalSequence, worktree.bgIsolation, claude agents launcher, rewind+summarize partial.

Inbox lifecycle

Item	Decisión
claude-agents-cli-flags	accept → incorporated_in: ['3.9.0']
fast-mode-opus-4-7-default	accept (informational)
hook-terminal-sequence	accept (informational)
plugin-dependency-enforcement	accept (monitoring: integration)
plugin-root-skill-md	accept (informational)
rewind-summarize-partial	accept (informational)
stop-hook-block-cap	accept (monitoring: logic)
worktree-bgisolation-none	accept (monitoring: config)
plugin-lsp-visibility	reject — informational, no requiere cambio (self-deferred)
stoic-babbage-session-changes	reject — auto-stub sin proyecto identificable
festive-maxwell-session-changes	reject — idem
powershell-execution-policy	defer — tag needs-windows-user
workspace-id-federation	defer — tag needs-enterprise-federation

Metrics

8 entradas nuevas en practices/metrics.yml: 3 monitoring (logic/config/integration con error_targeted), 5 informational.

v3.8.1 — Docs domain migration (docs.anthropic.com → code.claude.com)

Maintenance: docs domain migration.

• skills/watch-upstream/SKILL.md: 6 fetch URLs migrated from
  docs.anthropic.com/en/docs/claude-code/* to code.claude.com/docs/en/*
  (Anthropic flipped the canonical host between v3.7.x and v3.8.0).
  agent-tool slug also moved → sub-agents. Added llms.txt fallback
  note for future migrations.
• docs/internal/improvement-plan-internals.md: WebFetch reference
  updated to point at the new canonical host.

Practice: 2026-05-18-docs-domain-migration-claude-code (active,
informational).

v3.8.0 — Sync from Claude Code v2.1.129→v2.1.140 + new domain/auth.md

Highlights

/forge watch pass against code.claude.com covering Claude Code v2.1.129 → v2.1.140. Ten upstream practices accepted, seven auto-generated session-changes captures rejected.

Hooks (high impact)

• continueOnBlock: true for PostToolUse hooks (v2.1.139+) — flips block semantics from fatal stop to feedback loop: the hook's reason is fed back to Claude and the turn continues. Game-changer for non-fatal validators (lint, type-check, drift).
• Exec form (args: string[], v2.1.139+) — spawns directly via execve without a shell. No quoting needed for ${tool_input.*} placeholders. Eliminates shell injection via crafted payloads. Recommended whenever a hook consumes user-controlled values.
• Effort visibility (v2.1.133+) — every hook input includes effort.level; Bash tool subprocesses see $CLAUDE_EFFORT. Enables effort-aware decisions (stricter at low, relaxed at max).
• Distributed tracing (v2.1.139+) — subagent API requests carry x-claude-code-agent-id / x-claude-code-parent-agent-id headers; OTEL spans include matching attrs.

Auto mode

• autoMode.hard_deny (v2.1.136+) — third tier alongside allow and soft_deny. Blocks unconditionally with no override path. Recommended for Bash(curl *|sh), eval pipes, base64-decode pipes in projects handling cloud creds.

Auth model

• New domain/auth.md rule — covers the four auth sources (API key > setup-token OAuth > Claude.ai > Console) with precedence and a critical v2.1.139+ change: setting ANTHROPIC_API_KEY / apiKeyHelper / ANTHROPIC_AUTH_TOKEN silently disables Remote Control, /schedule, claude.ai MCP connectors, and notifications — even when a Claude.ai login is also present. CI runbook: use claude setup-token instead of an API key when Routines are needed.

Permission model fix

• Plan mode now precedes allow rules (v2.1.136 fix). Before this fix, a permissions.allow: ["Edit(*)"] would bypass plan mode's read-only constraint — silent security bug. The evaluation cascade in domain/permission-model.md is updated to reflect the fixed order.

Worktree subtle breaking

• worktree.baseRef setting (v2.1.133+). Between v2.1.128 and v2.1.132 the default was head (worktrees carried unpushed local commits); v2.1.133 reverted to fresh (branches from origin/<default>). Set worktree.baseRef: "head" if your Agent Teams workflow relied on local-HEAD propagation.

Background sessions

• claude --bg + lifecycle subcommands (attach/logs/respawn/rm/stop, v2.1.139+) — process-level isolation alongside filesystem-level --worktree. Pairs with claude agents agent-view (Research Preview).

Workflow automation

• /goal <condition> (v2.1.139+) — fourth temporal primitive: persistent completion condition across turns. Condition-driven (semantic) vs /loop's cadence-driven (temporal). Use when the stop signal is well-defined.

Other breaking surface

• Gateway model discovery (v2.1.129 breaking) — /v1/models discovery against custom ANTHROPIC_BASE_URL gateways now requires CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Was automatic in v2.1.126–v2.1.128. Affects Bedrock app-inference-profile, Vertex custom endpoints, Foundry, any gateway.

---

Verified

49 pass / 2 pre-existing fails — both predate v3.8.0:

• tests/test-hooks.sh: git commit -m "test" mismatch
• scripts/forge-behavior/tests/test_on_off.sh: search-first expected enabled (intentionally disabled in v3.6.1)

Full diff

v3.7.1...v3.8.0

v3.7.1 — Evidence-based compaction policy (80% threshold)

Política de compactación basada en evidencia

Investigación combinando academia (Liu et al. Stanford 2023, Chroma Research, Greg Kamradt) y práctica de campo en X (Boris Cherny y Cat Wu de Anthropic, Daniel San, Avthar, Paweł Huryn) consolidada en política operacional dotforge. Threshold canónico: 80% del context window (no 50%, no 96.7% default).

Nuevas piezas

• domain/compaction-strategy.md (nueva domain rule, 70 líneas) — política basada en evidencia: threshold 80%, distinción /compact vs /clear vs subagent, anti-patterns confirmados, cache economy (Paweł Huryn — invalidación de prefix cache), re-anchoring para mitigar "lost in the middle" (Liu et al.). Citas con URLs.
• /forge compact-task (nuevo slash command) — wrapper de /compact con hint estandarizado dotforge: preserve decisions, files modified, pending TODOs, behaviors disabled, last commit; drop tool output verbose. Resuelve el anti-pattern de /compact sin instructions custom.
• /forge context-status (nuevo slash command) — reporte read-only sobre uso estimado del context window, cache health proxy (basado en tool-latency.sh p50), edits recientes, recomendación de acción. No compacta.
• pre-compact-warning.sh (nuevo hook, wired en UserPromptSubmit) — alerta proactiva al 80% (warning) y 90% (urgent). Estimación: bytes del transcript / 5. Configurable via env vars: CLAUDE_CONTEXT_LIMIT, CLAUDE_COMPACT_WARN_PCT, CLAUDE_COMPACT_URGENT_PCT. Smoke-tested en 3 escenarios (debajo del threshold, warning, urgent).
• docs/internal/compaction-strategy.md (~200 líneas) — guía operacional canónica con flow chart ASCII, tabla de decisión /compact vs /clear vs subagent, configuración por tipo de proyecto (light/standard/heavy), bibliografía completa (académica + X).

Wiring

• .claude/settings.json: nuevo bloque UserPromptSubmit con pre-compact-warning.sh (timeout 3s)
• template/settings.json.tmpl: idem para propagación a 12 proyectos
• template/hooks/pre-compact-warning.sh: copia propagable

Hallazgos clave de la investigación

• Liu et al. (Stanford 2023): 30%+ accuracy loss para info en el medio del contexto (7-50% depth)
• Chroma Research (2024): 18 modelos frontier degradan dentro de su ventana declarada — Sonnet 200K muestra caídas desde 50K tokens
• Greg Kamradt: GPT-4 recall degrada >73K tokens
• Boris Cherny (Anthropic): auto-compact dispara ~155K tokens; plan acceptance auto-clears context
• Cat Wu (Anthropic): defiende auto-compact como preservador de info crítica
• Daniel San (X): mantiene auto-compact OFF, hook al 80% en producción ("every time it triggered for me, I lost important context")
• Avthar (X): "actively clear context yourself using /clear or /compact rather than waiting for auto-compact to happen mid-task, which can hurt performance"
• Paweł Huryn (X): cache economics dominan la decisión — bug de marzo 2026 causó 20× cost inflation por cache roto

Convergencia de la evidencia

Threshold	Veredicto
50%	Demasiado agresivo. Pérdida de thread reciente, summary acumula degradación
80%	Sweet spot. Coinciden Daniel San, Avthar, evidencia académica con safety margin
96.7% (default)	Demasiado tarde. Calidad ya degradada al disparar auto-compact

v3.7.0 — Smart init — startup snapshot + drift + Setup validation

Init inteligente — startup snapshot + drift detection + Setup validation

Cuatro piezas nuevas que cierran la simetría con auto-compact (v3.6.3): el SessionStart ahora captura, compara y persiste el estado inicial; el Setup hook valida invariantes antes de cualquier tool call.

Nuevos hooks

• .claude/hooks/session-startup.sh (wired en SessionStart, todos los source ≠ compact):

  • Captura branch, HEAD short, working tree count, archivos .claude/ editados en últimas 24h, TODOs/FIXMEs pendientes, behaviors deshabilitados
  • Compara HEAD actual con el HEAD del último snapshot en startup-history/ → emite "drift" line con commits-ahead
  • Escribe .claude/session/last-startup.md (snapshot completo) + startup-history/<ISO>.md (rotating, últimos 5)
  • Inyecta brief al stdout (Claude lo recibe como contexto inicial) SOLO si hay algo notable: tree dirty, recent edits, drift, behaviors off, TODOs pending. Silencioso si todo limpio
  • Silencioso en source=compact (delegado a session-restore.sh)

• .claude/hooks/pre-session-check.sh (wired en Setup, matchers init y maintenance):

  • Valida invariantes en claude --init-only / claude --maintenance:
    1. settings.json es JSON válido
    2. block-destructive.sh presente + ejecutable (security baseline)
    3. behaviors/index.yaml es YAML válido (si existe)
    4. Todos los hooks wireados existen y son ejecutables
    5. DOTFORGE_DIR resuelve (warn only)
  • Exit 2 bloquea session start si hay errores críticos
  • Output: silencioso en éxito, checklist completo en fallo

Cambios

• template/settings.json.tmpl — nuevos hooks wireados:
  • SessionStart agrega tercer entry: session-startup.sh (timeout 10s)
  • Setup con matchers init y maintenance apunta a pre-session-check.sh
• template/hooks/session-startup.sh y template/hooks/pre-session-check.sh — copias propagables a los 12 proyectos en próximo /forge sync
• domain/hook-events.md — documenta el wiring de dotforge en SessionStart (3 hooks) y Setup (pre-session-check). Refleja enabled en index.yaml para los 3 hooks y los matchers para Setup.

Verificación

Smoke tests sobre el proyecto dotforge mismo:

$ printf '{"source":"startup"}' | bash .claude/hooks/session-startup.sh
## Session Startup Brief
**Branch:** main @ fffc0b6
**Working tree:** 6 changed files
**Recent .claude/ edits (24h):** 14
**Behaviors disabled:** search-first,plan-before-code,objection-format

$ bash .claude/hooks/pre-session-check.sh
✓ dotforge pre-session check: all invariants pass

$ printf '{"source":"compact"}' | bash .claude/hooks/session-startup.sh
(silent — delegated to session-restore.sh)

$ # Inject broken hook reference, run check
$ bash .claude/hooks/pre-session-check.sh
── dotforge pre-session check ──
Errors (1):
  ✗ Wired hook missing: .claude/hooks/nonexistent.sh
─────────────────────────────────
exit=2

Lo que cierra de la auditoría inicial

Pre-v3.7.0	Post-v3.7.0
SessionStart sólo en compact re-inyecta contexto	Cubre los 4 sources (startup, resume, compact, clear)
No detección de drift entre sesiones	session-startup.sh compara HEAD vs último snapshot
Setup hook nunca wireado pese a estar documentado	pre-session-check.sh valida invariantes en --init-only
No histórico de session starts	startup-history/ rotating, último 5
Sin visibilidad de behaviors disabled al arrancar	Brief incluye lista explícita

v3.6.3 — Smart auto-compact — filter + rotating history

Auto-compact inteligente — filtrado y histórico

Capa de filtrado encima del compact_summary que genera Claude Code. Dos mejoras concretas al pipeline existente (PostCompact → last-compact.md → SessionStart restore):

• scripts/compact-filter.py (nuevo) — pipe filter conservador que reduce el summary antes de persistirlo. Heurísticas seguras:
  • Bloques fenced (```) >40 líneas → primer 5 + último 5 + nota de elisión
  • Runs de ≥30 líneas no-protegidas (sin markdown structure, sin paths, sin keywords decisión/error/fix/pending) → primer 3 + último 3 + nota
  • Paragraphs duplicados ≥3 veces → 1 sola copia
  • Runs de >2 newlines consecutivos → colapso a 2
  • Nunca filtra: lineas con #/-/|/>/=, paths (.md/.sh/.py/etc.), tokens críticos (decision, error, fix, pending, next step, commit, todo, blocker, warning, fail), primeras 10 líneas
  • Output a stdout, métricas (in/out bytes, ratio) a stderr
  • Tests: 2253B → 730B = 68% reducción sobre summary verbose; 22453B → 22447B = ~0% sobre summary ya denso (no daña).
• .claude/hooks/post-compact.sh + template/hooks/post-compact.sh — pipe summary por compact-filter, con fallback al raw si el filter falla. Métrica [compact-filter] queda en el frontmatter del checkpoint.
• Histórico rotatorio — últimas 5 compactaciones bajo .claude/session/compact-history/<ISO>.md. Permite diff entre compactaciones consecutivas o recovery si last-compact.md quedó stale.
• domain/context-window-optimization.md — actualizado con la nota del nuevo comportamiento del hook.

Verificación

Smoke test end-to-end con JSON sintético (40 líneas filler + decision + next steps):

[compact-filter] in=2253B  out=730B  saved=1523B  ratio=0.32

Sobre last-compact.md real de la sesión actual (22 KB de summary denso):

[compact-filter] in=22453B  out=22447B  saved=6B  ratio=1.00

Comportamiento esperado: summaries densos pasan casi sin tocar, summaries con tool dumps verbose se reducen 30-70%. Worst case el archivo queda igual — el filter es seguridad, no compresión agresiva.

v3.6.2 — Audit follow-ups — signal gate, metric rename, parallel-sessions split

Cierre de pendientes de auditoría

Aplicados los 4 pendientes registrados en v3.6.1.

• hooks/detect-claude-changes.sh — gate de señal: skip auto-stub si TOTAL < 15 archivos AND no hay cambios estructurales (agents/commands/skills = 0). Elimina ruido de inbox que el usuario no podía evaluar.
• Métrica honesta — not-applicable → informational en practices/metrics.yml (35 entradas), skills/update-practices/SKILL.md, practices/active/*.md (11 frontmatters), practices/README.md, docs/config-validation.md, docs/internal/config-validation-flow.md. Validation rate ahora calcula sobre 19 prácticas trackable (no sobre 54), produciendo 0/19 = 0% — métrica realista, no inflada por información general.
• registry/projects.yml — header reescrito como "EXAMPLE / REFERENCE FILE" explícito. Aclara que la fuente de verdad es projects.local.yml (gitignored) y por qué hay dos archivos.
• domain/parallel-sessions.md — 81 → 38 líneas. Las secciones de CLI flags no relacionadas con paralelismo migraron al nuevo domain/cli-flags.md (53 líneas), con globs distintos (CLAUDE.md, agents/*, skills/**/SKILL.md, scripts/**/*.sh, .github/workflows/*.yml) — cargan según contexto distinto.

Domain rules > 50 líneas tras este pase (8 restantes, no críticas)

Archivo	Líneas	Sobre
rule-effectiveness.md	68	+18
hook-architecture.md	63	+13
auto-mode.md	62	+12
permission-managed-settings.md	60	+10
permission-model.md	59	+9
agent-orchestration.md	59	+9
context-control-patterns.md	54	+4
cli-flags.md	53	+3
plugin-distribution.md	52	+2
context-window-optimization.md	52	+2

Diminishing returns: trim de wording en próxima iteración sin fragmentación adicional.

v3.6.1 — Audit fixes — search-first off, permission-model split

Auditoría crítica + pulidos de calidad

Sesión de auditoría a conciencia detectó tres degradaciones reales y se aplicaron las correcciones baratas + alto retorno.

Cambios

• behaviors/index.yaml — search-first.enabled: false. Evidencia: counter=7, escaló a soft_block y el usuario lo desactivó manualmente en sesión. Diseño actual (flag se consume tras cada Write/Edit) genera falsos positivos en sesiones tras compactación o con contexto ya cargado vía Read inicial. Revisitar cuando exista modo "sticky-flag".
• Hooks generados de search-first removidos — eliminados de .claude/hooks/generated/ y de settings.json. PreToolUse: 8 → 6 hooks. Latencia neta menor; los hooks restantes (block-destructive, no-destructive-git, respect-todo-state×2, verify-before-done×2) siguen activos.
• domain/permission-model.md dividido — 112 líneas → 59 (core: modes, cascade, prefix detection, core rules, auto-approvals tightening, glob/grep platform note). El nuevo domain/permission-managed-settings.md (60 líneas) absorbe enterprise managed settings, MCP server config y dynamic permissions from hooks. Globs distintos (managed-settings.json, .mcp.json) → cargan sólo cuando aplican.
• Limpieza de filesystem — borrados 9 backups huérfanos settings.json.bak.20260428-* (dotforge + 8 proyectos), worktree zombi reverent-banzai ya no aparecía.

Auditoría — qué SÍ aporta valor (con evidencia)

• block-destructive.sh: activo en 12 proyectos, nunca desactivado, intercepta patrones nuevos (find -delete, xargs rm)
• Fix session-report.sh (v3.3.1): corrigió bug silencioso de 5 meses en métricas
• tool-latency.sh: datos llegando — Bash p50=53ms, Edit p50=11ms (hooks no son cuello de botella)
• Domain rules con globs específicos: cargan sólo cuando aplican
• scripts/audit_all.py + sync_all.py + wire_hooks_all.py: real automatización 12× → 1×

Auditoría — pendientes (no críticos)

• 8 domain rules siguen >50 líneas (propio límite). Acumular en próximo refactor sin urgencia.
• practices/metrics.yml: 35/54 = not-applicable. Métrica engañosa — "validated" debería significar "previno error", no "5 ciclos sin pasar nada". Renombrar campo a informational y excluir de validation rate.
• Registry shadow: projects.yml (committed, ejemplo) vs projects.local.yml (gitignored, real) — aclarar en docs.
• inbox/*-session-changes.md automáticos sin detalle son ruido. Filtrar en post-session hook si sólo son conteos.