02. Tools and Permission Layers

Tool.ts as the Contract Layer

Tool.ts shows that tools are not ad hoc functions. They run inside a typed execution context with permission mode, working directories, app state hooks, notifications, tool JSX, MCP clients, model settings, and budget metadata. That means the tool system is a platform, not just a list of helpers.

tools.ts as the Capability Switchboard

tools.ts registers the concrete tool inventory: file tools, Bash, web, MCP, agents, tasks, planning, config, notebooks, search, and optional experimental tools. It also shows conditional inclusion for feature flags and internal-only variants.

BashTool Is the Best Safety Case Study

The Bash tool does not live in one file. It is split across many focused modules:

• BashTool.tsx: tool execution and UI glue
• bashSecurity.ts: command-level safety decisions
• bashPermissions.ts: permission integration
• pathValidation.ts: working-directory and path guardrails
• readOnlyValidation.ts: block write-like behavior in read-only contexts
• modeValidation.ts: mode-dependent execution rules
• sedValidation.ts and sedEditParser.ts: special handling for edit-like shell patterns
• destructiveCommandWarning.ts: user-facing risk escalation
• shouldUseSandbox.ts: sandbox decision logic

Why This Matters

A weak agent product exposes a raw shell. A serious one treats shell access as a policy problem. This source tree shows an architectural lesson: dangerous tooling should be decomposed into semantics, validation, permissions, path scope, and UX.

What To Learn Here

• How to wrap local execution in a structured contract.
• How to represent permission context as data rather than scattered conditionals.
• How to make one dangerous tool understandable by splitting risk areas into separate modules.
• How to keep the UI involved in permissioning instead of letting the model operate invisibly.