@abot-ai/runtime 1.3.1 → 1.4.0

package/docs/runtime-prompt-policy-contracts.md

@@ -11,14 +11,14 @@ contracts without selecting a fixed workflow.
 | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Supervisor decision        | `src/runtime/steps/supervisor-decision/`                                                                              | strict parser, default-policy child contracts, exact canonical root, and runtime-owned receipt plus verified lineage for returned Planner/Worker results                                                                                  | `supervisor-decision.test.ts`, `role-call-work-receipt-continuation-pr1.test.ts`, `supervisor-request-runner.test.ts`                                                                                    |
 | Supervisor response        | `src/runtime/steps/supervisor-response/`                                                                              | exact active root and bounded returned-child context; legacy normalized terminal mode                                                                                                                                                     | `supervisor-response.test.ts`, `supervisor-request-runner.test.ts`, `request-finalization.test.ts`                                                                                                       |
-| Execution Agent decision   | `src/runtime/steps/execution-agent/`                                                                                  | strict parser, direct-policy actions and root capability authority, exact canonical state                                                                                                                                                 | `execution-agent-decision.test.ts`, `execution-agent-request-runner.test.ts`                                                                                                                             |
+| Execution Agent decision   | `src/runtime/steps/execution-agent/`                                                                                  | strict parser, direct-policy actions and root capability authority, exact canonical state                                                                                                                                                 | `execution-agent-decision.test.ts`, `execution-agent-request-runner.test.ts`, `model-work-plan-contract.test.ts`, `model-work-plan-runner.test.ts`                                                       |
 | Execution Agent response   | `src/runtime/steps/execution-agent/response-*`                                                                        | raw non-empty bounded text from the exact accepted response state; direct-policy exact terminal mode only                                                                                                                                 | `execution-agent-request-runner.test.ts`, `request-finalization.test.ts`                                                                                                                                 |
 | Delegated Planner decision | `src/runtime/steps/planner-decision/`                                                                                 | strict parser, exact Planner caller, registered delegated child contracts, complete known plan declaration, one-Worker-item dispatch, and runtime-owned receipt plus verified lineage for the returned Worker                             | `planner-decision.test.ts`, `planner-plan-contract.test.ts`, `role-call-work-receipt-continuation-pr1.test.ts`, `role-call-planner-events.test.ts`                                                       |
-| Planner Graph advisory     | `src/runtime/steps/planner-graph/`                                                                                    | bounded acyclic proposal or decline from the exact advisory objective; no execution authority                                                                                                                                             | `execution-agent-advisory-executors.test.ts`, `execution-agent-request-runner.test.ts`                                                                                                                   |
+| Planner Graph advisory     | `src/runtime/steps/planner-graph/`                                                                                    | bounded acyclic proposal or decline from the exact advisory objective; no execution authority                                                                                                                                             | `planner-graph-development-topology.test.ts`, `execution-agent-advisory-executors.test.ts`, `model-work-plan-events.test.ts`                                                                             |
 | Worker decision            | `src/runtime/steps/worker-decision/`                                                                                  | strict parser, exact Worker activation, offered capability catalog, and compact receipts for explicit dependency results; a directly bound Planner item excludes the broader request, Planner objective, and sibling tool-result lane     | `worker-decision.test.ts`, `worker-capability-decision.test.ts`, `role-call-dependency-work-receipt-pr1.test.ts`, `planner-worker-context-isolation.test.ts`, `planner-worker-tool-result-scope.test.ts` |
 | Worker result              | `src/runtime/steps/worker-decision/result-author.ts`                                                                  | raw text from the exact projected Worker assignment and evidence; Planner-item results retain the same narrowed boundary                                                                                                                  | `worker-decision.test.ts`, `planner-worker-context-isolation.test.ts`, `supervisor-request-runner.test.ts`                                                                                               |
 | Reviewer decision          | `src/runtime/steps/reviewer-decision/`                                                                                | strict parser and bounded supplied-work projection                                                                                                                                                                                        | `reviewer-decision.test.ts`, `supervisor-request-runner.test.ts`                                                                                                                                         |
