agentpack-cli 0.3.4__tar.gz → 0.3.5__tar.gz

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.4
+Version: 0.3.5
 Summary: Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.
 License: MIT
 License-File: LICENSE
@@ -46,7 +46,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.3.4).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.5).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
 >
 > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. `cmd.exe` and bare Git setups are not a supported path yet.
 
@@ -77,7 +77,7 @@ Use AgentPack when a repo is too large to paste and you want faster, more consis
 - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
 - **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
-- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
+- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, stale-context warnings, MCP auto-refresh signals, and a machine-readable `agentpack:freshness` block in markdown fallback artifacts.
 - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
 - **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
 
@@ -188,7 +188,7 @@ AgentPack is best treated as a **ranked starting map**. It should reduce repeate
 | Pack time | Seconds on a warm cache; first summarize pass is slower |
 | Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
 | Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
-| Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
+| Freshness | Task or repo-stale MCP reads auto-refresh; static packs are clearly marked by task, git, and snapshot checks |
 
 Use real repo evals instead of trusting compression numbers:
 
@@ -246,12 +246,22 @@ This is the core reliability loop: pack, measure recall, inspect misses, then tu
 For MCP-capable agents, the preferred workflow is pull-based:
 
 1. Call `start_task(task)` when a new task begins. AgentPack writes `.agentpack/task.md`, packs context, and returns ranked markdown.
-2. Call `get_context()` when you need the latest cached pack; it tells you if the pack is stale.
+2. Call `get_context()` when you need the latest pack. It blocks for one refresh if `.agentpack/task.md` or the repo snapshot changed since the last pack, and otherwise prepends a freshness header.
 3. Call `get_delta_context()` after edits or hook hints to see what changed without loading the full pack.
 4. Call `explain_file(path)` or `get_related_files(path)` when a file looks relevant or suspicious.
 
 The CLI remains the setup/debug/release path. MCP is the best interactive path because the agent can ask for only the context it needs instead of relying on one static startup blob.
 
+Markdown context files are fallback artifacts for CI, logs, manual review, and non-MCP agents. Every rendered pack includes a machine-readable `agentpack:freshness` comment; agents should treat `active_context: mcp` as the preferred path and refresh before using markdown when `refresh_required: true`.
+
+For non-MCP agents, use the executable guard before editing:
+
+```bash
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+`guard` checks pack freshness, task freshness, repo snapshot freshness, and installed agent rules/hooks. With `--repair-stale --refresh-context`, it repairs stale AgentPack rule files and refreshes missing or stale context before returning success. `agentpack pack` also self-heals stale AgentPack rule blocks for the active agent, so older installs that still run `pack` get upgraded opportunistically.
+
 ## Before / After Agent Behavior
 
 Without AgentPack:
@@ -365,7 +375,7 @@ _*`--agent generic` outputs standard markdown. Claude adapter has richer instruc
 
 - AgentPack cannot intercept prompts inside IDEs — Cursor/Windsurf rely on rules being followed.
 - Claude wrapper (`agentpack claude`) is the most deterministic integration.
-- If the task changes drastically mid-session, context needs one refresh cycle.
+- If the task changes drastically mid-session, Claude hooks update `.agentpack/task.md` and block once for fresh hints; plain repo edits still use background repack to keep prompts fast.
 - AgentPack-selected files are ranked starting points, not absolute truth.
 
 ---
@@ -733,6 +743,36 @@ agentpack repair --agent all     # repair every supported integration
 
 ---
 
+### `agentpack guard`
+
+Run the pre-edit safety gate an agent can execute instead of only reading instructions.
+
+```bash
+agentpack guard                                      # check current agent + context
+agentpack guard --refresh-context                   # refresh stale/missing context
+agentpack guard --agent codex --repair-stale        # repair stale Codex rules/hooks
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+This is the strongest non-native enforcement AgentPack can provide: tools that run commands get a failing exit code when context is unsafe, and an automatic repair/refresh path when allowed.
+
+---
+
+### `agentpack migrate`
+
+Repair stale AgentPack integrations across existing repos after upgrading.
+
+```bash
+agentpack migrate --path . --agent auto
+agentpack migrate --path ~/src --discover --agent all
+agentpack migrate --path ~/src --discover --agent codex --refresh-context
+agentpack migrate --path ~/src --discover --dry-run
+```
+
+Use this when older repos still have stale `.cursorrules`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, VS Code tasks, or hook files. `--discover` scans nested repo folders, `--dry-run` reports without writing, and `--refresh-context` regenerates packs after repair.
+
+---
+
 ### `agentpack summarize`
 
 Build or refresh the offline summary cache. **No API calls, ever.**
