chore: add shared Claude Code permissions for parallel worktree agents

Background agents in git worktrees need pre-approved tool permissions
to avoid blocking on interactive prompts. Adds .claude/settings.json
(committed) with allow rules for standard operations, documents the
setup in AGENTS.md, and gitignores local-only Claude Code files.

Author: marc0olo

.claude/settings.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(npm run *)",
+      "Bash(ls *)",
+      "Bash(bd *)",
+      "Bash(gh *)",
+      "Bash(npx skills *)",
+      "Edit",
+      "Write",
+      "Read",
+      "Grep",
+      "Glob",
+      "WebSearch",
+      "WebFetch"
+    ],
+    "deny": [
+      "Bash(git push --force *)",
+      "Bash(rm -rf *)"
+    ]
+  }
+}

.docs-plan/decisions.md

@@ -130,3 +130,10 @@ Record decisions that constrain future work — things an agent needs to know th
 **Decision:** Never link to `internetcomputer.org/docs/` or `docs.internetcomputer.org` — these are the old docs being replaced by this project. Instead: (1) link to a page in this docs site using relative paths, even if it's still a stub, or (2) link to Learn Hub (`learn.internetcomputer.org`) for protocol internals, or (3) explain the concept inline if no suitable page exists yet.
 **Rationale:** Old docs URLs will break once the new site replaces the old one. Linking to stubs is fine — they'll have content by the time the site launches. If a topic has no planned page, flag it as a page proposal.
 **Alternatives considered:** Keep old links with a TODO to update later (easy to forget, broken links at launch)
+
+## 2026-03-13: Shared Claude Code permissions for parallel worktree agents
+
+**Context:** Background agents launched in git worktrees need Bash, Edit, Read, etc. but block waiting for interactive permission approval that never comes. Per-user settings at `~/.claude/projects/<path>/settings.json` don't apply to worktree agents because the worktree has a different filesystem path.
+**Decision:** Commit `.claude/settings.json` to the repo with pre-approved tools (git, npm, bd, gh, Edit, Write, Read, Grep, Glob). Deny destructive operations (force push, rm -rf). Gitignore `.claude/settings.local.json` and `.claude/worktrees/` (local-only).
+**Rationale:** Shared settings travel with the repo and apply to all agents regardless of working directory. Every developer gets the same permission baseline without manual configuration.
+**Alternatives considered:** Per-user project settings (doesn't apply to worktrees), fully permissive mode (too broad), manual approval (blocks background agents)

.gitignore

@@ -28,6 +28,10 @@ public/docs-manifest.json
 # macOS-specific files
 .DS_Store
 
+# Claude Code (local-only files; .claude/settings.json is committed)
+.claude/settings.local.json
+.claude/worktrees/
+
 # Dolt database files (added by bd init)
 .dolt/
 *.db

AGENTS.md

@@ -38,6 +38,21 @@ All tasks (content pages, infrastructure, tooling) are coordinated through [Bead
 
 If `bd` or `dolt` aren't installed, the script tells you how. Without them you can still write docs — check `.docs-plan/migration-plan.md` for tasks manually.
 
+### Parallel agents (worktrees)
+
+For batch operations like addressing PR feedback across multiple PRs, Claude Code can launch background agents in isolated git worktrees. Each agent works on a separate branch without conflicts.
+
+**Prerequisites:**
+- `.claude/settings.json` (committed to git) pre-approves tools that agents need (Bash, Edit, Read, etc.). Without this, background agents block waiting for interactive permission approval that never comes.
+- `.claude/settings.local.json` and `.claude/worktrees/` are gitignored (local-only).
+
+**How it works:**
+1. The parent agent claims tasks in Beads, then launches one background agent per PR using `isolation: "worktree"`
+2. Each agent gets its own git worktree (isolated copy of the repo), checks out its branch, makes edits, and commits
+3. The parent agent collects results, pushes branches, and posts feedback-addressed comments
+
+**If agents fail with permission errors:** Check that `.claude/settings.json` exists and includes all required tools. The shared settings file is the authoritative source — per-user `~/.claude/projects/` settings don't apply to worktree agents (different path).
+
 ### Session start
 
 ```bash
@@ -298,6 +313,7 @@ Add enough context in the notes so the next agent (or human) understands the blo
 - `docs/guides/tools/migrating-from-dfx.md` — Synced from `dfinity/icp-cli` (do not edit directly)
 - `.docs-plan/` — Analysis artifacts, decisions, and progress tracking (see `.docs-plan/README.md`)
 - `.sources/` — **Pinned submodules of upstream source repos** (see "Source material repos" below)
+- `.claude/settings.json` — Shared Claude Code permissions (committed to git). Ensures worktree/background agents can run without interactive approval.
 - `icp.yaml` — icp-cli project config (asset canister recipe)
 - `.icp/data/` — Canister ID mappings (committed to git). `.icp/cache/` is gitignored.