-| Auditor advisory           | `src/runtime/steps/auditor-decision/`                                                                                 | typed criteria, whole canonical evidence entries, and omission-gated pass                                                                                                                                                                 | `execution-agent-advisory-executors.test.ts`, `execution-agent-request-runner.test.ts`                                                                                                                   |
+| Auditor advisory           | `src/runtime/steps/auditor-decision/`                                                                                 | Auditor-selected exact originals, full inventory coverage, additional bundle requests, and unchanged-review suppression                                                                                                                   | `auditor-evidence-contract.test.ts`, `auditor-evidence-runner.test.ts`, `auditor-context-admission.test.ts`, `execution-agent-advisory-executors.test.ts`                                                |
 | Capability payload         | `src/runtime/orchestration/worker-capabilities/payload-author.ts`, `src/runtime/request/worker-capability-payload.ts` | frozen-policy Worker or root principal, selected operation, immutable controls and payload contract; only a runtime-issued direct-Planner-item receipt can omit source; work-result receipts and lineage are removed before raw authoring | `planner-worker-context-isolation.test.ts`, `worker-capability-payload-author.test.ts`, `worker-payload-dependency-projection-pr1.test.ts`, `execution-agent-request-runner.test.ts`                     |
 | Degraded finalization      | `src/runtime/steps/degraded-finalization/`                                                                            | bounded failure rendering only                                                                                                                                                                                                            | `degraded-finalization.test.ts`, `request-finalization.test.ts`                                                                                                                                          |
 
@@ -62,8 +62,40 @@ or completion authority.
   canonical ledger. They establish provenance only; the active model still
   owns the semantic next action and must not treat them as proof of correctness.
   Model-supplied receipts are rejected and `execution-agent-v1` is unchanged.
-- Auditor returns a passive verdict over explicitly supplied criteria and whole
-  evidence entries. Missing or omitted evidence cannot produce pass.
+- The Execution Agent treats a selected project or working folder as location,
+  not authorization to repurpose a discovered application. Its policy favors
+  a new observed-free destination for a new app and clarification when the
+  intended existing target remains ambiguous. This is model policy, not a new
+  filesystem sandbox. Complex integrated or sequential development may use
+  advisory planning; simple requests retain a direct path.
+- An Execution Agent may explicitly adopt a returned Planner proposal and
+  report item statuses alongside its existing action. The ledger validates
+  the full definition against the exact completed Planner proposal, including
+  summary, ordered item IDs, titles and objectives, before emitting plan events.
+  Adoption, source replacement and restored state use the same resolver.
+  Progress is a model report, not evidence that the paired action succeeded.
+  Policy requires matching an item's actual acceptance criteria: static checks
+  or written test instructions cannot stand in for unperformed functional tests.
+  The advisory remains passive until adoption; delegated plan semantics are
+  unchanged.
+- Auditor chooses its original evidence from the full canonical work inventory
+  and can request a different complete bundle through `needs_evidence`.
+  Inventory previews are not proof. Pass requires every inventory ID classified
+  and every needed original present in the current exact bundle. Runtime
+  admission validates identity and exact retention against the configured model
+  context budget, without a separate fixed entry/character limit or choosing
+  semantic relevance. Identical receipt supplements may point to their exact
+  location within the unchanged original adapter result; distinct data remains
+  complete. Unchanged finished reviews are not offered again; new work or
+  steering reopens them. The root normally requests completion review after
+  implementation and available validation, then addresses concrete findings
+  before re-review. Earlier targeted review remains a model decision when
+  requested or useful for the next implementation decision. The root owns
+  remediation and final response; availability never schedules an audit.
+  Advisory results retain the shared 8,192-character receipt limit. The review
+  schema and assignment expose a description limit derived from the complete
+  metadata, evidence IDs and worst-case JSON escaping. Metadata that leaves no
+  room for a description fails before review; evidence and IDs are not shortened.
 - `reconsider_capability_selection` is a canonical mechanical transition after
   direct controls refinement exhausts structured-output validation. It
   executes nothing, makes no semantic judgment, chooses no replacement, and

