docs(skill): document the permission allowlist agmsg needs on Claude Code - #551
Merged
Conversation
…Code Every step runs through the Bash tool, so without an allowlist entry the user confirms essentially every call. Neither the shared SKILL.md nor the Claude Code template said so, leaving each user to work the entries out. Both files change, because they reach different readers: install.sh generates the installed SKILL.md from the per-type template, so guidance added only to the repository SKILL.md never reaches an installed skill. The Claude Code template is the one that gets it — permissions.allow is a Claude Code concept, so the other type templates stay unchanged. Four entries rather than one: a rule matches the command string as written, and these scripts are invoked both as ~/... and as an absolute path, with or without a bash prefix. Also states that a rule does not carry across shell operators, so the scripts must be called one per Bash call. That is the part an allowlist alone does not fix: batching two steps behind ; or && prompts anyway. Fixes #488, reported by Paccho-Kun.
The previous wording read the permission docs backwards. The rule is that each subcommand must match independently, so two allowlisted scripts chained together are both covered; the official safe-cmd && other-cmd example is refused because the second half matches nothing. Written as "batching two agmsg steps prompts anyway", it imposed a one-script-per-call constraint the spec does not support. The report that prompted this documents the real case, and its example says so: the prompt in delivery.sh ... ; printenv AGMSG_SPAWNED comes from printenv, which no agmsg entry covers, not from the separator.
Offering "keep it in its own call, or allowlist it" as alternatives read as if separating the command removed the prompt. It does not — it only stops that prompt from gating the agmsg call. Only allowlisting makes it prompt-free, so the two are a sequence rather than a choice.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the
permissions.allowentries agmsg needs on Claude Code, plus the one rule an allowlist alone does not cover.Fixes #488, reported by @Paccho-Kun — the report arrived with the working entries, the docs citation, and an explicit note about which part the reporter could not verify, which is most of why this is a small change.
Two files, because they reach different readers
install.shgenerates the installedSKILL.mdfrom the per-type template, not from the repository'sSKILL.md. Guidance added only to the repository file would document the fix for people reading the repo while never reaching an installed skill — which is the copy the report is about. So both change: the repositorySKILL.mdfor readers here, andscripts/drivers/types/claude-code/template.mdfor what users actually get.permissions.allowis a Claude Code concept, so the other type templates are left alone.What is documented
The four allowlist entries from the report, with the reason there are four rather than one: a rule matches the command string as written, and these scripts get invoked both as
~/...and as an absolute path, with or without an explicitbashprefix.Then the part that an allowlist does not fix on its own — a prefix rule does not carry across shell operators, so a call that batches two agmsg steps behind
;or&&prompts even with the entries in place. The permission docs are explicit about this, and the report quoted them correctly; verified against the live page while preparing this. The guidance is therefore stated as a rule for the agent to follow — one script per Bash call — rather than left as a caveat for the user to discover.What is deliberately not documented
The report raised a second question and was careful to mark it unverified: whether
"$(pwd)"as the project argument prevents a prefix rule from matching. That is left out rather than guessed at. The published permission docs mention command substitution only for therm -rfcircuit breaker underbypassPermissions, not for prefix-rule matching in general, so there is nothing to cite either way, and asserting a behaviour here that turns out to be wrong would be worse than the current silence. It stays an open question on #488 rather than becoming documentation.Tests
bats tests/test_install.bats tests/test_claude_template.bats— 48/48, exit 0. Docs-only otherwise; no script behaviour changes.