@ai-support-agent/cli 0.1.32 → 0.1.33-beta.1

package/dist/plugin/commands/plan.md

@@ -0,0 +1,211 @@
+---
+description: Create an implementation plan grounded in the codebase's existing patterns before writing any code, and don't start implementing until it's approved
+argument-hint: "[free-form request | path to a requirements markdown file | leave empty]"
+resumable: true
+---
+
+# /plan - Create an implementation plan
+
+A command for drafting an implementation plan before writing code and getting the user's approval on it.
+It exists to prevent rework, misalignment, and drift from existing patterns that come from starting to implement without a plan.
+
+## Interpreting the input
+
+Evaluate `$ARGUMENTS` in this order.
+
+1. **Path to a markdown file**: read the file and treat its contents as the requirements/reference material.
+2. **Free-form text**: treat the text as the implementation request.
+3. **Empty input**: ask "What would you like a plan for? Please also share the purpose, background, and any constraints," and wait for the answer before continuing.
+
+## Procedure
+
+### Step 1: Restate the request
+
+Restate the request you received in your own words, in one to three sentences, and present it up front.
+Explicitly list any points open to interpretation and any assumptions you made.
+This step must not be skipped — it lets the user catch a mismatch between your restatement and their actual request early.
+
+### Step 2: Clarifying questions
+
+**This step can be skipped for trivial changes. It is required for small and larger changes.**
+
+Organize the ambiguities and open points left over from the restatement (Step 1) using the perspectives below,
+and ask the user about them together in one batch. Don't re-ask about anything already clear. Wait for the answer before moving to the next step.
+
+| Perspective | What to confirm |
+|---|---|
+| Target users and permissions | Who will use this feature? What permissions/preconditions are needed to operate it? |
+| Non-functional requirements | Are there performance, throughput, or scale targets? |
+| Backward compatibility and constraints | Must existing APIs, data formats, or external integrations be preserved? Are any technologies off-limits? |
+| Failure behavior | What should be returned to the user on failure? Is a rollback needed? |
+| Definition of done | What state counts as "complete"? Are there acceptance criteria? |
+
+If there's nothing unclear, declare "No clarifying questions" and move on.
+Fold the user's answers directly into the plan and the codebase investigation that follows.
+
+### Step 3: Codebase investigation
+
+Search the existing implementation for related code to ground the plan in. Investigate from these angles:
+
+- Naming conventions (file names, class names, function names, variable names)
+- Error-handling approach (exceptions, return values, error types, retries)
+- Logging approach (logger type, log-level usage, output format)
+- Data-access approach (ORM, repository layer, query style)
+- Testing conventions (framework, file placement, naming, mocking style)
+
+**Important**: if no similar code exists, say so honestly — "no matching existing pattern was found."
+Never fabricate a pattern that doesn't exist. Back every claim with a real file path.
+
+### Step 4: Draft the plan
+
+Based on the investigation, break the implementation into phases, and break each phase into steps.
+Attach to each step: the target file path, what to do, why, dependencies, and risk level (High/Medium/Low).
+Also include the test strategy (whether unit/integration/E2E tests are needed and what they cover), success criteria, and an overall complexity estimate (High/Medium/Low).
+
+For large plans — four or more phases, or more than ten affected files — you may delegate investigation and drafting to the planner subagent. Even then, this command handles the final presentation and approval check.
+(For a 3-phase plan, write the "Interfaces between phases" section yourself as described below; delegation is for four-plus phases.)
+
+#### No placeholders allowed
+
+Every step in the plan must be concrete enough to execute as written.
+Any of the following counts as **a failed plan** and must not appear:
+
+- "TBD," "TODO," "implement later," "details elsewhere"
+- "Add appropriate error handling," "add validation," "handle edge cases" (without saying what, specifically)
+- A step involving a code change with no code sample
+- "Same as Phase N" (later steps must not reference earlier ones — repeat what's needed instead)
+- Forward references to types, functions, or methods that aren't defined until a later step (e.g., a type used in Step N but only defined in Step N+1 or later)
+
+#### Interfaces between phases (large plans)
+
+For plans with three or more phases, add the following at the end of each phase:
+
+- **Inputs**: the artifacts this phase depends on from prior phases (name the specific function names, types, and file paths)
+- **Outputs**: what this phase hands off to later phases (name the specific function names, types, and file paths)
+
+The goal is for whoever implements a later phase to be able to work without reading the earlier phase's details.
+
+### Step 5: Self-review the plan
+
+Before presenting the plan, check it yourself against these three points.
+Fix any issues found on the spot. If nothing is wrong, move to the next step.
+
+1. **Requirement coverage**: does every requirement (from the request or requirements file) have a corresponding step?
+   Add a step for any requirement that's missing one.
+
+2. **Placeholder scan**: search for anything matching the "No placeholders allowed" list in Step 4.
+   Rewrite anything found into something concrete.
+
+3. **Name consistency**: are function, type, and constant names defined in earlier steps referenced by
+   the same names in later steps? Reconcile any mismatches.
+   After reconciling, re-run Check 1 (requirement coverage) and Check 2 (placeholder scan)
+   to make sure the renaming didn't introduce new problems.
+
+### Step 6: Present the plan
+
+Output the plan using the following template.
+
+```markdown
+# Implementation Plan: <title>
+
+## Restated request
+<the request in your own words, 1-3 sentences, including assumptions and interpretations>
+
+## Complexity estimate
+High / Medium / Low — <one-sentence rationale>
+
+## Existing patterns to follow
+| Aspect | Pattern to use | Evidence (real file path) |
+|------|----------------|--------------------------|
+| Naming | ... | ... |
+| Error handling | ... | ... |
+| Logging | ... | ... |
+| Data access | ... | ... |
+| Testing | ... | ... |
+
+*For any aspect with no matching pattern, write "No existing pattern (proposing a new approach)."*
+
+## Implementation phases
+
+### Phase 1: <phase name>
+| # | Target file | What to do | Why | Depends on | Risk |
+|---|------------|---------|------|------|--------|
+| 1-1 | path/to/file | ... | ... | none | Low |
+| 1-2 | path/to/file | ... | ... | 1-1 | Medium |
+
+<!-- Only for plans with 3+ phases -->
+- **Inputs**: (outputs from the prior phase; Phase 1 is "none")
+- **Outputs**: `functionName(arg: Type): ReturnType` — defined in path/to/file
+
+### Phase 2: <phase name>
+| # | Target file | What to do | Why | Depends on | Risk |
+|---|------------|---------|------|------|--------|
+| 2-1 | path/to/file | ... | ... | none | Low |
+| 2-2 | path/to/file | ... | ... | 2-1 | Medium |
+
+<!-- Only for plans with 3+ phases -->
+- **Inputs**: Phase 1's `functionName(arg: Type): ReturnType` — path/to/file
+- **Outputs**: `functionName2(arg: Type): ReturnType2` — defined in path/to/file
+
+## Test strategy
+- Unit tests: <scope and approach>
+- Integration tests: <scope and approach, or why they're not needed>
+- E2E tests: <scope and approach, or why they're not needed>
+
+## Success criteria
+- [ ] <verifiable criteria as a checklist>
+
+## Risks and mitigations
+- <risk>: <mitigation>
+```
+
+### Step 7: Confirm approval
+
+After presenting the plan, always ask: "Should I go ahead and start implementing this plan?"
+
+**The most important rule: don't write a single line of code until the user explicitly approves.**
+That includes creating or editing files, committing, and any "just a small preview" implementation.
+
+Handle the user's response as follows:
+
+- **Approval** ("OK," "go ahead," "approved," etc.): start implementing according to the plan.
+- **Requested changes** ("change this part," "drop Phase 2," etc.): revise the affected part of the plan, re-present it, and ask for approval again. Re-run the Step 5 self-review (all three checks) before re-presenting.
+- **Request for an alternative** ("try a different approach," etc.): draft a plan with a different approach and re-present it, optionally with a comparison table against the original.
+- **Rejection/abandonment**: discard the plan and don't implement anything.
+
+## Completion Marker Convention
+
+This command runs under `claude -p` (non-interactive), which restarts as a fresh process every turn — past turn 1, this command body is not guaranteed to be re-expanded, so gate discipline can silently erode across turns. To compensate, a hooks-based mechanism re-injects a digest of this command's must-obey constraints on the next turn whenever the flow is left incomplete.
+
+If this command's flow is **not yet complete** (e.g. stopped at Step 7's approval gate, waiting on clarifying questions, etc.), your response **MUST end** with a line that is an exact match of:
+
+`<!-- ai-support-agent:resume name="plan" -->`
+
+If the flow **is complete** (final user approval was obtained, or the plan was rejected/discarded), do **not** output this marker.
+
+Never output this marker inside a code block or as an illustrative example — only emit it as the actual last line of real output when the flow is genuinely incomplete.
+
+<!-- RESUME_DIGEST_START -->
+When resuming this command on turn 2+ without the full command body re-expanded, obey these constraints:
+
+- **Approval gate (Step 7)**: don't write a single line of code — no creating/editing files, no committing, no "just a small preview" — until the user explicitly approves the presented plan. Silence or a vague "sounds good" is not approval; ask "Should I go ahead and start implementing this plan?" and wait for an explicit yes.
+- Handle the user's response per Step 7: approval → start implementing; requested changes → revise only the affected part, re-present, and ask for approval again; request for an alternative → draft and present a different approach; rejection/abandonment → discard the plan and implement nothing.
+- Never self-interpret "roughly agreed to," silence, or an unrelated follow-up question as approval.
+- If clarifying questions (Step 2) are still outstanding for a small/standard-or-larger change, wait for the user's answers before drafting or re-drafting the plan.
+- Before presenting (or re-presenting) any plan, re-run the Step 5 self-review's three checks:
+  1. Requirement coverage — every requirement has a corresponding step.
+  2. Placeholder scan — no "TBD," "TODO," "add appropriate error handling," "same as Phase N," or forward references to undefined types/functions.
+  3. Name consistency — function/type/constant names match across steps; re-run checks 1 and 2 after any renaming.
+- **No placeholders allowed**: every step must be concrete enough to execute as written. A step with a code change but no code sample, or a vague instruction without specifics, is a failed plan.
+- Every claim in the plan (patterns, existing code) must be backed by a real file path — never fabricate a pattern that doesn't exist; say "no matching existing pattern was found" if that's the truth.
+- Once the user approves, implementation may begin; until then, remain at the gate and keep emitting the resume marker on every incomplete turn.
+<!-- RESUME_DIGEST_END -->
+
+## After implementation is done
+
+Once the plan is approved and implementation is complete, point to the next command as appropriate:
+
+- Code review: /code-review
+- Resolving build errors: /build-fix
+- Checking test coverage: /test-coverage
+- Keeping docs in sync: /update-docs

