codeforge-dev 1.11.0 → 1.12.0

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/README.md

@@ -0,0 +1,86 @@
+# protected-files-guard
+
+Claude Code plugin that blocks modifications to sensitive files — environment secrets, lock files, git internals, certificates, and credentials. Covers both direct file edits (Edit/Write tools) and indirect writes through Bash commands.
+
+## What It Does
+
+Intercepts file operations and checks target paths against a set of protected patterns. If a match is found, the operation is blocked with an error message explaining why and suggesting the correct approach (e.g., "use npm install instead" for package-lock.json).
+
+### Protected File Categories
+
+| Category | Patterns | Reason |
+|----------|----------|--------|
+| Environment secrets | `.env`, `.env.*` | Contains secrets |
+| Git internals | `.git/` | Managed by git |
+| Lock files | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Gemfile.lock`, `poetry.lock`, `Cargo.lock`, `composer.lock`, `uv.lock` | Must be modified via package manager |
+| Certificates & keys | `.pem`, `.key`, `.crt`, `.p12`, `.pfx` | Sensitive cryptographic material |
+| Credential files | `credentials.json`, `secrets.yaml`, `secrets.yml`, `secrets.json`, `.secrets` | Contains secrets |
+| Auth directories | `.ssh/`, `.aws/` | Contains authentication data |
+| Auth config files | `.netrc`, `.npmrc`, `.pypirc` | Contains authentication credentials |
+| SSH private keys | `id_rsa`, `id_ed25519`, `id_ecdsa` | SSH private key files |
+
+## How It Works
+
+### Two-Hook Architecture
+
+The plugin registers two PreToolUse hooks to cover different attack vectors:
+
+```
+Claude calls Edit or Write tool
+  │
+  └─→ guard-protected.py checks file_path against protected patterns
+       │
+       ├─→ Match → exit 2 (block)
+       └─→ No match → exit 0 (allow)
+
+Claude calls Bash tool
+  │
+  └─→ guard-protected-bash.py extracts write targets from the command
+       │
+       ├─→ Detects: > redirect, >> append, tee, cp, mv, sed -i, cat heredoc
+       ├─→ Checks each target against protected patterns
+       ├─→ Any match → exit 2 (block)
+       └─→ No match → exit 0 (allow)
+```
+
+### Bash Write Detection
+
+The Bash guard parses commands for write-indicating patterns and extracts the target file path:
+
+| Pattern | Example |
+|---------|---------|
+| Redirect (`>`, `>>`) | `echo "key=val" > .env` |
+| `tee` / `tee -a` | `cat data \| tee .env` |
+| `cp` / `mv` | `cp template .env` |
+| `sed -i` | `sed -i 's/old/new/' .env` |
+| `cat` heredoc | `cat <<EOF > .env` |
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| JSON parse failure | Fails closed (exit 2) — blocks the operation |
+| Other exceptions | Fails open (exit 0) — logs error, allows the operation |
+
+### Timeout
+
+Both hooks have a 5-second timeout.
+
+## Plugin Structure
+
+```
+protected-files-guard/
+├── .claude-plugin/
+│   └── plugin.json              # Plugin metadata
+├── hooks/
+│   └── hooks.json               # PreToolUse hook registrations (Edit|Write + Bash)
+├── scripts/
+│   ├── guard-protected.py       # Edit/Write file path checker
+│   └── guard-protected-bash.py  # Bash command write target checker
+└── README.md                    # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/hooks/hooks.json