@@ -881,18 +921,38 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 |---|---|
 | `start_task(task, mode, budget, max_tokens)` | Recommended MCP-first entry point. Writes `.agentpack/task.md`, generates a ranked pack, and returns packed markdown. |
 | `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack. If `task` is provided, writes it to `.agentpack/task.md`; if omitted, reads `task.md` or infers from git. |
-| `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
+| `get_context()` | Return the latest pack. If `.agentpack/task.md` or the repo snapshot differs from the packed metadata, it auto-refreshes before returning; otherwise it prepends a freshness header. |
 | `refresh()` | Refresh using the current `task.md` or git-inferred task. |
 | `explain_file(path, task)` | Show score, inclusion mode, reasons, symbols, imports, and importers for one file. |
 | `get_related_files(path, depth)` | Return import-graph neighbours and related tests for a file. |
 | `get_delta_context(max_files)` | Return the latest selected-file delta plus top current selected files. Useful for cheap prompt-time refresh checks. |
 | `get_stats()` | Return latest pack stats, savings, selection quality, excluded files, and benchmark-style signals. |
 
-**Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
+**Staleness detection:** `get_context()` compares the current task file, snapshot hash, and git state against the latest pack metadata. If `.agentpack/task.md` or the repo snapshot changed, it blocks for a fresh pack and prepends:
+
+```
+> Context auto-refreshed because .agentpack/task.md differs from the packed task ...
 ```
-> **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
+
+If auto-refresh fails, it falls back to the cached context with a loud stale warning and asks the agent to call `pack_context()` again.
+
+Static markdown cannot refresh itself, so rendered packs include a machine-readable fallback header:
+
+```text
+<!-- agentpack:freshness
+{
+  "active_context": "mcp",
+  "fallback_context": "markdown",
+  "refresh_required": false,
+  "mcp_refresh_tool": "agentpack_get_context",
+  "cli_refresh_command": "agentpack pack --task auto",
+  "guard_command": "agentpack guard --agent auto --repair-stale --refresh-context"
+}
+-->
 ```
 
+Claude prompt hooks also block once on clear task switches so first-turn hints are fresh. Non-MCP rule files and VS Code folder-open tasks use `agentpack guard --repair-stale --refresh-context` as the executable fallback. To prefer lower latency over first-turn freshness, set `blocking_task_refresh = false` under `[hooks]` in `.agentpack/config.toml`.
+
 **Smart truncation:** `start_task()` and `pack_context()` keep headers intact and trim file content blocks to fit the token budget, appending a note about how many files were omitted.
 
 Zero API calls — all analysis is offline. Summary cache keyed by file hash: cold run parallelises AST parsing across CPU cores; warm cache hits are instant.
@@ -1444,6 +1504,13 @@ src/agentpack/
     vscode_tasks.py            # install/remove .vscode/tasks.json entries
     global_install.py          # global: git template hooks + shell rc hook
 
+  ../native-integrations/       # tracked native-enforcement skeletons and blocked-status stubs
+    status.json                 # machine-readable native host enforcement status
+    cursor-extension/           # VS Code-style Cursor guard skeleton
+    windsurf-extension/         # VS Code-style Windsurf guard skeleton
+    claude-native/              # blocked native stub pending mandatory host API
+    codex-native/               # blocked native stub pending mandatory host API
+
   renderers/
     markdown.py                # renders pre-redacted ContextPack to markdown, including freshness/map/delta
     compact.py                 # compact protocol format for session context files
@@ -1496,7 +1563,8 @@ src/agentpack/
 - **`integrations/` vs `core/`**: git hooks, shell rc patching, and VS Code tasks are infrastructure concerns — they live in `integrations/`, not `core/`. `core/` is pure domain logic.
 - **Adapters render; installers configure**: `adapters/` knows how to write a context file for an agent. `installers/` knows how to configure the agent's tool (CLAUDE.md, .cursorrules, settings.json). They are separate concerns and separate classes.
 - **Agent integration contract is shared**: `integrations/agents.py` defines install, audit, and repair behavior for Claude, Cursor, Windsurf, Codex, Antigravity, and Generic. `install`, `repair`, `doctor --agent all`, and release verification use the same contract.
-- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()`, `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
+- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()` auto-refreshes stale task or repo-snapshot context and `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
+- **Native enforcement status is explicit**: `native-integrations/status.json` tracks host skeletons and blockers. Entries stay `guarded`, not `enforced`, until a host exposes mandatory pre-edit/pre-tool hooks that can block failed guard checks.
 
 ---
 
@@ -1521,6 +1589,7 @@ src/agentpack/
 - **Secret redaction**: covers AWS keys, GitHub tokens, OpenAI/Anthropic keys, JWTs, and private key blocks. Not a substitute for a dedicated secrets scanner on sensitive repos.
 - **Token estimates**: uses tiktoken `cl100k_base` — approximate, not exact for Claude's billing.
 - **Large repos (>5k files)**: global auto-bootstrap is skipped for repos over 5,000 files to avoid hangs. Run `agentpack init` explicitly in large codebases.
+- **Native hard enforcement**: tracked skeletons exist under `native-integrations/`, but all hosts remain `guarded` until their native APIs can guarantee mandatory pre-edit/pre-tool execution and block failed guard checks.
 
 ---
 

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.3.4).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.5).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
 >
 > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. `cmd.exe` and bare Git setups are not a supported path yet.
 
@@ -38,7 +38,7 @@ Use AgentPack when a repo is too large to paste and you want faster, more consis
 - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
 - **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
-- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
+- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, stale-context warnings, MCP auto-refresh signals, and a machine-readable `agentpack:freshness` block in markdown fallback artifacts.
 - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
 - **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
 
@@ -149,7 +149,7 @@ AgentPack is best treated as a **ranked starting map**. It should reduce repeate
 | Pack time | Seconds on a warm cache; first summarize pass is slower |
 | Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
 | Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
-| Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
+| Freshness | Task or repo-stale MCP reads auto-refresh; static packs are clearly marked by task, git, and snapshot checks |
 
 Use real repo evals instead of trusting compression numbers:
 
@@ -207,12 +207,22 @@ This is the core reliability loop: pack, measure recall, inspect misses, then tu
 For MCP-capable agents, the preferred workflow is pull-based:
 
 1. Call `start_task(task)` when a new task begins. AgentPack writes `.agentpack/task.md`, packs context, and returns ranked markdown.
-2. Call `get_context()` when you need the latest cached pack; it tells you if the pack is stale.
+2. Call `get_context()` when you need the latest pack. It blocks for one refresh if `.agentpack/task.md` or the repo snapshot changed since the last pack, and otherwise prepends a freshness header.
 3. Call `get_delta_context()` after edits or hook hints to see what changed without loading the full pack.
 4. Call `explain_file(path)` or `get_related_files(path)` when a file looks relevant or suspicious.
 
 The CLI remains the setup/debug/release path. MCP is the best interactive path because the agent can ask for only the context it needs instead of relying on one static startup blob.
 