package/dist/plugin/commands/test-coverage.md

@@ -0,0 +1,64 @@
+---
+description: Measure test coverage, identify important uncovered paths, and present a prioritized plan for adding tests.
+argument-hint: "[target directory/file | leave empty for the whole project]"
+---
+
+# /test-coverage command
+
+**Input**: $ARGUMENTS
+
+A command whose goal isn't "raise the number" but "close off the highest-risk gaps" — it measures coverage and points at what actually matters.
+
+## Behavior
+
+### 1. Measure coverage
+
+Detect the project type and measure accordingly:
+
+| Stack | Command |
+|---|---|
+| Jest | `npx jest --coverage --coverageReporters=text-summary --coverageReporters=text` |
+| Vitest | `npx vitest run --coverage` |
+| pytest | `pytest --cov --cov-report=term-missing` |
+| PHPUnit | `./vendor/bin/phpunit --coverage-text` (requires Xdebug/PCOV) |
+
+If `$ARGUMENTS` specifies a path, scope the measurement to it. If no coverage tool is set up, present setup instructions and stop (don't add dependencies on your own).
+
+### 2. Risk-assess the uncovered code
+
+Evaluate by **the importance of what's uncovered**, not by how many lines are uncovered in the report:
+
+| Priority | Scope |
+|---|---|
+| High | Payments/billing, authentication, authorization checks, data writes/deletes, external API integrations, error-handling branches |
+| Medium | Business-logic branches, validation, data transformation |
+| Low | Display formatters, reading config values, trivial getters |
+
+Flag tests with weak assertions (tests that merely execute code without verifying anything), even if coverage is high.
+Also flag any path involving DB reads/writes that is **covered only by mocked tests** (green in the coverage report but never verified against a real DB) as a gap needing an integration test against a real database (see the integration-testing skill).
+
+### 3. Report
+
+```
+## Coverage report
+
+Overall: <n>% (statements) / <n>% (branches)
+
+### Highest-priority uncovered code
+1. <file:line range> — <what it does> / <what breaks if it stays uncovered>
+2. ...
+
+### Recommended tests to add (by priority)
+1. Add <case> to <test file> — <why>
+2. ...
+```
+
+### 4. Add tests (only with user approval)
+
+After presenting the report, if the user approves, add tests starting with the highest priority. Match the style of the existing tests (framework, fixtures, naming). Don't change production code just to make it more testable (report testability problems instead of fixing them here).
+
+## Notes
+
+- Don't aim for 100% coverage. Covering the important paths is enough.
+- Don't pad coverage numbers by adding only snapshot tests.
+- Don't duplicate at the unit-test level what's already covered by E2E tests.

package/dist/plugin/commands/update-docs.md

@@ -0,0 +1,98 @@
+---
+description: Update documentation (README, API specs, CLAUDE.md, etc.) to keep it in sync with code changes. Detects and fixes drift between implementation and docs.
+argument-hint: "[target document | leave empty to auto-detect drift]"
+---
+
+# /update-docs command
+
+**Input**: $ARGUMENTS
+
+A command that detects drift between the implementation and its documentation, and updates the documentation to match reality.
+
+## Behavior
+
+### 1. Identify the target
+
+- If `$ARGUMENTS` specifies a document, target that.
+- If empty, infer which documents are affected from recent changes (`git diff HEAD~10 --name-only`, or uncommitted changes):
+
+| Change | Documents to check |
+|---|---|
+| API endpoints/DTOs | API spec, OpenAPI definitions, README's API section |
+| Public function signature changes | Function reference on the docs site (see the consistency check below) |
+| Tests added/changed | describe/it spec descriptions (see the test-description check below) |
+| Environment variables/config | README's setup section, `.env.example` |
+| CLI commands/scripts | README's usage section, `package.json` scripts descriptions |
+| DB schema | ER diagram/schema docs, migration instructions |
+| Architecture/conventions | CLAUDE.md, ADRs, CONTRIBUTING |
+
+### 2. Detect drift
+
+Cross-check the documentation against the implementation and look for:
+
+- References to files, commands, or endpoints that no longer exist
+- Steps, parameters, or default values that differ from the implementation
+- Added features/settings with no documentation
+- Documentation for features that have since been removed
+
+### 3. Update
+
+- **Prioritize fixing factual errors** (wrong instructions do more harm than a missing mention of a new feature).
+- Match the existing documentation's tone, structure, and language.
+- For docs auto-generated from code (OpenAPI, etc.), suggest re-running the generation command rather than hand-editing.
+- For anything you're not confident about (design rationale that isn't clear from the code, etc.), don't rewrite it blindly — list it as an open question instead.
+
+### 4. Docs-site consistency check (only for projects with a docs site)
+
+If a Docusaurus (or similar) docs-site directory exists, do the following.
+For detailed build/generation pipeline patterns, see the docs-site skill.
+
+1. **Cross-check hand-written function reference pages**
+   - Grep for pages whose frontmatter has a `source: <path>#<functionName>` key.
+   - For each such page, read the implementation at `source` and verify:
+     - **Errors**: function name, parameter names, required/optional status, or thrown exceptions that don't match the implementation
+     - **Missing coverage**: parameters or exceptions that exist in the implementation but aren't in the page's parameter table or error section
+     - **Stale content**: anything documented on the page that's been removed from the implementation
+   - Always correct the documentation **to match the implementation**. If the implementation itself looks wrong, don't fix it — add it to the open-questions list instead.
+   - List any hand-written reference page without a `source` key as "not checkable" and suggest adding the key.
+2. **Auto-generated pages (OpenAPI/TypeDoc)**
+   - Don't edit generated pages directly — suggest re-running the generation command (`openapi:generate`, etc.).
+   - Regenerate the committed `openapi.json` and diff it to catch decorator changes that weren't reflected.
+3. **Verify test links**
+   - For links to tests within reference pages, confirm the linked file actually exists in the repository.
+4. **i18n translation freshness**
+   - For hand-written pages that exist in multiple locales, compare git's last-modified timestamps and flag any translation older than its source as "needs review."
+
+### 5. Detect drift in test descriptions
+
+- Detect mismatches between what a describe/it name claims and what the body actually asserts
+  (e.g., named "throws an exception" but never checks for one; named "gets persisted" but never reads back from the DB).
+- Suggest renaming uninformative names ("happy path," "test1," etc.) only when a change already touches that test.
+
+### 6. Report
+
+```
+## Documentation update
+
+Files updated:
+- <file>: <summary of the fix>
+
+### Consistency check results (docs site)
+- Errors: <page:item> — <discrepancy with the implementation> (fixed/needs review)
+- Missing coverage: <page> — <item present in the implementation but undocumented>
+- Stale content: <page> — <documented item removed from the implementation>
+- Broken links: <page> — <nonexistent test file>
+- Stale translations: <page> — <source update date vs. translation update date>
+
+### Test descriptions
+- <test file:test name> — <mismatch between the name and the assertions>
+
+Detected but not fixed (needs review):
+- <file:section> — <reason (unclear intent, needs a judgment call)>
+```
+
+## Notes
+
+- Only create new documentation when explicitly requested — the primary job here is fixing drift.
+- Don't mechanically generate a CHANGELOG from commit history; keep it focused on user-facing changes.
+- When updating CLAUDE.md, keep it concise — it gets loaded into every session, so bulk has a real cost.

