Security & Guardrails

Running agentic AI tools locally on your development machine presents risks, such as executing destructive shell commands or writing malformed code. KnightCode enforces strict guardrails to give you full control.

Granular Tool Approvals

In BUILD mode (the default), KnightCode only pauses for an approval card on the tool calls that can change your machine or environment:

• Runs automatically — read-only and bookkeeping tools such as Read, Glob, Grep, WebSearch, WebFetch, Skill, the task ledger tools (TaskList, TaskGet, TaskOutput, TaskCreate, TaskUpdate, TaskStop), TodoWrite, and the read actions of Memory (list/get).
• Requires approval — Write, Edit, MultiEdit, NotebookEdit, Bash (unless the command matches the allowlist), Agent (spawning a subagent), Config writes, and the Memory update/delete actions.

In AUTO mode every tool call runs without prompting (the one exception is AskUserQuestion, where the agent explicitly wants your input). In PLAN mode the agent's file-editing and shell tools are removed entirely — Write, Edit, MultiEdit, NotebookEdit, Bash, and Agent (subagent spawning) are not exposed, so the model cannot edit files or run commands. A few non-file tools remain available for planning, including some that can still change state (Config writes and Memory update/delete), so PLAN is not a fully sandboxed read-only mode.

Allowed Commands (/allow)

To cut down on repetitive approvals in BUILD mode, you can allowlist safe shell command prefixes.

• Open the /allow dialog.
• Add command prefixes that do not need confirmation (e.g., git status, bun run lint, npm test).
• A Bash command runs without a prompt when it exactly matches a prefix, or starts with one followed by extra arguments — unless those extra arguments contain shell metacharacters (;, &, |, `, $, (, ), redirects, newlines), which are never auto-allowed.

Lifecycle Hooks (/hooks)

You can set up lifecycle hooks to enforce codebase-specific constraints. Run /hooks to open the Hooks management dialog. Five events are supported:

• PreToolUse: Runs before a tool call. It can block the call (useful for preventing modifications to sensitive folders).
• PostToolUse: Runs after a tool call succeeds. Useful for running formatters (Prettier/ESLint) or tests after edits.
• PostToolUseFailure: Runs after a tool call fails.
• UserPromptSubmit: Runs before your message is sent to the agent. It can block the submission.
• Stop: Runs when the agent finishes responding.

Each hook is a shell command attached to an optional matcher; hook configuration is stored in ~/.knightcode/settings.json.