@@ -1,17 +1,27 @@
 {
-  "description": "Block modifications to protected files",
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-protected.py",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
+	"description": "Block modifications to protected files",
+	"hooks": {
+		"PreToolUse": [
+			{
+				"matcher": "Edit|Write",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-protected.py",
+						"timeout": 5
+					}
+				]
+			},
+			{
+				"matcher": "Bash",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-protected-bash.py",
+						"timeout": 5
+					}
+				]
+			}
+		]
+	}
 }

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected-bash.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+Block bash commands that write to protected files.
+
+Reads tool input from stdin, checks the command field for write operations
+targeting protected file patterns.
+Exit code 2 blocks the command with error message.
+Exit code 0 allows the command to proceed.
+"""
+
+import json
+import re
+import sys
+
+# Same patterns as guard-protected.py
+PROTECTED_PATTERNS = [
+    (r"(^|/)\.env$", "Blocked: .env contains secrets - edit manually if needed"),
+    (
+        r"(^|/)\.env\.[^/]+$",
+        "Blocked: .env.* files contain secrets - edit manually if needed",
+    ),
+    (r"(^|/)\.git(/|$)", "Blocked: .git is managed by git"),
+    (
+        r"(^|/)package-lock\.json$",
+        "Blocked: package-lock.json - use npm install instead",
+    ),
+    (r"(^|/)yarn\.lock$", "Blocked: yarn.lock - use yarn install instead"),
+    (r"(^|/)pnpm-lock\.yaml$", "Blocked: pnpm-lock.yaml - use pnpm install instead"),
+    (r"(^|/)Gemfile\.lock$", "Blocked: Gemfile.lock - use bundle install instead"),
+    (r"(^|/)poetry\.lock$", "Blocked: poetry.lock - use poetry install instead"),
+    (r"(^|/)Cargo\.lock$", "Blocked: Cargo.lock - use cargo build instead"),
+    (r"(^|/)composer\.lock$", "Blocked: composer.lock - use composer install instead"),
+    (r"(^|/)uv\.lock$", "Blocked: uv.lock - use uv sync instead"),
+    (r"\.pem$", "Blocked: .pem files contain sensitive cryptographic material"),
+    (r"\.key$", "Blocked: .key files contain sensitive cryptographic material"),
+    (r"\.crt$", "Blocked: .crt certificate files should not be edited directly"),
+    (r"\.p12$", "Blocked: .p12 files contain sensitive cryptographic material"),
+    (r"\.pfx$", "Blocked: .pfx files contain sensitive cryptographic material"),
+    (r"(^|/)credentials\.json$", "Blocked: credentials.json contains secrets"),
+    (r"(^|/)secrets\.yaml$", "Blocked: secrets.yaml contains secrets"),
+    (r"(^|/)secrets\.yml$", "Blocked: secrets.yml contains secrets"),
+    (r"(^|/)secrets\.json$", "Blocked: secrets.json contains secrets"),
+    (r"(^|/)\.secrets$", "Blocked: .secrets file contains secrets"),
+    (r"(^|/)\.ssh/", "Blocked: .ssh/ contains sensitive authentication data"),
+    (r"(^|/)\.aws/", "Blocked: .aws/ contains AWS credentials"),
+    (r"(^|/)\.netrc$", "Blocked: .netrc contains authentication credentials"),
+    (
+        r"(^|/)\.npmrc$",
+        "Blocked: .npmrc may contain auth tokens - edit manually if needed",
+    ),
+    (r"(^|/)\.pypirc$", "Blocked: .pypirc contains PyPI credentials"),
+    (r"(^|/|-)id_rsa($|\.)", "Blocked: SSH private key file"),
+    (r"(^|/)id_ed25519", "Blocked: SSH private key file"),
+    (r"(^|/)id_ecdsa", "Blocked: SSH private key file"),
+]
+
+# Patterns that indicate a bash command is writing to a file
+# Each captures the target file path for checking against PROTECTED_PATTERNS
+WRITE_PATTERNS = [
+    # Redirect: > file, >> file
+    r"(?:>|>>)\s*([^\s;&|]+)",
+    # tee: tee file, tee -a file
+    r"\btee\s+(?:-a\s+)?([^\s;&|]+)",
+    # cp/mv: cp src dest, mv src dest
+    r"\b(?:cp|mv)\s+(?:-[^\s]+\s+)*[^\s]+\s+([^\s;&|]+)",
+    # sed -i: sed -i '' file
+    r'\bsed\s+-i[^\s]*\s+(?:\'[^\']*\'\s+|"[^"]*"\s+|[^\s]+\s+)*([^\s;&|]+)',
+    # cat > file (heredoc style)
+    r"\bcat\s+(?:<<[^\s]*\s+)?>\s*([^\s;&|]+)",
+]
+
+
+def extract_write_targets(command: str) -> list[str]:
+    """Extract file paths that the command writes to."""
+    targets = []
+    for pattern in WRITE_PATTERNS:
+        for match in re.finditer(pattern, command):
+            target = match.group(1).strip("'\"")
+            if target:
+                targets.append(target)
+    return targets
+
+
+def check_path(file_path: str) -> tuple[bool, str]:
+    """Check if file path matches any protected pattern."""
+    normalized = file_path.replace("\\", "/")
+    for pattern, message in PROTECTED_PATTERNS:
+        if re.search(pattern, normalized, re.IGNORECASE):
+            return True, message
+    return False, ""
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        tool_input = input_data.get("tool_input", {})
+        command = tool_input.get("command", "")
+
+        if not command:
+            sys.exit(0)
+
+        targets = extract_write_targets(command)
+
+        for target in targets:
+            is_protected, message = check_path(target)
+            if is_protected:
+                print(json.dumps({"error": f"{message} (via bash command)"}))
+                sys.exit(2)
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Fail closed: can't parse means can't verify safety
+        sys.exit(2)
+    except Exception as e:
+        # Log error but don't block on hook failure
+        print(f"Hook error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected.py

@@ -20,7 +20,7 @@ PROTECTED_PATTERNS = [
         "Blocked: .env.* files contain secrets - edit manually if needed",
     ),
     # Git internals
-    (r"(^|/)\.git/", "Blocked: .git/ directory is managed by git"),
+    (r"(^|/)\.git(/|$)", "Blocked: .git is managed by git"),
     # Lock files (should be modified via package manager)
     (
         r"(^|/)package-lock\.json$",
@@ -97,8 +97,8 @@ def main():
         sys.exit(0)
 
     except json.JSONDecodeError:
-        # If we can't parse input, allow by default
-        sys.exit(0)
+        # Fail closed: can't parse means can't verify safety
+        sys.exit(2)
     except Exception as e:
         # Log error but don't block on hook failure
         print(f"Hook error: {e}", file=sys.stderr)

package/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/README.md

@@ -0,0 +1,96 @@
+# ticket-workflow
+
+Claude Code plugin that provides an EARS-based ticket workflow with GitHub issues as the single source of truth. Command-driven — no hooks or scripts, just a custom system prompt and four slash commands.
+
+## What It Does
+
+Provides a structured workflow for creating, planning, reviewing, and shipping work through GitHub issues. All major decisions, plans, and progress are posted as issue comments to maintain an audit trail.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ticket:new` | Transform requirements into a structured GitHub issue with EARS-formatted business requirements |
+| `/ticket:work` | Retrieve a ticket, create a technical implementation plan, and post it to the GitHub issue |
+| `/ticket:review-commit` | Conduct a thorough code review, verify requirements are met, and commit with a detailed message |
+| `/ticket:create-pr` | Create a pull request with aggressive security and architecture review |
+
+### EARS Requirement Format
+
+Every requirement uses one of these patterns:
+
+| Type | Template |
+|------|----------|
+| Ubiquitous | The `<system>` shall `<response>`. |
+| Event-Driven | WHEN `<trigger>`, the `<system>` shall `<response>`. |
+| State-Driven | WHILE `<state>`, the `<system>` shall `<response>`. |
+| Unwanted Behavior | IF `<condition>`, THEN the `<system>` shall `<response>`. |
+| Optional Feature | WHERE `<feature>`, the `<system>` shall `<response>`. |
+
+## How It Works
+
+### Workflow Lifecycle
+
+```
+/ticket:new [requirements]
+  │
+  └─→ Gather requirements → Create EARS-formatted GitHub issue
+       │
+       └─→ /ticket:work #123
+            │
+            └─→ Fetch issue → Create technical plan → Post plan as issue comment
+                 │
+                 │  ... implementation work ...
+                 │
+                 └─→ /ticket:review-commit
+                      │
+                      └─→ Review changes → Verify requirements → Commit
+                           │
+                           └─→ /ticket:create-pr
+                                │
+                                └─→ Create PR → Security/architecture review → Post findings
+```
+
+### Ticket Structure
+
+Each ticket created by `/ticket:new` includes:
+- **Overview**: Plain language description
+- **Requirements**: EARS-formatted business requirements
+- **Technical Questions**: Open questions for implementation
+- **Acceptance Criteria**: Verifiable conditions for completion
+
+### Audit Trail
+
+| Action | Destination |
+|--------|-------------|
+| Plans | Issue comment |
+| Decisions | Issue comment |
+| Requirement changes | Issue comment |
+| Commit summaries | Issue comment |
+| Review findings | PR + issue comment |
+| Created sub-issues | Linked to source ticket |
+
+### Custom System Prompt
+
+The plugin injects a system prompt that defines the assistant persona, coding standards (SOLID, DRY, KISS, YAGNI), testing standards, and the ticket workflow rules. This ensures consistent behavior across all four commands.
+
+## Plugin Structure
+
+```
+ticket-workflow/
+├── .claude-plugin/
+│   ├── plugin.json                  # Plugin metadata
+│   ├── system-prompt.md             # Custom system prompt (persona + workflow rules)
+│   └── commands/
+│       ├── ticket:new.md            # Create EARS-formatted issue
+│       ├── ticket:work.md           # Implementation planning
+│       ├── ticket:review-commit.md  # Review and commit
+│       └── ticket:create-pr.md      # PR creation with review
+└── README.md                        # This file
+```
+
+## Requirements
+
+- Claude Code with plugin command support
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated
+- A GitHub repository as the working context

package/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/README.md

@@ -0,0 +1,94 @@
+# workspace-scope-guard
+
+Claude Code plugin that enforces working directory scope for all file operations. Blocks writes outside the current project directory and warns on reads outside it. Prevents accidental cross-project modifications in multi-project workspaces.
+
+## What It Does
+
+Intercepts file operations (Read, Write, Edit, NotebookEdit, Glob, Grep) and checks whether the target path is within the current working directory:
+
+| Operation | Out-of-scope behavior |
+|-----------|-----------------------|
+| Write, Edit, NotebookEdit | **Blocked** (exit 2) with error message |
+| Read, Glob, Grep | **Warned** (exit 0) with advisory context |
+
+When the current working directory is `/workspaces` (the workspace root), all operations are unrestricted.
+
+### Allowed Prefixes
+
+These paths are always permitted regardless of working directory:
+
+| Path | Reason |
+|------|--------|
+| `/workspaces/.claude/` | Claude Code configuration |
+| `/workspaces/.tmp/` | Temporary files |
+| `/workspaces/.devcontainer/` | Container configuration |
+| `/tmp/` | System temp directory |
+| `/home/vscode/` | User home directory |
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude calls Read, Write, Edit, NotebookEdit, Glob, or Grep
+  │
+  └─→ PreToolUse hook fires
+       │
+       └─→ guard-workspace-scope.py
+            │
+            ├─→ cwd is /workspaces? → allow (unrestricted)
+            ├─→ No target path? → allow (tool defaults to cwd)
+            ├─→ Resolve path via os.path.realpath() (handles symlinks/worktrees)
+            ├─→ Path is within cwd? → allow
+            ├─→ Path matches allowed prefix? → allow
+            ├─→ Write tool + out of scope → exit 2 (block)
+            └─→ Read tool + out of scope → exit 0 (warn via additionalContext)
+```
+
+### Symlink and Worktree Handling
+
+Target paths are resolved with `os.path.realpath()` before scope checking. This correctly handles:
+- Symbolic links that point outside the working directory
+- Git worktree paths (`.git` file containing `gitdir:`)
+
+### Path Field Mapping
+
+The script extracts the target path from different tool input fields:
+
+| Tool | Input Field |
+|------|-------------|
+| Read | `file_path` |
+| Write | `file_path` |
+| Edit | `file_path` |
+| NotebookEdit | `notebook_path` |
+| Glob | `path` |
+| Grep | `path` |
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| JSON parse failure | Fails open (exit 0) |
+| Other exceptions | Fails open (exit 0) — logs error to stderr |
+
+### Timeout
+
+The hook has a 5-second timeout.
+
+## Plugin Structure
+
+```
+workspace-scope-guard/
+├── .claude-plugin/
+│   └── plugin.json                # Plugin metadata
+├── hooks/
+│   └── hooks.json                 # PreToolUse hook registration
+├── scripts/
+│   └── guard-workspace-scope.py   # Scope enforcement (PreToolUse)
+└── README.md                      # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support

package/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/scripts/guard-workspace-scope.py

@@ -21,7 +21,7 @@ ALLOWED_PREFIXES = [
     "/workspaces/.tmp/",
     "/workspaces/.devcontainer/",
     "/tmp/",
-    "/home/",
+    "/home/vscode/",
 ]
 
 WRITE_TOOLS = {"Write", "Edit", "NotebookEdit"}

package/.devcontainer/scripts/check-setup.sh

@@ -34,7 +34,7 @@ warn_check() {
 echo ""
 echo "Core:"
 check "Claude Code installed" "command -v claude"
-warn_check "Claude native binary" "[ -x /usr/local/bin/claude ]"
+warn_check "Claude native binary" "[ -x ~/.local/bin/claude ] || [ -x /usr/local/bin/claude ]"
 check "cc alias configured" "grep -q 'alias cc=' ~/.bashrc 2>/dev/null || grep -q 'alias cc=' ~/.zshrc 2>/dev/null"
 check "Config directory exists" "[ -d '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}' ]"
 check "Settings file exists" "[ -f '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}/settings.json' ]"

package/.devcontainer/scripts/setup-projects.sh

@@ -29,7 +29,7 @@ is_excluded() {
 
 has_project_markers() {
 	local dir="$1"
-	[ -d "$dir/.git" ] || [ -f "$dir/package.json" ] || [ -f "$dir/pyproject.toml" ] ||
+	[ -d "$dir/.git" ] || [ -f "$dir/.git" ] || [ -f "$dir/package.json" ] || [ -f "$dir/pyproject.toml" ] ||
 		[ -f "$dir/Cargo.toml" ] || [ -f "$dir/go.mod" ] || [ -f "$dir/deno.json" ] ||
 		[ -f "$dir/Makefile" ] || [ -f "$dir/CLAUDE.md" ]
 }
@@ -38,7 +38,11 @@ detect_tags() {
 	local dir="$1"
 	local tags=()
 
-	[ -d "$dir/.git" ] && tags+=("git")
+	if [ -f "$dir/.git" ] && grep -q "gitdir:" "$dir/.git" 2>/dev/null; then
+		tags+=("git" "worktree")
+	elif [ -d "$dir/.git" ]; then
+		tags+=("git")
+	fi
 	[ -f "$dir/package.json" ] && tags+=("node")
 	[ -f "$dir/pyproject.toml" ] && tags+=("python")
 	[ -f "$dir/Cargo.toml" ] && tags+=("rust")
@@ -95,6 +99,19 @@ scan_and_update() {
 				is_excluded "$subname" && continue
 				new_projects=$(register_project "$new_projects" "$subname" "$subdir")
 			done
+
+			# Depth 3: .worktrees/ is hidden (not matched by */) — scan explicitly
+			local wtcontainer="${dir%/}/.worktrees"
+			if [ -d "$wtcontainer" ]; then
+				for wtdir in "${wtcontainer%/}"/*/; do
+					[ -d "$wtdir" ] || continue
+					local wtname
+					wtname=$(basename "$wtdir")
+					if has_project_markers "$wtdir"; then
+						new_projects=$(register_project "$new_projects" "$wtname" "$wtdir")
+					fi
+				done
+			fi
 		fi
 	done
 
@@ -158,20 +175,10 @@ start_watcher() {
 		stop_watcher
 	fi
 
-	# Check if inotifywait is available
+	# Check if inotifywait is available (installed by tmux feature at build time)
 	if ! command -v inotifywait &>/dev/null; then
-		echo "$LOG_PREFIX Installing inotify-tools..."
-		if command -v sudo &>/dev/null; then
-			sudo apt-get update -qq && sudo apt-get install -y -qq inotify-tools >/dev/null 2>&1
-		else
-			apt-get update -qq && apt-get install -y -qq inotify-tools >/dev/null 2>&1
-		fi
-
-		if ! command -v inotifywait &>/dev/null; then
-			echo "$LOG_PREFIX WARNING: Could not install inotify-tools, watcher disabled"
-			return 1
-		fi
-		echo "$LOG_PREFIX inotify-tools installed"
+		echo "$LOG_PREFIX WARNING: inotify-tools not installed, watcher disabled"
+		return 1
 	fi
 
 	# Fork background watcher in its own process group for clean shutdown
@@ -181,7 +188,7 @@ start_watcher() {
 		# -r watches subdirectories (catches events inside container dirs like projects/)
 		# --exclude filters noisy dirs that generate frequent irrelevant events
 		inotifywait -m -r -q -e create,delete,moved_to,moved_from \
-			--exclude '(node_modules|\.git/|\.tmp|__pycache__|\.venv)' \
+			--exclude '(node_modules|\.git|\.tmp|__pycache__|\.venv)' \
 			--format '%w%f %e' "$WORKSPACE_ROOT" 2>/dev/null |
 			while read -r _path event; do
 				# Small delay to let filesystem settle (e.g., move operations)

package/.devcontainer/scripts/setup.sh

@@ -22,8 +22,9 @@ fi
 : "${SETUP_UPDATE_CLAUDE:=true}"
 : "${SETUP_PROJECTS:=true}"
 : "${SETUP_TERMINAL:=true}"
+: "${SETUP_POSTSTART:=true}"
 
-export CLAUDE_CONFIG_DIR CONFIG_SOURCE_DIR SETUP_CONFIG SETUP_ALIASES SETUP_AUTH SETUP_PLUGINS SETUP_UPDATE_CLAUDE SETUP_PROJECTS SETUP_TERMINAL
+export CLAUDE_CONFIG_DIR CONFIG_SOURCE_DIR SETUP_CONFIG SETUP_ALIASES SETUP_AUTH SETUP_PLUGINS SETUP_UPDATE_CLAUDE SETUP_PROJECTS SETUP_TERMINAL SETUP_POSTSTART
 
 SETUP_START=$(date +%s)
 SETUP_RESULTS=()
@@ -42,12 +43,16 @@ run_script() {
     if [ "$enabled" = "true" ]; then
         if [ -f "$script" ]; then
             printf "  %-30s" "$name..."
-            if bash "$script" 2>&1; then
+            local output
+            if output=$(bash "$script" 2>&1); then
                 echo "done"
                 SETUP_RESULTS+=("$name:ok")
             else
-                echo "FAILED (exit $?)"
+                local exit_code=$?
+                echo "FAILED (exit $exit_code)"
                 SETUP_RESULTS+=("$name:failed")
+                # Show output on failure for diagnostics
+                echo "$output" | sed 's/^/    /'
             fi
         else
             echo "  $name... not found, skipping"
@@ -59,6 +64,30 @@ run_script() {
     fi
 }
 
+run_poststart_hooks() {
+    local hook_dir="/usr/local/devcontainer-poststart.d"
+    if [ ! -d "$hook_dir" ]; then
+        return 0
+    fi
+    local count=0
+    for hook in "$hook_dir"/*.sh; do
+        [ -f "$hook" ] || continue
+        [ -x "$hook" ] || continue
+        local name
+        name="$(basename "$hook")"
+        printf "  %-30s" "$name..."
+        if bash "$hook" 2>&1; then
+            echo "done"
+            count=$((count + 1))
+        else
+            echo "FAILED (exit $?)"
+        fi
+    done
+    if [ $count -gt 0 ]; then
+        SETUP_RESULTS+=("poststart-hooks:ok ($count)")
+    fi
+}
+
 run_script "$SCRIPT_DIR/setup-symlink-claude.sh" "true"
 run_script "$SCRIPT_DIR/setup-auth.sh" "$SETUP_AUTH"
 run_script "$SCRIPT_DIR/setup-config.sh" "$SETUP_CONFIG"
@@ -66,7 +95,20 @@ run_script "$SCRIPT_DIR/setup-aliases.sh" "$SETUP_ALIASES"
 run_script "$SCRIPT_DIR/setup-plugins.sh" "$SETUP_PLUGINS"
 run_script "$SCRIPT_DIR/setup-projects.sh" "$SETUP_PROJECTS"
 run_script "$SCRIPT_DIR/setup-terminal.sh" "$SETUP_TERMINAL"
-run_script "$SCRIPT_DIR/setup-update-claude.sh" "$SETUP_UPDATE_CLAUDE"
+
+# Background the update to avoid blocking container start
+if [ "$SETUP_UPDATE_CLAUDE" = "true" ] && [ -f "$SCRIPT_DIR/setup-update-claude.sh" ]; then
+    bash "$SCRIPT_DIR/setup-update-claude.sh" &>/dev/null &
+    disown
+    SETUP_RESULTS+=("setup-update-claude:background")
+else
+    SETUP_RESULTS+=("setup-update-claude:disabled")
+fi
+
+# Run post-start hooks
+if [ "$SETUP_POSTSTART" = "true" ]; then
+    run_poststart_hooks
+fi
 
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -77,10 +119,11 @@ for result in "${SETUP_RESULTS[@]}"; do
     name="${result%%:*}"
     status="${result##*:}"
     case "$status" in
-        ok)       printf "  ✓ %s\n" "$name" ;;
+        ok*)      printf "  ✓ %s\n" "$name" ;;
         failed)   printf "  ✗ %s (FAILED)\n" "$name"; FAILURES=$((FAILURES + 1)) ;;
         disabled) printf "  - %s (disabled)\n" "$name" ;;
         missing)  printf "  ? %s (not found)\n" "$name" ;;
+        background) printf "  ⇢ %s (background)\n" "$name" ;;
     esac
 done
 ELAPSED=$(( $(date +%s) - SETUP_START ))