package/dist/plugin/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-dangerous-commands.sh\""
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-secrets-before-commit.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/protect-sensitive-files.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-format.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/on-command-resume.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/on-command-stop.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/plugin/hooks/scripts/auto-format.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Auto-format after edits (PostToolUse / Edit, Write)
+# Only formats the edited file when the project already has a matching
+# formatter configured. Never performs network access to fetch tooling
+# (e.g. downloading via npx). Always exits successfully.
+set -u
+
+input=$(cat)
+command -v python3 >/dev/null 2>&1 || exit 0
+
+fp=$(printf '%s' "$input" | python3 -c 'import json,sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("file_path", ""))
+except Exception:
+    pass' 2>/dev/null) || exit 0
+[ -n "$fp" ] && [ -f "$fp" ] || exit 0
+
+proj="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+ext="${fp##*.}"
+
+has_prettier_config() {
+  ls "$proj"/.prettierrc "$proj"/.prettierrc.* "$proj"/prettier.config.* >/dev/null 2>&1 && return 0
+  [ -f "$proj/package.json" ] && grep -q '"prettier"' "$proj/package.json" && return 0
+  return 1
+}
+
+# Resolve Python tools preferring the project's virtual environment.
+# Priority order: $proj/.venv/bin -> $proj/venv/bin -> $VIRTUAL_ENV/bin -> global
+find_py_tool() {
+  tool="$1"
+  for dir in "$proj/.venv/bin" "$proj/venv/bin" "${VIRTUAL_ENV:-}/bin"; do
+    if [ -x "$dir/$tool" ]; then
+      printf '%s' "$dir/$tool"
+      return 0
+    fi
+  done
+  command -v "$tool" 2>/dev/null
+}
+
+case "$ext" in
+  ts|tsx|js|jsx|mjs|cjs|json|css|scss|vue)
+    # Only use a locally installed prettier; never auto-fetch via npx.
+    if [ -x "$proj/node_modules/.bin/prettier" ] && has_prettier_config; then
+      "$proj/node_modules/.bin/prettier" --write --log-level silent "$fp" >/dev/null 2>&1 || true
+    fi
+    ;;
+  py)
+    ruff_bin=$(find_py_tool ruff)
+    if [ -n "$ruff_bin" ]; then
+      if [ -f "$proj/ruff.toml" ] || [ -f "$proj/.ruff.toml" ] || { [ -f "$proj/pyproject.toml" ] && grep -q '\[tool\.ruff' "$proj/pyproject.toml"; }; then
+        "$ruff_bin" format --quiet "$fp" >/dev/null 2>&1 || true
+      fi
+    fi
+    ;;
+  php)
+    if [ -x "$proj/vendor/bin/pint" ]; then
+      "$proj/vendor/bin/pint" --quiet "$fp" >/dev/null 2>&1 || true
+    elif [ -x "$proj/vendor/bin/php-cs-fixer" ] && { [ -f "$proj/.php-cs-fixer.php" ] || [ -f "$proj/.php-cs-fixer.dist.php" ]; }; then
+      "$proj/vendor/bin/php-cs-fixer" fix --quiet "$fp" >/dev/null 2>&1 || true
+    fi
+    ;;
+esac
+exit 0

