`exec_shell` tool remains unavailable despite `allow_shell = true` + `trusted = true`

[Dr3259]

Problem Description

I'm using CodeWhale v0.8.49 on Windows. Even after correctly configuring allow_shell = true and trusted = true, the exec_shell tool still cannot be used.

Reproduction Steps

1. Configure in config.toml:

   [workspace.'C:\Users\Rui\Codes\zhenhai']
   allow_shell = true
   trusted = true

2. Save the configuration and fully restart CodeWhale (close the terminal and reopen).

3. Try executing shell commands, e.g.:

   • echo test
   • Remove-Item "somefile.md" -Force

Actual Result

Always shows the following error:

Shell tools are gated by allow_shell; enable allow_shell = true for trusted workspaces, or switch to an auto-approve mode that permits shell access...

Even though the configuration is correct and has been restarted, exec_shell still cannot be invoked.

Expected Result

After configuring allow_shell = true + trusted = true, the exec_shell tool should work normally.

Environment

• CodeWhale version: 0.8.49
• OS: Windows 11
• Workspace path: C:\Users\Rui\Codes\zhenhai
• Config file location: Confirmed that config.toml is loaded correctly

Additional Info

• I tried restarting multiple times, modifying the config path, etc., all to no avail.
• This prevents the Agent from performing common system tasks like file deletion and directory operations, forcing reliance on limited tools like write_file / edit_file.

[Dr3259]

I'm just starting to learn Rust, and I'd like to try fixing this bug myself. What level of proficiency or preparation do I need to reach before you'd be comfortable with me submitting a PR for this?

[buko]

I ran into this exact same bug. There are actually many bugs around the configuration of the shell. They all need to be fixed. If you fix them you you'll certainly save me some time :)

Copy the files below into your workspace to begin you analysis:

---

/shell-too-feature-flag.xhtml:

<title>TASK: Fix shell_tool Feature Flag Bugs</title>

TASK: Fix shell_tool Feature Flag Bugs

<section id="task-summary">
  <header><h2>Task Summary</h2></header>
  <p>The <code>[features] shell_tool</code> configuration key in <code>config.toml</code>
  has multiple defects in how it enables, disables, and propagates the
  <code>exec_shell</code> tool. This task groups the related sub-bugs under a
  single umbrella.</p>
</section>

<section id="sub-bugs">
  <header><h2>Sub-Bugs</h2></header>

  <ol>
    <li id="bug-asymmetric-disable">
      <h3>Asymmetric Disable</h3>
      <p>Setting <code>[features] shell_tool = false</code> gates out
      <code>exec_shell</code> but does <em>not</em> gate
      <code>task_shell_start</code> or <code>task_shell_wait</code>.
      All three shell tools should be gated consistently — either all
      remain available or all are removed.</p>
    </li>

    <li id="bug-stale-system-prompt">
      <h3>Stale System Prompt References</h3>
      <p>When <code>exec_shell</code> is gated out by the feature flag,
      the system prompt (Constitution, Statutes, and tool descriptions)
      still references <code>exec_shell</code> as an available tool.
      The model sees the tool described in its instructions but cannot
      call it, causing confusion and wasted turns attempting to use a
      tool that will fail.</p>
      <p>The system prompt should either omit <code>exec_shell</code>
      references when gated, or include a clear note that the tool is
      disabled.</p>
    </li>

    <li id="bug-broken-re-enable">
      <h3>Broken Re-Enable via true</h3>
      <p>Setting <code>[features] shell_tool = true</code> does
      <em>not</em> re-enable <code>exec_shell</code>. The gate logic
      appears to treat any explicit value (including <code>true</code>)
      as "customized &rarr; disabled." The only way to restore
      <code>exec_shell</code> is to remove the key entirely from
      <code>config.toml</code>.</p>
      <p>Expected behavior: <code>shell_tool = true</code> should
      explicitly enable the tool, <code>shell_tool = false</code>
      should disable it, and omitting the key should use the default
      (enabled).</p>
    </li>

    <li id="bug-documentation">
      <h3>No Documentation of Behavior</h3>
      <p>The <code>shell_tool</code> feature flag is not documented in
      <code>config.example.toml</code> or
      <code>docs/CONFIGURATION.md</code>. Users discovering the key
      have no way to know its valid values, default behavior, or
      side effects without reading the source.</p>
    </li>

    <li id="bug-relation-to-configurable-shell">
      <h3>Overlap with Configurable Shell Task</h3>
      <p>The <a href="../configurable-shell/index.xhtml">Configurable Shell</a>
      task proposes a <code>[shell]</code> config section for specifying
      the shell binary. The relationship between <code>[features]
      shell_tool</code> (enable/disable) and <code>[shell]
      binary</code> (which shell to use) needs to be clarified. If
      <code>shell_tool = false</code> is meant to disable shell tools
      entirely, it must gate all three tools and remove them from the
      prompt. If it's meant to disable auto-detection and defer to
      <code>[shell]</code>, that's a different contract that needs
      explicit design.</p>
    </li>
  </ol>