+Markdown context files are fallback artifacts for CI, logs, manual review, and non-MCP agents. Every rendered pack includes a machine-readable `agentpack:freshness` comment; agents should treat `active_context: mcp` as the preferred path and refresh before using markdown when `refresh_required: true`.
+
+For non-MCP agents, use the executable guard before editing:
+
+```bash
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+`guard` checks pack freshness, task freshness, repo snapshot freshness, and installed agent rules/hooks. With `--repair-stale --refresh-context`, it repairs stale AgentPack rule files and refreshes missing or stale context before returning success. `agentpack pack` also self-heals stale AgentPack rule blocks for the active agent, so older installs that still run `pack` get upgraded opportunistically.
+
 ## Before / After Agent Behavior
 
 Without AgentPack:
@@ -326,7 +336,7 @@ _*`--agent generic` outputs standard markdown. Claude adapter has richer instruc
 
 - AgentPack cannot intercept prompts inside IDEs — Cursor/Windsurf rely on rules being followed.
 - Claude wrapper (`agentpack claude`) is the most deterministic integration.
-- If the task changes drastically mid-session, context needs one refresh cycle.
+- If the task changes drastically mid-session, Claude hooks update `.agentpack/task.md` and block once for fresh hints; plain repo edits still use background repack to keep prompts fast.
 - AgentPack-selected files are ranked starting points, not absolute truth.
 
 ---
@@ -694,6 +704,36 @@ agentpack repair --agent all     # repair every supported integration
 
 ---
 
+### `agentpack guard`
+
+Run the pre-edit safety gate an agent can execute instead of only reading instructions.
+
+```bash
+agentpack guard                                      # check current agent + context
+agentpack guard --refresh-context                   # refresh stale/missing context
+agentpack guard --agent codex --repair-stale        # repair stale Codex rules/hooks
+agentpack guard --agent auto --repair-stale --refresh-context
+```
+
+This is the strongest non-native enforcement AgentPack can provide: tools that run commands get a failing exit code when context is unsafe, and an automatic repair/refresh path when allowed.
+
+---
+
+### `agentpack migrate`
+
+Repair stale AgentPack integrations across existing repos after upgrading.
+
+```bash
+agentpack migrate --path . --agent auto
+agentpack migrate --path ~/src --discover --agent all
+agentpack migrate --path ~/src --discover --agent codex --refresh-context
+agentpack migrate --path ~/src --discover --dry-run
+```
+
+Use this when older repos still have stale `.cursorrules`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, VS Code tasks, or hook files. `--discover` scans nested repo folders, `--dry-run` reports without writing, and `--refresh-context` regenerates packs after repair.
+
+---
+
 ### `agentpack summarize`
 
 Build or refresh the offline summary cache. **No API calls, ever.**
@@ -842,18 +882,38 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 |---|---|
 | `start_task(task, mode, budget, max_tokens)` | Recommended MCP-first entry point. Writes `.agentpack/task.md`, generates a ranked pack, and returns packed markdown. |
 | `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack. If `task` is provided, writes it to `.agentpack/task.md`; if omitted, reads `task.md` or infers from git. |