package/dist/plugin/hooks/scripts/check-secrets-before-commit.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Check for leaked secrets before committing (PreToolUse / Bash)
+# When running git commit, inspect the staged content for known token
+# formats. If any are found, require manual confirmation (ask).
+# False positives can simply be approved by the user.
+set -u
+
+input=$(cat)
+command -v python3 >/dev/null 2>&1 || exit 0
+command -v git >/dev/null 2>&1 || exit 0
+
+cmd=$(printf '%s' "$input" | python3 -c 'import json,sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("command", ""))
+except Exception:
+    pass' 2>/dev/null) || exit 0
+
+# Also detect commit invocations with extra options, e.g. git -C <dir> commit
+# or git -c key=val commit.
+printf '%s' "$cmd" | grep -Eq '(^|[;&|[:space:]])git[[:space:]][^;|&]*commit' || exit 0
+
+cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+# Only target high-confidence token formats (generic patterns like password=
+# are excluded because they produce too many false positives).
+pattern='AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|sk_live_[A-Za-z0-9]{20,}|AIza[0-9A-Za-z_-]{35}|-----BEGIN [A-Z ]*PRIVATE KEY-----'
+
+# Read NUL-separated so filenames containing spaces are not missed.
+hit_files=""
+while IFS= read -r -d '' f; do
+  if git show ":$f" 2>/dev/null | grep -EIq "$pattern"; then
+    hit_files="$hit_files $f"
+  fi
+done < <(git diff --cached --name-only --diff-filter=ACM -z 2>/dev/null)
+
+if [ -n "$hit_files" ]; then
+  python3 - "$hit_files" <<'PYEOF'
+import json, sys
+files = sys.argv[1].strip()
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "Guard: the staged content may contain secrets (API keys, tokens, or private keys). Affected files: " + files + " -- review the content and approve only if it is safe."
+    }
+}, ensure_ascii=False))
+PYEOF
+fi
+exit 0

