@archships/dim-plugin-plan-mode

@archships/dim-plugin-plan-mode

Official supported plan-mode plugin for dim-agent-sdk.

Requires @archships/dim-agent-sdk >= 0.0.23 and @archships/dim-plugin-api >= 0.0.9.

What it does

• publishes AgentMode metadata through setup().modes
• injects a planning guardrail into the real system prompt through prompt.resolve
• restricts the visible toolset to read-only inspection tools plus plan_read / plan_write
• denies hidden or fabricated implementation tool calls through tool.beforeExecute
• keeps exec visible, but only allows an allowlisted set of read-only argv inspection commands
• exposes a session-scoped controller through session.getPlugin('plan-mode')
• stores session drafts under <hostDataDir>/plans/<sessionId>/plan.md

Usage

import { createAgent, createModel } from '@archships/dim-agent-sdk'
import { createPlanModePlugin } from '@archships/dim-plugin-plan-mode'

const agent = createAgent({
  model: createModel(adapter),
  hostDataDir: '/tmp/dim-host-data',
  plugins: [createPlanModePlugin()],
})

const session = await agent.createSession({
  metadata: { planMode: true },
})

const planMode = session.getPlugin('plan-mode')
await planMode?.disable()
await planMode?.enable()
await planMode?.clearDraft()

Controller behavior

• getState(): returns { active, pendingActive?, draftPath }
• enable(): enables plan mode for the next run; if no run is in flight, it becomes active immediately
• disable(): disables plan mode for the next run; if no run is in flight, it becomes inactive immediately
• clearDraft(): deletes the current session draft directory under hostDataDir

Options

• activationMetadataKey: defaults to planMode
• extraVisibleTools: extends the default visible toolset with additional read-only tools
• allowedExecPatterns: extends the built-in allow / deny / ask rules for exec

Notes

• the current runtime still does not consume AgentMode directly; the behavior comes from the plugin hooks and session controller
• hostDataDir is required so plan drafts stay outside the workspace
• write, edit, and patch style tools are blocked while plan mode is active
• exec must use argv-style command: string[] input while plan mode is active
• plan_write is the only writable artifact exposed to the model in plan mode
• state changes are next run only for in-flight runs
• deleting the session through agent.deleteSession(sessionId) also deletes the plan draft directory
• run pnpm run demo:plan-mode in the repo for the scripted walkthrough