package/docs/runtime-public-contracts.md

@@ -160,6 +160,23 @@ the active role has changed before completion. These fields are display identity
 they do not change runtime stages, tool parameters, approval inputs or evidence.
 The root role identifier remains `supervisor` regardless of its selected contract.
 
+Input `eventPresentation.metadata` mappings support typed boolean parameters
+without converting strings or numbers into booleans. Omitted or mistyped values
+use a declared default or remain absent. The system command declaration exposes
+its `elevated` flag (default false) in activity and approval evidence.
+
+Input `eventPresentation.metadata` string mappings may opt into `maxLength`
+(an integer from 1 to 4,096) and `preserveWhitespace` (boolean). These options
+apply to string mappings. `preserveWhitespace` is also supported on string arrays:
+opted-in arrays preserve empty values and positions, show up to 32 items bounded
+to 500 characters each, and include `<key>Truncated` and `<key>OmittedCount`.
+Existing mappings keep their 500-character,
+trimmed display summaries. Opted-in strings expose a companion
+`<key>Truncated` flag, preserve text when requested and avoid splitting Unicode
+surrogate pairs. They affect client display only, never accepted tool inputs.
+The system command plugin declares its full 4,096-character command bound;
+clients render that recorded command as inert text, separately from model intent.
+
 `eventPresentation.resultMetadata` maps optional display keys to existing tool
 result fields through `{path, kind}` descriptors. Paths select `output` or an
 own-property path under `data` (at most four segments). Kinds are `preview`,

package/package.json

@@ -81,6 +81,7 @@
     "dist/src/plugin-contract/",
     "dist/src/plugin-sdk/",
     "dist/src/web-ui/",
+    "dist/plugins/system/",
     "runtime.config.schema.json",
     "src/runtime/README.md",
     "src/runtime/scheduler/README.md",
@@ -93,6 +94,7 @@
     "docs/known-limitations.md",
     "docs/long-term-memory.md",
     "docs/plugins.md",
+    "docs/projects-and-full-plus.md",
     "docs/publishing.md",
     "docs/running-locally.md",
     "docs/runtime-invariant-coverage.md",
@@ -118,6 +120,7 @@
     "plugins/local-search/",
     "plugins/memory/",
     "plugins/project-orientation/",
+    "plugins/system/",
     "plugins/system-probe/",
     "plugins/web/"
   ],
@@ -169,10 +172,10 @@
     "typecheck:all": "tsc -p tsconfig.json --noEmit",
     "typecheck:plugins": "tsc -p tsconfig.plugins.json",
     "validate": "npm run check:plugin-build && npm run typecheck:all && npm test -- --run && npm run build && npm run check:plugins && npm run smoke:runtime-package && npm run check:runtime-package && npm run smoke:packed-runtime-package && npm run check:publication && npm run check:public-snapshot",
-    "web-ui": "tsx src/web-ui/server.ts",
+    "web-ui": "tsx scripts/build-host-companion.ts && tsx src/web-ui/server.ts",
     "web-ui:install-user-services": "tsx scripts/install-runtime-web-ui-user-services.ts"
   },
   "type": "module",
   "types": "./dist/src/runtime/index.d.ts",
-  "version": "1.3.1"
+  "version": "1.4.0"
 }

package/plugins/exec/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "exec",
   "version": "1.0.0",
