Improve instructions and security

AGENTS.md

@@ -6,12 +6,12 @@ Package manager: **Bun** (`bun.lock`). Verify with `bun run check` (typecheck +
 
 ## Permission boundaries
 
-| Mode             | Scope                                                                                                                                                                                                 |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| READ             | Whole repo; method details in `skills/agent-memory/vendor/memory/instructions.md`                                                                                                                     |
-| WRITE            | `skills/agent-memory/`, `hooks/`, `install.ts`, `lib/cli/`, `tests/`, `bin/cli.js` (via `bun run build`), root docs (`README.md`, `CHANGELOG.md`, this file), `package.json` / `bun.lock` when asked  |
-| NEVER            | Invent a repo-root `agent-memory/` path for writes; push; create git tags or npm publish unless the user explicitly asks; install hooks into a consumer project from this agent (print commands only) |
-| HUMAN_CHECKPOINT | Version bump; release tag; npm publish; any change that rewrites consumer memory Markdown outside this meta-repo                                                                                      |
+| Mode             | Scope |
+| ---------------- | ----- |
+| READ             | Whole repo; method details in `skills/agent-memory/vendor/memory/instructions.md` |
+| WRITE            | `skills/agent-memory/`, `hooks/`, `install.ts`, `lib/cli/`, `tests/`, `bin/cli.js` (via `bun run build`), root docs (`README.md`, `CHANGELOG.md`, `SECURITY.md`, this file), `package.json` / `bun.lock` when asked |
+| NEVER            | Invent a repo-root `agent-memory/` path for writes; push; create git tags or npm publish unless the user explicitly asks; install hooks into a consumer project from this agent (print commands only); add `shell: true` on child processes; forward full `process.env` to hook children; write Markdown from hooks |
+| HUMAN_CHECKPOINT | Version bump; release tag; npm publish; any change that rewrites consumer memory Markdown outside this meta-repo |
 
 ## Precedence
 
@@ -29,6 +29,7 @@ If blocked (missing permission, ambiguous SemVer, conflict between docs and code
 - Agent-memory block: `skills/agent-memory/references/agent-block.md`
 - Installed memory shape: `skills/agent-memory/vendor/memory/`
 - Harness parity (hooks vs agent): `skills/agent-memory/vendor/memory/instructions.md` → _Harness parity — memory contract_
+- Trust boundary / intentional capabilities (CLI + hooks): `SECURITY.md`
 - Migrations: `skills/agent-memory/vendor/UPDATE.md`
 - Release history: `CHANGELOG.md` ([Keep a Changelog][kac], [SemVer][semver])
 - Package / skill / hooks version: `package.json` `version` → mirror `skills/agent-memory/SKILL.md` → `metadata.version`
@@ -37,7 +38,8 @@ If blocked (missing permission, ambiguous SemVer, conflict between docs and code
 ## Conventions
 
 - **Skill boundary** — `/agent-memory` is manual-only (`disable-model-invocation: true`). Never auto-trigger it. Follow `SKILL.md` + `references/<command>.md`. The skill **never** installs hooks (print instructions only).
-- **Hooks** — under `hooks/` (not inside the skill). Shared scripts in `hooks/agent-memory-hooks/`; per-host config in `hooks/<harness>/`. User installs via `hooks/install-hooks.sh` or `npx` CLI. Deterministic checkpoint: ephemeral evidence in `.hook-sync-state` only — **no Markdown writes**, no LLM loops (`followup_message` on Cursor `stop` unused). Upgrade notes: [Known issues](#known-issues).
+- **Hooks** — under `hooks/` (not inside the skill). Shared scripts in `hooks/agent-memory-hooks/`; per-host config in `hooks/<harness>/`. User installs via `hooks/install-hooks.sh` or `npx` CLI. Deterministic checkpoint: ephemeral evidence in `.hook-sync-state` only — **no Markdown writes**, no LLM loops (`followup_message` on Cursor `stop` unused). Trust model and audit path: `SECURITY.md`. Upgrade notes: [Known issues](#known-issues).
+- **Security (CLI / OpenCode spawn)** — details in `SECURITY.md`. Keep `ENV_ALLOWLIST_EXACT` aligned (`lib/cli/constants.ts` ↔ `hooks/opencode/agent-memory.ts`). OpenCode spawn must go through `hooks/opencode/safe-script.ts` before `execFileSync`. Do not add `--minify` to `bun run build` (auditability; `bun run build:check`). Closure for spawn/security edits: `bun run test` (includes `tests/opencode-safe-script.test.ts`).
 - **Markdown** — normal paragraphs (no hard-wrap for line length); `.markdownlint.json` (MD013 off).
 - **Content language** — English in repo docs and commits.
 

CHANGELOG.md

@@ -8,6 +8,16 @@ Migration details for `/agent-memory update` live in [`skills/agent-memory/vendo
 
 ## [Unreleased]
 
+### Security
+
+- OpenCode plugin: refuse symlink hook scripts, confine resolved paths under `.opencode/hooks`, and validate session/conversation binding IDs before env/stdin.
+- Document trust boundary and intentional capabilities in `SECURITY.md`.
+
+### Changed
+
+- `instructions.md` slimmed for always-load: permission boundaries, numbered precedence, task-organized sections, observable turn closure, and formats linked to templates (`TEMPLATE.md`, `log.md`, `decisions.md`) instead of duplicated inventories.
+- CLI build publishes `bin/cli.js` without minify for supply-chain auditability.
+
 ## [0.1.0] - 2026-07-27
 
 ### Breaking

README.md

@@ -127,4 +127,6 @@ agent-memory/
 
 MIT. See [LICENSE](./LICENSE).
 
+Security and trust model: [SECURITY.md](./SECURITY.md).
+
 [llm-wiki]: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

SECURITY.md

@@ -0,0 +1,47 @@
+# Security
+
+This document explains intentional capabilities in `@dosx/agent-memory`, the trust boundary for hooks, and how to audit the published package.
+
+## Intentional capabilities
+
+The CLI and OpenCode plugin use Node.js APIs that security scanners often flag:
+
+| Capability                                 | Where                                                    | Why                                                                                                                                                                                             |
+| ------------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem** (`node:fs`)                 | `install.ts`, `lib/cli/`, `hooks/opencode/`              | Install the skill and hooks; check for `.agents/memory` and hook scripts under the project.                                                                                                     |
+| **Child processes** (`node:child_process`) | `lib/cli/hooks-run.ts`, `hooks/opencode/agent-memory.ts` | Run the hook installer (`install-hooks.sh`) and shared sync scripts. Always **argv form** — `spawnSync` / `execFileSync` with `shell: false` (no shell metachar parsing).                       |
+| **Environment variables**                  | CLI + OpenCode plugin                                    | Forward an **allowlisted** subset of the parent env to hook children (`ENV_ALLOWLIST_EXACT` in `lib/cli/constants.ts`); set `AGENT_MEMORY_*` for project dir, host, event, and session binding. |
+
+Hooks write only gitignored `.agents/memory/.hook-sync-state` (ephemeral evidence). They **never** edit Markdown under `.agents/memory/`.
+
+## Trust boundary
+
+Installing agent-memory hooks is equivalent to trusting the project directory — the same model as **git hooks**:
+
+- Hook scripts are copied into harness paths (e.g. `.cursor/hooks/`, `.opencode/hooks/`) under the consumer project.
+- Cursor, Claude Code, Codex, Copilot, Gemini, and OpenCode all run those local scripts on lifecycle events.
+- Anyone who can modify hook scripts or the project working directory already has local code execution in that project.
+
+The OpenCode plugin spawns the same shared bash sync script as other harnesses; it adds runtime checks (regular file only, `realpath` confinement under `.opencode/hooks`, binding ID charset validation) before `execFileSync`.
+
+## What we do not do
+
+- No network calls from the CLI or hook scripts.
+- No `shell: true` on child processes.
+- No full parent `process.env` forwarded to hook children.
+- No Markdown writes from hooks (semantic memory is agent-owned only).
+
+## How to audit
+
+1. **CLI source** — `install.ts` and `lib/cli/` (TypeScript).
+2. **Published CLI** — `bin/cli.js` is a Bun bundle (CJS, **not minified**) generated by `bun run build`; verify with `bun run build:check`.
+3. **Hook scripts** — `hooks/agent-memory-hooks/*.sh` and `hooks/install-hooks.sh`.
+4. **OpenCode plugin** — `hooks/opencode/agent-memory.ts` and `hooks/opencode/safe-script.ts`.
+5. **Tests** — `bun run test` includes security fixtures (`tests/opencode-safe-script.test.ts`, symlink refusal in `tests/hooks-checkpoint.sh`).
+
+Report vulnerabilities via GitHub issues on the repository. Do not open public issues for undisclosed critical findings without coordination.
+
+## See also
+
+- [hooks/README.md](./hooks/README.md) — hook install and events
+- [CHANGELOG.md](./CHANGELOG.md) — security-related release notes