docs: add guarded local agent execution pattern

[jiezeng2004-design]

Summary

Proposes a new security pattern guide: docs/guarded-local-agent-execution.md.

The document describes the "guarded local agent execution pattern" — confining a local coding agent's authority to a narrow, declarative surface instead of exposing a general-purpose shell. It is written to stand on its own and does not depend on any specific executor.

Why

agentseal guard already detects threats in agent configs, MCP descriptions, and skill files. This guide gives operators a concrete confinement pattern to aim for, and shows how AgentSeal's existing mechanisms (.agentseal.yaml allowlists + the custom YAML rule engine) can verify a project follows it.

Changes

• New file: docs/guarded-local-agent-execution.md (275 lines)
  • Five pillars: workspace confinement, exact-match command allowlists, pre-registered agents, sensitive-file blocking, auditable task evidence.
  • Detection-side guidance mapped to AgentSeal concepts (allowed_agents -> GUARD-001, allowed_mcp_servers -> GUARD-002, two example custom rules GUARD-EXEC-001 / GUARD-EXEC-002 with inline tests).
  • A "detector hygiene" section: detectors read policy metadata and evidence file names, never secret file contents. If a policy appears to embed a secret, flag it instead of echoing the value.
  • A pillar-to-detection mapping table and an explicit scope / non-goals section.
  • PatchWarden is mentioned only as one concrete executor instance of the pattern; the pattern itself is implementation-agnostic.

Design notes

• Docs-only change; no code or tests touched.
• The example custom rules use the exact schema the rule engine already validates (id, title, severity, verdict, match.type, tests) per python/agentseal/rules.py.
• No secret values, tokens, or credential contents appear anywhere in the document.

Test Plan

• N/A for CI — markdown only; no Python/JS tests affected.
• Example YAML rule snippets manually checked against the rule schema (severity in critical/high/medium/low, verdict in danger/warning, match.type in mcp/skill/agent).
• (Optional, follow-up) move the example rules into a fixtures YAML and add agentseal guard test coverage in a separate code PR if maintainers want it runnable.

Open questions for maintainers

• Is a top-level docs/ directory acceptable, or should this live elsewhere (e.g., alongside PROBES.md at root, or only on agentseal.org/docs)?
• Would you prefer the two example custom rules shipped as a real rules/guarded-execution.yaml file instead of inline in the doc? Happy to split that into a separate code PR.

Related Issues

None — maintainer feedback on scope and placement is welcome.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.