Local Agent Tool Definitions

Agent tool definitions live in src/pro/main/ipc/handlers/local_agent/tools/. Each tool has a ToolDefinition with optional flags.

Read-only / plan-only mode

modifiesState: true must be set on any tool that writes to disk or modifies external state (files, database, etc.). This flag controls whether the tool is available in read-only (ask) mode and plan-only mode — see buildAgentToolSet in tool_definitions.ts.
Similarly, code in the handleLocalAgentStream handler that writes to the workspace (e.g., ensureDyadGitignored, injecting synthetic todo reminders) should be guarded with if (!readOnly && !planModeOnly) checks. Injecting instructions that reference state-changing tools into non-writable runs will confuse the model since those tools are filtered out.

Use fs.promises (not sync fs methods) in any code running on the Electron main process (e.g., todo_persistence.ts) to avoid blocking the event loop.

For Local Agent post-tool side effects that happen after the model/tool loop (for example shared Supabase function redeploys), use ctx.onXmlComplete(...) with escaped <dyad-output> content to surface warnings/errors inline. warningMessages creates toast warnings, and throwing turns the whole stream into a ChatErrorBox.
ctx.onXmlComplete only updates the message content column and the UI; it does NOT make output visible to future agent turns. parseAiMessagesJson reads from aiMessagesJson whenever it's present and ignores content entirely. For post-loop output that the agent should see next turn (deploy results, step-limit notices), also push a trailing assistant message into accumulatedAiMessages BEFORE the aiMessagesJson write, e.g.: accumulatedAiMessages.push({ role: "assistant", content: [{ type: "text", text: xml }] }).

requireMcpToolConsent resolves to a structured result, not a bare boolean. If npm run ts reports Argument of type 'boolean' is not assignable to parameter of type 'McpConsentResult', update mocks to return { approved: true/false }.

When changing execute_sql consent metadata or safety checks, audit both Agent mode (shouldAutoApproveAgentTool / executeSqlTool.getConsentMetadata) and Build mode auto-apply (chat_stream_handlers.ts with autoApproveChanges). A SQL safety rule only on the Agent tool path can still be bypassed by Build mode global auto-approve.
SQL destructive-action classifiers that gate auto-approval must be conservative: incomplete/unparseable SQL, opaque dynamic execution (DO/CALL), and executing wrappers such as EXPLAIN ANALYZE should require consent unless the wrapped statement can be proven safe.
Treat prepared-statement execution as opaque for SQL auto-approval too: top-level PREPARE can hide the statement body and top-level EXECUTE runs a previously prepared statement, so both should require consent unless the classifier can prove the executed statement is safe.

When extending handleLocalAgentStream retry behavior, do not only match transport errors like "terminated". Providers can emit structured stream errors such as { type: "error", error: { type: "server_error", ... } }, and those transient 5xx / rate-limit failures need explicit retry classification too.

If a metadata-only tool such as set_chat_summary is added to stopWhen, audit downstream pass gates that inspect the final step's toolCalls. A final metadata tool call should not suppress safety follow-up passes such as incomplete todo reminders.

When changing local-agent prompt text or tool descriptions, update both prompt unit snapshots and E2E request snapshots; stale request snapshots can still contain old tool descriptions even after unit prompt snapshots pass.
Search all e2e-tests/snapshots/ baselines for old tool-description text after regenerating request snapshots. Some request baselines are extensionless files such as local_agent_explore_code.spec.ts_disabled, not just .txt snapshots.
When a local-agent tool is gated by a setting or experiment, keep related user-message hints in sync with the same gate. Request snapshots for the default-disabled path should not advertise or include a tool that buildAgentToolSet filters out.
In testing/fake-llm-server, keep Anthropic local-agent fixture routing in sync with the OpenAI chat-completions route for synthetic continuation messages (incomplete todo(s), persisted unfinished todos, and stream retry prompts). If Anthropic routing misses those markers, multi-pass fixtures fall back to the canned file1.txt response mid-flow.

When deleting old .dyad/media attachment files, also prune attachments-manifest.json entries under the attachments-manifest:${appPath} lock. Read-time filtering hides broken entries but still leaves stale logical names that force unnecessary suffixes like notes-2.txt on future uploads.
When registering .dyad/media files that may already exist (for example repeated @media: mentions), reuse an existing manifest entry for the same storedFileName before allocating a new logical name. Otherwise repeated references create noisy attachments:* aliases like image-2.png, image-3.png.

When adding a required field to AgentContext (in tools/types.ts), grep src/pro/main/ipc/handlers/local_agent/tools/*.spec.ts and update every mock context literal. The TS error appears as e.g. Property 'nitroEnabled' is missing in type ... but required in type 'AgentContext' and surfaces only via npm run ts — npm run lint does not catch it.