</section>

<section id="task-requirements">
  <header><h2>Task Requirements</h2></header>
  <ul>
    <li>Push to a branch on the remote fork (<code>buko/CodeWhale</code>). Do NOT push directly to main.</li>
    <li>All three shell tools (<code>exec_shell</code>, <code>task_shell_start</code>,
    <code>task_shell_wait</code>) must be gated consistently by the feature flag.</li>
    <li>The system prompt must be dynamically generated to reflect the actual
    set of available tools — no stale references to gated tools.</li>
    <li><code>shell_tool = true</code> must enable; <code>shell_tool = false</code>
    must disable; omitting the key must use the default (enabled).</li>
    <li>Document the feature flag in <code>config.example.toml</code> and
    <code>docs/CONFIGURATION.md</code>.</li>
  </ul>
</section>

<section id="task-deliverables">
  <header><h2>Task Deliverables</h2></header>
  <ol>
    <li>Fix to the feature-flag gate logic (likely in the tool registration or
    tool dispatch layer).</li>
    <li>Dynamic system prompt generation that omits or annotates gated tools.</li>
    <li>Unit tests for <code>true</code>, <code>false</code>, and omitted states.</li>
    <li>Updated documentation.</li>
  </ol>
</section>

---

---

configurable-shell.xhtml

<title>TASK: Configurable Shell for CodeWhale</title>

TASK: Configurable Shell for CodeWhale

<section id="task-summary">
  <header><h2>Task Summary</h2></header>

  <p>Add a user-configurable shell option to CodeWhale's <code>config.toml</code>
  so that both <code>exec_shell</code> and <code>task_shell_start</code> execute
  commands in the user's preferred shell instead of the auto-detected default.</p>

  <p>On this workspace's Windows system, the default detection lands on
  <code>cmd.exe</code>, which breaks Unix-style commands. The goal is to
  allow users to specify Cygwin bash (or any other shell) in their config,
  so all shell tools use it consistently.</p>
</section>

<section id="the-problem">
  <header><h2>The Problem</h2></header>

  <p>CodeWhale's shell detection in <code>crates/tui/src/shell_dispatcher.rs</code>
  runs an automatic probe at startup: <code>$SHELL</code> &rarr; pwsh &rarr;
  powershell &rarr; cmd.exe &rarr; WSL/Git Bash &rarr; fallback to
  <code>cmd.exe</code>. There is no config key to override this.</p>

  <p>On Windows systems where the user has Cygwin bash installed but not in
  the global <code>PATH</code>, the detection falls through to
  <code>cmd.exe</code>. This means:</p>

  <ul>
    <li><code>exec_shell</code> runs commands via <code>cmd.exe /C</code>,
        breaking <code>mkdir -p</code>, <code>cp -r</code>, <code>rm -rf</code>,
        and other Unix-style commands.</li>
    <li><code>task_shell_start</code> uses the same dispatcher singleton, so
        background shell tasks have the same problem.</li>
    <li>Both tools share the <code>ShellDispatcher::global_dispatcher()</code>
        singleton, so fixing the shell selection for one fixes it for both.</li>
  </ul>
