Skip to content

docs(permissions): clarify project-layer scope and log canonical grant-file path #1474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheGreatAxios merged 3 commits into from
Oct 17, 2026
Merged

docs(permissions): clarify project-layer scope and log canonical grant-file path #1474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b125da5
docs(permissions): clarify project-layer scope and log canonical gran…
TheGreatAxios Oct 17, 2026
95791c2
docs(permissions): match grant-file help and load log
TheGreatAxios Oct 17, 2026
70d0e57
docs(permissions): format the grant-file help row
TheGreatAxios Oct 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions docs/IMPLEMENTATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@ Provider and model configuration lives in JSON settings files. The global file h

- Per-repo: `.corbits/settings.json` — **selection only**, e.g. `{ "provider": "firepass", "model": "fp-small" }`. Any other key (notably `apiKey` or `baseURL`) is rejected by the loader, and the file is gitignored. It is also on the secret-guard denylist for path-keyed tools, as is the global file, so the agent cannot `read_file` its own credentials (shell references still require explicit operator approval). The project grant store (`.corbits/permissions.json`) is on the same denylist so the agent cannot write a standing auto-approval. An unconfirmed project file still contributes no grants.

`corbits exec --permissions <path>` replaces the user-global and provider-model grants for that process only. The file is `{ "approvals": [ { "tool": "run_shell", "pattern": "bun install*" } ] }` (`providerModel` optional). It is not merged with `~/.corbits/permissions.json` and is not a settings key. A missing `approvals` key is an empty replacement; a `providerModels` map in that file is not applied. Session grants stay in memory and project grants still use the project permissions file. While the flag is set, global and provider-model Allow Always append to that file's `approvals` array, and `/permissions` revoke removes the row from it. Neither path reads or writes `~/.corbits/permissions.json`. A missing, unreadable, or invalid file, or a wildcard-only pattern, fails at start.
`corbits exec --permissions <path>` replaces the user-global and provider-model grants for that process only. The file is `{ "approvals": [ { "tool": "run_shell", "pattern": "bun install*" } ] }` (`providerModel` optional). It is not merged with `~/.corbits/permissions.json` and is not a settings key. A missing `approvals` key is an empty replacement; a `providerModels` map in that file is not applied. Session grants stay in memory and project grants still use the project permissions file. While the flag is set, global and provider-model Allow Always append to that file's `approvals` array, and `/permissions` revoke removes the row from it. Neither path reads or writes `~/.corbits/permissions.json`. A missing, unreadable, or invalid file, or a wildcard-only pattern, fails at start. Every load (startup validation, seed, `/permissions` reseed) logs the canonical realpath target and approval count.

`baseURL` is editable provider metadata, but it still belongs in the global provider definition rather than the per-repo selection file. `apiKey` is secret and must never be projected into TUI display-only provider lists.

Expand Down Expand Up @@ -425,27 +425,27 @@ This release changes no settings, OAuth-store, or session persistence format and
Printed by `corbits --help` / `-h` from `CLI_HELP_TEXT` in `src/config/index.ts`
(that constant is the source of truth; keep this table in sync when flags change).

