agentpack-cli 0.3.33__tar.gz → 0.3.34__tar.gz

{agentpack_cli-0.3.33 → agentpack_cli-0.3.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.33
+Version: 0.3.34
 Summary: Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows.
 Project-URL: Homepage, https://github.com/vishal2612200/agentpack
 Project-URL: Documentation, https://vishal2612200.github.io/agentpack/
@@ -183,14 +183,14 @@ It reuses cached file summaries and snapshot metadata so repeated packs do not s
 - freshness warnings when task or git state changes
 - local benchmark data when selected context misses real changed files
 
-## What's Current In 0.3.33
+## What's Current In 0.3.34
 
-- Grounded broad context now supports review, sharing, audit, and repo-overview tasks with citation checks and scoped safety gates.
-- Review workflows now push agents through preflight, understanding, and findings stages instead of letting review prompts answer inline.
-- Pack and route fallbacks are stricter about stale context, missing MCP surfaces, and source provenance.
-- The npm wrapper preserves the selected Python descriptor when creating the versioned CLI environment.
-- Packaged Codex plugin metadata, docs URLs, and scanner automation now score cleanly in local HOL scans.
-- Light fixture recall improved by keeping correlated source/deploy summaries and using concrete owner terms in fixture tasks.
+- MCP setup is now checked in normal install, repair, and doctor flows, with clear separation between config registration, local runtime readiness, and live host exposure.
+- Agent instructions now prefer MCP only after a readiness call proves live tools, then fall back to bounded diagnostics, CLI context refresh, and direct repo search when host tools are missing.
+- Review and deployment tasks now get stronger source-of-truth routing so PR reviews stay anchored to the target diff and deploy work prioritizes rendered config plus live platform state.
+- `agentpack pack --task "<task>"` works again as a one-command task write plus context pack path, while `--task auto` remains the default context-source mode.
+- TOON citation validation is stricter about path tokens so prose before evidence no longer turns into a bogus file path.
+- Hook reminders are deduplicated per task/session and explain MCP fallback without repeating on every prompt.
 
 ## Proof So Far
 
@@ -346,7 +346,7 @@ pipx ensurepath
 
 ## Status
 
-Alpha: `0.3.33`.
+Alpha: `0.3.34`.
 
 Works, tested, and used in real sessions. Python and JavaScript/TypeScript have strongest support. APIs may change before 1.0.
 

{agentpack_cli-0.3.33 → agentpack_cli-0.3.34}/README.md

@@ -136,14 +136,14 @@ It reuses cached file summaries and snapshot metadata so repeated packs do not s
 - freshness warnings when task or git state changes
 - local benchmark data when selected context misses real changed files
 
-## What's Current In 0.3.33
+## What's Current In 0.3.34
 
-- Grounded broad context now supports review, sharing, audit, and repo-overview tasks with citation checks and scoped safety gates.
-- Review workflows now push agents through preflight, understanding, and findings stages instead of letting review prompts answer inline.
-- Pack and route fallbacks are stricter about stale context, missing MCP surfaces, and source provenance.
-- The npm wrapper preserves the selected Python descriptor when creating the versioned CLI environment.
-- Packaged Codex plugin metadata, docs URLs, and scanner automation now score cleanly in local HOL scans.
-- Light fixture recall improved by keeping correlated source/deploy summaries and using concrete owner terms in fixture tasks.
+- MCP setup is now checked in normal install, repair, and doctor flows, with clear separation between config registration, local runtime readiness, and live host exposure.
+- Agent instructions now prefer MCP only after a readiness call proves live tools, then fall back to bounded diagnostics, CLI context refresh, and direct repo search when host tools are missing.
+- Review and deployment tasks now get stronger source-of-truth routing so PR reviews stay anchored to the target diff and deploy work prioritizes rendered config plus live platform state.
+- `agentpack pack --task "<task>"` works again as a one-command task write plus context pack path, while `--task auto` remains the default context-source mode.
+- TOON citation validation is stricter about path tokens so prose before evidence no longer turns into a bogus file path.
+- Hook reminders are deduplicated per task/session and explain MCP fallback without repeating on every prompt.
 
 ## Proof So Far
 
@@ -299,7 +299,7 @@ pipx ensurepath
 
 ## Status
 
-Alpha: `0.3.33`.
+Alpha: `0.3.34`.
 
 Works, tested, and used in real sessions. Python and JavaScript/TypeScript have strongest support. APIs may change before 1.0.
 

{agentpack_cli-0.3.33 → agentpack_cli-0.3.34}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.33"
+version = "0.3.34"
 description = "Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows."
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.3.33 → agentpack_cli-0.3.34}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.3.33"
+__version__ = "0.3.34"