</section>

<section id="task-description">
  <header><h2>Task Description</h2></header>

  <p>Before writing any code, read the research document at
  <a href="research/index.xhtml">research/index.xhtml</a>. It contains a
  detailed analysis of the shell dispatcher architecture, the exact code
  paths involved, and the minimal changes required.</p>

  <section id="requirements">
    <header><h3>Requirements</h3></header>

    <ol>
      <li>Add a <code>[shell]</code> section to <code>config.toml</code> with a
          <code>binary</code> key (the path to the shell executable) and an
          optional <code>flag</code> key (the flag used to pass a command string,
          e.g. <code>-c</code> for bash, <code>/C</code> for cmd.exe).</li>
      <li>Modify <code>ShellDispatcher::detect()</code> in
          <code>crates/tui/src/shell_dispatcher.rs</code> to check the config
          for a <code>[shell]</code> section before running the automatic probe.
          If a valid <code>binary</code> is found, use it with
          <code>ShellKind::Custom { binary, flag }</code>.</li>
      <li>Ensure the <code>Custom</code> variant's quoting and argument-passing
          conventions are correct for the specified shell.</li>
      <li>Preserve the existing automatic detection as a fallback when no
          <code>[shell]</code> config is present.</li>
      <li>Document the new config option in <code>config.example.toml</code>
          and <code>docs/CONFIGURATION.md</code>.</li>
      <li>Re-enable the <code>exec_shell</code> tool (currently disabled in the
          workspace Shell skill). Once the configurable shell is working,
          <code>exec_shell</code> will use the same correct shell via the
          dispatcher singleton.</li>
    </ol>
  </section>

  <section id="example-config">
    <header><h3>Example Config</h3></header>

    <pre><code>[shell]

binary = "C:\data\applications\cygwin64\bin\bash.exe"
flag = "-c"

<section id="task-deliverables">
  <header><h2>Task Deliverables</h2></header>

  <ol>
    <li>Modified <code>crates/tui/src/shell_dispatcher.rs</code> with config-aware
        detection.</li>
    <li>Updated <code>config.example.toml</code> with the <code>[shell]</code> section.</li>
    <li>Updated <code>docs/CONFIGURATION.md</code> with documentation of the new key.</li>
    <li>Unit tests verifying config override works and fallback preserves existing
        behavior.</li>
  </ol>
</section>

---

[Dr3259]

My issue is specifically that the exec_shell tool cannot be invoked at all — this only happens on Windows, and I suspect it works fine on Ubuntu. Could you identify the root cause on your end?

[Hmbown]

Fixed in the v0.8.50 harvest branch #2504.

The branch now includes @cyq1017's #2529 as 7dfec0ed4 / 1d8cbbd40, plus 3d5edfee8 for legacy [projects] coverage and a docs note about project-overlay precedence. This makes matching user-owned [workspace.'...'] / legacy [projects.'...'] allow_shell = true entries apply during both interactive startup and engine-backed exec, while preserving env and managed-config precedence.

Verified locally with:

• cargo test -p codewhale-tui --all-features --locked user_workspace_overlay -- --nocapture
• cargo clippy -p codewhale-tui --all-targets --all-features --locked -- -D warnings
• ./scripts/release/check-versions.sh

Live #2504 CI is green across Ubuntu, macOS, Windows, lint, version drift, CodeQL, mobile smoke, npm smoke, and GitGuardian. Thanks @Dr3259 for the report and @cyq1017 for the focused fix. This should close automatically when #2504 merges.