-| `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
+| `get_context()` | Return the latest pack. If `.agentpack/task.md` or the repo snapshot differs from the packed metadata, it auto-refreshes before returning; otherwise it prepends a freshness header. |
 | `refresh()` | Refresh using the current `task.md` or git-inferred task. |
 | `explain_file(path, task)` | Show score, inclusion mode, reasons, symbols, imports, and importers for one file. |
 | `get_related_files(path, depth)` | Return import-graph neighbours and related tests for a file. |
 | `get_delta_context(max_files)` | Return the latest selected-file delta plus top current selected files. Useful for cheap prompt-time refresh checks. |
 | `get_stats()` | Return latest pack stats, savings, selection quality, excluded files, and benchmark-style signals. |
 
-**Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
+**Staleness detection:** `get_context()` compares the current task file, snapshot hash, and git state against the latest pack metadata. If `.agentpack/task.md` or the repo snapshot changed, it blocks for a fresh pack and prepends:
+
+```
+> Context auto-refreshed because .agentpack/task.md differs from the packed task ...
 ```
-> **Stale context** — repo changed since last pack (generated: ...). Run pack_context() to refresh.
+
+If auto-refresh fails, it falls back to the cached context with a loud stale warning and asks the agent to call `pack_context()` again.
+
+Static markdown cannot refresh itself, so rendered packs include a machine-readable fallback header:
+
+```text
+<!-- agentpack:freshness
+{
+  "active_context": "mcp",
+  "fallback_context": "markdown",
+  "refresh_required": false,
+  "mcp_refresh_tool": "agentpack_get_context",
+  "cli_refresh_command": "agentpack pack --task auto",
+  "guard_command": "agentpack guard --agent auto --repair-stale --refresh-context"
+}
+-->
 ```
 
+Claude prompt hooks also block once on clear task switches so first-turn hints are fresh. Non-MCP rule files and VS Code folder-open tasks use `agentpack guard --repair-stale --refresh-context` as the executable fallback. To prefer lower latency over first-turn freshness, set `blocking_task_refresh = false` under `[hooks]` in `.agentpack/config.toml`.
+
 **Smart truncation:** `start_task()` and `pack_context()` keep headers intact and trim file content blocks to fit the token budget, appending a note about how many files were omitted.
 
 Zero API calls — all analysis is offline. Summary cache keyed by file hash: cold run parallelises AST parsing across CPU cores; warm cache hits are instant.
@@ -1405,6 +1465,13 @@ src/agentpack/
     vscode_tasks.py            # install/remove .vscode/tasks.json entries
     global_install.py          # global: git template hooks + shell rc hook
 
+  ../native-integrations/       # tracked native-enforcement skeletons and blocked-status stubs
+    status.json                 # machine-readable native host enforcement status
+    cursor-extension/           # VS Code-style Cursor guard skeleton
+    windsurf-extension/         # VS Code-style Windsurf guard skeleton
+    claude-native/              # blocked native stub pending mandatory host API
+    codex-native/               # blocked native stub pending mandatory host API
+
   renderers/
     markdown.py                # renders pre-redacted ContextPack to markdown, including freshness/map/delta
     compact.py                 # compact protocol format for session context files
@@ -1457,7 +1524,8 @@ src/agentpack/
 - **`integrations/` vs `core/`**: git hooks, shell rc patching, and VS Code tasks are infrastructure concerns — they live in `integrations/`, not `core/`. `core/` is pure domain logic.
 - **Adapters render; installers configure**: `adapters/` knows how to write a context file for an agent. `installers/` knows how to configure the agent's tool (CLAUDE.md, .cursorrules, settings.json). They are separate concerns and separate classes.
 - **Agent integration contract is shared**: `integrations/agents.py` defines install, audit, and repair behavior for Claude, Cursor, Windsurf, Codex, Antigravity, and Generic. `install`, `repair`, `doctor --agent all`, and release verification use the same contract.
-- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()`, `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
+- **MCP is the interactive path**: `start_task()` writes task state and returns a fresh pack, while `get_context()` auto-refreshes stale task or repo-snapshot context and `get_delta_context()`, `explain_file()`, and `get_related_files()` let agents pull follow-up context on demand.
+- **Native enforcement status is explicit**: `native-integrations/status.json` tracks host skeletons and blockers. Entries stay `guarded`, not `enforced`, until a host exposes mandatory pre-edit/pre-tool hooks that can block failed guard checks.
 
 ---
 
@@ -1482,6 +1550,7 @@ src/agentpack/
 - **Secret redaction**: covers AWS keys, GitHub tokens, OpenAI/Anthropic keys, JWTs, and private key blocks. Not a substitute for a dedicated secrets scanner on sensitive repos.
 - **Token estimates**: uses tiktoken `cl100k_base` — approximate, not exact for Claude's billing.
 - **Large repos (>5k files)**: global auto-bootstrap is skipped for repos over 5,000 files to avoid hangs. Run `agentpack init` explicitly in large codebases.
+- **Native hard enforcement**: tracked skeletons exist under `native-integrations/`, but all hosts remain `guarded` until their native APIs can guarantee mandatory pre-edit/pre-tool execution and block failed guard checks.
 
 ---
 

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.4"
+version = "0.3.5"
 description = "Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs."
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/src/agentpack/__init__.py

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

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/src/agentpack/application/pack_service.py

@@ -15,6 +15,7 @@ from agentpack.core.diff import diff_snapshots
 from agentpack.core import git
 from agentpack.core.context_pack import select_files, save_pack_metadata, load_pack_metadata
 from agentpack.core.models import ContextPack, DependencyGraph, FileInfo, ScanResult, SelectedFile, Receipt
+from agentpack.core.task_freshness import read_task_md, task_metadata
 from agentpack.core.token_estimator import estimate_tokens
 from agentpack.renderers.markdown import render_generic
 from agentpack.analysis.ranking import (
@@ -851,19 +852,7 @@ def _change_source(root: Path, since: str | None, snapshot_changed: set[str], gi
 
 
 def _task_md_body(root: Path) -> str | None:
-    task_md_path = root / ".agentpack" / "task.md"
-    if not task_md_path.exists():
-        return None
-    try:
-        content = task_md_path.read_text(encoding="utf-8").strip()
-    except OSError:
-        return None
-    lines = [ln for ln in content.splitlines() if ln.strip() and not ln.startswith("#")]
-    body = lines[0].strip() if lines else ""
-    placeholder = "Write or update the current coding task here."
-    if body and placeholder not in body:
-        return body
-    return None
+    return read_task_md(root)
 
 
 def _build_freshness_metadata(
@@ -885,6 +874,7 @@ def _build_freshness_metadata(
         "task_class_signals": plan.task_class_signals,
         "dirty_files_count": len(dirty),
     }
+    metadata.update(task_metadata(root, request.task))
     if plan.workspace:
         metadata["workspace"] = plan.workspace
     if plan.workspace_roots:
@@ -909,7 +899,7 @@ def _freshness_warnings(root: Path, request: PackRequest, freshness: dict[str, A
     task_md = freshness.get("task_md")
     if task_md and task_md != request.task:
         warnings.append(
-            ".agentpack/task.md differs from the packed task; rerun with --task auto if task.md should win."
+            ".agentpack/task.md differs from the packed task; AgentPack-controlled context reads should auto-refresh, or run `agentpack pack --task auto`."
         )
     if freshness.get("changed_files_source") == "no live changes; ranking used task keywords and history":
         warnings.append("No live changed files were detected; treat selected files as keyword-based hints.")

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/src/agentpack/cli.py

@@ -7,10 +7,12 @@ from agentpack.commands import (
     diff,
     doctor,
     explain,
+    guard,
     hook_cmd,
     init,
     install,
     mcp_cmd,
+    migrate,
     monitor,
     pack,
     quickstart,
@@ -51,8 +53,10 @@ for mod in [
     pack,
     install,
     repair,
+    migrate,
     monitor,
     explain,
+    guard,
     doctor,
     tune,
     watch,

{agentpack_cli-0.3.4 → agentpack_cli-0.3.5}/src/agentpack/commands/doctor.py

@@ -18,6 +18,7 @@ from agentpack.integrations.global_install import (
 )
 from agentpack.commands._shared import console, _root
 from agentpack.core.context_pack import load_pack_metadata
+from agentpack.core.task_freshness import task_freshness
 from agentpack.integrations.agents import SUPPORTED_AGENTS, check_agent_integration, expand_agents
 
 
@@ -126,6 +127,14 @@ def register(app: typer.Typer) -> None:
                 age = time.time() - context_path.stat().st_mtime
                 age_str = f"{int(age // 3600)}h {int((age % 3600) // 60)}m" if age > 3600 else f"{int(age // 60)}m"
                 console.print(f"  [green]✓[/] context pack present (age: {age_str})")
+                task_state = task_freshness(root, load_pack_metadata(root))
+                if task_state.is_stale:
+                    console.print(
+                        "  [yellow]![/] task context stale — "
+                        f"packed: {task_state.packed_task}; current: {task_state.current_task}. "
+                        "MCP get_context auto-refreshes this, or run: agentpack pack --task auto"
+                    )
+                    ok = False
             else:
                 console.print("  [yellow]![/] No context pack yet — write .agentpack/task.md, then run: agentpack pack --task auto")
 
@@ -236,13 +245,20 @@ def register(app: typer.Typer) -> None:
             console.print(f"  [dim]Auto-detected agent: {agents[0]}[/]")
         for selected in agents:
             console.print(f"  [bold]{selected}[/]")
+            selected_ok = True
             for check in check_agent_integration(root, selected):
                 if check.ok:
                     console.print(f"    [green]✓[/] {check.label}: {check.detail}")
                     continue
                 fix = f" — run: {check.fix}" if check.fix else ""
                 console.print(f"    [red]✗[/] {check.label}: {check.detail}{fix}")
+                selected_ok = False
                 ok = False
+            if not selected_ok:
+                console.print(
+                    f"    [yellow]![/] executable guard repair: "
+                    f"agentpack guard --agent {selected} --repair-stale --refresh-context"
+                )
 
         # --- Release hygiene ---
         console.print("\n[bold]Release hygiene[/]")

agentpack_cli-0.3.5/src/agentpack/commands/guard.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import typer
+
+from agentpack.commands._shared import console, _root, run_refresh
+from agentpack.core.config import load_config
+from agentpack.core.context_pack import load_pack_metadata
+from agentpack.core.ignore import load_spec
+from agentpack.core.scanner import scan
+from agentpack.core.snapshot import build_snapshot
+from agentpack.core.task_freshness import task_freshness
+from agentpack.application.pack_service import AdapterRegistry
+from agentpack.integrations.agents import (
+    SUPPORTED_AGENTS,
+    check_agent_integration,
+    expand_agents,
+    install_agent_integration,
+)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command()
+    def guard(
+        agent: str = typer.Option(
+            "auto",
+            "--agent",
+            help=f"Agent integration to guard ({' | '.join(SUPPORTED_AGENTS)}).",
+        ),
+        repair_stale: bool = typer.Option(
+            False,
+            "--repair-stale",
+            help="Repair stale/missing AgentPack rule and hook files before returning.",
+        ),
+        refresh_context: bool = typer.Option(
+            False,
+            "--refresh-context",
+            help="Refresh the context pack when it is missing or stale.",
+        ),
+        mode: str = typer.Option("balanced", "--mode", help="Refresh mode (minimal|balanced|deep)."),
+        budget: int = typer.Option(0, "--budget", help="Refresh token budget (0 = config default)."),
+    ) -> None:
+        """Executable pre-edit gate for agents before they trust packed context."""
+        if agent not in SUPPORTED_AGENTS:
+            console.print(f"[yellow]Unknown agent: {agent}. Supported: {', '.join(SUPPORTED_AGENTS)}[/]")
+            raise typer.Exit(1)
+        if mode not in ("minimal", "balanced", "deep"):
+            console.print(f"[red]Invalid mode: {mode}. Use minimal|balanced|deep.[/]")
+            raise typer.Exit(1)
+
+        root = _root()
+        agents = expand_agents(agent, root)
+        ok = True
+
+        for selected in agents:
+            checks = check_agent_integration(root, selected)
+            failing = [check for check in checks if not check.ok]
+            if failing and repair_stale and selected != "generic":
+                _repair_agent(root, selected)
+                checks = check_agent_integration(root, selected)
+                failing = [check for check in checks if not check.ok]
+
+            if failing:
+                ok = False
+                console.print(f"[yellow]Agent integration needs repair: {selected}[/]")
+                for check in failing:
+                    fix = f" Run: {check.fix}" if check.fix else ""
+                    console.print(f"  [yellow]![/] {check.label}: {check.detail}.{fix}")
+            else:
+                console.print(f"[green]✓[/] Agent integration current: {selected}")
+
+        context_ok, context_reason = _context_is_fresh(root)
+        if not context_ok and refresh_context:
+            selected_agent = agents[0] if agents else "generic"
+            console.print(f"[yellow]Refreshing context: {context_reason}[/]")
+            stats = run_refresh(root, selected_agent, mode, budget)
+            if stats is None:
+                ok = False
+            else:
+                context_ok, context_reason = _context_is_fresh(root)
+
+        if context_ok:
+            console.print("[green]✓[/] Context pack fresh")
+        else:
+            ok = False
+            console.print(f"[yellow]Context pack unsafe: {context_reason}[/]")
+            console.print("  Run: agentpack guard --repair-stale --refresh-context")
+
+        if not ok:
+            raise typer.Exit(1)
+
+
+def _repair_agent(root, agent: str) -> None:
+    from agentpack.commands.install import _install_slash_command
+
+    console.print(f"[yellow]Repairing AgentPack integration: {agent}[/]")
+    install_agent_integration(
+        root,
+        agent,
+        global_install=False,
+        install_slash_command=_install_slash_command,
+    )
+
+
+def _context_is_fresh(root) -> tuple[bool, str]:
+    meta = load_pack_metadata(root)
+    if not meta:
+        return False, "missing context pack metadata"
+
+    task_state = task_freshness(root, meta)
+    if task_state.is_stale:
+        return False, ".agentpack/task.md differs from packed task"
+
+    try:
+        cfg = load_config(root)
+        ignore_spec = load_spec(root / cfg.project.ignore_file)
+        scan_result = scan(
+            root,
+            ignore_spec,
+            cfg.context.max_file_tokens,
+            always_skip_paths=AdapterRegistry.generated_output_paths(root, cfg),
+        )
+        current = build_snapshot(scan_result.packable)
+    except Exception as exc:
+        return False, f"could not compute repo snapshot: {exc}"
+
+    if current["root_hash"] != meta.get("snapshot_root_hash"):
+        return False, "repo snapshot differs from packed snapshot"
+
+    return True, "fresh"