chore: capture 7 practices from /forge watch (Claude Code v2.1.120-128)

Inbox additions for next /forge update cycle:

HIGH:
- posttooluse-updated-output-all-tools (v2.1.121) — PostToolUse hooks can now
  rewrite output for ALL tools, not just MCP. Significant capability shift.

MEDIUM:
- setup-hook-event — domain/hook-architecture.md says 31 events; should be 32
  (Setup fires for --init-only/--maintenance with init/maintenance matchers)
- mcp-alwaysload-option (v2.1.121) — alwaysLoad: true per MCP server bypasses
  tool-search deferral
- claude-ultrareview-cli (v2.1.120) — non-interactive code review CLI for CI
- claude-effort-skill-placeholder (v2.1.120) — ${CLAUDE_EFFORT} in skill content
  enables effort-aware skill design
- settings-fields-missing — availableModels, effortLevel, defaultShell, viewMode,
  pluginTrustMessage, enableWeakerNestedSandbox; plus managed-only enterprise
  fields (allowManagedPermissionRulesOnly, allowManagedDomainsOnly,
  allowManagedReadPathsOnly, strictKnownMarketplaces, blockedMarketplaces)

LOW (batched):
- misc-v2-1-120-128 — --plugin-dir .zip, claude plugin prune, AI_AGENT subprocess
  env, ANTHROPIC_BEDROCK_SERVICE_TIER, --channels API-key auth needs
  channelsEnabled, workspace reserved MCP name

Inbox: 7 pending. Run /forge update next cycle.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: luiseiman

practices/inbox/2026-05-05-claude-effort-skill-placeholder.md

@@ -0,0 +1,34 @@
+---
+id: claude-effort-skill-placeholder
+source: watch:code.claude.com/docs/en/changelog
+status: inbox
+captured: 2026-05-05
+tags: [skills, effort, design-pattern, medium-priority, v2.1.120]
+tested_in: []
+incorporated_in: []
+---
+
+# `${CLAUDE_EFFORT}` skill placeholder (v2.1.120) — effort-aware skill content
+
+## Observation
+
+v2.1.120 added support for `${CLAUDE_EFFORT}` in skill content (markdown body, not just frontmatter). Resolves at runtime to the active effort tier (`low | medium | high | xhigh | max`).
+
+## Why it matters for dotforge
+
+Several dotforge skills change behavior based on depth needed:
+- `skills/audit-project` could parameterize check depth (low: file presence; high: content + cross-checks)
+- `skills/benchmark` could pin its A/B comparisons to current effort
+- `skills/session-insights` could adjust how deep it walks history
+
+Currently these skills don't reference effort at all. Adding `${CLAUDE_EFFORT}` lets the user say "give me a quick audit" (effort low) vs "thorough one" (effort high) without forking the skill.
+
+## Required update
+
+1. `domain/rule-effectiveness.md` — frontmatter table already lists `effort`; add to the body the `${CLAUDE_EFFORT}` runtime placeholder concept (skill content, not just frontmatter).
+2. Pilot adoption in one skill (likely `audit-project` or `session-insights`) before retrofitting all.
+
+## Affected files
+
+- `.claude/rules/domain/rule-effectiveness.md`
+- (pilot) `skills/audit-project/SKILL.md` or `skills/session-insights/SKILL.md`

practices/inbox/2026-05-05-claude-ultrareview-cli.md

@@ -0,0 +1,37 @@
+---
+id: claude-ultrareview-cli
+source: watch:code.claude.com/docs/en/cli-reference
+status: inbox
+captured: 2026-05-05
+tags: [cli, ci, code-review, medium-priority, v2.1.120]
+tested_in: []
+incorporated_in: []
+---
+
+# `claude ultrareview [target]` non-interactive CLI subcommand (v2.1.120)
+
+## Observation
+
+v2.1.120 added a non-interactive variant of `/ultrareview`:
+
+```bash
+claude ultrareview 1234              # PR number → review with multi-agent analysis
+claude ultrareview 1234 --json       # raw payload
+claude ultrareview --timeout 60 ...  # override 30-min default
+# exit 0 = clean, 1 = findings/error
+```
+
+## Why it matters for dotforge
+
+CI integration becomes trivial — pre-merge review gates without needing an interactive session.
+
+Currently `docs/usage-guide.md` doesn't cover automated review at all. Dotforge ships a `code-reviewer` agent for interactive use; pairing with `claude ultrareview` in CI is the natural extension.
+
+## Required update
+
+1. `docs/usage-guide.md` — new subsection in CI/automation context describing the pattern: invoke `claude ultrareview <PR>` in GitHub Actions, capture `--json` output, post as PR comment.
+2. Optional: example workflow file in `docs/examples/` (would need a new dir).
+
+## Affected files
+
+- `docs/usage-guide.md`

practices/inbox/2026-05-05-mcp-alwaysload-option.md

