Modes & permissions

After workspace trust, use Auto for direct local work or Strict to review edits and commands. Read the actual action and scope before approving; /grants shows remembered decisions. Workspace trust explains the authority you grant at launch.

The two modes

Mode	Behavior
auto	Default. Ordinary edits, shell/code, and bounded first-party publication run with local authority. Protected file writes and MCP retain review.
strict	Reads/search run; edits and non-read-only shell ask. Arbitrary code asks.

Neither mode creates an OS sandbox. Change the active mode with ++shift+tab++, bare /mode, or /mode auto|strict. Mode is human-owned; the model cannot change it.

Legacy names resolve with a deprecation note: default → strict, accept-edits → auto, plan → strict. Planning itself is a separate freeze.

Tools × decisions

Allow runs, Ask requests review, and Deny returns a refusal. Strict shell’s classifier chooses Allow only for a narrow recognized read; uncertainty asks.

Kind	Examples	Auto	Strict
Read	Files, search, web retrieval	Allow	Allow
Meta	Todos, questions, skills, agent dispatch	Allow	Allow
Edit	File writes, local Git mutations	Allow	Ask
Shell	Shell and code	Allow	Classify shell; code asks
MCP	Mutating external tools	Ask	Ask
Network	Structured Git fetch/sync and PR reads	Allow	Ask
Publish	Normal push and PR open	Allow	Ask

Specific gates still apply. Protected file-tool writes ask in Auto. Force-with-lease always needs fresh review and cannot reuse a grant. Trusted read-only MCP definitions are adapted to Read; applicable explicit grants can cover other MCP tools. Git credential-route trust is separate from operation approval. The conceptual guide explains the chain.

The shell allowlist

Strict’s conservative classifier recognizes simple reads and supported safe flags. Substitution, redirection, leading assignments, and ambiguous commands ask. run_code always asks in Strict. KIN_SHELL_ALLOWLIST=0 disables the classifier and reviews every shell call. Auto executes directly; the classifier is a review convenience, not containment.

Tri-state approvals

Choice	Effect
Allow once (a)	Approve this call.
Session (s)	Approve the displayed reusable scope for this session.
Deny (d / Escape)	Refuse; Kin receives the refusal.
Deny with a note (n)	Refuse with guidance such as “use pnpm instead.”

Escape first closes a denial-note input, then denies on a second press. Fresh-state actions can omit Session. Eligible MCP calls also offer MCP server (m, legacy v), covering the reviewed initial unchanged tool surface across launches while its identity remains valid.

The modal shows the command, arguments, or complete bounded edit diff. Kin freezes the call and review evidence; invisible control characters are shown as escapes. If a reviewed file changes before execution, the write fails stale and needs a new read/review. Diffs come from the executing session’s workdir.

Session scopes differ by tool:

• A simple safe-shaped shell invocation can share a command-head scope; compound commands bind their exact string.
• Git/GitHub binds repository, operation, remote, branch, and applicable PR base.
• Ordinary tools can bind the tool name. For file-edit tools that may cover later edits broadly; the modal advises preferring Once.

A reusable grant only relaxes Ask, never Deny. It cannot lift planning or create workspace trust. Credential and server trust retain their own checks.

Cycling modes

++shift+tab++ and bare /mode toggle Auto/Strict; /mode NAME selects one. During planning, use the plan controls below. A mode toggle cannot bypass the freeze.

Planning

Planning denies edits, shell, MCP, network/publication, and named configuration or fresh-workspace handoffs, including in children. Reads/search/todos and plan authoring remain available. Plan mode is yours: you enter it and only you leave it.

/plan TASK enters planning and sends the task. Bare /plan toggles it. When Kin thinks a task needs design agreement before any change, it asks to enter plan mode with a one-sentence reason and you approve or decline; if you decline, it carries on with the work. Kin’s default is to do the work, and writing a plan never enters the freeze by itself. The main agent presents the saved plan for review.

Review action	Effect
Approve & execute	Lift the freeze with current context.
Approve, clear & re-inject	Execute from the self-contained plan without exploratory history.
Review plan first (adversarial)	Obtain a read-only critique; stay frozen while making bounded plan revisions.

Escape keeps planning. Plans survive under <workdir>/.kin/plans/. The transient freeze is not persisted; a resumed mid-plan session uses Strict. See Agents for planner/critic roles.

Model-writable settings

/config starts visible guided configuration. read_settings shows redacted values; propose_settings offers a fresh reviewed diff for only these keys: temperature, top_p, top_k, max_tokens, context_window, enable_thinking, effort, thinking_type, cache_ttl, and model. Proposals affect new-session settings, not an unannounced live backend change.

Every other key is human-only until source explicitly adds it. Proposals cannot change credentials, endpoints, routes, workspace trust, mode, or grants; they are root-only and denied during planning. Use dedicated controls for those families. The settings reference owns validation and scope.

Troubleshooting

• A grant did not apply: compare its displayed scope with this call. Changed targets or server/credential identity require review; fresh-state operations and arbitrary run_code cannot reuse approval.
• An Auto edit asks: check protected paths such as lockfiles or Kin config.
• Mode will not change: planning requires its own review/toggle action; dismissing the review keeps the freeze.
• A read command asks: uncertainty stays Ask. Approve the exact operation rather than broadening policy just to suppress a prompt.

Managing grants

/grants lists workspace trust, tool approvals, related-directory scopes, MCP trust, and Git-host routes. Select a row, press r, then y; moving the selection cancels that confirmation. /grants revoke <number|key> revokes directly.

Stale, replaced, noncanonical, and invalid workspace rows stay visible but grant nothing. Removing persistent trust makes the next matching launch/connection ask again. Legacy sandbox rows remain inert and cannot become workspace trust.