oacp-cli 0.5.3__tar.gz → 0.5.4__tar.gz

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/.gitattributes

@@ -9,3 +9,6 @@ tests/conformance/signing/messages/** -text
 tests/conformance/signing/messages/tamper_crlf_trailer.yaml whitespace=-trailing-space
 tests/conformance/signing/messages/tamper_trailing_space.yaml whitespace=-trailing-space
 tests/conformance/signing/messages/tamper_trailing_blank_line.yaml whitespace=-blank-at-eof
+
+# Not part of source exports; the sdist excludes it in pyproject.toml.
+tests/dev_only export-ignore

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-10-27
+
+Scripts run under an envelope by sha256 pin only, and the Claude envelope hook judges more shell shapes instead of asking on them or passing them unjudged.
+
+### Added
+
+- Receiver config `envelope.trusted_scripts` pins the scripts the envelope hook may run ([config](docs/protocol/autonomy.md#receiver-config)).
+- `oacp trust pin-script` records a script's pin and re-signs the receiver config ([signing](docs/protocol/message_signing.md#policy-file-signing)).
+- `oacp doctor --project <name>` reports malformed, missing and stale script pins ([config](docs/protocol/autonomy.md#receiver-config)).
+- The envelope hook logs asks and denies to `envelope_decisions.jsonl` ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+
+### Changed
+
+- The envelope hook runs a pinned script and asks on an unpinned one ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- The envelope hook judges an App-token `gh` chain by its final command ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- The envelope hook passes more read-only shell forms as reads ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- The envelope hook stops denying a destructive word in a search pattern ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- The envelope hook allows `--attach-audit` stamps on the task's record ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- `oacp verify --attach-audit` refuses another message's record ([spec](docs/protocol/message_signing.md#receiver-audit-stamping---attach-audit)).
+- The finalizer refuses an uncovered `--realized` grant-only effect ([contract](docs/protocol/autonomy.md#terminal-finalization-and-audit-integrity)).
+- Audit sweeps report the legacy work-clock advisory as one line ([validation](docs/protocol/autonomy.md#terminal-finalization-and-audit-integrity)).
+
+### Fixed
+
+- `oacp trust sign-policy` locks the policy and keeps it whole when a run fails ([signing](docs/protocol/message_signing.md#policy-file-signing)).
+- The envelope hook judges commands nested in shell compound commands ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- The envelope hook asks on a program name built by shell expansion ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+- The envelope hook judges `/usr/bin/env gh …` like `env gh …` ([adapter](docs/protocol/autonomy.md#delivery-static-shim-dynamic-envelope)).
+
 ## [0.5.3] - 2026-10-20
 
 Kernel commands regroup under `agent`, `trust`, and `autonomy`, and the retired memory, packet, and findings surfaces leave the kernel.
@@ -959,6 +988,7 @@ The central debrief store is the headline change: every agent's full end-of-sess
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[0.5.4]: https://github.com/kiloloop/oacp/compare/v0.5.3...v0.5.4
 [0.5.3]: https://github.com/kiloloop/oacp/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/kiloloop/oacp/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/kiloloop/oacp/compare/v0.5.0...v0.5.1

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oacp-cli
-Version: 0.5.3
+Version: 0.5.4
 Summary: Open Agent Coordination Protocol CLI for file-based multi-agent workflows
 Project-URL: Homepage, https://github.com/kiloloop/oacp
 Project-URL: Repository, https://github.com/kiloloop/oacp

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/docs/guides/setup.md

@@ -42,7 +42,8 @@ oacp init <project>
 ```
 
 By default, `oacp init` creates `claude`, `codex`, and `cursor` agents.
-Use `--agents` to include Gemini or custom agent names.
+Use `--agents` to include Gemini or custom agent names, and `--dry-run` to
+preview the plan without writing anything.
 
 Cursor support is scaffold-only until Cursor-owned rules land. Cursor sessions
 must set `OACP_RUNTIME=cursor` or pass `--from` explicitly when sending messages.
@@ -53,12 +54,23 @@ With artifact symlinks from a repo checkout:
 oacp init <project> --repo /path/to/repo
 ```
 
+`workspace.json` is generated in the project workspace directory. Symlink it
+into the repo root so the CLI and runtime hooks discover the workspace from
+inside the repo without `OACP_HOME` set (`oacp init` prints this hint):
+
+```bash
+ln -sf $OACP_HOME/projects/<project>/workspace.json /path/to/repo/.oacp
+```
+
 ## 3) Set up templates (source checkout only)
 
-If you installed from source, copy and customize the templates you need:
+`oacp init` does not create role, guardrail or skills-manifest files, and the
+package does not ship their templates. They are optional project conventions;
+seed them from a source checkout:
 
 ```bash
 # From the oacp repo root:
+mkdir -p $OACP_HOME/projects/<project>/roles $OACP_HOME/projects/<project>/guardrails
 
 # Roles
 cp templates/roles/role_baseline.template.md $OACP_HOME/projects/<project>/roles/baseline.md
@@ -73,15 +85,36 @@ cp templates/skills_manifest.template.yaml $OACP_HOME/projects/<project>/skills_
 
 Edit each file and fill in the `# CUSTOMIZE:` points.
 
-> **Packaged install?** Templates are bundled inside the package. You can find them by running `python3 -c "import oacp; print(oacp.__path__)"` and looking in the `_templates/` directory, or browse them on [GitHub](https://github.com/kiloloop/oacp/tree/main/templates).
+> **Packaged install?** The wheel bundles only the templates the CLI itself
+> uses (inbox message, agent card, agent profile, agent status, receiver config,
+> runtime capabilities, and the Claude role agent) under the package's
+> `_templates/` directory. Browse the rest on
+> [GitHub](https://github.com/kiloloop/oacp/tree/main/templates).
+
+## 4) Runtime setup
+
+`oacp setup <runtime>` generates the runtime's configuration files in the repo.
+Run it from the repo the agent works in; the project is read from the `.oacp`
+marker when `--project` is omitted:
 
-## 4) Claude-specific setup (source checkout only)
+```bash
+oacp setup claude --project <project>
+```
 
-For Claude Code projects, copy templates into the repo's `.claude/` directory:
+For Claude Code this creates `.claude/agents/<project>.md` from the bundled
+role agent template and `.claude/skills/`, and registers the
+`oacp-envelope-hook` PreToolUse hook in `.claude/settings.json`. The agent file
+and skills directory are created only when missing and `settings.json` is
+merged, so re-running after an upgrade is safe. `codex`, `cursor`, and `gemini`
+take the same shape; the [Quick Start](../../QUICKSTART.md#4-connect-your-runtime)
+lists what each writes.
+
+**Source checkout only:** the Claude guardrail rules file is not generated and
+its template is not bundled. Copy it from the repo:
 
 ```bash
 # From the oacp repo root:
-cp templates/claude/agents/role_agent.template.md /path/to/repo/.claude/agents/<role>.md
+mkdir -p /path/to/repo/.claude/rules
 cp templates/claude/rules/guardrail.template.md /path/to/repo/.claude/rules/guardrails.md
 ```
 
@@ -92,9 +125,11 @@ bundles a packet initializer or review, merge-decision and handoff templates.
 See the [migration notes](command-migration.md#packet-and-handoff-templates)
 and [review workflow documentation](../protocol/review_loop.md).
 
-## 6) Update existing workspaces (source checkout only)
+## 6) Update existing workspaces
 
-After pulling new standards, sync your workspace structure:
+`oacp init` refuses an existing workspace (exit 3). After upgrading, bring a
+workspace up to the current directory layout with the idempotent sync script.
+From a source checkout:
 
 ```bash
 make update PROJECT=<project>
@@ -102,12 +137,12 @@ make update PROJECT=<project>
 make update PROJECT=<project> ARGS="--dry-run"
 ```
 
-**Note:** `workspace.json` is generated in the project workspace directory. Runtimes should symlink it into the repo root:
-
-```bash
-ln -sf $OACP_HOME/projects/<project>/workspace.json /path/to/repo/.oacp
-```
+Packaged installs ship the same script as `_scripts/update_workspace.sh` inside
+the installed `oacp` package; run it with `bash <path> <project> [--dry-run]`.
+There is no `oacp` subcommand for it.
 
 ## 7) Wire project-local helpers (optional)
 
-Project-local wrappers can call these scripts using the `OACP_HOME` environment variable (defaults to `$HOME/oacp`).
+Project-local wrappers should resolve the workspace the way the CLI does: an
+explicit `--oacp-dir`, else `OACP_HOME`, else the repo's `.oacp` marker, else
+`$HOME/oacp`.

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/docs/guides/unified_skill_spec.md

@@ -89,7 +89,7 @@ One-line summary.
 
 ## Learned from Runs
 
-- Dated entries capturing bugs and fixes discovered during use
+See [references/learned-from-runs.md](references/learned-from-runs.md).
 ```
 
 ## Conventions
@@ -150,12 +150,20 @@ Safety rules (user confirmation, scope gates, delete-only-after-processing) appl
 
 ### 6. Learned from Runs section
 
-Both runtimes should append to the same `## Learned from Runs` section with dated, tagged entries:
+The SKILL.md body loads on every trigger, so dated run notes do not live in it. Both runtimes record what a run taught in the same way:
 
-```markdown
-- **Feb 14 (claude)**: Haiku subagent can't sleep in sandbox. Use background Bash.
-- **Feb 14 (codex)**: gh auth requires escalated sandbox permissions.
-```
+1. The entry goes to `references/learned-from-runs.md` beside the skill, dated and tagged with the runtime that hit it:
+
+   ```markdown
+   - **Feb 14 (claude)**: subagents can't sleep in the sandbox; wait with a background Bash poll instead.
+   - **Feb 14 (codex)**: gh auth requires escalated sandbox permissions.
+   ```
+
+2. `## Learned from Runs` in SKILL.md keeps a one-line link to that file and nothing else.
+
+3. The lasting rule behind the entry is folded into `## Instructions` (or the relevant `## Runtime Adapters` subsection) as a present-tense statement — "Wait with a background Bash poll; subagents cannot sleep in the sandbox" — so the skill carries the rule without the history. The reference file keeps the dated provenance.
+
+An entry that does not yield a durable rule stays in the reference file only.
 
 ## Migration Path
 

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/docs/protocol/autonomy.md

@@ -39,8 +39,36 @@ autonomy:
     - example-org/private-repo
   continuation_grants:
     enabled: false
+envelope:
+  trusted_scripts:
+    - path: ~/skills/example/scripts/finish_task.sh
+      sha256: <sha256 of the file's bytes>
+      env: [OACP_DONE_TYPE]
 ```
 
+`envelope.trusted_scripts` (optional) pins scripts the receiver's runtime
+adapter may run as `bash <script>` under an active envelope without
+escalating. Each entry names a script by absolute or `~/`-rooted `path`, the
+`sha256` of its bytes, and optionally `env`, the assignment names a caller
+may prefix (`OACP_DONE_TYPE=… bash <script>`); names that retarget a script
+are refused: the script shells' startup files and function or module paths
+(`ENV`, `BASH_ENV`, `ZDOTDIR`, `FPATH`, `MODULE_PATH`, …), loader and
+interpreter paths (`LD_*`, `DYLD_*`, `PYTHON*`, …), the programs a tool execs
+(`PAGER`, `EDITOR`, `*_ASKPASS`, …) and the homes, identities and
+configuration a tool reads (`PATH`, `HOME`, `TMPDIR`, `XDG_*`, `GH_*`,
+`GIT_*`, `OACP_HOME`, …; the compiler's `RETARGETING_ENV_NAMES` and
+`RETARGETING_ENV_PREFIXES` are the list). A pin is the human's review of
+those exact bytes: the compiler carries the list into the envelope, the
+adapter allows the call only while the file still hashes to its pin, and a
+malformed entry fails compilation (`envelope_compile_error`). A literal
+script that carries no pin asks as not registered: the adapter never reads
+an unpinned script's text, so the pin is the one review a script version
+gets, and `oacp trust pin-script <path> --project <p> --agent <r>` records
+it (appending or refreshing the entry) and re-signs the config. The
+admission gate ignores the block; `oacp doctor --project <p>` reports a
+malformed entry, a pinned file that is missing, and a pin whose digest no
+longer matches the file.
+
 When config is absent, receivers behave as `always_pause`. A present config
 that omits the `autonomy` block entirely, such as a signing-only config,
 resolves the same way: `always_pause`, not `config_malformed`. An explicit but
@@ -934,6 +962,15 @@ oacp autonomy finalize <audit.yaml> --final-state done \
   --reply-message-id <msg-id>
 ```
 
+`--realized` names only effects the record's admission covers. A grant-only
+effect — `sends_oacp_reply`, `submits_github_review`,
+`writes_findings_packet` — is refused at call time (exit 2, nothing
+written) unless the scope envelope declares it, an accepted continuation
+grant or a recorded re-authorization scope names it, or an answered
+checkpoint already recorded it realized; the completion reply is recorded
+through `--reply-message-id`. A `--checkpoint` still presents such an
+effect for re-authorization.
+
 Hand-edited terminal blocks are what produced off-enum vocabulary,
 duplicate live evaluations, and terminal records still carrying a paused
 checkpoint action; the finalizer enforces the pinned enums and
@@ -1154,7 +1191,11 @@ reports pinned finding codes (`off_enum_completion_kind`,
 `noncanonical_checkpoint_axis`, `terminal_missing_actuals`,
 `terminal_missing_work_started_at`, `legacy_born_done_unfinalized`), and
 `oacp doctor` sweeps every receiver's audit directory with the same
-checks. Duplicate YAML keys are refused
+checks. A directory sweep (`--sweep`, and doctor) reports the repeated
+legacy `terminal_missing_work_started_at` advisories as one aggregated
+line per code — the records stay byte-preserved and `--json` keeps the
+per-record detail — so advisories of every other code surface
+individually. Duplicate YAML keys are refused
 outright — plain YAML loading silently keeps the later value. The
 fixture set lives in `tests/conformance/autonomy/records/`.
 
@@ -1756,7 +1797,8 @@ The envelope is written to
     "touches_auth_config_or_secrets": false,
     "touches_dependencies": false,
     "public_visibility": false,
-    "private_repo_allowlist": ["example-org/private-repo"]
+    "private_repo_allowlist": ["example-org/private-repo"],
+    "trusted_scripts": []
   },
   "counters": {"files_touched": []},
   "enforcement": "hooks",
@@ -1780,8 +1822,9 @@ Compilation rules:
   reason code `envelope_compile_error` instead of executing unenforced.
 - The compiler reuses the gate evaluator's normalization and pattern
   constants directly, so admission spec and runtime enforcement cannot drift.
-- The receiver-side `private_repo_allowlist` is embedded at compile time;
-  runtime enforcement never trusts sender declarations alone.
+- The receiver-side `private_repo_allowlist` and `envelope.trusted_scripts`
+  pins are embedded at compile time; runtime enforcement never trusts sender
+  declarations alone.
 - Granular side-effect fields absent from a legacy profile compile to
   `false`. `counters` are runtime state and always start empty.
 - **Adapter detection.** `enforcement` is earned, not assumed. The
@@ -1854,7 +1897,15 @@ abbreviations and help flags, while unknown options continue to fail closed.
 Runtime decisions:
 
 - **deny** — the call breaches a declared-false capability (destructive
-  tokens, undeclared commits/pushes/PR mutations, undeclared merges or
+  tokens — except one inside a literal quoted pattern operand of `grep`,
+  `rg`, `awk` or `sed -n` (single quotes, or double quotes carrying no live
+  expansion), directly or under `xargs` / `find -exec`, judged at that
+  operand's own position: data the program matches against its input. The
+  token in command position, in an unquoted word, in a heredoc body, inside
+  a `$(…)` within the quotes, in an awk program with a redirect, pipe,
+  `system`, `getline` or `@` directive, in a sed script outside the
+  print-only grammar, or in any other program's operand still denies —
+  undeclared commits/pushes/PR mutations, undeclared merges or
   issue filing, secret-class or dependency-manifest writes — including
   determinable Bash write targets such as redirects and common writer
   programs), targets a repo outside the embedded allowlist or pinned
@@ -1888,7 +1939,65 @@ Runtime decisions:
   review; unenforceable never silently degrades to allowed. The read-only
   `gh` verbs (`view`, `list`, `status`, `checks`, `diff`, `download`), `gh api`
   GET requests, and the `gh search` group (a read in every subcommand) pass
-  without escalation.
+  without escalation. So do `xargs` and `find -exec`/`-execdir` runs whose
+  nested program is a plain read-only utility (`cat`, `grep`, `hash`, `head`,
+  `jq`, `ls`, `pwd`, `rg` without `--pre`, `stat`, `tail`, `test`, `type`,
+  `wc`, `which`), the lookups `command -v NAME` / `command -V NAME` (they run
+  nothing; any other wrapper flag still asks), and the write-free
+  `oacp autonomy finalize` forms (`--validate`, `--dry-run`); every other
+  `oacp autonomy` invocation edits the task's own audit record and is
+  escalated. Inline Python code (`python3 -c`) is admitted through a
+  positive read-only grammar judged on its syntax tree: every free name a
+  listed builtin or a name the code binds, every import a listed module and
+  member, every attribute of a module alias in that module's member set,
+  every other attribute in the read-only attribute set, every open-like
+  call carrying a literal read mode — behind read-only interpreter options,
+  in a static segment (no `$` or backtick outside single quotes anywhere in
+  it) that redirects to no file. Otherwise the ask names the first construct
+  outside the grammar (a module, an attribute, a mode, an option, a shell
+  expansion inside the code, a redirect, …). `node -e`, `perl -e` and
+  `ruby -e` bodies have no read-only grammar and keep the ask.
+  `oacp verify <message> --attach-audit <record>` passes exactly when the
+  record is the active envelope's own admission record — a `.yaml` directly
+  inside the canonical `audit/autonomy_decisions/` directory whose
+  `message_id`, `receiver` and `message_sha256` match the envelope — and the
+  message file named on the command hashes to that `message_sha256`, in a
+  standalone command with no `OACP_HOME=` override and with selectors that
+  match the envelope; it is the canonical writer of the receiver's own
+  verification stamp (the `--attach-audit` grammar of `message_signing.md`,
+  which refuses other message bytes on its own). Any other record, other
+  message bytes, `--quarantine` or an abbreviation keeps the ask.
+  A literal `bash <script>` (or `sh`, `zsh`, `dash`, `ksh`) is trusted by
+  pin when the shell is named bare or by a path in a system bin directory
+  (`/bin`, `/usr/bin`, `/usr/local/bin`, Homebrew's or MacPorts' `bin`)
+  that resolves inside the system trees: a path pinned in the receiver's
+  `envelope.trusted_scripts` passes with any arguments while the file
+  hashes to its pin, under an env prefix limited to the pin's `env` names;
+  any other literal script asks as not registered under `trusted_scripts`,
+  wherever it lives and whatever it does — the adapter never reads an
+  unpinned script's text, so the pin (the human's review of the bytes,
+  recorded in the signed receiver config) is the one review a script
+  version gets, once, at registration. A shell flag, a `-c` body, a
+  variable path, an executable elsewhere that merely shares a shell's
+  name, or a changed pinned file keeps the ask. A
+  parenthesised subshell group (`( gh pr merge 7 )`), inline or in a script,
+  is judged by the words inside it, and so is the command after shell
+  syntax at a segment's head — a keyword (`if true; then gh pr merge 7;
+  fi`, `! gh …`, `{ gh …; }`), a function header (`f() { gh …; }`), a
+  `case WORD in pattern)` opener, a `coproc` — with the syntax and the
+  wrappers dropped in turns until the head is a program (`time ! git
+  commit` drops `time`, then `!`); a program name the shell
+  would produce by brace expansion, a glob, a variable or a command
+  substitution (`{gh,pr,merge,7}`, `$(echo gh) pr …`) asks, while `[`,
+  `[[` and an arithmetic command head a segment without naming a program;
+  a wrapper spelled by its system path (`/usr/bin/env gh …`) is dropped
+  like the bare wrapper, and a wrapper-named executable elsewhere asks.
+  The App-identity token-minting
+  compound — `T=$(<path>/<token-helper> <app>) && GH_TOKEN="$T" gh …`,
+  every earlier segment such a mint and every join `&&` — is judged as the
+  standalone `gh` command it ends in, under the allow classes and repository
+  gate above; a `;`, a `cd`, any other assignment or helper keeps the
+  compound ask.
 - **allow** — emitted as *no output*: the envelope can only narrow the
   harness's own permission surface, never widen or bypass it.
 - Every emitted **ask** or **deny** reason starts with the stable
@@ -1896,6 +2005,13 @@ Runtime decisions:
   the reason also includes `[task <message-id>]`; operators can therefore
   distinguish an envelope decision from the harness's native permission
   prompt and identify the task that caused it.
+- Every emitted **ask** or **deny** under an active envelope is also
+  appended as one JSON line to
+  `agents/<receiver>/audit/envelope_decisions.jsonl` — `ts`, `message_id`,
+  `session_id`, `tool`, `decision`, `reason` — so a receiver can count the
+  escalations a task cost. The ledger is best-effort instrumentation beside
+  the audit records (never a record itself: sweeps read only `*.yaml`), and
+  a write failure never changes the decision.
 - Compound Bash classification is quote-aware: separators inside quoted
   arguments remain argument data, backslash-newline continuations stay in the
   same segment, and top-level or command-substitution segments are still
@@ -1955,9 +2071,10 @@ Runtime decisions:
   and mutator operands or Bash write targets bearing shell expansion syntax
   escalate to **ask** — the shell expands patterns after classification, so
   a literal spelling proves nothing about the effective target. The
-  canonical audit writers (`oacp autonomy finalize`,
-  `oacp autonomy outcome`, `oacp verify --attach-audit`) reach the record
-  as classified commands that escalate for review, never as file writes.
+  canonical audit writers reach the record as classified commands, never as
+  file writes: `oacp autonomy finalize` and `oacp autonomy outcome` escalate
+  for review, and `oacp verify --attach-audit` passes only against the
+  envelope's own admission record (above).
   The boundary is deliberately scoped to the session the envelope binds: it
   is the *self*-authorization path that must close, and a concurrent
   session is already outside that envelope's reach.

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/docs/protocol/message_signing.md

@@ -214,6 +214,13 @@ inference), so pass the record's canonical runtime path — audit records
 live under `$OACP_HOME`, not the source checkout. The record must already
 exist: write the autonomy decision record first, then stamp it.
 
+The stamp binds to the record's accepted snapshot: when the record carries
+a `message_sha256`, the message file being verified must hash to it, or
+the attach is refused (`attach-audit failed: message bytes do not match the
+audit record's accepted snapshot`, exit 2) and the record is left as it
+was. Verify the bytes the gate admitted, never a re-read of a file that may
+have changed since.
+
 This is the one supported stamping path. It writes the block under the
 shared audit lock, atomically, and refuses to overwrite a recorded block —
 hand-writing a `message_auth` block (or free-text prose about the
@@ -282,6 +289,25 @@ can never authenticate a message.
   verifies them. Unlike messages (append-once, immutable), policy files
   are long-lived and edited: signing strips any existing trailer and signs
   the current content — run it again after every policy edit.
+- **Pin a script** the runtime adapter may run under an envelope:
+
+  ```bash
+  oacp trust pin-script <path> --project <name> --agent <receiver> [--env NAME] [--all-projects]
+  ```
+
+  records the script under the receiver's `envelope.trusted_scripts` — the
+  path as spelled (absolute or `~/`-rooted), the sha256 of the file's bytes
+  and the `--env` names a caller may prefix — appending the entry or
+  refreshing the one that names the same file, validates the block with the
+  envelope compiler's loader, writes `config.yaml` with every other key
+  unchanged, and re-signs it as `sign-policy` would (enrolling the config
+  target). A signed or enrolled config is never written while the
+  receiver's key is unavailable; an unsigned bootstrap config is written
+  unsigned. The pin is the human's review of those bytes: run it once per
+  script version, and again after every edit to a pinned file, or the
+  adapter asks `does not match its pinned sha256` until it is refreshed.
+  `oacp doctor --project <name>` reports a malformed block, a missing file
+  or a stale digest.
 - **Enrollment (downgrade resistance)**: the first successful
   `sign-policy` run enrolls each target in the machine-local registry
   `$OACP_HOME/keys/policy_enrollment.json` (part of the keystore trust
@@ -298,6 +324,17 @@ can never authenticate a message.
   written — a writer never strips an enrolled file's signature as a side
   effect, and a fleet-wide revoke either fully lands signed or leaves
   zero pins changed.
+- **Writers lock, then commit only what verifies**: `sign-policy` and
+  `pin-script` hold a policy file's sibling lock (`<name>.lock`) from
+  their read to their atomic replace, so overlapping runs serialize
+  instead of the later one discarding the earlier, and a signed
+  candidate is verified against the keystore before it replaces the
+  file, so a failed run leaves the previous bytes on disk — an enrolled
+  file is never on disk with a stale signature. An editor that bypasses
+  the lock is refused when the compare before staging or the one at the
+  commit boundary sees its write; that is best-effort detection, not
+  compare-and-swap (a portable replace offers none), so the lock is the
+  contract between writers.
 - **One authorized read path**: consumers load policy files through a
   single loader that reads the file once (bounded at 1 MiB), verifies
   those bytes, and parses the policy from the same snapshot — the bytes

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/oacp/cli.py

@@ -46,6 +46,7 @@ Examples:
   oacp trust keygen --agent claude
   oacp trust import /path/to/<kid>.pub.json --project my-project --agent claude
   oacp trust revoke <kid> --project my-project --agent claude
+  oacp trust pin-script ~/tools/finish.sh --project my-project --agent claude
   oacp autonomy outcome /path/to/audit.yaml --decision approved
   oacp autonomy finalize /path/to/audit.yaml --final-state done --started-at 2026-08-30T10:05:00Z --actual-files-touched 3
   oacp envelope compile /path/to/message.yaml --receiver claude
@@ -86,6 +87,11 @@ COMMAND_GROUPS = {
         "list": ("trust_cli.py", ("list",), "List project catalog entries and receiver pins"),
         "revoke": ("trust_cli.py", ("revoke",), "Revoke a receiver pin"),
         "sign-policy": ("trust_cli.py", ("sign-policy",), "Sign receiver policy files"),
+        "pin-script": (
+            "trust_cli.py",
+            ("pin-script",),
+            "Pin a script under a receiver's envelope.trusted_scripts and re-sign",
+        ),
     },
     "autonomy": {
         "outcome": ("record_autonomy_outcome.py", (), "Record a human approval or decline"),

{oacp_cli-0.5.3 → oacp_cli-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oacp-cli"
-version = "0.5.3"
+version = "0.5.4"
 description = "Open Agent Coordination Protocol CLI for file-based multi-agent workflows"
 readme = "README.md"
 license = "Apache-2.0"
@@ -57,6 +57,7 @@ dev = [
 exclude = [
   "/.claude",
   "/.codex",
+  "/tests/dev_only",
 ]
 
 [tool.hatch.build.targets.wheel]