Skip to content
Content
Agent

permission-gate

**Navigation**: [Agents package rules](../AGENTS.md) → **Permission gate**

From plugin
nodetool
63614 skills14 agents

Claude Code

$ npx -y skills add nodetool-ai/nodetool --agent claude-code

Agent definition

permission-gate.md

Permission gate

**Navigation**: [Agents package rules](../AGENTS.md) → **Permission gate**

Paths are relative to `packages/agents/` unless they name another package.

Where the permission gate is set

One ladder decides every actionable call. `decidePermission` (`tools/tool-permissions.ts`) reads a mode and a category, `invokeCapability` (`capabilities/invoke.ts`) runs the sequence around it (read-class fast path, mode decision, session allow-set, approval round trip), and `gateLegacyTools` (`capabilities/legacy-tools.ts`) is the door a `Tool` walks through it. What differs between hosts is who answers when the ladder asks.

A host publishes one `PermissionGateOptions` under `PERMISSION_GATE_CONTEXT_KEY` (`src/types.ts`), and every loop under it reads that object with `gateFromContext` instead of building a gate of its own (invariant I-1). This is the channel `RunBudget` already travels on, for the same reason: `ProcessingContext.copy()` shallow-copies the variable bag, so a child shares the host's gate object rather than a clone, which is what makes a mid-turn `set_permission_mode` and an "allow for this chat" answer reach a loop that started before them. The contract itself — the key, the types, `decidePermission`, `headlessGate` — lives in `@nodetool-ai/runtime` (`permission-gate.ts`) so the workflow hosts below this package can set a gate; this package re-exports the names. Every host sets one, so a context carrying no gate is a bug: `gateFromContext` logs it at error level and answers a gate that lets read-class calls through and denies everything else (mode `default`, approver `deny`). A host that means "nobody to ask" says so with `headlessGate(hostName)`.

| Host | Where its gate comes from | Mode | Approver | |---|---|---|---| | Chat turn (web, Telegram) | `chat-turn.ts` sets `chatGate` on the turn context | the thread's live mode, read through a getter so `set_permission_mode` lands mid-turn | round trip to the client (`requestToolApproval`) | | MCP mount | `mcpSessionGate()` in `mcp-agent-tools.ts` — `headlessGate("MCP")` with `execute_code` seeded into `sessionAllow` — and one session-owned `CapabilityRun`, so direct registrations, namespace imports, and `tools.<name>()` meet the same ladder | `auto`: the client's user connected this agent deliberately, and an MCP session has no approval UI of its own to prompt through | nobody: the headless deny. The one standing approval is `execute_code`, because the client already put that call, code included, in front of its user; an escalation from inside a run (an un-allowlisted Apify actor) has no such answer and is denied | | `run_node` child | `runSingleNode` builds a context of its own, so the turn's gate is passed in as an argument and set on it | the calling turn's, the same object | the calling turn's client | | `AgentNode` in a workflow | `genProcess` wraps what `buildTools` returned in `gateFromContext(context, "Agent node")` | the host's, or `auto` when no host set one | the host's, or the headless deny | | JS script | `js-script-sandbox.ts` passes `gateFromContext(context, "JS script")` to `createCapabilityRun` | same | same | | `nodetool.code.Code` node | `code-node.ts` reads `gateFromContext(context, "Code node")` and uses it for both doors: `createCapabilityRun` for the `@nodetool-ai/sandbox-nodetool/*` imports, `capabilityRunForTools` for the belt the bridge invokes | same | same | | Kernel workflow run | `buildWorkspaceExecutionContext` (`packages/execution/src/service/workflow-workspace.ts`) sets `headlessGate("kernel workflow run")` on the context it builds, and `ExecutionSession.create` sets the same on a caller's own context when that caller set none (see below) | `auto` | nobody: the headless deny | | Headless job runner (trigger-driven runs) | `packages/websocket/src/headless-job-runner.ts` sets `headlessGate("headless job runner")` on the run context | `auto` | nobody: the headless deny | | `nodetool agent run` on a TTY | `createCliPermissionGate` (`packages/cli-chat/src/permission-gate.ts`), host name `nodetool agent run`, set on the run's context | `--permission-mode`, defaulting to `default` | the terminal: `y / n / a` prompted on stderr, because stdout carries the result. `a` answers `allow_for_chat`, and the name lands in the run's shared `sessionAllow` | | `nodetool agent run` with the objective piped in | the same builder, not interactive | `--permission-mode`, defaulting to `auto` | nobody: `headlessGate`'s deny, its reason printed once per run | | `nodetool-chat` reading piped stdin (`runStdinMode`) | the same builder, host name `nodetool-chat`, set on each line's context | `--permission-mode`, defaulting to `auto` | nobody: the headless deny | | `nodetool-chat --url` | no gate is built here | — | the server's chat turn, which gates the belt it runs | | `nodetool-chat` interactive session | **nothing**: the Ink session builds its own belt in `app.tsx`, wraps it in no `gateLegacyTools`, and puts no key on its context | none | nobody |

A CLI run that cannot prompt keeps the mode it was asked for and changes only the approver, so a piped `--permission-mode plan` still blocks what plan mode blocks. The `sessionAllow` Set is created once per run and shared by reference, which is what makes `a` outlive the call that answered it: `nodetool-chat` rebuilds its belt for every input line and consults the same Set. Under `--json` the notice and any prompt ride the event stream rather than stderr, so that stream stays one JSON object per line.

**The interactive CLI session is the host A2 left open.** Its belt is `RunSubtaskTool` plus raw tools, so nothing there meets the ladder. The reason is the terminal, not the design: the Ink session reads stdin itself (`useInput`), so the `readline` prompt every other CLI path uses cannot share it, and an approval there needs an Ink component instead. Rather than accept a mode it would ignore, `packages/cli-chat/src/chat-entry.ts` prints that `--permission-mode` does no

Read more
@nodetool-ai
Ships withnodetool

Open-source AI film studio · agent + node workflows Direct AI films, shot by shot. Start with one sentence. The agent writes the story, draws a still for every shot, and cuts the clips on a timeline.

6361 skill14 agents
Get the whole plugin

Stars on GitHub

Momentum

stars in total
636
Star history of nodetool-ai/nodetool on GitHub, a chart by star-history.com

Other agents on nodetool.

MUTATION_TESTING

MUTATION_TESTING

Agent

The agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…

cli

cli

Agent

**Navigation**: [Agents package rules](../AGENTS.md) → **Running Agents from CLI**

More agents from other plugins.

prompt-manager

prompt-manager

Agent

Agent for managing AI prompts on prompts.chat - search, save, improve, and organize your prompt library.

@gh-f@gh-fInstall Agent
humanize-diagnostician

humanize-diagnostician

Agent

정밀(strict) 모드 1단계 진단 에이전트. 글 전체를 한 번에 보고 "가장 지배적인 AI 티 패턴 3~6개"를 taxonomy ID와 함께 진단한다. 불안정한 span 열거(0↔18개로 요동) 대신 "무엇이 이 글을…

@epoko77-ai@epoko77-aiInstall Agent
blog-cluster-curator
Auto-invoked

blog-cluster-curator

Agent

Topic Clusters curator for the Claude Blog Brain. Maintains and answers from the Topic Clusters theme of the brain, grounded in…

@agricidaniel@agricidanielInstall Agent

Questions about permission-gate.

Which coding agents can use permission-gate?
permission-gate installs in Claude Code and Cursor: each loads subagents from .claude/agents, so copy the file there. Flowy's auto-invocation runs in Claude Code only.