pkgwhy 1.0.0__tar.gz → 1.6.0__tar.gz

{pkgwhy-1.0.0 → pkgwhy-1.6.0}/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 1.6.0 - 2026-07-01
+
+- Improve agent JSON consistency across decision commands with shared top-level fields for command, target, recommended next action, exit code, exit-code meaning, evidence summary, source freshness, and policy where available.
+- Add `pkgwhy.error.v1` JSON error objects for handled `--json` user/configuration errors in agent-facing gates.
+- Improve pyproject precheck routing for explicitly passed TOML files that contain a `[project]` table.
+- Add batch precheck summaries: `blocking_targets`, `review_targets`, `allowed_targets`, and `aggregate_recommendation`.
+- Add JSON output for registry trust-state commands: `trust`, `review`, `quarantine`, `block`, and `blocked`.
+- Make local registry `blocked` and `quarantined` trust states produce blocking `pkgwhy tool judge` decisions without weakening hash, signature, manifest, or static-analysis cautions.
+- Add non-executing `pkgwhy tool validate <path> --json` for local private-tool source validation.
+- Add static capability analysis for verified local tool bundles during `pkgwhy tool judge`.
+- Add `pkgwhy agent check <target> --json` as a safe dispatcher for package specs, requirements files, pyproject-style TOML files, and local tool folders/scripts.
+- Document the public agent integration contract, exit-code meanings, batch summary interpretation, pip gate safety model, and registry trust-state effects.
+- No cloud services, billing, hosted review, secrets, publishing, or OS-level sandboxing claims were added.
+
+## 1.5.0 - 2026-06-30
+
+- Add `docs/commercial-agent-platform.md` to describe the future commercial and agent platform direction without implementing cloud services, billing, hosted review, API keys, or secrets.
+- Document the product habit around `pkgwhy precheck`, `pkgwhy pip install`, and `pkgwhy agent precheck`.
+- Document future tiers for the free local CLI, Pro local policy packs, team review dashboard, hosted package review cache, shared organization policy, and agent install gateway.
+- Add explicit hosted-review boundaries so the current local CLI does not imply active cloud review or definitive malware detection.
+- Add tests that keep the commercial platform design doc future-only and boundary-aware.
+- Harden precheck and pip-gate follow-up review items: direct-reference handling, hash-locked requirements parsing, PyPI specifier release selection, Python 3.11-compatible tar extraction, private pip decision log paths/permissions, and CI pyproject gate coverage.
+- Harden second-pass review items: sanitized artifact URLs, stable-release preference for PyPI specifiers, safer keep-artifact failure handling, advisory-mode CI audit behavior, quarantine CLI coverage, and stricter pip requirements snapshot boundaries.
+
+## 1.4.0 - 2026-06-30
+
+- Add local registry trust states: `trusted`, `reviewed`, `quarantined`, `blocked`, and `unknown`.
+- Add trust-state storage to registry index entries and include trust state in tool judgement JSON and human output.
+- Add `pkgwhy registry trust <tool>`, `pkgwhy registry review <tool>`, `pkgwhy registry quarantine <tool>`, `pkgwhy registry block <tool>`, and `pkgwhy registry blocked`.
+- Enforce registry trust state in the local runner policy: `quarantined` and `blocked` tools are refused before execution.
+- Keep newly published local tools at `unknown` trust until a human marks them.
+- Keep tool lock/verify and registry export/import deferred rather than inventing incomplete trust guarantees.
+
+## 1.3.0 - 2026-06-30
+
+- Add a reusable GitHub Actions package-gate template at `examples/github-actions/pkgwhy-package-gate.yml`.
+- Document CI advisory, strict, and agent modes in `docs/ci-templates.md`.
+- The CI template installs `pkgwhy`, runs requirements precheck, emits JSON and Markdown audit reports, optionally runs agent precheck, uploads reports, and fails only in strict or agent mode.
+- Keep CI package-gate usage local and secret-free by default; no cloud service, hosted review, billing, or credentials are required.
+- Add static validation tests for the CI template and documentation boundaries.
+
+## 1.2.0 - 2026-06-30
+
+- Add `pkgwhy pip install <package>` as a local pip install gate over `pkgwhy precheck`.
+- Add `pkgwhy pip install -r requirements.txt` for requirements-file gate checks before pip is invoked.
+- Add schema-versioned `pkgwhy.pip_install_gate.v1` JSON with precheck decision, gate exit code, pip invocation status, override status, warnings, reasons, and embedded precheck output.
+- Add `--policy strict`, `--dry-run`, `--override-review`, `--override-block`, and `--override-reason` for explicit install-gate workflows.
+- Add best-effort compact local pip gate decision logs that omit full precheck evidence.
+- Keep tests deterministic by using fake pip runners and dry-run paths; tests do not install arbitrary public packages.
+- Keep the pip gate conservative: pip is called only after precheck allows it or an explicit override is used, and unavailable or incomplete precheck evidence exits without invoking pip.
+
+## 1.1.0 - 2026-06-30
+
+- Add top-level `pkgwhy precheck` as a local pre-install package gate for humans, CI, and agents.
+- Add schema-versioned `pkgwhy.precheck.v1` JSON for single package requirements, including decision, risk, confidence, evidence summaries, vulnerability/provenance/typosquat/static summaries, and embedded package judgement.
+- Add schema-versioned `pkgwhy.precheck_batch.v1` JSON for `pkgwhy precheck -r requirements.txt` and `pkgwhy precheck pyproject.toml`.
+- Add explicit `--download-artifacts` support that queries PyPI, downloads one wheel or source artifact to a temporary review directory, verifies SHA-256 when PyPI metadata provides it, extracts safely, statically inspects files, and deletes temporary files unless `--keep-artifacts` is set.
+- Add optional `--pypi`, `--osv`, and local `--vulnerability-file` enrichment boundaries to precheck without enabling network by default.
+- Add `--enforce-exit-code` for gate usage while keeping default JSON and human precheck commands easy to inspect interactively.
+- Keep precheck static-first: it does not install, import, or execute inspected package code.
+
 ## 1.0.0 - 2026-06-30
 
 - Promote the `1.0.0rc1` release-candidate surface to the final 1.0.0 tracked codebase after local release-prep review.

