agentpack-cli 0.3.30__tar.gz → 0.3.31__tar.gz

{agentpack_cli-0.3.30 → agentpack_cli-0.3.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.30
+Version: 0.3.31
 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/
@@ -65,6 +65,8 @@ Description-Content-Type: text/markdown
   <a href="https://pepy.tech/projects/agentpack-cli"><img alt="PyPI downloads" src="https://static.pepy.tech/personalized-badge/agentpack-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads"></a>
   <a href="https://www.npmjs.com/package/@vishal2612200/agentpack"><img alt="npm version" src="https://img.shields.io/npm/v/@vishal2612200/agentpack.svg"></a>
   <a href="https://www.npmjs.com/package/@vishal2612200/agentpack"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg"></a>
+  <a href="https://hol.org/registry/plugins/agentpack%2Fagentpack"><img alt="HOL trust score" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dagentpack%252Fagentpack%26metric%3Dtrust%26style%3Dflat"></a>
+  <a href="https://hol.org/registry/plugins/agentpack%2Fagentpack"><img alt="HOL security score" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dagentpack%252Fagentpack%26metric%3Dsecurity%26style%3Dflat"></a>
   <a href="https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
 </p>
@@ -227,10 +229,19 @@ Inside Codex:
 ```text
 @agentpack-route fix auth token expiry
 @agentpack-pack fix auth token expiry
-@agentpack-review
+@agentpack-review focus on backward compatibility
 ```
 
-The plugin calls the local AgentPack engine. It does not upload code and does not turn AgentPack into a coding agent.
+The Codex plugin calls the local AgentPack engine. Codex setup enables the
+local `agentpack@local` bundle so commands like `@agentpack-review` match the
+installed CLI version. Verify with `agentpack doctor --agent codex` after
+upgrades.
+
+The review flow prepares a local two-stage PR review bundle: preflight metadata,
+a runbook, stage prompts, and branch-scoped understanding/findings JSON files.
+It does not replace `gh pr view`, `git diff`, direct code reads, or tests.
+
+AgentPack does not upload code and does not turn AgentPack into a coding agent.
 
 See [`docs/agent-plugins.md`](docs/agent-plugins.md) and [`docs/codex-plugin.md`](docs/codex-plugin.md).
 

{agentpack_cli-0.3.30 → agentpack_cli-0.3.31}/README.md

@@ -18,6 +18,8 @@
   <a href="https://pepy.tech/projects/agentpack-cli"><img alt="PyPI downloads" src="https://static.pepy.tech/personalized-badge/agentpack-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads"></a>
   <a href="https://www.npmjs.com/package/@vishal2612200/agentpack"><img alt="npm version" src="https://img.shields.io/npm/v/@vishal2612200/agentpack.svg"></a>
   <a href="https://www.npmjs.com/package/@vishal2612200/agentpack"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg"></a>
+  <a href="https://hol.org/registry/plugins/agentpack%2Fagentpack"><img alt="HOL trust score" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dagentpack%252Fagentpack%26metric%3Dtrust%26style%3Dflat"></a>
+  <a href="https://hol.org/registry/plugins/agentpack%2Fagentpack"><img alt="HOL security score" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dagentpack%252Fagentpack%26metric%3Dsecurity%26style%3Dflat"></a>
   <a href="https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
 </p>
@@ -180,10 +182,19 @@ Inside Codex:
 ```text
 @agentpack-route fix auth token expiry
 @agentpack-pack fix auth token expiry
-@agentpack-review
+@agentpack-review focus on backward compatibility
 ```
 
-The plugin calls the local AgentPack engine. It does not upload code and does not turn AgentPack into a coding agent.
+The Codex plugin calls the local AgentPack engine. Codex setup enables the
+local `agentpack@local` bundle so commands like `@agentpack-review` match the
+installed CLI version. Verify with `agentpack doctor --agent codex` after
+upgrades.
+
+The review flow prepares a local two-stage PR review bundle: preflight metadata,
+a runbook, stage prompts, and branch-scoped understanding/findings JSON files.
+It does not replace `gh pr view`, `git diff`, direct code reads, or tests.
+
+AgentPack does not upload code and does not turn AgentPack into a coding agent.
 
 See [`docs/agent-plugins.md`](docs/agent-plugins.md) and [`docs/codex-plugin.md`](docs/codex-plugin.md).
 

{agentpack_cli-0.3.30 → agentpack_cli-0.3.31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.30"
+version = "0.3.31"
 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.30 → agentpack_cli-0.3.31}/src/agentpack/__init__.py

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

{agentpack_cli-0.3.30 → agentpack_cli-0.3.31}/src/agentpack/commands/review_cmd.py

@@ -6,23 +6,28 @@ import shutil
 import subprocess
 from pathlib import Path
 from typing import Any
+from uuid import uuid4
 
 import typer
 
 from agentpack.analysis.tests import find_related_tests
 from agentpack.commands._shared import _atomic_write, _now_iso, _root, console
 from agentpack.core import git as git_core
+from agentpack.core.toon_parser import ToonParseError, load_toon
 
 _PREFLIGHT_PATH = Path(".agentpack/review-preflight.json")
 _RUNBOOK_PATH = Path(".agentpack/review.prompt.md")
 _UNDERSTANDING_PROMPT_PATH = Path(".agentpack/review-understanding.prompt.md")
 _JUDGE_PROMPT_PATH = Path(".agentpack/review-judge.prompt.md")
+_REVIEW_RUNS_DIR = Path(".agentpack/reviews")
+_LLM_REVIEW_FORMAT = "TOON"
 
 
 def register(app: typer.Typer) -> None:
     @app.command("review")
     def review(
         review_context: str = typer.Argument("", help="Optional reviewer or developer context for this PR review."),
+        resume: str = typer.Option("", "--resume", help="Resume a previous review run by run id."),
     ) -> None:
         """Prepare the full two-stage PR review bundle for the current branch or PR."""
         root = _root()
@@ -30,8 +35,17 @@ def register(app: typer.Typer) -> None:
             console.print("[red]agentpack review requires a git repository.[/]")
             raise typer.Exit(1)
 
-        outputs = _review_output_paths(root)
-        preflight = _build_review_preflight(root, review_context.strip(), outputs)
+        if resume.strip():
+            preflight = _load_review_run(root, resume.strip())
+            outputs = _review_output_paths(
+                root,
+                branch_prefix=preflight["review"]["branch_prefix"],
+                run_id=preflight["review"]["run_id"],
+            )
+        else:
+            outputs = _review_output_paths(root)
+            preflight = _build_review_preflight(root, review_context.strip(), outputs)
+
         runbook = _render_review_runbook(preflight)
         understanding_prompt = _render_stage_prompt(
             "stage1-understanding.md",
@@ -46,16 +60,23 @@ def register(app: typer.Typer) -> None:
             prior_path=outputs["understanding"],
         )
 
-        for rel_path, content in {
+        artifacts = {
+            outputs["preflight"]: json.dumps(preflight, indent=2) + "\n",
+            outputs["runbook"]: runbook,
+            outputs["understanding_prompt"]: understanding_prompt,
+            outputs["judge_prompt"]: judge_prompt,
             _PREFLIGHT_PATH: json.dumps(preflight, indent=2) + "\n",
             _RUNBOOK_PATH: runbook,
             _UNDERSTANDING_PROMPT_PATH: understanding_prompt,
             _JUDGE_PROMPT_PATH: judge_prompt,
-        }.items():
+        }
+        for rel_path, content in artifacts.items():
             abs_path = root / rel_path
             abs_path.parent.mkdir(parents=True, exist_ok=True)
             _atomic_write(abs_path, content)
 
+        console.print(f"[green]✓[/] Review run id: [bold]{preflight['review']['run_id']}[/]")
+        console.print(f"[green]✓[/] Review run dir: [bold]{preflight['paths']['run_dir']}[/]")
         console.print(f"[green]✓[/] Review preflight: [bold]{_PREFLIGHT_PATH}[/]")
         console.print(f"[green]✓[/] Review runbook: [bold]{_RUNBOOK_PATH}[/]")
         console.print(f"[green]✓[/] Stage 1 prompt: [bold]{_UNDERSTANDING_PROMPT_PATH}[/]")
@@ -69,8 +90,8 @@ def register(app: typer.Typer) -> None:
         console.print("Use the runbook from your agent host; it drives understanding, then judge, against exact diff and code evidence.")
 
 
-def _build_review_preflight(root: Path, review_context: str, outputs: dict[str, Path]) -> dict[str, Any]:
-    branch = git_core.current_branch(root) or "HEAD"
+def _build_review_preflight(root: Path, review_context: str, outputs: dict[str, Any]) -> dict[str, Any]:
+    branch = outputs["branch"]
     sha = git_core.current_sha(root) or ""
     pr = _gh_pr_metadata(root)
     all_paths = _repo_paths(root)
@@ -88,6 +109,12 @@ def _build_review_preflight(root: Path, review_context: str, outputs: dict[str,
     return {
         "generated_at": _now_iso(),
         "review_context": review_context,
+        "review": {
+            "mode": "fresh",
+            "run_id": outputs["run_id"],
+            "branch": branch,
+            "branch_prefix": outputs["branch_prefix"],
+        },
         "git": {
             "branch": branch,
             "branch_prefix": outputs["branch_prefix"],
@@ -102,30 +129,78 @@ def _build_review_preflight(root: Path, review_context: str, outputs: dict[str,
             "changed_files_count": len(changed_files),
         },
         "paths": {
-            "preflight": str(_PREFLIGHT_PATH),
-            "runbook": str(_RUNBOOK_PATH),
-            "understanding_prompt": str(_UNDERSTANDING_PROMPT_PATH),
-            "judge_prompt": str(_JUDGE_PROMPT_PATH),
+            "run_dir": _rel_to_root(outputs["run_dir"], root),
+            "preflight": _rel_to_root(outputs["preflight"], root),
+            "runbook": _rel_to_root(outputs["runbook"], root),
+            "understanding_prompt": _rel_to_root(outputs["understanding_prompt"], root),
+            "judge_prompt": _rel_to_root(outputs["judge_prompt"], root),
             "understanding_output": _rel_to_root(outputs["understanding"], root),
             "findings_output": _rel_to_root(outputs["findings"], root),
+            "active_preflight": str(_PREFLIGHT_PATH),
+            "active_runbook": str(_RUNBOOK_PATH),
+            "active_understanding_prompt": str(_UNDERSTANDING_PROMPT_PATH),
+            "active_judge_prompt": str(_JUDGE_PROMPT_PATH),
         },
         "changed_files": changed_files,
         "warnings": warnings,
     }
 
 
-def _review_output_paths(root: Path) -> dict[str, Any]:
+def _review_output_paths(
+    root: Path,
+    *,
+    branch_prefix: str | None = None,
+    run_id: str | None = None,
+) -> dict[str, Any]:
     branch = git_core.current_branch(root) or "HEAD"
-    branch_prefix = branch.replace("/", "-")
-    understanding = root / f"{branch_prefix}_understanding.json"
-    findings = root / f"{branch_prefix}_findings.json"
+    branch_prefix = branch_prefix or branch.replace("/", "-")
+    run_id = run_id or _new_review_run_id()
+    run_dir = root / _REVIEW_RUNS_DIR / branch_prefix / run_id
     return {
+        "branch": branch,
         "branch_prefix": branch_prefix,
-        "understanding": understanding,
-        "findings": findings,
+        "run_id": run_id,
+        "run_dir": run_dir,
+        "preflight": run_dir / "preflight.json",
+        "runbook": run_dir / "runbook.md",
+        "understanding_prompt": run_dir / "understanding.prompt.md",
+        "judge_prompt": run_dir / "judge.prompt.md",
+        "understanding": run_dir / "understanding.toon",
+        "findings": run_dir / "findings.toon",
     }
 
 
+def _new_review_run_id() -> str:
+    return f"{_now_iso().replace(':', '').replace('-', '').replace('.', '')}-{uuid4().hex[:8]}"
+
+
+def _load_review_run(root: Path, run_id: str) -> dict[str, Any]:
+    branch = git_core.current_branch(root) or "HEAD"
+    branch_prefix = branch.replace("/", "-")
+    preflight_path = root / _REVIEW_RUNS_DIR / branch_prefix / run_id / "preflight.json"
+    if not preflight_path.exists():
+        console.print(f"[red]Review run not found:[/] {preflight_path}")
+        raise typer.Exit(1)
+    try:
+        preflight = json.loads(preflight_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        console.print(f"[red]Review run preflight is invalid JSON:[/] {preflight_path}")
+        raise typer.Exit(1)
+    understanding_path = preflight_path.parent / "understanding.toon"
+    findings_path = preflight_path.parent / "findings.toon"
+    try:
+        if understanding_path.exists():
+            _validate_review_artifact(understanding_path, kind="understanding")
+        if findings_path.exists():
+            _validate_review_artifact(findings_path, kind="findings")
+    except ValueError as exc:
+        console.print(f"[red]Review run artifact invalid:[/] {exc}")
+        raise typer.Exit(1)
+    preflight.setdefault("review", {})
+    preflight["review"]["mode"] = "resume"
+    return preflight
+
+
 def _render_review_runbook(preflight: dict[str, Any]) -> str:
     return (
         "# AgentPack Review Workflow\n\n"
@@ -135,6 +210,9 @@ def _render_review_runbook(preflight: dict[str, Any]) -> str:
         "## Reviewer Context\n\n"
         f"{preflight['review_context'] or '(none)'}\n\n"
         "## Preflight\n\n"
+        f"- Review mode: {preflight['review'].get('mode', 'fresh')}\n"
+        f"- Review run id: {preflight['review']['run_id']}\n"
+        f"- Review run dir: {preflight['paths']['run_dir']}\n"
         f"- Branch: {preflight['git']['branch']}\n"
         f"- Branch prefix: {preflight['git']['branch_prefix']}\n"
         f"- Head SHA: {preflight['git']['head_sha']}\n"
@@ -147,13 +225,13 @@ def _render_review_runbook(preflight: dict[str, Any]) -> str:
         f"- Preflight JSON: `{preflight['paths']['preflight']}`\n"
         f"- Stage 1 prompt: `{preflight['paths']['understanding_prompt']}`\n"
         f"- Stage 2 prompt: `{preflight['paths']['judge_prompt']}`\n"
-        f"- Stage 1 output: `{preflight['paths']['understanding_output']}`\n"
-        f"- Stage 2 output: `{preflight['paths']['findings_output']}`\n\n"
+        f"- Stage 1 output ({_LLM_REVIEW_FORMAT}): `{preflight['paths']['understanding_output']}`\n"
+        f"- Stage 2 output ({_LLM_REVIEW_FORMAT}): `{preflight['paths']['findings_output']}`\n\n"
         "## Workflow\n\n"
-        "1. Read the Stage 1 prompt file completely and produce the understanding JSON at the declared output path.\n"
-        "2. Confirm the understanding JSON parses before moving on.\n"
-        "3. Read the Stage 2 prompt file completely and produce the findings JSON at the declared output path.\n"
-        "4. Confirm the findings JSON parses before reporting back.\n"
+        f"1. Read the Stage 1 prompt file completely and produce the understanding {_LLM_REVIEW_FORMAT} at the declared output path.\n"
+        f"2. Confirm the understanding {_LLM_REVIEW_FORMAT} file exists and follows the declared schema before moving on.\n"
+        f"3. Read the Stage 2 prompt file completely and produce the findings {_LLM_REVIEW_FORMAT} at the declared output path.\n"
+        f"4. Confirm the findings {_LLM_REVIEW_FORMAT} file exists and follows the declared schema before reporting back.\n"
         "5. In the final user-facing response, summarize findings and validation gaps without exposing internal stage names.\n"
     )
 
@@ -167,23 +245,28 @@ def _render_stage_prompt(
 ) -> str:
     root = _root().resolve()
     abs_output = output_path.resolve()
-    lines = [
-        "# AgentPack Review Stage",
-        "",
-        "## AgentPack Context",
-        "",
-        f"- Reviewer context: {preflight['review_context'] or '(none)'}",
-        f"- Preflight JSON: {preflight['paths']['preflight']}",
-        f"- Diff range: {preflight['diff']['range']}",
-        f"- Diff source: {preflight['diff']['source']}",
-        f"- Output path: {_rel_to_root(abs_output, root)}",
-    ]
+    lines = [_load_review_template(template_name)]
+    lines.extend(
+        [
+            "",
+            "## AgentPack Run Inputs",
+            "",
+            f"- Review run id: {preflight['review']['run_id']}",
+            f"- Review mode: {preflight['review'].get('mode', 'fresh')}",
+            f"- Preflight JSON: {preflight['paths']['preflight']}",
+            f"- Head SHA: {preflight['git']['head_sha']}",
+            f"- Diff range: {preflight['diff']['range']}",
+            f"- Diff source: {preflight['diff']['source']}",
+            f"- Output path: {_rel_to_root(abs_output, root)}",
+            f"- Structured output format: {_LLM_REVIEW_FORMAT}",
+        ]
+    )
     if prior_path is not None:
         lines.append(f"- Input path: {_rel_to_root(prior_path.resolve(), root)}")
     if preflight["warnings"]:
         lines.extend(["", "## Warnings", ""])
         lines.extend(f"- {warning}" for warning in preflight["warnings"])
-    lines.extend(["", "## Stage Prompt", "", _load_review_template(template_name)])
+    lines.extend(["", "Reviewer context:", preflight["review_context"] or "(none)"])
     return "\n".join(lines).rstrip() + "\n"
 
 
@@ -296,6 +379,7 @@ def _warnings(root: Path, pr: dict[str, Any] | None, diff_info: dict[str, str],
     dirty = sorted(git_core.dirty_files(root))
     if dirty:
         warnings.append(f"dirty tree has {len(dirty)} path(s); review the checked-out PR head, not local edits")
+    warnings.extend(_incomplete_review_run_warnings(root))
     if not pr:
         warnings.append("gh PR metadata unavailable; review is using local git context only")
     if diff_info["source"] != "pr-base":
@@ -308,6 +392,53 @@ def _warnings(root: Path, pr: dict[str, Any] | None, diff_info: dict[str, str],
     return warnings
 
 
+def _incomplete_review_run_warnings(root: Path) -> list[str]:
+    branch = git_core.current_branch(root) or "HEAD"
+    branch_prefix = branch.replace("/", "-")
+    branch_dir = root / _REVIEW_RUNS_DIR / branch_prefix
+    if not branch_dir.exists():
+        return []
+    warnings: list[str] = []
+    for run_dir in sorted((path for path in branch_dir.iterdir() if path.is_dir()), reverse=True):
+        understanding = run_dir / "understanding.toon"
+        findings = run_dir / "findings.toon"
+        if understanding.exists():
+            try:
+                _validate_review_artifact(understanding, kind="understanding")
+            except ValueError as exc:
+                warnings.append(f"invalid understanding TOON in {run_dir.name}: {exc}")
+                break
+        if findings.exists():
+            try:
+                _validate_review_artifact(findings, kind="findings")
+            except ValueError as exc:
+                warnings.append(f"invalid findings TOON in {run_dir.name}: {exc}")
+                break
+        if understanding.exists() and not findings.exists():
+            warnings.append(
+                f"incomplete previous review run {run_dir.name}; start fresh by default or resume with `agentpack review --resume {run_dir.name}`"
+            )
+            break
+    return warnings
+
+
+def _validate_review_artifact(path: Path, *, kind: str) -> dict[str, Any]:
+    try:
+        payload = load_toon(path)
+    except (OSError, ToonParseError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{path.name} is not valid TOON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path.name} must decode to an object")
+    if kind == "understanding":
+        required = ("intent", "change_units", "open_questions")
+    else:
+        required = ("findings", "coverage")
+    missing = [key for key in required if key not in payload]
+    if missing:
+        raise ValueError(f"{path.name} missing required key(s): {', '.join(missing)}")
+    return payload
+
+
 def _rel_to_root(path: Path, root: Path) -> str:
     try:
         return str(path.relative_to(root)).replace("\\", "/")

{agentpack_cli-0.3.30 → agentpack_cli-0.3.31}/src/agentpack/core/config.py

@@ -128,6 +128,12 @@ class AgentConfig(BaseModel):
     patch_claude_md: bool = False
 
 
+class AgenticConfig(BaseModel):
+    llm_structured_format: str = "auto"
+    enforce_llm_toon: bool = True
+    toon_fallback_when_larger: bool = True
+
+
 class AgentsConfig(BaseModel):
     claude: AgentConfig = Field(
         default_factory=lambda: AgentConfig(
@@ -175,6 +181,7 @@ class Config(BaseModel):
     runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
     hooks: HooksConfig = Field(default_factory=HooksConfig)
     skills: SkillsConfig = Field(default_factory=SkillsConfig)
+    agentic: AgenticConfig = Field(default_factory=AgenticConfig)
     agents: AgentsConfig = Field(default_factory=AgentsConfig)
     scoring: ScoringWeights = Field(default_factory=ScoringWeights)
 
@@ -275,6 +282,11 @@ max_selected = 3
 always_recommend = ["karpathy-guidelines"]
 allow_external_side_effects = false
 
+[agentic]
+llm_structured_format = "auto"
+enforce_llm_toon = true
+toon_fallback_when_larger = true
+
 [scoring]
 # Scoring weights — higher wins budget allocation.
 # Tune these to make agentpack favour your team's file layout.

agentpack_cli-0.3.31/src/agentpack/core/pack_handoff.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any, Literal
+
+from agentpack.core.models import ContextPack, OmittedRelevantFile
+
+NextAction = Literal[
+    "ready_to_inspect_selected",
+    "inspect_omitted_first",
+    "refresh_context",
+    "deepen_pack",
+    "run_direct_search",
+]
+
+
+def build_pack_handoff(pack: ContextPack) -> dict[str, Any]:
+    """Return a compact operational receipt for agents before editing.
+
+    The receipt intentionally avoids correctness/confidence claims. It only
+    summarizes signals AgentPack already computed and recommends the next
+    inspection step before code changes.
+    """
+    omitted_relevant_files = pack.pack_handoff_omitted_relevant_files or pack.omitted_relevant_files
+    high_risk_omitted = [item for item in omitted_relevant_files if item.risk == "high"]
+    excluded_receipts = [receipt for receipt in pack.receipts if receipt.action == "excluded"]
+    stale = pack.stale or bool(pack.freshness_warnings)
+    budget_pressure = pack.budget > 0 and pack.token_estimate >= int(pack.budget * 0.95)
+    omitted_reason_counts = Counter(_omitted_reason_bucket(_omitted_reason(item)) for item in omitted_relevant_files)
+    excluded_reason_counts = Counter(_excluded_reason_bucket(receipt.reason) for receipt in excluded_receipts)
+    freshness_warnings = list(pack.freshness_warnings)
+
+    if stale:
+        action: NextAction = "refresh_context"
+        reason = "pack is stale or has freshness warnings"
+    elif high_risk_omitted:
+        action = "inspect_omitted_first"
+        reason = "high-risk omitted relevant files matched the task"
+    elif budget_pressure:
+        action = "deepen_pack"
+        reason = "pack rendered close to the token budget"
+    elif not pack.selected_files:
+        action = "run_direct_search"
+        reason = "no selected files were included in the pack"
+    else:
+        action = "ready_to_inspect_selected"
+        reason = "selected files are available and no refresh or omitted-file gate fired"
+
+    verifier_hint = _verifier_hint(action)
+    return {
+        "schema_version": 2,
+        "recommended_action": action,
+        "reason": reason,
+        "before_editing": {
+            "recommended_action": action,
+            "verifier_hint": verifier_hint,
+        },
+        "task": pack.task,
+        "task_hash": pack.freshness.get("packed_task_hash") or pack.freshness.get("task_hash") or "",
+        "context_path": pack.freshness.get("context_path", ""),
+        "repo_ref": {
+            "branch": pack.freshness.get("git_branch", ""),
+            "sha": pack.freshness.get("git_sha", ""),
+        },
+        "pack_snapshot": {
+            "generated_at": pack.freshness.get("generated_at", ""),
+            "snapshot_hash": pack.freshness.get("snapshot_root_hash", ""),
+        },
+        # Backward-compatible aliases for existing consumers.
+        "git_sha": pack.freshness.get("git_sha", ""),
+        "git_branch": pack.freshness.get("git_branch", ""),
+        "budget": {
+            "target_tokens": pack.budget,
+            "rendered_tokens": pack.token_estimate,
+            "pressure": budget_pressure,
+        },
+        "selected": {
+            "files": len(pack.selected_files),
+            "tests": sum(1 for item in pack.selected_files if _looks_like_test(item.path)),
+        },
+        "omitted_relevant": {
+            "files": len(omitted_relevant_files),
+            "high_risk": len(high_risk_omitted),
+            "top": [item.path for item in high_risk_omitted[:5]],
+            "reason_counts": _sorted_counts(omitted_reason_counts),
+        },
+        "skipped_uncertain": {
+            "excluded_files": len(excluded_receipts),
+            "excluded_reason_counts": _sorted_counts(excluded_reason_counts),
+            "freshness_warnings": freshness_warnings,
+        },
+        "freshness": {
+            "refresh_required": stale,
+            "warnings": freshness_warnings,
+        },
+        # Machine-readable extension point for non-markdown consumers. The
+        # markdown renderer already prints the same verifier hint inline.
+        "suggested_checks": [verifier_hint] if verifier_hint else [],
+    }
+
+
+def _looks_like_test(path: str) -> bool:
+    lower = path.lower()
+    name = lower.rsplit("/", 1)[-1]
+    return lower.startswith(("tests/", "test/")) or name.startswith("test_") or name.endswith(("_test.py", ".test.ts", ".test.js", ".spec.ts", ".spec.js"))
+
+
+def _omitted_reason(item: OmittedRelevantFile) -> str:
+    if item.reasons:
+        return item.reasons[0]
+    return item.omission_reason
+
+
+def _sorted_counts(counts: Counter[str]) -> dict[str, int]:
+    return dict(sorted(counts.items(), key=lambda item: (-item[1], item[0])))
+
+
+def _omitted_reason_bucket(reason: str) -> str:
+    lower = reason.lower()
+    if lower.startswith(("related test", "test for")) or "has related tests" in lower:
+        return "related_test"
+    if lower.startswith(("caller of selected symbol", "reverse dependency")):
+        return "caller_or_reverse_dependency"
+    if lower.startswith(("direct dependency", "direct content evidence")):
+        return "direct_evidence"
+    if lower.startswith(("keyword phrase match:", "literal definition match:", "quoted literal match:")):
+        return "literal_or_phrase_match"
+    if lower.startswith(("matched call:", "matched define:", "matched entrypoint:")):
+        return "symbol_or_entrypoint_match"
+    if lower.startswith(("matched env read:", "matched external system:", "matched side effect:")):
+        return "side_effect_or_external_match"
+    if lower.startswith("multi-term path match"):
+        return "multi_term_path_match"
+    if lower.startswith("api route owner match"):
+        return "api_route_owner_match"
+    if lower.startswith("api endpoint pair with"):
+        return "api_endpoint_pair"
+    if lower.startswith("api producer for frontend call"):
+        return "api_producer_for_frontend_call"
+    if lower.startswith("generic public api penalty"):
+        return "generic_public_api_penalty"
+    if lower.startswith("weak filename-only match"):
+        return "weak_filename_only_match"
+    if lower.startswith(("matched domain:", "matched naming keyword:", "matched ranking keyword:", "matched role keyword:")):
+        return "broad_keyword_match"
+    if lower.startswith(("workspace match", "release/version metadata", "build/dependency metadata")):
+        return "repo_metadata_match"
+    if lower.startswith("budget"):
+        return "budget"
+    return reason
+
+
+def _excluded_reason_bucket(reason: str) -> str:
+    lower = reason.lower()
+    if lower.startswith("marginal slot replaced by"):
+        return "marginal_slot_replaced"
+    return _omitted_reason_bucket(reason)
+
+
+def _verifier_hint(action: NextAction) -> str:
+    if action == "refresh_context":
+        return "run `agentpack pack` before editing"
+    if action == "inspect_omitted_first":
+        return "inspect high-risk omitted files before editing shared behavior"
+    if action == "deepen_pack":
+        return "increase the budget or rerun a deeper pack before broad edits"
+    if action == "run_direct_search":
+        return "run direct search because no files were selected"
+    return "inspect selected files before editing"

agentpack_cli-0.3.31/src/agentpack/core/structured_format.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+from agentpack.core.config import load_config
+from agentpack.core.token_estimator import estimate_tokens
+from agentpack.renderers.toon import is_toon_friendly, render_toon
+
+StructuredFormat = Literal["auto", "toon", "json"]
+
+
+def to_machine(value: Any) -> str:
+    return json.dumps(value, indent=2, sort_keys=True)
+
+
+def choose_llm_format(root: Path, value: Any, *, requested: StructuredFormat = "auto") -> Literal["toon", "json"]:
+    if requested == "json":
+        return "json"
+    if requested == "toon":
+        return "toon"
+
+    cfg = load_config(root)
+    configured = cfg.agentic.llm_structured_format
+    if configured == "json":
+        return "json"
+    if configured == "toon":
+        return "toon"
+    if not cfg.agentic.enforce_llm_toon:
+        return "json"
+
+    if not is_toon_friendly(value):
+        return "json"
+
+    json_text = json.dumps(value, indent=2, sort_keys=True)
+    toon_text = render_toon(value)
+    if cfg.agentic.toon_fallback_when_larger and estimate_tokens(toon_text) >= estimate_tokens(json_text):
+        return "json"
+    return "toon"
+
+
+def to_llm(root: Path, value: Any, *, requested: StructuredFormat = "auto", root_name: str | None = None) -> str:
+    chosen = choose_llm_format(root, value, requested=requested)
+    if chosen == "json":
+        return to_machine(value)
+    return render_toon(value, root_name=root_name)