| Verb / Flag | Default | Description |
| ------------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _(no verb)_ | — | Interactive session; optional trailing task text |
| `exec` / `run` / `-p` | — | Run a prompt (non-interactive / one-shot). `-p` is the same path as `exec` and may appear in any flag position. |
| `resume` / `continue` | — | Open the session picker for this folder (project-keyed to this checkout's git toplevel). Lists the 10 most recently persisted sessions, completed included. Type to filter. |
| `--resume [<session-id>]` | — | Interactive: open the session picker, or reopen a specific session when an id is given. With `exec` / `-p` the id is required, that session is continued, and the new prompt is sent (no picker). |
| `resume <session-id>` | — | Reopen a specific session in the TUI (does not auto-send a prompt) |
| `exec --resume <session-id>` | — | Headless: load that session and send `<prompt>`, then exit. Missing or unreadable ids error and do not create a session. `--resume` without an id errors. |
| `-p --resume <session-id>` | — | Same headless continue path as `exec --resume` |
| `resume --pick` / `--list` | — | Interactive session picker |
| `--cwd <dir>` | `process.cwd()` | Working directory |
| `--config <path>` | `~/.corbits/settings.json` | Active settings file for provider definitions and TUI persistence such as `/yolo`; composes with (does not exclude) home-level codex/xai OAuth credentials |
| `--permissions <path>` | — | Process-only grant file. Its `approvals` replace user-global and provider-model grants for this process and are not merged with `~/.corbits/permissions.json`. Missing, unreadable, invalid JSON, or a wildcard-only pattern fails at start. |
| `--provider <name>` | from settings | Select a configured provider |
| `--model <id>` | provider default | Select a model for the active provider |
| `--profile <name>` | — | Settings profile |
| `--dangerously-skip-permissions`, `--yolo` | false | Process-only aliases that auto-allow anything not denied by the authorization layer (gate + pre-gate workspace sandboxes; secret-guard / authz hard denies remain). `/yolo [on\|off\|toggle]` persists to the active settings file instead. |
| `--auto` | true (default) | Force auto mode on (workspace writes + unconstrained shell without prompts) |
| `--no-auto` | false | Start with auto mode off (ask on every consequential action); no in-session key toggles it |
| `--help`, `-h` | — | Show help (exit 0 via `CliHelpError`) |
| `--version`, `-V` | — | Print `corbits v` plus the running `package.json` version (exit 0 via `CliVersionError`) |
| Verb / Flag | Default | Description |
| ------------------------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _(no verb)_ | — | Interactive session; optional trailing task text |
| `exec` / `run` / `-p` | — | Run a prompt (non-interactive / one-shot). `-p` is the same path as `exec` and may appear in any flag position. |
| `resume` / `continue` | — | Open the session picker for this folder (project-keyed to this checkout's git toplevel). Lists the 10 most recently persisted sessions, completed included. Type to filter. |
| `--resume [<session-id>]` | — | Interactive: open the session picker, or reopen a specific session when an id is given. With `exec` / `-p` the id is required, that session is continued, and the new prompt is sent (no picker). |
| `resume <session-id>` | — | Reopen a specific session in the TUI (does not auto-send a prompt) |
| `exec --resume <session-id>` | — | Headless: load that session and send `<prompt>`, then exit. Missing or unreadable ids error and do not create a session. `--resume` without an id errors. |
| `-p --resume <session-id>` | — | Same headless continue path as `exec --resume` |
| `resume --pick` / `--list` | — | Interactive session picker |
| `--cwd <dir>` | `process.cwd()` | Working directory |
| `--config <path>` | `~/.corbits/settings.json` | Active settings file for provider definitions and TUI persistence such as `/yolo`; composes with (does not exclude) home-level codex/xai OAuth credentials |
| `--permissions <path>` | — | Process-only grant file. Its `approvals` replace user-global and provider-model grants for this process and are not merged with `~/.corbits/permissions.json`. Session and project grants still apply; project entries still need trust confirmation. Missing, unreadable, invalid JSON, or a wildcard-only pattern fails at start. |
| `--provider <name>` | from settings | Select a configured provider |
| `--model <id>` | provider default | Select a model for the active provider |
| `--profile <name>` | — | Settings profile |
| `--dangerously-skip-permissions`, `--yolo` | false | Process-only aliases that auto-allow anything not denied by the authorization layer (gate + pre-gate workspace sandboxes; secret-guard / authz hard denies remain). `/yolo [on\|off\|toggle]` persists to the active settings file instead. |
| `--auto` | true (default) | Force auto mode on (workspace writes + unconstrained shell without prompts) |
| `--no-auto` | false | Start with auto mode off (ask on every consequential action); no in-session key toggles it |
| `--help`, `-h` | — | Show help (exit 0 via `CliHelpError`) |
| `--version`, `-V` | — | Print `corbits v` plus the running `package.json` version (exit 0 via `CliVersionError`) |

Positional arguments after flags are joined into the optional initial task delivered when the TUI mounts. With no positional task, the operator starts from an empty prompt.

Expand Down
7 changes: 5 additions & 2 deletions src/config/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -622,7 +622,8 @@ export interface Config {
/**
* Absolute path from `--permissions`. When set, that file's approvals
* replace the user-global and provider-model grant lists for this process
* only. Not a settings key.
* only. Session and project layers still apply, and project-file entries
* still need trust confirmation. Not a settings key.
*/
permissionsPath?: string;
globalDefaultProvider?: string;
Expand Down Expand Up @@ -733,7 +734,9 @@ Continue verbs (project-keyed to this checkout's git toplevel):
Flags:
--cwd <dir> working directory (default: process.cwd())
--config <path> settings file (default: ~/.corbits/settings.json)
--permissions <path> grant file replacing ~/.corbits/permissions.json for this process
--permissions <path> grant file replacing global + provider-model grants
for this process only (session + project layers still
apply; project entries still need trust confirmation)
--provider <name> configured provider name
--model <id> model for the active provider
--profile <name> settings profile
Expand Down
Loading
Loading