Permission modes: saying no in code, not in the prompt

/**
 * PLAN / BUILD / REVIEW / SCAN / FIX mode, tool access levels.
 *
 * PLAN. Read-only operations (read, list, glob, grep).
 * BUILD. Full tool access (write, edit, shell).
 * REVIEW. Read-only + diff (same as PLAN, used for PR review context).
 * SCAN. Read-only + security analysis tools.
 * FIX (read + write (no shell) safe auto-fix mode).
 */

export const Mode = Object.freeze({
  BUILD: 'BUILD',
  PLAN: 'PLAN',
  REVIEW: 'REVIEW',
  SCAN: 'SCAN',
  FIX: 'FIX',
  SWE: 'SWE',
});

export function isReadOnlyTool(toolName) {
  return [
    'readFile', 'listDirectory', 'glob', 'grep', 'codeMap', 'searchWeb',
    'todoRead', 'skill', 'bgCheck', 'teamStatus',
  ].includes(toolName);
}

/**
 * Check if a tool is allowed in the given mode.
 * @param {string} toolName
 * @param {string} mode
 * @returns {boolean}
 */
export function isToolAllowedInMode(toolName, mode) {
  if (mode === Mode.BUILD || mode === Mode.SWE) return true;

  if (mode === Mode.PLAN || mode === Mode.REVIEW || mode === Mode.SCAN) {
    return isReadOnlyTool(toolName) || toolName === 'diffFile';
  }

  if (mode === Mode.FIX) {
    // FIX mode: read + write tools, but no shell
    return toolName !== 'bash' && toolName !== 'runTests';
  }

  return true;
}

async function executeOneTool({ tc, mode, opts, subagentState, editCounts, gateState }) {
  const { onPermissionRequest, allowAll, createStream, model, workdir } = opts;

  // 1. The mode gate. First, because it is the only one the model cannot
  //    influence, and because everything below it assumes the tool may run.
  if (!isToolAllowedInMode(tc.name, mode)) {
    return { output: { error: `Tool ${tc.name} is not available in ${mode} mode` } };
  }

  // 2. Built-in + registered PreToolUse hooks (block before permission UI).
  const builtin = builtinPreToolUseGuard(tc.name, tc.input);
  if (builtin?.block) return { output: { error: builtin.reason } };
  const hookBlock = await runHooks('preToolUse', { toolName: tc.name, input: tc.input, mode });
  if (hookBlock?.block) return { output: { error: hookBlock.reason || `Blocked by hook: ${tc.name}` } };

  // 3. Blast-radius gate: the first write to a migration, a CI workflow, a
  //    lockfile, auth code and friends is refused once, with the
  //    justification and rollback spelled out.
  if (gateState) {
    const radius = checkBlastRadius({ toolName: tc.name, input: tc.input, state: gateState });
    if (radius?.block) return { output: { error: radius.reason, blastRadius: true } };
  }

  // 4. Classify, then ask. Read-only tools never prompt: a dialog per
  //    readFile stalled a live TUI turn for minutes.
  const shellish = tc.name === 'bash' || tc.name === 'runTests' || tc.name === 'bgRun';
  const risk = shellish ? riskLevel(tc.input?.command, workdir) : null;
  let permission = null;
  if (onPermissionRequest && !isReadOnlyTool(tc.name)) {
    permission = await onPermissionRequest(tc.name, tc.id, {
      ...(tc.input || {}),
      __risk: risk ? explainRisk(risk) : undefined,
    });
  }
  if (permission === 'deny') return { output: { error: 'User denied permission' } };

  // 5. Execute.
  return executeLocalTool(tc.name, tc.input);
}

$ sentinel ask "fix the failing auth test"     # read-only by default
Reading src/auth/session.js…
Reading __tests__/auth.test.js…

The test expects the session to expire after 30 minutes of inactivity, but
session.js sets maxAge to 900 seconds and never touches it on activity.

I can fix this by changing the idle-timeout calculation in session.js, but
that requires a write, which PLAN mode does not allow.

Re-run with -b to apply the fix.

// The model sees the refusal as an ordinary tool result and can adapt.
messages.push({ role: 'tool', tool_call_id: tc.id, content: JSON.stringify(result.output) });
// -> { "error": "Tool writeFile is not available in PLAN mode" }

