Add isolated Code Mode and reliable terminal execution

.gitattributes

@@ -0,0 +1 @@
+third_party/quickjs/** -whitespace

.github/workflows/ci.yml

@@ -323,6 +323,11 @@ jobs:
           mib=$(awk -v b="$bytes" 'BEGIN { printf "%.2f", b / 1048576 }')
           echo "${{ matrix.name }}: $bytes bytes ($mib MiB)"
           echo "${{ matrix.name }}: $bytes bytes ($mib MiB)" >> "$GITHUB_STEP_SUMMARY"
+          helper_bytes=$(stat -c%s zig-out/bin/fx-code-host)
+          helper_mib=$(awk -v b="$helper_bytes" 'BEGIN { printf "%.3f", b / 1048576 }')
+          echo "${{ matrix.name }} code host: $helper_bytes bytes ($helper_mib MiB)"
+          echo "${{ matrix.name }} code host: $helper_bytes bytes ($helper_mib MiB)" >> "$GITHUB_STEP_SUMMARY"
+          test "$helper_bytes" -le 1703936
 
   lint-scripts:
     name: Shellcheck

.github/workflows/dev-release.yml

@@ -50,8 +50,8 @@ jobs:
         run: |
           package_dir="$RUNNER_TEMP/fx-package-${{ matrix.name }}"
           mkdir -p "$package_dir"
-          cp zig-out/bin/fx LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
-          tar -czf fx-${{ matrix.name }}.tar.gz -C "$package_dir" fx LICENSE THIRD_PARTY_NOTICES.md
+          cp zig-out/bin/fx zig-out/bin/fx-code-host LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
+          tar -czf fx-${{ matrix.name }}.tar.gz -C "$package_dir" fx fx-code-host LICENSE THIRD_PARTY_NOTICES.md
           sha256sum fx-${{ matrix.name }}.tar.gz > fx-${{ matrix.name }}.tar.gz.sha256
 
       - name: Upload artifact

.github/workflows/release.yml

@@ -69,8 +69,8 @@ jobs:
         run: |
           package_dir="$RUNNER_TEMP/fx-package-${{ matrix.name }}"
           mkdir -p "$package_dir"
-          cp zig-out/bin/fx LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
-          tar -czf fx-${{ matrix.name }}.tar.gz -C "$package_dir" fx LICENSE THIRD_PARTY_NOTICES.md
+          cp zig-out/bin/fx zig-out/bin/fx-code-host LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
+          tar -czf fx-${{ matrix.name }}.tar.gz -C "$package_dir" fx fx-code-host LICENSE THIRD_PARTY_NOTICES.md
           sha256sum fx-${{ matrix.name }}.tar.gz > fx-${{ matrix.name }}.tar.gz.sha256
 
       - name: Upload artifact
@@ -105,14 +105,16 @@ jobs:
           APPLE_NOTARY_KEY_P8_BASE64: ${{ secrets.APPLE_NOTARY_KEY_P8_BASE64 }}
           APPLE_NOTARY_KEY_ID: ${{ secrets.APPLE_NOTARY_KEY_ID }}
           APPLE_NOTARY_ISSUER_ID: ${{ secrets.APPLE_NOTARY_ISSUER_ID }}
-        run: scripts/sign-and-notarize-macos.sh zig-out/bin/fx
+        run: |
+          scripts/sign-and-notarize-macos.sh zig-out/bin/fx
+          FX_SIGNING_IDENTIFIER=com.vercel.fx.code-host scripts/sign-and-notarize-macos.sh zig-out/bin/fx-code-host
 
       - name: Package
         run: |
           package_dir="$RUNNER_TEMP/fx-package-macos-x86_64"
           mkdir -p "$package_dir"
-          cp zig-out/bin/fx LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
-          tar -czf fx-macos-x86_64.tar.gz -C "$package_dir" fx LICENSE THIRD_PARTY_NOTICES.md
+          cp zig-out/bin/fx zig-out/bin/fx-code-host LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
+          tar -czf fx-macos-x86_64.tar.gz -C "$package_dir" fx fx-code-host LICENSE THIRD_PARTY_NOTICES.md
           shasum -a 256 fx-macos-x86_64.tar.gz > fx-macos-x86_64.tar.gz.sha256
 
       - name: Upload artifact
@@ -147,6 +149,14 @@ jobs:
       - name: Require native arm64 host
         run: test "$(uname -m)" = arm64
 
+      - name: Setup Zig
+        uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2
+        with:
+          version: "0.16.0"
+
+      - name: Build code host
+        run: zig build code-host -Doptimize=ReleaseSafe -Dtarget=aarch64-macos
+
       - name: Download eligible candidate
         uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
@@ -166,15 +176,17 @@ jobs:
           APPLE_NOTARY_KEY_P8_BASE64: ${{ secrets.APPLE_NOTARY_KEY_P8_BASE64 }}
           APPLE_NOTARY_KEY_ID: ${{ secrets.APPLE_NOTARY_KEY_ID }}
           APPLE_NOTARY_ISSUER_ID: ${{ secrets.APPLE_NOTARY_ISSUER_ID }}
-        run: scripts/sign-and-notarize-macos.sh "$RUNNER_TEMP/fx-pgso-aggregate/candidate/fx"
+        run: |
+          scripts/sign-and-notarize-macos.sh "$RUNNER_TEMP/fx-pgso-aggregate/candidate/fx"
+          FX_SIGNING_IDENTIFIER=com.vercel.fx.code-host scripts/sign-and-notarize-macos.sh zig-out/bin/fx-code-host
 
       - name: Package stable release candidate
         run: |
           archive="$RUNNER_TEMP/fx-macos-aarch64.tar.gz"
           package_dir="$RUNNER_TEMP/fx-release-package"
           mkdir -p "$package_dir"
-          cp "$RUNNER_TEMP/fx-pgso-aggregate/candidate/fx" LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
-          tar -czf "$archive" -C "$package_dir" fx LICENSE THIRD_PARTY_NOTICES.md
+          cp "$RUNNER_TEMP/fx-pgso-aggregate/candidate/fx" zig-out/bin/fx-code-host LICENSE THIRD_PARTY_NOTICES.md "$package_dir/"
+          tar -czf "$archive" -C "$package_dir" fx fx-code-host LICENSE THIRD_PARTY_NOTICES.md
           cd "$RUNNER_TEMP"
           shasum -a 256 fx-macos-aarch64.tar.gz > fx-macos-aarch64.tar.gz.sha256
 

CONTRIBUTING.md

@@ -35,6 +35,10 @@ zig build test
 zig build run
 ```
 
+Native builds install both `zig-out/bin/fx` and the isolated
+`zig-out/bin/fx-code-host` companion. The main binary does not load or spawn
+the companion unless the model selects the `code` tool.
+
 ## Verification Workflow
 
 Keep the local development loop focused: run the narrowest test that covers the changed path, build fx, and exercise the change using `./zig-out/bin/fx`. The installed `fx` on `PATH` is not valid development evidence.

README.md

@@ -103,6 +103,14 @@ With `--json`, `output` contains accumulated assistant Markdown across the reque
 
 Foreground terminal commands run with an explicit finite deadline. fx uses durable terminal sessions for services, watchers, GUI applications, and other long-lived work, and keeps captured foreground output available through an opaque bounded-read handle for the active session or `--no-save` process.
 
+For bounded multi-step inspection, models can use the `code` tool to compose
+file reads, searches, stored-result reads, and foreground terminal commands in
+restricted JavaScript. Each nested operation still uses fx validation,
+permissions, execution, and lifecycle reporting. The isolated
+`fx-code-host` companion has no filesystem, network, environment, package, or
+subprocess API of its own; direct tools remain the path for simple work,
+persistent terminal sessions, file mutations, and interactive approval.
+
 fx starts in `auto` permission mode. Routine understood development actions run directly. Each unresolved action receives one narrow safety review based on the current user request and the exact pending action. A clear result authorizes only that action. A caution or unavailable review holds the action and returns advice to the agent without opening a permission prompt or ending the turn. See [Permissions](https://fx.sh/docs/configure-fx/permissions) for other modes and persistent rules.
 
 JSON and quiet requests stay noninteractive by default. Add `--prompt-permissions` to allow configured approval prompts when stdin is a TTY. Automatic safety review never opens that prompt. Prompt text is written to stderr, so JSON stdout stays parseable and quiet stdout stays empty. Piped or redirected stdin remains noninteractive and fails instead of waiting for approval.

THIRD_PARTY_NOTICES.md

@@ -2,6 +2,36 @@
 
 fx includes material from the following projects and data sources.
 
+## QuickJS-ng
+
+The `fx-code-host` companion embeds the QuickJS-ng JavaScript engine from
+<https://github.com/quickjs-ng/quickjs>, version 0.15.0.
+
+The MIT License (MIT)
+
+Copyright (c) 2017-2026 Fabrice Bellard
+Copyright (c) 2017-2024 Charlie Gordon
+Copyright (c) 2023-2026 Ben Noordhuis
+Copyright (c) 2023-2026 Saúl Ibarra Corretgé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 ## cuelume
 
 The embedded interface sounds are derived from the sound recipes in

build.zig

@@ -68,6 +68,36 @@ pub fn build(b: *std.Build) void {
 
     b.installArtifact(exe);
 
+    const code_mode_protocol_module = b.createModule(.{
+        .root_source_file = b.path(
+            "src/core/agent/code_mode_protocol.zig",
+        ),
+    });
+    const code_host = b.addExecutable(.{
+        .name = "fx-code-host",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/code_host/main.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+            .stack_check = false,
+            .stack_protector = false,
+            .omit_frame_pointer = true,
+            .unwind_tables = .none,
+            .error_tracing = false,
+            .strip = optimize != .Debug,
+        }),
+    });
+    code_host.root_module.addImport(
+        "code_mode_protocol",
+        code_mode_protocol_module,
+    );
+    addQuickJsCore(b, code_host.root_module);
+    const install_code_host = b.addInstallArtifact(code_host, .{});
+    b.getInstallStep().dependOn(&install_code_host.step);
+    const code_host_step = b.step("code-host", "Build the isolated code host");
+    code_host_step.dependOn(&install_code_host.step);
+
     const run_cmd = b.addRunArtifact(exe);
     run_cmd.step.dependOn(b.getInstallStep());
     if (b.args) |args| {
@@ -86,10 +116,35 @@ pub fn build(b: *std.Build) void {
         "FX_TEST_PRODUCT_EXE",
         b.getInstallPath(.bin, "fx"),
     );
+    run_exe_tests.setEnvironmentVariable(
+        "FX_TEST_CODE_HOST_EXE",
+        b.getInstallPath(.bin, "fx-code-host"),
+    );
 
     const test_step = b.step("test", "Run tests");
     test_step.dependOn(&run_exe_tests.step);
 
+    const code_host_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/code_host/main.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+    });
+    code_host_tests.root_module.addImport(
+        "code_mode_protocol",
+        code_mode_protocol_module,
+    );
+    addQuickJsCore(b, code_host_tests.root_module);
+    const run_code_host_tests = b.addRunArtifact(code_host_tests);
+    test_step.dependOn(&run_code_host_tests.step);
+    const test_code_host_step = b.step(
+        "test-code-host",
+        "Run the isolated code host tests",
+    );
+    test_code_host_step.dependOn(&run_code_host_tests.step);
+
     if (wasm_surface != .none) {
         addWasmArtifact(b, wasm_surface, git_commit, app_version, update_channel);
     }
@@ -308,6 +363,29 @@ pub fn build(b: *std.Build) void {
     }
 }
 
+fn addQuickJsCore(b: *std.Build, module: *std.Build.Module) void {
+    module.addIncludePath(b.path("third_party/quickjs"));
+    module.addCSourceFiles(.{
+        .files = &.{
+            "third_party/quickjs/quickjs.c",
+            "third_party/quickjs/dtoa.c",
+            "third_party/quickjs/libregexp.c",
+            "third_party/quickjs/libunicode.c",
+        },
+        .flags = &.{
+            "-std=gnu11",
+            "-D_GNU_SOURCE",
+            "-DQUICKJS_NG_BUILD",
+            "-funsigned-char",
+            "-Wno-sign-compare",
+            "-Wno-unused-parameter",
+            "-Wno-unused-but-set-variable",
+            "-Wno-unused-result",
+        },
+    });
+    module.linkSystemLibrary("m", .{});
+}
+
 fn addWasmArtifact(
     b: *std.Build,
     surface: WasmSurface,

build.zig.zon

@@ -45,6 +45,7 @@
         "build.zig.zon",
         "LICENSE",
         "src",
+        "third_party",
         "THIRD_PARTY_NOTICES.md",
     },
 }

scripts/pgso/corpus.json

@@ -97,6 +97,7 @@
     {"name": "e2e-mcp-stdio", "argv": ["bun", "test", "--max-concurrency", "1", "./mcp-stdio.test.ts"], "test_file": "mcp-stdio.test.ts"},
     {"name": "e2e-mcp-auth", "argv": ["bun", "test", "--max-concurrency", "1", "./mcp-auth.test.ts"], "test_file": "mcp-auth.test.ts", "allow_keychain": true},
     {"name": "e2e-session-recovery", "argv": ["bun", "test", "--max-concurrency", "1", "./session-recovery.test.ts"], "test_file": "session-recovery.test.ts"},
+    {"name": "e2e-shell-parity", "argv": ["bun", "test", "--max-concurrency", "1", "./shell-parity.test.ts"], "test_file": "shell-parity.test.ts", "requires_tmux": false},
     {"name": "e2e-terminal-host", "argv": ["bun", "test", "--max-concurrency", "1", "./terminal-host.test.ts"], "test_file": "terminal-host.test.ts"},
     {"name": "e2e-tui-startup", "argv": ["bun", "test", "--max-concurrency", "1", "./tui-startup.test.ts"], "test_file": "tui-startup.test.ts"},
     {"name": "e2e-permission-errors", "argv": ["bun", "test", "--max-concurrency", "1", "./permission-errors.test.ts"], "test_file": "permission-errors.test.ts"},

scripts/sign-and-notarize-macos.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 umask 077
 
 signing_identity="Developer ID Application: Vercel, Inc (JW6Y669B67)"
-signing_identifier="com.vercel.fx"
+signing_identifier="${FX_SIGNING_IDENTIFIER:-com.vercel.fx}"
 signing_team_id="JW6Y669B67"
 
 openssl_bin="${FX_SIGNING_OPENSSL_BIN:-/usr/bin/openssl}"

scripts/tests/test_macos_signing.py

@@ -258,6 +258,25 @@ def test_signs_notarizes_and_cleans_credentials_without_printing_secrets(
             self.assertIn("xcrun notarytool submit", events)
             self.assertIn("xcrun notarytool log", events)
 
+    def test_accepts_a_distinct_code_host_signing_identifier(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="fx-macos-signing-test-") as tmp:
+            root = pathlib.Path(tmp)
+            identifier = "com.vercel.fx.code-host"
+            result, _, _, event_log = self.run_script(
+                root,
+                {
+                    "FX_SIGNING_IDENTIFIER": identifier,
+                    "FX_SIGNING_TEST_IDENTIFIER": identifier,
+                },
+            )
+
+            output = result.stdout + result.stderr
+            self.assertEqual(0, result.returncode, output)
+            self.assertIn(
+                f"--identifier {identifier}",
+                event_log.read_text(encoding="utf-8"),
+            )
+
     def test_imports_pkcs12_private_key_for_codesign_and_security(self) -> None:
         self.assertTrue(SCRIPT_PATH.is_file(), "macOS signing helper is missing")
         with tempfile.TemporaryDirectory(prefix="fx-macos-signing-test-") as tmp: