docs(kickoff): clarify agent permissions live in .claude/settings.json, not config keys#589
Merged
Conversation
…n, not config keys (#730, GH#581) `--skip-permissions` is a per-invocation override of Claude's permission prompts; it is not the configuration knob. Persistent agent permissions live in the worktree's `.claude/settings.json` (`allowedTools` array + Claude Code's `permissions.allow` / `permissions.deny` blocks), which crosslink writes via `init` and preserves across `init --force` merges. Documents the contrast in three places per GH#581: - `docs_src/guides/kickoff.qmd` — new "Configuring agent permissions" subsection at the end of "Controlled agent execution", explaining both levers and when to use each. Links to Claude Code's settings reference for the canonical schema. - `docs_src/guides/container-agents.qmd` — extends the existing `--dangerously-skip-permissions` paragraph with a pointer to the persistent mechanism, cross-linked to the new kickoff section. - `crosslink/src/main.rs` — tightens both `--skip-permissions` clap doc-comments (kickoff `run` and kickoff `plan`) so `--help` surfaces the contrast inline. Verified rendered output via `kickoff run --help`. Pure docs/help-text change — no behavioral surface, no new tests. `cargo fmt --check` clean, `cargo check` clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
GH#581 was filed proposing a new
kickoff.skip_permissionsconfig key. Per the maintainer comment on the issue, that's the wrong lever — agent permissions are already configured via the agent config file (.claude/settings.json), and the gap is documentation, not a missing config knob. This PR closes that gap.Three surfaces updated:
docs_src/guides/kickoff.qmd— new "Configuring agent permissions" subsection at the end of "Controlled agent execution", contrasting the persistent.claude/settings.jsonmechanism (allowedToolsarray + Claude Code'spermissions.allow/permissions.denyblocks, preserved acrossinit --forcemerges) with the per-invocation--skip-permissionsflag, and pointing at Claude Code's settings reference for the canonical schema.docs_src/guides/container-agents.qmd— extends the existing--dangerously-skip-permissionsparagraph with a pointer to the persistent mechanism, cross-linked back to the kickoff guide section.crosslink/src/main.rs— tightens both--skip-permissionsclap doc-comments (kickoffrunand kickoffplan) so--helpitself surfaces the contrast inline.Closes GH#581. Tracked locally as #730.
Test plan
cargo fmt --check— cleancargo check --lib --bin crosslink— cleancrosslink kickoff run --help— verified the new doc-comment renders correctly under--skip-permissions🤖 Generated with Claude Code