// And with a FIX-mode denial, the message says what to do next:
messages.push({
  role: 'tool',
  tool_call_id: tc.id,
  content: JSON.stringify({
    error: 'Tool bash is not available in FIX mode. You may edit files but not execute commands.',
  }),
});

export function buildSystemPrompt({ mode, dir }) {
  return [
    `# Environment
You are running inside ${dir}. All tool paths are resolved inside that
directory, and reads outside it are refused rather than silently redirected.`,

    `# Mode: ${mode}
${MODE_BRIEFING[mode]}`,

    `# How to work
Prefer reading before writing. When a task is ambiguous, state the
assumption you are making rather than asking, the user sees your plan and
can correct it.`,
  ].join('\n\n');
}

const MODE_BRIEFING = {
  PLAN: 'You can read, search and run read-only commands. You cannot write files or run commands that change state. If the task needs a change, explain what the change would be and stop.',
  FIX: 'You can read and edit files. You cannot run commands, so you cannot run tests to verify a change. Make the smallest correct edit, then say clearly what the user should run to verify it.',
  BUILD: 'You can read, write and run commands. Every write is checkpointed and reversible. Prefer verifying a change by running the test that failed rather than reasoning about whether it would pass.',
};

program
  .command('ask [question...]')
  .option('-b, --build', 'Allow file edits and shell commands (BUILD mode)')
  .option('-y, --yes', 'With --build: auto-approve tools incl. shell')
  .option('--fix', 'Allow file edits but no shell (FIX mode)')
  .action(async (questionParts, options) => {
    // Read-only is the default. Granting access must be deliberate and visible
    // in the command the user typed, not a config file they forgot about.
    const mode = options.build ? 'BUILD' : options.fix ? 'FIX' : 'PLAN';
    ...
  });

import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
import { isToolAllowedInMode, isReadOnlyTool, Mode } from '../src/shared/schemas/mode.js';
import { getToolContracts } from '../src/shared/tools/index.js';

describe('permission modes', () => {
  // Exhaustive by construction: if a tool is added and not listed here, this fails.
  const ALL_TOOLS = Object.keys(getToolContracts(Mode.BUILD));

  test('PLAN allows every read-only tool', () => {
    for (const t of ALL_TOOLS.filter(isReadOnlyTool)) {
      assert.equal(isToolAllowedInMode(t, 'PLAN'), true, `${t} should be allowed in PLAN`);
    }
  });

  test('PLAN refuses every tool that can change state', () => {
    const WRITES = ['writeFile', 'editFile', 'batchEdit', 'applyPatch', 'bash', 'runTests'];
    for (const t of WRITES) {
      assert.equal(isToolAllowedInMode(t, 'PLAN'), false, `${t} must be refused in PLAN`);
    }
  });

  test('FIX grants writes but withholds the shell', () => {
    assert.equal(isToolAllowedInMode('writeFile', 'FIX'), true);
    assert.equal(isToolAllowedInMode('editFile', 'FIX'), true);
    assert.equal(isToolAllowedInMode('bash', 'FIX'), false);
    assert.equal(isToolAllowedInMode('runTests', 'FIX'), false);
  });

  test('the shell is unavailable in every mode except BUILD and SWE', () => {
    for (const mode of ['PLAN', 'REVIEW', 'SCAN', 'FIX']) {
      assert.equal(isToolAllowedInMode('bash', mode), false);
    }
  });

  test('an unknown tool defaults to refused, not allowed', () => {
    // The mode list is not the tool list. A tool nobody classified must not
    // fall through to permission by accident.
    assert.equal(isToolAllowedInMode('someNewToolNobodyClassified', 'PLAN'), false);
  });
});

# read-only: the model may plan, never write
sentinel ask "how would you fix the date parser?"

# writes but no shell: the agent can edit, cannot execute
sentinel ask --fix "fix the typo in src/index.js"

# full access
sentinel ask -b "fix the typo in src/index.js and run the tests"

# the mode gate is a pure function, so you can ask it directly
node -e "
  const { isToolAllowedInMode } = await import('./src/shared/schemas/mode.js');
  for (const m of ['PLAN','FIX','BUILD']) {
    console.log(m.padEnd(6), ['writeFile','bash','grep']
      .map(t => `${t}=${isToolAllowedInMode(t,m) ? 'y' : 'n'}`).join('  '));
  }
"