@@ -0,0 +1,37 @@
+---
+id: mcp-alwaysload-option
+source: watch:code.claude.com/docs/en/changelog
+status: inbox
+captured: 2026-05-05
+tags: [mcp, permissions, performance, medium-priority, v2.1.121]
+tested_in: []
+incorporated_in: []
+---
+
+# `alwaysLoad: true` MCP server option (v2.1.121) — bypass tool-search deferral
+
+## Observation
+
+v2.1.121 added `alwaysLoad: true` to MCP server config. When set, all tools from that server skip the tool-search deferral mechanism and are always available in the prompt.
+
+Tradeoff: faster access, more context spent. The default deferral was added precisely because MCP servers can ship dozens of tools that bloat the prompt.
+
+## Why it matters for dotforge
+
+Projects that use specific MCP servers heavily (Atlassian for jira-nbch, Supabase for InviSight-iOS) can opt-in to skip the search overhead when those tools are needed every session.
+
+`domain/permission-model.md` covers `enableAllProjectMcpServers`, `allowedMcpServers`, etc. but does NOT document `alwaysLoad`. Worth a sentence.
+
+## Required update
+
+`domain/permission-model.md` MCP section — add:
+```
+- `alwaysLoad: true` (per-server, v2.1.121+): all tools from that server skip
+  tool-search deferral and stay available in the prompt. Use only when MCP
+  tools are needed in every turn — costs context for fewer tool-search
+  invocations.
+```
+
+## Affected files
+
+- `.claude/rules/domain/permission-model.md`

practices/inbox/2026-05-05-misc-v2-1-120-128.md

@@ -0,0 +1,39 @@
+---
+id: misc-v2-1-120-128
+source: watch:code.claude.com/docs/en/changelog
+status: inbox
+captured: 2026-05-05
+tags: [misc, low-priority, v2.1.120, v2.1.122, v2.1.128]
+tested_in: []
+incorporated_in: []
+---
+
+# Misc v2.1.120-128 deltas (batched, low priority)
+
+Single capture for low-impact items. Each gets one line in `docs/best-practices.md` or a relevant existing doc — no new domain rule warranted.
+
+## Items
+
+1. **`--plugin-dir` accepts `.zip` archives** (v2.1.128) — alternative dotforge plugin distribution path. Could ship a release `.zip` from CI alongside git clone instructions.
+
+2. **`claude plugin prune`** + **`plugin uninstall --prune`** (v2.1.121) — orphan dependency cleanup. Mention in dotforge install/uninstall docs.
+
+3. **`AI_AGENT` env var auto-set for subprocesses** (v2.1.120) — useful for observability when dotforge hooks invoke `gh`, `kubectl`, etc. No code change; doc note that subprocess attribution works out of the box.
+
+4. **`ANTHROPIC_BEDROCK_SERVICE_TIER` env var** (v2.1.122) — Bedrock tier selection (default | flex | priority). Only relevant for Bedrock users; no current dotforge user.
+
+5. **`--channels` works with API-key auth** (v2.1.128) — requires `channelsEnabled: true` in settings. Update `integrations/channels/README.md` to note this.
+
+6. **`workspace` reserved as MCP server name** (v2.1.128) — verified no dotforge stack uses this name. Doc note for users.
+
+7. **`claude install [version]`** (existing but worth doc note) — pin specific CC versions for reproducibility.
+
+## Affected files
+
+- `docs/best-practices.md` (collect minor tips)
+- `integrations/channels/README.md` (channelsEnabled note)
+- `docs/usage-guide.md` (install section — `.zip` distribution, `plugin prune`)
+
+## Decision
+
+Pendiente — incorporar como un solo update menor a docs cuando haya tema relacionado, no promover a práctica activa individualmente.

practices/inbox/2026-05-05-posttooluse-updated-output-all-tools.md

@@ -0,0 +1,38 @@
+---
+id: posttooluse-updated-output-all-tools
+source: watch:code.claude.com/docs/en/changelog
+status: inbox
+captured: 2026-05-05
+tags: [hooks, post-tool-use, capability, high-priority, v2.1.121]
+tested_in: []
+incorporated_in: []
+---
+
+# `PostToolUse.hookSpecificOutput.updatedToolOutput` now works for ALL tools (v2.1.121)
+
+## Observation
+
+v2.1.121 changelog: `PostToolUse` hooks can replace tool output for any tool — Bash, Edit, Write, Read, etc. — via `hookSpecificOutput.updatedToolOutput`. Previously this field only worked for MCP tools (named `updatedMCPToolOutput`).
+
+## Why it matters for dotforge
+
+`domain/hook-events.md` documents `updatedMCPToolOutput` for MCP tools only. The expanded capability changes hook design tradeoffs:
+
+- Lint/format hooks could rewrite Bash output (e.g. strip trailing whitespace from `cat` results) before the model reads it
+- `block-destructive.sh` could be paired with a PostToolUse handler that redacts sensitive output from `git diff` or `env` calls
+- Test runners could compress verbose output to a one-line summary before consumption
+
+But also new risks:
+- Output rewriting can hide errors the model needs to see (failing tests pass silently if output is overwritten)
+- Audit trail confusion: what the model sees ≠ what the tool actually returned
+
+## Required update
+
+1. `domain/hook-events.md` — replace `updatedMCPToolOutput` notes with `updatedToolOutput` (general, since v2.1.121); preserve historical note that pre-v2.1.121 it was MCP-only.
+2. `domain/hook-architecture.md` — section on PostToolUse should call out the design tradeoff.
+3. Consider whether dotforge ships any hook that should use this (lint-on-save? session-report? probably not — both are fine emitting alongside, not replacing).
+
+## Affected files
+
+- `.claude/rules/domain/hook-events.md`
+- `.claude/rules/domain/hook-architecture.md`