package/dist/plugin/hooks/scripts/guard-dangerous-commands.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Guard against dangerous commands before execution (PreToolUse / Bash)
+# When a destructive command is detected, block execution and require the
+# user to manually confirm (ask) before it proceeds.
+# If python3 is unavailable, do nothing (fail open).
+set -u
+
+input=$(cat)
+command -v python3 >/dev/null 2>&1 || exit 0
+
+cmd=$(printf '%s' "$input" | python3 -c 'import json,sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("command", ""))
+except Exception:
+    pass' 2>/dev/null) || exit 0
+[ -z "$cmd" ] && exit 0
+
+reason=""
+# Detect rm with both recursive (-r/-R/--recursive) and force (-f/--force)
+# flags, regardless of whether they are combined, separate, or long-form.
+if printf '%s' "$cmd" | grep -Eq '(^|[;&|[:space:]])rm[[:space:]]' \
+  && printf '%s' "$cmd" | grep -Eq '[[:space:]]-[a-zA-Z]*[rR]|[[:space:]]--recursive' \
+  && printf '%s' "$cmd" | grep -Eq '[[:space:]]-[a-zA-Z]*f|[[:space:]]--force'; then
+  reason="recursive forced delete (rm -rf or equivalent)"
+elif printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push[^;|&]*([[:space:]](--force|-f))([[:space:]]|$)'; then
+  reason="git force push"
+elif printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+reset[[:space:]]+--hard'; then
+  reason="git reset --hard (discards working tree changes)"
+elif printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+clean[^;|&]*[[:space:]]-[a-zA-Z]*f'; then
+  reason="git clean -f (removes untracked files)"
+elif printf '%s' "$cmd" | grep -Eiq '(^|[^a-z])(drop[[:space:]]+(table|database|schema)|truncate[[:space:]]+table|truncate[[:space:]]+[a-z_]+;)'; then
+  reason="SQL containing DROP / TRUNCATE"
+elif printf '%s' "$cmd" | grep -Eq 'chmod[[:space:]]+(-R[[:space:]]+)?777'; then
+  reason="chmod 777 (grants full permissions to everyone)"
+elif printf '%s' "$cmd" | grep -Eq '(^|[;&|[:space:]])aws[[:space:]][^;|&]*[[:space:]](create|update|delete|put|terminate|stop|reboot|modify)-[a-z-]+'; then
+  reason="AWS resource mutation operation"
+elif printf '%s' "$cmd" | grep -Eq '(^|[;&|[:space:]])aws[[:space:]]+lambda[[:space:]]+invoke'; then
+  reason="AWS Lambda invocation (lambda invoke)"
+elif printf '%s' "$cmd" | grep -Eq '(^|[;&|[:space:]])aws[[:space:]]+ssm[[:space:]]+send-command'; then
+  reason="remote command execution via SSM"
+fi
+
+if [ -n "$reason" ]; then
+  python3 - "$reason" <<'PYEOF'
+import json, sys
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "Guard: detected " + sys.argv[1] + ". Review the command and its target before approving."
+    }
+}, ensure_ascii=False))
+PYEOF
+fi
+exit 0