{agentpack_cli-0.3.33 → agentpack_cli-0.3.34}/src/agentpack/commands/doctor.py

@@ -8,6 +8,7 @@ from collections.abc import Mapping
 from pathlib import Path
 
 import typer
+from rich.markup import escape
 
 from agentpack.integrations.global_install import (
     _GIT_TEMPLATE_DIR,
@@ -20,6 +21,7 @@ from agentpack.commands._shared import console, _root
 from agentpack.core.command_surface import available_cli_commands, installed_cli_status, refresh_commands
 from agentpack.core.context_pack import load_pack_metadata
 from agentpack.core.ignore import agentignore_sync_status, format_import_summary
+from agentpack.core.mcp_runtime import McpRuntimeCheck, check_mcp_runtime
 from agentpack.core.task_freshness import task_freshness
 from agentpack.core.thread_context import detect_conflicts, list_thread_rows
 from agentpack.integrations.agents import SUPPORTED_AGENTS, check_agent_integration, expand_agents, install_agent_integration
@@ -249,12 +251,14 @@ def register(app: typer.Typer) -> None:
         if _local_has_hooks and not _global_has_hooks:
             console.print("  [yellow]![/] Hooks local-only — context won't auto-inject in other repos. Run: agentpack install --agent claude --global")
 
-        # --- MCP server ---
-        console.print("\n[bold]MCP server[/]")
+        # --- MCP registration ---
+        console.print("\n[bold]MCP registration[/]")
         mcp_json = root / ".mcp.json"
         global_claude_settings_for_mcp = Path.home() / ".claude" / "settings.json"
+        codex_config_for_mcp = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser() / "config.toml"
         _local_has_mcp = False
         _global_has_mcp = False
+        _codex_has_mcp = False
         if mcp_json.exists():
             try:
                 mcp_data = _json.loads(mcp_json.read_text())
@@ -275,16 +279,44 @@ def register(app: typer.Typer) -> None:
                     _global_has_mcp = True
             except Exception:
                 pass
-        if not _local_has_mcp and not _global_has_mcp:
+        if codex_config_for_mcp.exists():
+            try:
+                codex_text = codex_config_for_mcp.read_text(encoding="utf-8")
+                if (
+                    "[mcp_servers.agentpack]" in codex_text
+                    and 'command = "agentpack"' in codex_text
+                    and 'args = ["mcp"]' in codex_text
+                ):
+                    console.print(f"  [green]✓[/] MCP server registered (Codex): {codex_config_for_mcp}")
+                    _codex_has_mcp = True
+            except Exception:
+                pass
+        if not _local_has_mcp and not _global_has_mcp and not _codex_has_mcp:
             console.print("  [yellow]![/] MCP server not registered — mcp__agentpack__* tools unavailable")
-            console.print("  [yellow]![/] exact repair: agentpack install --agent claude")
+            console.print("  [yellow]![/] exact repair: agentpack install --agent codex or agentpack install --agent claude")
             ok = False
         else:
             console.print(
                 "  [green]✓[/] expected MCP tools: "
                 "readiness, route_task, pack_context, get_context, refresh, get_stats"
             )
-            console.print("  [green]✓[/] live exposure proof: call MCP tool `readiness` from the agent host")
+
+        # --- MCP runtime ---
+        console.print("\n[bold]MCP runtime[/]")
+        mcp_runtime = check_mcp_runtime(root=root)
+        _print_mcp_runtime_doctor(mcp_runtime)
+        if not mcp_runtime.ok:
+            ok = False
+
+        # --- Live host exposure ---
+        console.print("\n[bold]Live host exposure[/]")
+        console.print("  [yellow]![/] cannot be proven from CLI")
+        console.print("  Call `agentpack_readiness()` or `mcp__agentpack__readiness()` from the agent host.")
+        if mcp_runtime.ok:
+            console.print(
+                "  If readiness is absent, MCP local server is runnable but this host session has not exposed tools; "
+                "run `agentpack repair --agent <agent>` and restart the host."
+            )
 
         # --- Agent integration matrix ---
         console.print("\n[bold]Agent integration audit[/]")
@@ -377,6 +409,23 @@ def _safe_fix(root: Path, agent: str) -> None:
             console.print(f"  [green]✓[/] repaired {selected} integration")
 
 
+def _print_mcp_runtime_doctor(check: McpRuntimeCheck) -> None:
+    if check.status == "stdio_waiting":
+        console.print("  [green]✓[/] agentpack mcp starts and waits for stdio")
+        return
+    if check.status == "ready":
+        console.print(f"  [green]✓[/] {check.detail}")
+        return
+    if check.status == "missing_extra":
+        console.print("  [yellow]![/] missing MCP extra")
+    elif check.status == "command_missing":
+        console.print("  [yellow]![/] agentpack command missing")
+    else:
+        console.print(f"  [yellow]![/] {check.detail}")
+    for command in check.remediation:
+        console.print(f"  Fix: {escape(command)}")
+
+
 def _thread_conflict_findings(root: Path) -> list[str]:
     findings: list[str] = []
     for row in list_thread_rows(root, active_only=True):

{agentpack_cli-0.3.33 → agentpack_cli-0.3.34}/src/agentpack/commands/hook_cmd.py

@@ -69,6 +69,87 @@ _VAGUE_TASK_REFERENCES = {
     "this",
     "those",
 }
+_RUNTIME_INFRA_TERMS = {
+    "alb",
+    "aws",
+    "cfn",
+    "cloud",
+    "cloudformation",
+    "cloudwatch",
+    "copilot",
+    "deploy",
+    "deployment",
+    "ecs",
+    "github",
+    "iam",
+    "infra",
+    "lambda",
+    "log",
+    "logs",
+    "otp",
+    "package",
+    "rendered",
+    "runbook",
+    "runtime",
+    "secret",
+    "service",
+    "security",
+    "ssm",
+    "waf",
+    "workflow",
+}
+_DEPLOY_TASK_TERMS = {
+    "aws",
+    "cfn",
+    "cloudformation",
+    "cloudwatch",
+    "copilot",
+    "deploy",
+    "deployment",
+    "ecs",
+    "iam",
+    "lambda",
+    "prod",
+    "production",
+    "release",
+    "rollback",
+    "serverless",
+    "ship",
+}
+_RUNTIME_INFRA_PATH_TERMS = {
+    ".github/workflows",
+    "aws",
+    "cfn",
+    "cloudformation",
+    "copilot",
+    "deploy",
+    "ecs",
+    "iam",
+    "infra",
+    "lambda",
+    "manifest",
+    "override",
+    "security",
+    "serverless",
+    "waf",
+}
+_DEPLOY_PATH_TERMS = {
+    ".github/workflows",
+    "buildspec",
+    "cfn.patches",
+    "cloudformation",
+    "copilot",
+    "deploy",
+    "deployment",
+    "dockerfile",
+    "ecs",
+    "iam",
+    "manifest",
+    "package",
+    "pipeline",
+    "rendered",
+    "serverless",
+}
 
 
 def register(app: typer.Typer) -> None:
@@ -144,7 +225,10 @@ def _review_preflight_note(*, review_intent: bool, context_stale: bool, has_mcp:
     if not review_intent:
         return ""
     if has_mcp:
-        refresh = f'Call agentpack_pack_context(task="{task}") before PR diff/code review.'
+        refresh = (
+            f'If the AgentPack MCP tool is visible, call agentpack_pack_context(task="{task}") before PR diff/code review; '
+            f"otherwise run `{refresh_commands('auto').primary}` and use direct repo evidence."
+        )
     else:
         refresh = f"Run `{refresh_commands('auto').primary}` before PR diff/code review."
     lines = [
@@ -156,6 +240,109 @@ def _review_preflight_note(*, review_intent: bool, context_stale: bool, has_mcp:
     return "\n".join(lines) + "\n"
 
 
+def _review_reminder_key(task: str, packed_root_hash: str | None, current_root_hash: str | None) -> str:
+    return json.dumps(
+        {
+            "task": task,
+            "packed_root_hash": packed_root_hash or "",
+            "current_root_hash": current_root_hash or "",
+        },
+        sort_keys=True,
+    )
+
+
+def _should_emit_review_preflight(
+    root: Path,
+    *,
+    review_intent: bool,
+    task: str,
+    packed_root_hash: str | None,
+    current_root_hash: str | None,
+) -> bool:
+    if not review_intent:
+        return False
+    reminder_path = root / ".agentpack" / ".review_preflight_reminded"
+    key = _review_reminder_key(task, packed_root_hash, current_root_hash)
+    try:
+        if reminder_path.exists() and reminder_path.read_text(encoding="utf-8") == key:
+            return False
+        reminder_path.parent.mkdir(parents=True, exist_ok=True)
+        reminder_path.write_text(key, encoding="utf-8")
+    except OSError:
+        return True
+    return True
+
+
+def _source_of_truth_note(task: str) -> str:
+    if _looks_like_deploy_task(task):
+        return (
+            "AgentPack: guardrail + context frame only.\n"
+            "Source of truth: GitHub PR/head, clean worktree, rendered deploy config, live AWS/ECS/CloudFormation status, and CloudWatch logs.\n"
+        )
+    if not _looks_like_runtime_infra_task(task):
+        return ""
+    return (
+        "SOURCE OF TRUTH: treat AgentPack as guardrail/orientation only. "
+        "Use direct repo search, rendered config, cloud/provider validation, and focused tests for final evidence.\n"
+    )
+
+
+def _looks_like_runtime_infra_task(task: str) -> bool:
+    terms = _task_terms(task)
+    return bool(terms & _RUNTIME_INFRA_TERMS)
+
+
+def _looks_like_deploy_task(task: str) -> bool:
+    terms = _task_terms(task)
+    return bool(terms & _DEPLOY_TASK_TERMS)
+
+
+def _filter_runtime_infra_hints(task: str, hints: list[dict]) -> list[dict]:
+    if not _looks_like_runtime_infra_task(task):
+        return hints
+    task_terms = _task_terms(task)
+    if _looks_like_deploy_task(task):
+        return [hint for hint in hints if _deploy_hint_relevant(hint, task_terms)]
+    filtered = [hint for hint in hints if _runtime_infra_hint_relevant(hint, task_terms)]
+    return filtered
+
+
+def _deploy_hint_relevant(hint: dict, task_terms: set[str]) -> bool:
+    haystack = f"{hint.get('path', '')} {hint.get('why', '')}".lower()
+    if any(term in haystack for term in _DEPLOY_PATH_TERMS):
+        return True
+    return any(term in haystack for term in task_terms if len(term) >= 4)
+
+
+def _runtime_infra_hint_relevant(hint: dict, task_terms: set[str]) -> bool:
+    haystack = f"{hint.get('path', '')} {hint.get('why', '')}".lower()
+    if any(term in haystack for term in task_terms if len(term) >= 3):
+        return True
+    return any(term in haystack for term in _RUNTIME_INFRA_PATH_TERMS)
+
+
+def _review_stage_gate_note(root: Path, *, review_intent: bool) -> str:
+    if not review_intent:
+        return ""
+    state_path = root / ".agentpack" / "review-state.json"
+    if not state_path.exists():
+        return ""
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except Exception:
+        return "REVIEW STAGE BLOCK: active review state is unreadable. Run `agentpack review --check`.\n"
+    status = str(state.get("status") or "")
+    if status == "complete":
+        return ""
+    if status == "awaiting_understanding":
+        return "REVIEW STAGE BLOCK: Stage 1 understanding artifact missing. Write it, then run `agentpack review --check`.\n"
+    if status == "awaiting_findings":
+        return "REVIEW STAGE BLOCK: Stage 2 findings artifact missing. Write it, then run `agentpack review --check` before final summary.\n"
+    if status == "blocked_invalid_artifact":
+        return "REVIEW STAGE BLOCK: active review artifact invalid. Run `agentpack review --check` for exact error.\n"
+    return f"REVIEW STAGE BLOCK: active review status `{status}`. Run `agentpack review --check`.\n"
+
+
 def _prompt_task(prompt: str) -> str:
     if not prompt or not _looks_like_coding_prompt(prompt):
         return ""
@@ -301,6 +488,51 @@ def _current_root_hash(root: Path) -> str | None:
         return None
 
 
+def _stale_reasons(
+    *,
+    pack_missing: bool,
+    repo_changed: bool,
+    task_switched: bool,
+    pack_task_changed: bool,
+) -> list[str]:
+    reasons: list[str] = []
+    if pack_missing:
+        reasons.append("pack missing metadata")
+    if repo_changed:
+        reasons.append("repo snapshot changed")
+    if task_switched:
+        reasons.append("prompt switched task")
+    if pack_task_changed:
+        reasons.append("task differs from packed task")
+    return reasons
+
+
+def _stale_note(reasons: list[str]) -> str:
+    return f"stale reason: {', '.join(reasons)}\n" if reasons else ""
+
+
+def _mcp_status_note(root: Path, *, has_mcp: bool, task: str) -> str:
+    reminder_path = root / ".agentpack" / ".mcp_reminded"
+    key = json.dumps({"task": task, "has_mcp": has_mcp}, sort_keys=True)
+    try:
+        if reminder_path.exists() and reminder_path.read_text(encoding="utf-8") == key:
+            return ""
+        reminder_path.parent.mkdir(parents=True, exist_ok=True)
+        reminder_path.write_text(key, encoding="utf-8")
+    except OSError:
+        pass
+    if has_mcp:
+        return (
+            "MCP registration found. Live exposure must be proven by readiness(). "
+            "If readiness is absent, run one bounded `agentpack mcp` diagnostic, then use CLI/direct search fallback. "
+            "Do not keep `agentpack mcp` running manually.\n"
+        )
+    return (
+        "MCP unavailable: run `agentpack repair --agent auto`. Using CLI/direct search fallback. "
+        "A bounded `agentpack mcp` diagnostic can distinguish setup failure from host exposure failure.\n"
+    )
+
+
 # ---------------------------------------------------------------------------
 # Event handlers
 # ---------------------------------------------------------------------------
@@ -311,6 +543,7 @@ def _run_session_start(root: Path) -> None:
         root / ".agentpack" / ".mcp_reminded",
         root / ".agentpack" / ".context_injected",
         root / ".agentpack" / ".no_task_reminded",
+        root / ".agentpack" / ".review_preflight_reminded",
     ]:
         try:
             sentinel.unlink(missing_ok=True)
@@ -396,6 +629,12 @@ def _run_user_prompt_submit(root: Path) -> None:
     pack_task_changed = bool(task != "auto" and packed_task and packed_task != task)
 
     context_stale = pack_missing or repo_changed or task_switched or pack_task_changed
+    stale_reasons = _stale_reasons(
+        pack_missing=pack_missing,
+        repo_changed=repo_changed,
+        task_switched=task_switched,
+        pack_task_changed=pack_task_changed,
+    )
     blocking_refresh = bool(cfg.hooks.blocking_task_refresh and context_stale)
     refresh_state = "fresh"
     refresh_error = ""
@@ -417,13 +656,26 @@ def _run_user_prompt_submit(root: Path) -> None:
     review_intent = _looks_like_review_prompt(prompt)
     delta = _load_delta_summary(root)
     safe_hints = not pack_missing and not pack_task_changed and not task_switched and not repo_changed
-    hints = _load_hints(root, n=5 if has_mcp else 8) if safe_hints else []
+    raw_hints = _load_hints(root, n=5 if has_mcp else 8) if safe_hints else []
+    hints = _filter_runtime_infra_hints(current_task, raw_hints)
+    hints_suppressed = safe_hints and bool(raw_hints) and not hints
+    emit_review_preflight = _should_emit_review_preflight(
+        root,
+        review_intent=review_intent,
+        task=current_task,
+        packed_root_hash=packed_root_hash,
+        current_root_hash=current_hash,
+    )
     review_note = _review_preflight_note(
         review_intent=review_intent,
         context_stale=context_stale,
         has_mcp=has_mcp,
         task=current_task,
-    )
+    ) if emit_review_preflight else ""
+    review_stage_gate = _review_stage_gate_note(root, review_intent=review_intent)
+    source_note = _source_of_truth_note(current_task)
+    stale_detail = _stale_note(stale_reasons)
+    mcp_detail = _mcp_status_note(root, has_mcp=has_mcp, task=current_task)
 
     if has_mcp:
         if hints:
@@ -443,11 +695,16 @@ def _run_user_prompt_submit(root: Path) -> None:
                 f"AgentPack {status_note}\n"
                 f"task: {current_task}\n"
                 + review_note
+                + review_stage_gate
+                + source_note
+                + stale_detail
+                + mcp_detail
                 + (f"refresh error: {refresh_error}\n" if refresh_error else "")
                 + (f"delta: {delta}\n" if delta else "")
                 +
                 f"top files:\n{files_lines}\n"
-                f"Call agentpack_get_delta_context() for delta or agentpack_pack_context(task=\"...\") for full ranked context."
+                "If the AgentPack MCP tools are visible, call agentpack_get_delta_context() for delta or "
+                'agentpack_pack_context(task="...") for full ranked context; otherwise use direct repo search.'
             )
         elif refresh_state == "refresh pending":
             msg = (
@@ -455,7 +712,14 @@ def _run_user_prompt_submit(root: Path) -> None:
                 f"task: {current_task}\n"
                 + (f"packed task: {packed_task}\n" if packed_task and packed_task != current_task else "")
                 + review_note
-                + "Call agentpack_get_context() to refresh the current task pack."
+                + review_stage_gate
+                + source_note
+                + stale_detail
+                + mcp_detail
+                + (
+                    "If the AgentPack MCP tool is visible, call agentpack_get_context(); "
+                    f"otherwise run `{refresh_commands('auto').primary}` and use direct repo search."
+                )
             )
         elif refresh_state == "refresh failed":
             msg = (
@@ -463,13 +727,39 @@ def _run_user_prompt_submit(root: Path) -> None:
                 f"task: {current_task}\n"
                 + (f"packed task: {packed_task}\n" if packed_task and packed_task != current_task else "")
                 + review_note
+                + review_stage_gate
+                + source_note
+                + stale_detail
+                + mcp_detail
                 + (f"refresh error: {refresh_error}\n" if refresh_error else "")
-                + "Call agentpack_pack_context(task=\"...\") to rebuild the current task pack."
+                + (
+                    'If the AgentPack MCP tool is visible, call agentpack_pack_context(task="..."); '
+                    f"otherwise run `{refresh_commands('auto').primary}` and use direct repo search."
+                )
+            )
+        elif hints_suppressed:
+            msg = (
+                "AgentPack guardrail active. Selected-file hints suppressed because they did not match this runtime/infra task.\n"
+                f"task: {current_task}\n"
+                + review_note
+                + review_stage_gate
+                + source_note
+                + mcp_detail
+                + (f"delta: {delta}\n" if delta else "")
+                + (
+                    "If the AgentPack MCP tools are visible, call agentpack_pack_context(task=\"...\") for a fresh pack; "
+                    f"otherwise run `{refresh_commands('auto').primary}` or use direct repo search."
+                )
             )
         else:
             msg = (
-                "AgentPack active. No pack yet — call agentpack_pack_context(task=\"...\") "
-                "to build context for this task."
+                "AgentPack active. No pack yet.\n"
+                + source_note
+                + mcp_detail
+                + (
+                    'If the AgentPack MCP tool is visible, call agentpack_pack_context(task="..."); '
+                    f"otherwise run `{refresh_commands('auto').primary}`."
+                )
             )
     else:
         if hints:
@@ -489,6 +779,10 @@ def _run_user_prompt_submit(root: Path) -> None:
                 f"AgentPack context{changed_note}\n"
                 f"task: {current_task}\n"
                 + review_note
+                + review_stage_gate
+                + source_note
+                + stale_detail
+                + mcp_detail
                 + (f"refresh error: {refresh_error}\n" if refresh_error else "")
                 + (f"delta: {delta}\n" if delta else "")
                 +
@@ -501,7 +795,11 @@ def _run_user_prompt_submit(root: Path) -> None:
                 f"task: {current_task}\n"
                 + (f"packed task: {packed_task}\n" if packed_task and packed_task != current_task else "")
                 + review_note
-                + "Run `agentpack pack --task auto` or install MCP and call `agentpack_get_context()`."
+                + review_stage_gate
+                + source_note
+                + stale_detail
+                + mcp_detail
+                + f"Run `{refresh_commands('auto').primary}`. If tools stay unavailable, use direct repo search."
             )
         elif refresh_state == "refresh failed":
             msg = (
@@ -509,13 +807,29 @@ def _run_user_prompt_submit(root: Path) -> None:
                 f"task: {current_task}\n"
                 + (f"packed task: {packed_task}\n" if packed_task and packed_task != current_task else "")
                 + review_note
+                + review_stage_gate
+                + source_note
+                + stale_detail
+                + mcp_detail
                 + (f"refresh error: {refresh_error}\n" if refresh_error else "")
-                + "Run `agentpack pack --task auto` to rebuild the current task pack."
+                + f"Run `{refresh_commands('auto').primary}` to rebuild the current task pack."
+            )
+        elif hints_suppressed:
+            msg = (
+                "AgentPack guardrail active. Selected-file hints suppressed because they did not match this runtime/infra task.\n"
+                f"task: {current_task}\n"
+                + review_note
+                + review_stage_gate
+                + source_note
+                + mcp_detail
+                + (f"delta: {delta}\n" if delta else "")
+                + f"Run `{refresh_commands('auto').primary}` for a fresh pack, or use direct repo search."
             )
         else:
             msg = (
                 "AgentPack active. Write `.agentpack/task.md`, then run `agentpack pack --task auto` to build context.\n"
-                "For auto context, install MCP: agentpack install --agent claude"
+                + mcp_detail
+                + "For auto context, install MCP: agentpack install --agent claude"
             )
 
         if len(msg) > 3000: