Adom Hydrogen (platform base)

@@ -0,0 +1,116 @@+---+name: hydrogen-claude-permission-modes+description: >+  Why ah makes Claude Code's "Bypass permissions" mode VISIBLE in the editor's Modes menu, and+  when an Adom user should reach for it. ah ships+  claudeCode.allowDangerouslySkipPermissions: true so the row APPEARS, while leaving+  claudeCode.initialPermissionMode: "auto" so Auto is still the default, two settings doing+  two different jobs. Read this before telling a user to "switch off permissions", before+  editing ~/.claude/settings.json to change a permission default, or when a session reports+  that a safety check has blocked an action and will keep blocking it. Covers the auto-mode+  classifier's worst failure shape (it can disable Bash for the REST of a session while+  read-only tools keep working, so the thread looks alive but cannot act), the+  compound-command tell, what Adom shipped in response (natural-language agent_permissions on+  the whole wiki catalogue), and the honest case for NOT using bypass. Trigger words: bypass+  permissions, dangerously skip permissions, allowDangerouslySkipPermissions, permission mode,+  modes menu, auto mode, classifier blocked, blocked by classifier, safety check blocked,+  claude won't run, bricked session, defaultMode, bypassPermissions, turn off permissions.+---++# Claude Code permission modes in ah++## What ah does, and where++Two settings, two different jobs, and they are frequently confused:++| goal | file | setting |+|---|---|---|+| make the **Bypass permissions** row APPEAR in the editor's Modes menu | `~/.local/share/code-server/User/settings.json` | `"claudeCode.allowDangerouslySkipPermissions": true` |+| choose which mode a session STARTS in | same file | `"claudeCode.initialPermissionMode": "auto"` |+| change the CLI's own default permission mode | `~/.claude/settings.json` | `"permissions": { "defaultMode": "bypassPermissions" }` |++**ah sets the first two and deliberately does NOT set the third.** The row is visible, Auto is+still the default, and the user chooses. Claude Code also shows its own one-time consent+dialog before bypass takes effect, so nothing here silently drops a user's guardrails.++`hydrogen-bootstrap`'s `install.sh` writes those two lines, and the update hook re-runs it, so+the fleet gets the row without anyone editing a file by hand.++**⛔ Do not "fix" a user's permission problem by writing `defaultMode: "bypassPermissions"`+into `~/.claude/settings.json`.** That is a different mechanism with a much broader effect: it+makes bypass the default for every session on that machine, rather than making a choice+available. If a user wants that, it is their decision to make deliberately, not a workaround+to apply on their behalf.++## Why Adom users need the row at all++Adom users are power users driving long, tool-heavy sessions: bridges, hardware, browsers,+containers, other people's desktops. Auto mode's classifier is right most of the time and its+failures are cheap most of the time. **The failure that is not cheap is this one:**++> Auto mode could not evaluate this action and is blocking it for safety, a safety check+> separate from auto mode blocked this request because of **earlier conversation content**. It+> isn't about the action itself. **Retrying it will hit the same refusal**, so don't rewrite or+> rework the action to get around this, **it will keep firing for the rest of this+> conversation.**++Read that carefully, because the shape matters:++- It is **not a judgement about the action.** It reacts to earlier conversation content.+- It is **sticky for the whole session.** A retry, a rephrase, a different approach: same result.+- **Read-only tools keep working.** So the thread still answers, still reads files, still+  reasons, and cannot run a command. It looks alive while being unable to act, which is the+  most confusing possible state to hand a user.++Real cases from the Adom team, on ordinary work:++- A Fusion bridge thread was blocked from **dismissing a dialog box in Fusion**. Not a+  destructive command, a modal.+- A session had **Bash disabled for the remainder of its life** mid-task and could only report+  status from read-only tools.++The reasonable user response to a session that cannot act is to abandon it, and abandoning a+long thread costs its whole accumulated context. **That is the cost the visible menu row+exists to avoid.**++## The compound-command tell++Observed repeatedly, and worth trying before anything drastic: **the classifier blocks some+COMPOUND commands whose individual parts it allows.** A single `bash -c` doing an edit and+then a publish gets refused; the same two steps as two separate calls both go through.++So before concluding a capability is unavailable:++1. **Split the command into its separate steps** and run them individually.+2. If a step is genuinely the blocked one, you now know which, and you can say so precisely.++This is not a way around the intent of a refusal, a genuinely blocked action stays blocked.+It is a way to stop a batching artifact from reading as a permission decision.++## What Adom shipped in response++Rather than telling every user to switch off permissions, the toolchain declares its own+posture: **the wiki registry serves natural-language `agent_permissions` for the whole+catalogue**, and `adom-wiki` composes a managed `autoMode` region in `~/.claude/settings.json`+from the packages a user actually has installed. A package's `bin` also registers a+`Bash(<bin>:*)` allowlist rule on install and removes it on uninstall.++The effect is that Adom's own binaries stop being ambiguous to the classifier, which removes+most of the routine friction. **It does not remove the sticky-block failure above**, because+that one is about conversation content rather than about the command.++## When NOT to use bypass++Bypass means Claude will not ask before running potentially dangerous commands. That is a real+trade, and it is the right trade in some threads and the wrong one in others.++**Reasonable:** a long tool-driven session you are supervising, where the work is repetitive,+the blast radius is a container you can rebuild, and permission prompts are interrupting a loop+you are watching.++**Not reasonable:** a thread you are not watching, one with reach into a machine you cannot+easily restore, or one doing something you have not done before and cannot predict. Auto mode+exists because most sessions are that second kind.++**And prefer the narrower fix when one exists.** A recurring prompt for one tool is better+solved by an allowlist rule for that tool than by turning the guardrail off for everything.