{pkgwhy-1.0.0 → pkgwhy-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkgwhy
-Version: 1.0.0
+Version: 1.6.0
 Summary: Offline-first Python package intelligence and supply-chain security decision support.
 Project-URL: Homepage, https://github.com/devlukeg/pkgwhy
 Project-URL: Repository, https://github.com/devlukeg/pkgwhy
@@ -36,17 +36,19 @@ Description-Content-Type: text/markdown
 
 # pkgwhy
 
+pip install pkgwhy
+
 Know why a package exists before you or your agent trusts it.
 
 `pkgwhy` is an offline-first Python package intelligence, agent policy, and local private-tool CLI. It explains installed packages, inspects local package files without importing them, reports conservative vulnerability, provenance, and static security signals, produces agent-readable JSON judgements, and can publish and run local private Python tools from a local registry.
 
 ## Status
 
-`pkgwhy` 1.0.0 is a Python supply-chain security decision-support tool for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, and the local private-registry and runner MVP.
+`pkgwhy` 1.6.0 is a Python supply-chain security decision-support tool and local pip/CI install gate for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, artifact precheck, guarded pip installs, CI package-gate templates, local registry trust states, local tool validation, agent check dispatching, and the local private-registry and runner MVP.
 
 It is not a production security scanner, not malware-detection certainty, and not a full sandbox. Results are evidence and signals for review, not proof that a package is safe or malicious.
 
-Current packaged version: `1.0.0`.
+Current packaged version: `1.6.0`.
 
 ## What Works Now
 
@@ -58,8 +60,16 @@ pkgwhy explain typer
 pkgwhy why typer
 pkgwhy inspect typer
 pkgwhy judge typer --json
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+pkgwhy precheck annotated-doc==0.0.4 --download-artifacts --json
+pkgwhy pip install typer --dry-run
+pkgwhy pip install -r requirements.txt --dry-run
 pkgwhy agent policy --json
 pkgwhy agent precheck typer --json
+pkgwhy agent check typer --json
 pkgwhy risk typer
 pkgwhy audit --limit 5 --json
 pkgwhy audit --limit 5 --json --vulnerability-file ./osv-fixture.json
@@ -87,6 +97,15 @@ Implemented capabilities include:
 - Metadata-derived provenance/source-trust fields from installed metadata and optional PyPI JSON, with unsupported attestation and trusted-publishing checks marked as unknown or not implemented.
 - Conservative risk level, decision, warning, recommendation, evidence, confidence, risk model version, and rule-ID output.
 - Human `inspect`, `risk`, and `judge` reports that show compact rule-evidence summaries, while JSON reports include structured rule details.
+- Pre-install package precheck for package requirements, requirements files, and `pyproject.toml` dependencies.
+- Explicit artifact-download precheck that downloads a PyPI wheel or source artifact to a temporary review directory, verifies SHA-256 when available, extracts safely, statically inspects files, and deletes temporary files by default.
+- Optional gate exit codes via `pkgwhy precheck --enforce-exit-code`.
+- Guarded pip install flow via `pkgwhy pip install`, with precheck first, stable exit codes, explicit overrides, and compact local decision logs.
+- Reusable GitHub Actions package-gate template with advisory, strict, and agent modes.
+- Local registry trust states for private tools: `trusted`, `reviewed`, `quarantined`, `blocked`, and `unknown`.
+- Local private-tool source validation with `pkgwhy tool validate <path> --json`.
+- Agent check dispatching with `pkgwhy agent check <target> --json` for package specs, dependency files, pyproject-style TOML, and local tool folders/scripts.
+- Commercial and agent platform architecture documentation for future local policy packs, team review, hosted evidence cache, shared organization policy, and agent install gateway.
 - Stable JSON output for agent workflows.
 - Schema-versioned agent policy and package precheck output.
 - Conservative non-interactive agent defaults that block unknown or high-risk package use until a human reviews the evidence.
@@ -100,8 +119,12 @@ pkgwhy registry list
 pkgwhy registry add local-copy ~/.pkgwhy/registry
 pkgwhy registry use local
 pkgwhy publish ./my_tool.py
+pkgwhy registry trust local/my_tool
+pkgwhy registry quarantine local/my_tool
+pkgwhy registry blocked
 pkgwhy tool inspect local/my_tool
 pkgwhy tool judge local/my_tool --json
+pkgwhy tool validate ./my-tool-folder --json
 pkgwhy run local/my_tool
 pkgwhy run local/my_tool --non-interactive
 ```
@@ -121,6 +144,7 @@ Current runner policy is intentionally conservative:
 - Corrupt registry indexes fail closed for publish and tool-judgement paths.
 - Symlinks are not bundled, and stored registry paths must remain inside the registry root.
 - Bundle hash mismatch or a missing bundle blocks execution.
+- Quarantined or blocked registry trust states block execution.
 - `sandbox_only` and `block` tool judgements block execution.
 - Non-interactive execution is blocked unless both the judgement and manifest agent policy allow it.
 - Tools with declared dependencies are not run yet because dependency installation is not implemented.
@@ -134,11 +158,12 @@ These are roadmap items, not current features:
 
 - Complete vulnerability database coverage, transitive vulnerability analysis, or guaranteed advisory freshness.
 - Default online vulnerability lookup. Network access is only used when explicitly requested.
-- Cached PyPI/source lookup beyond the current OSV response cache.
+- Persistent cached PyPI/source lookup beyond the current OSV response cache.
 - Cloud/private remote registry backends.
 - `pull`, mirroring, and remote synchronization.
 - Tool dependency installation in the runner.
 - Tool bundle signing and signature verification.
+- Tool lock/verify commands and registry export/import.
 - Dynamic sandbox analysis for arbitrary packages.
 - Tool-specific `pkgwhy agent judge` expansion beyond the current package precheck path.
 - `pkgwhy agent explain-decision <review-id>`.
@@ -197,15 +222,70 @@ Emit machine-readable judgement JSON:
 pkgwhy judge typer --json
 ```
 
+Before installing a package, run a local precheck:
+
+```bash
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+```
+
+By default, `pkgwhy precheck` uses local installed metadata when available and does not use the network. Add `--pypi` or `--osv` only when you want explicit online enrichment. Add `--download-artifacts` to query PyPI, download one wheel or source artifact, verify its SHA-256 when PyPI metadata provides it, extract it to a temporary review directory, inspect it statically, and delete the temporary files. The command does not install, import, or execute inspected package code.
+
+For CI or install-gate usage, add `--enforce-exit-code`:
+
+```bash
+pkgwhy precheck typer --json --enforce-exit-code
+```
+
+Exit codes are:
+
+- `0`: allow.
+- `1`: allow with caution or manual review.
+- `2`: block or sandbox-only.
+- `4`: requested online/artifact lookup was unavailable or failed.
+
+To gate an install, use `pkgwhy pip install` instead of raw `pip install`:
+
+```bash
+pkgwhy pip install typer
+pkgwhy pip install typer --policy strict
+pkgwhy pip install -r requirements.txt
+pkgwhy pip install typer --dry-run --json
+```
+
+The pip gate always runs precheck first. It invokes pip only when the precheck policy allows the install, or when a human uses an explicit override flag. Review/caution results exit `1`, block/sandbox-only results exit `2`, tool/config errors exit `3`, and unavailable or incomplete requested evidence exits `4`. `--dry-run` evaluates the gate and writes the local decision log without invoking pip.
+
+Overrides are explicit:
+
+```bash
+pkgwhy pip install typer --override-review --override-reason "reviewed local evidence"
+pkgwhy pip install suspicious-name --override-block --override-reason "temporary isolated test"
+```
+
+Agents and automated workflows should use `pkgwhy pip install` when dependency policy is required, not raw `pip install`. The command is still decision support: it does not prove a package is safe and it does not sandbox pip or installed package code.
+
+For CI package gates, start from the reusable GitHub Actions template:
+
+```text
+examples/github-actions/pkgwhy-package-gate.yml
+```
+
+See [CI Templates](docs/ci-templates.md) for advisory, strict, and agent-mode usage. The template does not require secrets or a hosted `pkgwhy` service.
+
 Inspect the default agent policy and run a conservative agent precheck:
 
 ```bash
 pkgwhy agent policy --json
 pkgwhy agent precheck typer --json
 pkgwhy agent judge typer --json
+pkgwhy agent check typer --json
+pkgwhy agent check requirements.txt --json
+pkgwhy agent check ./my-tool-folder --json
 ```
 
-`pkgwhy agent precheck` applies policy to the package judgement. In the default non-interactive mode, unknown and high-risk package decisions are blocked until a human reviews the judgement evidence. The command writes a compact local decision log under the user config directory when that directory is writable and does not install, import, or execute the package.
+`pkgwhy agent precheck` applies policy to the package judgement. In the default non-interactive mode, unknown and high-risk package decisions are blocked until a human reviews the judgement evidence. `pkgwhy agent check` dispatches the target to the safest matching local check and returns one normalized decision envelope. These commands do not install, import, or execute inspected package code. Agent precheck writes a compact local decision log under the user config directory when that directory is writable.
 
 Run a conservative risk report:
 
@@ -314,10 +394,36 @@ Apply the stricter non-interactive runner policy:
 pkgwhy run local/my_tool --non-interactive
 ```
 
-## Agent JSON Contracts
+## Agent Integration Contract
 
 Compatibility policy: [docs/json-schema-compatibility.md](docs/json-schema-compatibility.md).
 
+Decision-oriented JSON commands expose a shared top-level contract where the field applies: `schema_version`, `command`, `target`, `target_type`, `decision`, `risk_level`, `confidence`, `recommended_next_action`, `exit_code`, `exit_code_meaning`, `warnings`, `evidence`, `evidence_summary`, `source_freshness`, `policy`, and `errors` for JSON error objects. Existing command-specific fields remain available.
+
+Exit code meanings are stable for agent consumers:
+
+- `0`: allowed or completed successfully.
+- `1`: review or caution required before proceeding.
+- `2`: blocked by policy or risk decision.
+- `3`: tool, configuration, or user input error.
+- `4`: external data unavailable or evidence incomplete.
+
+Decision meanings:
+
+- `allow`: proceed under normal review practices.
+- `allow_with_caution`: proceed only after reviewing warnings and evidence.
+- `review_manually`: ask a human to review before proceeding.
+- `sandbox_only`: use only inside a real sandbox; a Python virtual environment is not a full OS sandbox.
+- `block`: do not install, import, or run unless a human approves a policy exception.
+
+When `--json` is set and a handled user/configuration error occurs, commands emit `pkgwhy.error.v1` with `error_type`, `message`, `exit_code`, `exit_code_meaning`, `suggested_fix`, `command`, `target`, and `target_type` where available.
+
+Batch precheck JSON includes top-level `blocking_targets`, `review_targets`, `allowed_targets`, and `aggregate_recommendation` so automation can see the package-level reason without walking every nested result. Full evidence remains available, and `evidence_summary` gives compact counts, top evidence, top warnings, and top rule IDs for agents that need a smaller decision surface.
+
+The pip gate safety model is unchanged: `pkgwhy pip install` runs precheck before pip and does not invoke pip in dry-run mode, for blocked decisions, or when required evidence is unavailable. It does not sandbox pip or installed package code.
+
+Local registry trust state now affects tool judgement. `blocked` and `quarantined` tools return blocking `tool judge` decisions. `trusted` and `reviewed` are local human labels; they do not override hash mismatch, signature status, manifest approval requirements, or static capability warnings.
+
 Package judgement schema version: `pkgwhy.package_judgement.v1`.
 
 Field shape for `pkgwhy judge <package> --json`:
@@ -457,13 +563,68 @@ Field shape for `pkgwhy tool judge <tool> --json`:
   "hash_status": "verified",
   "signature_status": "not_implemented",
   "warnings": [
-    "Signature verification is not implemented yet.",
-    "Static capability detection for tool bundles is not implemented yet."
+    "Signature verification is not implemented yet."
   ],
   "recommendation": "Review declared permissions and manifest metadata before running this private tool."
 }
 ```
 
+Tool validation schema version: `pkgwhy.tool_validation.v1`.
+
+Field shape for `pkgwhy tool validate ./folder --json`:
+
+```json
+{
+  "schema_version": "pkgwhy.tool_validation.v1",
+  "command": "pkgwhy tool validate",
+  "target": "./folder",
+  "target_type": "tool_folder",
+  "valid": true,
+  "decision": "allow",
+  "risk_level": "low",
+  "confidence": "high",
+  "entrypoint": "main.py",
+  "declared_permissions": [],
+  "detected_capabilities": [],
+  "issues": [],
+  "errors": [],
+  "warnings": [],
+  "policy": {
+    "executes_tool_code": false,
+    "writes_to_registry": false,
+    "symlinks_supported": false
+  }
+}
+```
+
+Tool validation reads local files and manifests, checks path boundaries and entrypoints, and statically analyzes files. It does not publish to a registry and does not execute tool code.
+
+Agent check schema version: `pkgwhy.agent_check.v1`.
+
+Field shape for `pkgwhy agent check <target> --json`:
+
+```json
+{
+  "schema_version": "pkgwhy.agent_check.v1",
+  "command": "pkgwhy agent check",
+  "target": "requirements.txt",
+  "target_type": "requirements",
+  "decision": "block",
+  "risk_level": "high",
+  "confidence": "medium",
+  "recommended_next_action": "conservative next action text",
+  "exit_code": 2,
+  "exit_code_meaning": "blocked by policy or risk decision",
+  "evidence_summary": {},
+  "result_schema_version": "pkgwhy.precheck_batch.v1",
+  "result": {
+    "schema_version": "pkgwhy.precheck_batch.v1"
+  }
+}
+```
+
+`pkgwhy agent check` currently dispatches package specs to package precheck, requirements files and pyproject-style TOML files to batch precheck, and local tool folders/scripts to tool validation.
+
 Supported package and tool decision values are:
 
 - `allow`
@@ -669,6 +830,7 @@ Release and process references:
 - [1.0.0 Feature Surface](docs/release-candidate-surface.md)
 - [Threat Model](docs/threat-model.md)
 - [Production Readiness Blockers](docs/production-readiness.md)
+- [Commercial And Agent Platform Direction](docs/commercial-agent-platform.md)
 
 ## Roadmap
 

{pkgwhy-1.0.0 → pkgwhy-1.6.0}/README.md

@@ -1,16 +1,18 @@
 # pkgwhy
 
+pip install pkgwhy
+
 Know why a package exists before you or your agent trusts it.
 
 `pkgwhy` is an offline-first Python package intelligence, agent policy, and local private-tool CLI. It explains installed packages, inspects local package files without importing them, reports conservative vulnerability, provenance, and static security signals, produces agent-readable JSON judgements, and can publish and run local private Python tools from a local registry.
 
 ## Status
 
-`pkgwhy` 1.0.0 is a Python supply-chain security decision-support tool for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, and the local private-registry and runner MVP.
+`pkgwhy` 1.6.0 is a Python supply-chain security decision-support tool and local pip/CI install gate for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, artifact precheck, guarded pip installs, CI package-gate templates, local registry trust states, local tool validation, agent check dispatching, and the local private-registry and runner MVP.
 
 It is not a production security scanner, not malware-detection certainty, and not a full sandbox. Results are evidence and signals for review, not proof that a package is safe or malicious.
 
-Current packaged version: `1.0.0`.
+Current packaged version: `1.6.0`.
 
 ## What Works Now
 
@@ -22,8 +24,16 @@ pkgwhy explain typer
 pkgwhy why typer
 pkgwhy inspect typer
 pkgwhy judge typer --json
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+pkgwhy precheck annotated-doc==0.0.4 --download-artifacts --json
+pkgwhy pip install typer --dry-run
+pkgwhy pip install -r requirements.txt --dry-run
 pkgwhy agent policy --json
 pkgwhy agent precheck typer --json
+pkgwhy agent check typer --json
 pkgwhy risk typer
 pkgwhy audit --limit 5 --json
 pkgwhy audit --limit 5 --json --vulnerability-file ./osv-fixture.json
@@ -51,6 +61,15 @@ Implemented capabilities include:
 - Metadata-derived provenance/source-trust fields from installed metadata and optional PyPI JSON, with unsupported attestation and trusted-publishing checks marked as unknown or not implemented.
 - Conservative risk level, decision, warning, recommendation, evidence, confidence, risk model version, and rule-ID output.
 - Human `inspect`, `risk`, and `judge` reports that show compact rule-evidence summaries, while JSON reports include structured rule details.
+- Pre-install package precheck for package requirements, requirements files, and `pyproject.toml` dependencies.
+- Explicit artifact-download precheck that downloads a PyPI wheel or source artifact to a temporary review directory, verifies SHA-256 when available, extracts safely, statically inspects files, and deletes temporary files by default.
+- Optional gate exit codes via `pkgwhy precheck --enforce-exit-code`.
+- Guarded pip install flow via `pkgwhy pip install`, with precheck first, stable exit codes, explicit overrides, and compact local decision logs.
+- Reusable GitHub Actions package-gate template with advisory, strict, and agent modes.
+- Local registry trust states for private tools: `trusted`, `reviewed`, `quarantined`, `blocked`, and `unknown`.
+- Local private-tool source validation with `pkgwhy tool validate <path> --json`.
+- Agent check dispatching with `pkgwhy agent check <target> --json` for package specs, dependency files, pyproject-style TOML, and local tool folders/scripts.
+- Commercial and agent platform architecture documentation for future local policy packs, team review, hosted evidence cache, shared organization policy, and agent install gateway.
 - Stable JSON output for agent workflows.
 - Schema-versioned agent policy and package precheck output.
 - Conservative non-interactive agent defaults that block unknown or high-risk package use until a human reviews the evidence.
@@ -64,8 +83,12 @@ pkgwhy registry list
 pkgwhy registry add local-copy ~/.pkgwhy/registry
 pkgwhy registry use local
 pkgwhy publish ./my_tool.py
+pkgwhy registry trust local/my_tool
+pkgwhy registry quarantine local/my_tool
+pkgwhy registry blocked
 pkgwhy tool inspect local/my_tool
 pkgwhy tool judge local/my_tool --json
+pkgwhy tool validate ./my-tool-folder --json
 pkgwhy run local/my_tool
 pkgwhy run local/my_tool --non-interactive
 ```
@@ -85,6 +108,7 @@ Current runner policy is intentionally conservative:
 - Corrupt registry indexes fail closed for publish and tool-judgement paths.
 - Symlinks are not bundled, and stored registry paths must remain inside the registry root.
 - Bundle hash mismatch or a missing bundle blocks execution.
+- Quarantined or blocked registry trust states block execution.
 - `sandbox_only` and `block` tool judgements block execution.
 - Non-interactive execution is blocked unless both the judgement and manifest agent policy allow it.
 - Tools with declared dependencies are not run yet because dependency installation is not implemented.
@@ -98,11 +122,12 @@ These are roadmap items, not current features:
 
 - Complete vulnerability database coverage, transitive vulnerability analysis, or guaranteed advisory freshness.
 - Default online vulnerability lookup. Network access is only used when explicitly requested.
-- Cached PyPI/source lookup beyond the current OSV response cache.
+- Persistent cached PyPI/source lookup beyond the current OSV response cache.
 - Cloud/private remote registry backends.
 - `pull`, mirroring, and remote synchronization.
 - Tool dependency installation in the runner.
 - Tool bundle signing and signature verification.
+- Tool lock/verify commands and registry export/import.
 - Dynamic sandbox analysis for arbitrary packages.
 - Tool-specific `pkgwhy agent judge` expansion beyond the current package precheck path.
 - `pkgwhy agent explain-decision <review-id>`.
@@ -161,15 +186,70 @@ Emit machine-readable judgement JSON:
 pkgwhy judge typer --json
 ```
 
+Before installing a package, run a local precheck:
+
+```bash
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+```
+
+By default, `pkgwhy precheck` uses local installed metadata when available and does not use the network. Add `--pypi` or `--osv` only when you want explicit online enrichment. Add `--download-artifacts` to query PyPI, download one wheel or source artifact, verify its SHA-256 when PyPI metadata provides it, extract it to a temporary review directory, inspect it statically, and delete the temporary files. The command does not install, import, or execute inspected package code.
+
+For CI or install-gate usage, add `--enforce-exit-code`:
+
+```bash
+pkgwhy precheck typer --json --enforce-exit-code
+```
+
+Exit codes are:
+
+- `0`: allow.
+- `1`: allow with caution or manual review.
+- `2`: block or sandbox-only.
+- `4`: requested online/artifact lookup was unavailable or failed.
+
+To gate an install, use `pkgwhy pip install` instead of raw `pip install`:
+
+```bash
+pkgwhy pip install typer
+pkgwhy pip install typer --policy strict
+pkgwhy pip install -r requirements.txt
+pkgwhy pip install typer --dry-run --json
+```
+
+The pip gate always runs precheck first. It invokes pip only when the precheck policy allows the install, or when a human uses an explicit override flag. Review/caution results exit `1`, block/sandbox-only results exit `2`, tool/config errors exit `3`, and unavailable or incomplete requested evidence exits `4`. `--dry-run` evaluates the gate and writes the local decision log without invoking pip.
+
+Overrides are explicit:
+
+```bash
+pkgwhy pip install typer --override-review --override-reason "reviewed local evidence"
+pkgwhy pip install suspicious-name --override-block --override-reason "temporary isolated test"
+```
+
+Agents and automated workflows should use `pkgwhy pip install` when dependency policy is required, not raw `pip install`. The command is still decision support: it does not prove a package is safe and it does not sandbox pip or installed package code.
+
+For CI package gates, start from the reusable GitHub Actions template:
+
+```text
+examples/github-actions/pkgwhy-package-gate.yml
+```
+
+See [CI Templates](docs/ci-templates.md) for advisory, strict, and agent-mode usage. The template does not require secrets or a hosted `pkgwhy` service.
+
 Inspect the default agent policy and run a conservative agent precheck:
 
 ```bash
 pkgwhy agent policy --json
 pkgwhy agent precheck typer --json
 pkgwhy agent judge typer --json
+pkgwhy agent check typer --json
+pkgwhy agent check requirements.txt --json
+pkgwhy agent check ./my-tool-folder --json
 ```
 
-`pkgwhy agent precheck` applies policy to the package judgement. In the default non-interactive mode, unknown and high-risk package decisions are blocked until a human reviews the judgement evidence. The command writes a compact local decision log under the user config directory when that directory is writable and does not install, import, or execute the package.
+`pkgwhy agent precheck` applies policy to the package judgement. In the default non-interactive mode, unknown and high-risk package decisions are blocked until a human reviews the judgement evidence. `pkgwhy agent check` dispatches the target to the safest matching local check and returns one normalized decision envelope. These commands do not install, import, or execute inspected package code. Agent precheck writes a compact local decision log under the user config directory when that directory is writable.
 
 Run a conservative risk report:
 
@@ -278,10 +358,36 @@ Apply the stricter non-interactive runner policy:
 pkgwhy run local/my_tool --non-interactive
 ```
 
-## Agent JSON Contracts
+## Agent Integration Contract
 
 Compatibility policy: [docs/json-schema-compatibility.md](docs/json-schema-compatibility.md).
 
+Decision-oriented JSON commands expose a shared top-level contract where the field applies: `schema_version`, `command`, `target`, `target_type`, `decision`, `risk_level`, `confidence`, `recommended_next_action`, `exit_code`, `exit_code_meaning`, `warnings`, `evidence`, `evidence_summary`, `source_freshness`, `policy`, and `errors` for JSON error objects. Existing command-specific fields remain available.
+
+Exit code meanings are stable for agent consumers:
+
+- `0`: allowed or completed successfully.
+- `1`: review or caution required before proceeding.
+- `2`: blocked by policy or risk decision.
+- `3`: tool, configuration, or user input error.
+- `4`: external data unavailable or evidence incomplete.
+
+Decision meanings:
+
+- `allow`: proceed under normal review practices.
+- `allow_with_caution`: proceed only after reviewing warnings and evidence.
+- `review_manually`: ask a human to review before proceeding.
+- `sandbox_only`: use only inside a real sandbox; a Python virtual environment is not a full OS sandbox.
+- `block`: do not install, import, or run unless a human approves a policy exception.
+
+When `--json` is set and a handled user/configuration error occurs, commands emit `pkgwhy.error.v1` with `error_type`, `message`, `exit_code`, `exit_code_meaning`, `suggested_fix`, `command`, `target`, and `target_type` where available.
+
+Batch precheck JSON includes top-level `blocking_targets`, `review_targets`, `allowed_targets`, and `aggregate_recommendation` so automation can see the package-level reason without walking every nested result. Full evidence remains available, and `evidence_summary` gives compact counts, top evidence, top warnings, and top rule IDs for agents that need a smaller decision surface.
+
+The pip gate safety model is unchanged: `pkgwhy pip install` runs precheck before pip and does not invoke pip in dry-run mode, for blocked decisions, or when required evidence is unavailable. It does not sandbox pip or installed package code.
+
+Local registry trust state now affects tool judgement. `blocked` and `quarantined` tools return blocking `tool judge` decisions. `trusted` and `reviewed` are local human labels; they do not override hash mismatch, signature status, manifest approval requirements, or static capability warnings.
+
 Package judgement schema version: `pkgwhy.package_judgement.v1`.
 
 Field shape for `pkgwhy judge <package> --json`:
@@ -421,13 +527,68 @@ Field shape for `pkgwhy tool judge <tool> --json`:
   "hash_status": "verified",
   "signature_status": "not_implemented",
   "warnings": [
-    "Signature verification is not implemented yet.",
-    "Static capability detection for tool bundles is not implemented yet."
+    "Signature verification is not implemented yet."
   ],
   "recommendation": "Review declared permissions and manifest metadata before running this private tool."
 }
 ```
 
+Tool validation schema version: `pkgwhy.tool_validation.v1`.
+
+Field shape for `pkgwhy tool validate ./folder --json`:
+
+```json
+{
+  "schema_version": "pkgwhy.tool_validation.v1",
+  "command": "pkgwhy tool validate",
+  "target": "./folder",
+  "target_type": "tool_folder",
+  "valid": true,
+  "decision": "allow",
+  "risk_level": "low",
+  "confidence": "high",
+  "entrypoint": "main.py",
+  "declared_permissions": [],
+  "detected_capabilities": [],
+  "issues": [],
+  "errors": [],
+  "warnings": [],
+  "policy": {
+    "executes_tool_code": false,
+    "writes_to_registry": false,
+    "symlinks_supported": false
+  }
+}
+```
+
+Tool validation reads local files and manifests, checks path boundaries and entrypoints, and statically analyzes files. It does not publish to a registry and does not execute tool code.
+
+Agent check schema version: `pkgwhy.agent_check.v1`.
+
+Field shape for `pkgwhy agent check <target> --json`:
+
+```json
+{
+  "schema_version": "pkgwhy.agent_check.v1",
+  "command": "pkgwhy agent check",
+  "target": "requirements.txt",
+  "target_type": "requirements",
+  "decision": "block",
+  "risk_level": "high",
+  "confidence": "medium",
+  "recommended_next_action": "conservative next action text",
+  "exit_code": 2,
+  "exit_code_meaning": "blocked by policy or risk decision",
+  "evidence_summary": {},
+  "result_schema_version": "pkgwhy.precheck_batch.v1",
+  "result": {
+    "schema_version": "pkgwhy.precheck_batch.v1"
+  }
+}
+```
+
+`pkgwhy agent check` currently dispatches package specs to package precheck, requirements files and pyproject-style TOML files to batch precheck, and local tool folders/scripts to tool validation.
+
 Supported package and tool decision values are:
 
 - `allow`
@@ -633,6 +794,7 @@ Release and process references:
 - [1.0.0 Feature Surface](docs/release-candidate-surface.md)
 - [Threat Model](docs/threat-model.md)
 - [Production Readiness Blockers](docs/production-readiness.md)
+- [Commercial And Agent Platform Direction](docs/commercial-agent-platform.md)
 
 ## Roadmap