-  "description": "Execute, observe, and cancel bounded non-interactive /bin/bash processes on Linux and macOS.",
+  "description": "Execute, observe, and cancel trusted non-interactive /bin/bash processes on Linux and macOS with per-action approval in Ask/Full.",
   "extensions": {
     "ai.abot.runtime": {
       "version": 1,
@@ -19,19 +19,29 @@
       "capabilities": {
         "exec": {
           "catalogGroups": ["read", "write", "exec"],
-          "description": "Execute one bounded non-interactive /bin/bash command on Linux or macOS. The explicit cwd must resolve inside agent work or the configured workspace; `.` means the agent-work root and `workspace/...` selects the workspace. The shell itself runs with the runtime process permissions and is not an operating-system sandbox. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it. Prefer dedicated inspection and file-mutation capabilities when they can express the task.",
+          "description": "Execute one trusted non-interactive /bin/bash command on Linux or macOS. Use an explicit existing directory: `.` and relative paths start at the agent-work root, `workspace/...` selects the workspace, and absolute host paths are accepted. Commands run with the runtime OS user permissions without parsing their contents for path or sensitivity restrictions. Ask/Full require approval of the exact action; FULL+ executes without that prompt. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it.",
           "routingCapability": "filesystem_inspection",
-          "developmentRoles": ["inspect", "establish", "verify", "auxiliary"],
+          "developmentRoles": ["inspect", "establish", "mutate", "verify", "auxiliary"],
           "eventPresentation": {
             "metadata": {
-              "command": { "param": "command", "kind": "string" },
-              "cwd": { "param": "cwd", "kind": "string" }
+              "command": {
+                "param": "command",
+                "kind": "string",
+                "maxLength": 4096,
+                "preserveWhitespace": true
+              },
+              "cwd": {
+                "param": "cwd",
+                "kind": "string",
+                "maxLength": 4096,
+                "preserveWhitespace": true
+              }
             }
           },
           "skills": ["exec_skill"],
           "operations": {
             "execute_command": {
-              "summary": "Execute one bounded non-interactive /bin/bash command on Linux or macOS in an explicit existing agent-work or workspace directory. The cwd boundary is not an OS sandbox. Full-access availability does not authorize servers, GUI automation, installs, service changes, background work, or other sensitive effects.",
+              "summary": "Execute one trusted non-interactive /bin/bash command in an explicit existing directory. This sensitive operation requires exact-action approval in Ask/Full and runs automatically in FULL+. The OS user permissions still apply; the selected folder is not a sandbox.",
               "input": {
                 "type": "object",
                 "additionalProperties": false,
@@ -46,7 +56,7 @@
                 "required": ["command", "cwd"]
               },
               "effect": "mixed",
-              "approval": "request_policy"
+              "approval": "always"
             }
           }
         },
@@ -55,6 +65,12 @@
           "description": "Continue observing the exact running shell process returned by exec. Use only the process ID and next cursor from the latest exec or exec_wait result. This does not start the command again.",
           "routingCapability": "filesystem_inspection",
           "developmentRoles": ["inspect", "verify", "auxiliary"],
+          "eventPresentation": {
+            "metadata": {
+              "processId": { "param": "process_id", "kind": "string" },
+              "cursor": { "param": "cursor", "kind": "number" }
+            }
+          },
           "skills": ["exec_process_skill"],
           "operations": {
             "wait_for_process": {
@@ -77,7 +93,7 @@
                 "required": ["process_id", "cursor"]
               },
               "effect": "read_only",
-              "approval": "request_policy"
+              "approval": "always"
             }
           }
         },
@@ -86,6 +102,11 @@
           "description": "Cancel one running shell process previously returned by exec. Use only when the current task no longer needs that process or the user asks to stop it.",
           "routingCapability": "filesystem_inspection",
           "developmentRoles": ["auxiliary"],
+          "eventPresentation": {
+            "metadata": {
+              "processId": { "param": "process_id", "kind": "string" }
+            }
+          },
           "skills": ["exec_process_skill"],
           "operations": {
             "cancel_process": {
@@ -103,7 +124,7 @@
                 "required": ["process_id"]
               },
               "effect": "mixed",
-              "approval": "request_policy"
+              "approval": "always"
             }
           }
         }

package/plugins/exec/skills/exec_process_skill/SKILL.md

@@ -5,3 +5,4 @@
 - Use `exec_cancel` only when the current task no longer needs the active process or the user asks to stop it.
 - Process IDs belong to one loaded plugin instance and session; never reuse one across runtimes or sessions.
 - Do not cancel a process whose result is still required, and do not retry a stale cursor unchanged.
+- These are sensitive actions like command execution: Ask/Full request approval through the runtime; FULL+ proceeds without an extra prompt. Approval never permits a different process or a replay of the original command.