practices/inbox/2026-05-05-settings-fields-missing.md

@@ -0,0 +1,45 @@
+---
+id: settings-fields-missing
+source: watch:code.claude.com/docs/en/settings
+status: inbox
+captured: 2026-05-05
+tags: [settings, drift, enterprise, medium-priority]
+tested_in: []
+incorporated_in: []
+---
+
+# settings.json fields missing from domain rules
+
+## Observation
+
+A walk through the official settings.json schema surfaces fields not documented anywhere in `.claude/rules/domain/`:
+
+**Generally relevant**:
+- `availableModels` — restrict selectable models (subset of all)
+- `effortLevel` — persist effort across sessions (vs session-only `--effort` flag)
+- `defaultShell` — bash | powershell at the settings level (cross-platform)
+- `viewMode` — default | verbose | focus (transcript view)
+- `pluginTrustMessage` — custom warning shown on plugin trust prompts
+- `enableWeakerNestedSandbox` — Docker-friendly relaxed sandbox
+
+**Managed-only (enterprise)**:
+- `allowManagedPermissionRulesOnly` — locks projects to managed permission rules
+- `network.allowManagedDomainsOnly` — managed-domain-only outbound
+- `filesystem.allowManagedReadPathsOnly` — managed-read-only filesystem
+- `strictKnownMarketplaces` — managed marketplace allowlist (exact match, supports github/git/url/npm/file/directory/hostPattern)
+- `blockedMarketplaces` — managed denylist
+
+## Why it matters
+
+- `availableModels` / `effortLevel`: relevant for any team standardizing on a model/effort baseline (e.g., "this project uses Sonnet at high, no Opus").
+- Managed-only fields: critical for any enterprise that wants to deploy dotforge across an org with controlled marketplace and permission policy. Currently `domain/permission-model.md` covers `allowedMcpServers`/`deniedMcpServers` but stops there.
+
+## Required update
+
+1. `domain/rule-effectiveness.md` or new `domain/settings-fields.md` — document the generally-relevant fields with one-line each.
+2. `domain/permission-model.md` Enterprise managed settings section — add the five managed-only fields with use case.
+
+## Affected files
+
+- `.claude/rules/domain/rule-effectiveness.md` (or new file)
+- `.claude/rules/domain/permission-model.md`

practices/inbox/2026-05-05-setup-hook-event.md

@@ -0,0 +1,34 @@
+---
+id: setup-hook-event
+source: watch:code.claude.com/docs/en/hooks
+status: inbox
+captured: 2026-05-05
+tags: [hooks, lifecycle, drift, medium-priority]
+tested_in: []
+incorporated_in: []
+---
+
+# `Setup` hook event missing from domain rules — should be 32 events not 31
+
+## Observation
+
+Per current hooks doc, the lifecycle event roster includes `Setup` — fires for `--init-only` and `--maintenance` runs with matchers `init` and `maintenance` respectively.
+
+`domain/hook-architecture.md` opens with: "Events (31 total, verified v2.1.114 — code.claude.com/docs/en/hooks)" and groups session-level events as `SessionStart, SessionEnd, InstructionsLoaded`. **`Setup` is not listed.**
+
+## Why it matters
+
+- CI/automation flows that use `claude --init-only` or `--maintenance` rely on `Setup` hooks to provision env vars, validate prerequisites, or rotate creds before the session starts.
+- Contributors writing init-time hooks may put them on `SessionStart` and miss the `Setup` lifecycle entirely (or the inverse — Setup hooks they expect to run on every session do not).
+
+## Required update
+
+1. `domain/hook-architecture.md` — add `Setup` to session-level events; bump verified tag and total count to 32.
+2. `domain/hook-events.md` — document `Setup` payload + matchers `init|maintenance`; note non-blockable.
+3. CLI flag refs in `domain/parallel-sessions.md` — cross-reference `--init-only` / `--maintenance` to the `Setup` hook.
+
+## Affected files
+
+- `.claude/rules/domain/hook-architecture.md`
+- `.claude/rules/domain/hook-events.md`
+- `.claude/rules/domain/parallel-sessions.md`