package/plugins/exec/skills/exec_skill/SKILL.md

@@ -1,12 +1,11 @@
 # Exec Skill
 
-- Use `exec` for narrow shell-native discovery or verification when a dedicated tool is insufficient.
-- `exec` is available on Linux and macOS with executable `/bin/bash`; it does not select a Windows shell or another fallback shell. Commands must use the utilities and options available on the host.
-- Resolve `.` and ordinary relative `cwd` values from the configured agent work directory. They are never rewritten to the active Worker working directory. Use `workspace/...` only when the configured workspace is explicitly intended.
-- Always provide an explicit existing `cwd`. For an existing project, use its project path. To create a new project, use an existing parent `cwd` (normally `.`) and create the project path in the command.
-- The cwd is restricted to configured roots, but the shell runs with the runtime process permissions and is not an operating-system sandbox.
-- Keep commands deterministic, non-interactive, and scoped to the selected configured root.
-- Availability under full-access mode is not user authorization for sensitive effects. Starting a listener or server, launching a browser or GUI automation, installing software, changing services, or creating long-running background work requires explicit authorization in the current user request.
-- For multi-line input, use a single-quoted here-document instead of fragile quoted one-line payloads.
-- Prefer an active file creation or editing capability over shell redirection when it can express the requested change.
-- If a process remains active, continue the same process with `exec_wait`; do not launch it again.
+- Use `exec` for shell work needed by the user's task. Prefer dedicated capabilities when they express that work directly.
+- `exec` uses non-interactive `/bin/bash` on Linux and macOS; it does not select a Windows shell. Use commands available on that target OS.
+- Supply an explicit existing `cwd`. `.` and relative paths start from the configured agent-work directory, not an implicit Worker directory. `workspace/...` selects the configured workspace; absolute host directories are accepted.
+- To create a project, select an existing parent `cwd` and create its directory in the command. A selected project provides working context, not a filesystem sandbox.
+- The whole exec family is sensitive: Ask and Full request approval of each exact action through the normal tool flow; FULL+ executes without an additional ABot prompt. Submit the needed operation instead of declaring it unavailable solely because of the selected mode.
+- Commands run as the runtime OS user. The plugin does not parse command contents to infer sensitivity or restrict referenced paths. OS permissions still apply; FULL+ does not grant root or Administrator rights.
+- Execution has no interactive terminal and retains time, output and process limits. Use non-interactive forms; a terminal prompt cannot be answered through this tool.
+- For multi-line input, use a single-quoted here-document when it preserves the intended shell input.
+- If a process remains active, continue that exact process with `exec_wait`; do not launch the command again.

package/plugins/exec/source/handlers.ts

@@ -15,9 +15,9 @@ import {
   captureExecFilesystemSnapshot,
   diffExecFilesystemSnapshots,
 } from "./filesystem-observer.js";
-import { resolveExecScopedPath, resolveExecWorkingDirectory } from "./paths.js";
+import { resolveExecWorkingDirectory } from "./paths.js";
 import { createExecProcessManager } from "./process-manager.js";
-import { EXEC_COMMAND_MAX_CHARS, type ExecSettings } from "./settings.js";
+import type { ExecSettings } from "./settings.js";
 import type {
   ExecActionSummary,
   ExecFilesystemDelta,
@@ -25,12 +25,7 @@ import type {
   ExecStreamSnapshot,
   PendingExecExecution,
 } from "./types.js";
-import {
-  isInteractiveCommand,
-  sanitizeExecCommand,
-  scopedPathTokens,
-  stripHereDocBodies,
-} from "./validation.js";
+import { readExecCommand } from "./validation.js";
 
 const COMMAND_PREVIEW_MAX_CHARS = 768;
 
@@ -81,9 +76,6 @@ function runningResult(
   const rendered = renderedOutput(
     [
       `Command: ${execution.commandPreview}`,
-      ...(execution.commandWasNormalized
-        ? ["Command normalization: invalid control characters were removed."]
-        : []),
       `CWD: ${execution.cwd.logicalPath}`,
       "Process status: running",
       `Process ID: ${snapshot.processId}`,
@@ -222,9 +214,6 @@ async function finalizeExecResult(params: {
   const rendered = renderedOutput(
     [
       `Command: ${execution.commandPreview}`,
-      ...(execution.commandWasNormalized
-        ? ["Command normalization: invalid control characters were removed."]
-        : []),
       `CWD: ${execution.cwd.logicalPath}`,
       `Process ID: ${snapshot.processId}`,
       `Process status: ${snapshot.terminationReason ?? "completed"}`,
@@ -332,34 +321,12 @@ export function createExecHandlers(
 
   const exec: ToolImplementation = async (params, context) => {
     try {
-      const rawCommand = readRequiredString(params.command, {
-        name: "command",
-        trim: false,
-        maxLength: EXEC_COMMAND_MAX_CHARS,
-      });
-      const { command, normalized } = sanitizeExecCommand(rawCommand);
-      if (!command) {
-        throw new ExecPluginError(
-          "exec_command_invalid",
-          "The command is empty after invalid control characters are removed.",
-        );
-      }
-      const interactive = isInteractiveCommand(command);
-      if (interactive) {
-        throw new ExecPluginError(
-          "exec_interactive_command_blocked",
-          `Interactive command ${interactive} is not supported by the non-interactive exec plugin.`,
-        );
-      }
+      const command = readExecCommand(params.command);
       const cwd = await resolveExecWorkingDirectory(
         pluginContext,
         context,
         params.cwd,
       );
-      const staticCommand = stripHereDocBodies(command);
-      for (const token of scopedPathTokens(staticCommand)) {
-        resolveExecScopedPath(pluginContext, context, token, cwd);
-      }
       const filesystemStateBefore = await captureExecFilesystemSnapshot(
         cwd.absolutePath,
         cwd.logicalPath,
@@ -370,7 +337,6 @@ export function createExecHandlers(
       }).text;
       const execution: PendingExecExecution = Object.freeze({
         commandPreview,
-        commandWasNormalized: normalized,
         cwd,
         filesystemStateBefore,
         hardTimeoutMs: settings.hardTimeoutMs,

package/plugins/exec/source/paths.ts

@@ -1,69 +1,86 @@
-import { stat } from "node:fs/promises";
-import { isAbsolute, posix } from "node:path";
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, posix, relative, sep } from "node:path";
 
 import {
   readRequiredString,
   resolvePluginPath,
-  type ResolvedRuntimeToolPath,
   type RuntimePluginLoadContext,
   type ToolExecutionContext,
 } from "../../../src/plugin-sdk/index.js";
-
 import { ExecPluginError } from "./errors.js";
+import type { ExecWorkingDirectory } from "./types.js";
 
-const EXEC_ALLOWED_LOCATIONS = Object.freeze([
-  "agent_work",
-  "workspace",
-] as const);
-
-function resolverContext(
-  pluginContext: RuntimePluginLoadContext,
-  executionContext: ToolExecutionContext | undefined,
-): Pick<RuntimePluginLoadContext, "runtimePathResolver"> {
-  return {
-    runtimePathResolver:
-      executionContext?.runtimePathResolver ??
-      pluginContext.runtimePathResolver,
-  };
-}
-
-export function resolveExecPath(
+function resolveContextualDirectory(
   pluginContext: RuntimePluginLoadContext,
   executionContext: ToolExecutionContext | undefined,
-  rawPath: unknown,
-): ResolvedRuntimeToolPath {
-  return resolvePluginPath(
-    resolverContext(pluginContext, executionContext),
-    rawPath,
+  requestedPath: string,
+): Readonly<{ absolutePath: string; base?: ExecWorkingDirectory }> {
+  if (isAbsolute(requestedPath)) return { absolutePath: requestedPath };
+  const isWorkspaceAlias =
+    requestedPath === "workspace" || requestedPath.startsWith("workspace/");
+  const base = resolvePluginPath(
     {
-      requirePath: true,
-      allowedLocations: EXEC_ALLOWED_LOCATIONS,
+      runtimePathResolver:
+        executionContext?.runtimePathResolver ??
+        pluginContext.runtimePathResolver,
     },
+    isWorkspaceAlias ? "workspace" : ".",
+    { allowedLocations: [isWorkspaceAlias ? "workspace" : "agent_work"] },
   );
+  const relativePath = isWorkspaceAlias
+    ? requestedPath.slice("workspace".length + 1) || "."
+    : requestedPath;
+  return { absolutePath: `${base.absolutePath}${sep}${relativePath}`, base };
+}
+
+function isOutsideExecContextBase(relativePath: string): boolean {
+  if (relativePath === "..") return true;
+  if (relativePath.startsWith(`..${sep}`)) return true;
+  return isAbsolute(relativePath);
+}
+
+function logicalDirectory(
+  absolutePath: string,
+  base: ExecWorkingDirectory | undefined,
+): string {
+  if (!base) return absolutePath;
+  const fromBase = relative(base.absolutePath, absolutePath);
+  if (isOutsideExecContextBase(fromBase)) return absolutePath;
+  return posix.join(base.logicalPath, fromBase.split(sep).join("/") || ".");
 }
 
 export async function resolveExecWorkingDirectory(
   pluginContext: RuntimePluginLoadContext,
   executionContext: ToolExecutionContext | undefined,
   rawPath: unknown,
-): Promise<ResolvedRuntimeToolPath> {
+): Promise<ExecWorkingDirectory> {
   const requestedPath = readRequiredString(rawPath, {
     name: "cwd",
+    trim: false,
     maxLength: 4_096,
   });
-  const target = resolveExecPath(
+  if (requestedPath.includes("\0")) {
+    throw new ExecPluginError(
+      "exec_cwd_invalid",
+      "The selected cwd contains NUL characters.",
+    );
+  }
+  const target = resolveContextualDirectory(
     pluginContext,
     executionContext,
     requestedPath,
   );
+  let absolutePath: string;
   let info;
   try {
-    info = await stat(target.absolutePath);
+    // The contextual base is not a permission boundary for raw shell execution.
+    absolutePath = await realpath(target.absolutePath);
+    info = await stat(absolutePath);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       throw new ExecPluginError(
         "exec_cwd_not_found",
-        "The selected cwd does not exist. Select an existing agent-work or workspace directory.",
+        "The selected cwd does not exist. Select an existing directory.",
       );
     }
     throw new ExecPluginError(
@@ -77,21 +94,8 @@ export async function resolveExecWorkingDirectory(
       "The selected cwd is not a directory.",
     );
   }
-  return target;
-}
-
-export function resolveExecScopedPath(
-  pluginContext: RuntimePluginLoadContext,
-  executionContext: ToolExecutionContext | undefined,
-  rawPath: string,
-  cwd: ResolvedRuntimeToolPath,
-): ResolvedRuntimeToolPath {
-  const normalized = rawPath.replaceAll("\\", "/");
-  const requested =
-    isAbsolute(rawPath) ||
-    normalized === "workspace" ||
-    normalized.startsWith("workspace/")
-      ? rawPath
-      : posix.join(cwd.logicalPath, normalized || ".");
-  return resolveExecPath(pluginContext, executionContext, requested);
+  return Object.freeze({
+    absolutePath,
+    logicalPath: logicalDirectory(absolutePath, target.base),
+  });
 }

package/plugins/exec/source/types.ts

@@ -1,5 +1,3 @@
-import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
-
 export type ExecActionSummary = Readonly<{
   type: string;
   target?: string;
@@ -66,10 +64,14 @@ export type ExecFilesystemDelta = Readonly<{
   }>;
 }>;
 
+export type ExecWorkingDirectory = Readonly<{
+  absolutePath: string;
+  logicalPath: string;
+}>;
+
 export type PendingExecExecution = Readonly<{
   commandPreview: string;
-  commandWasNormalized: boolean;
-  cwd: ResolvedRuntimeToolPath;
+  cwd: ExecWorkingDirectory;
   filesystemStateBefore: ExecFilesystemSnapshot | null;
   hardTimeoutMs: number;
   idleTimeoutMs: number;