@piagent/platform 1.46.4 → 1.48.0

package/packages/piagent-core/extensions/policy-core.js

@@ -1,5 +1,5 @@
-import { excludedFindSelectorValue, findSelectorOption, SEARCH_COMMANDS, SEARCH_FILE_OPTIONS, SEARCH_GLOB_OPTIONS,
-  SEARCH_PATTERN_OPTIONS, searchSelectorIsExclusion, searchSelectorWithinToken } from "./shell-selector-policy.js";
+import { excludedFindSelectorValue, findSelectorOption, SEARCH_COMMANDS, SEARCH_FILE_OPTIONS, SEARCH_GLOB_OPTIONS, SEARCH_PATTERN_OPTIONS, searchSelectorIsExclusion, searchSelectorWithinToken } from "./shell-selector-policy.js";
+import { CONTROL_PREFIXES, gitSubcommandWords } from "./shell-command-words.js";
 
 const PATH_REDIRECT_OPERATORS = new Set(["<", ">", ">>", "1>", "1>>", "2>", "2>>", "&>", "&>>"]);
 const DATA_ONLY_COMMANDS = new Set(["echo", "printf"]);
@@ -35,7 +35,7 @@ const INLINE_CODE_FLAGS = new Map([
   ["perl", new Set(["-e", "-E"])],
   ["php", new Set(["-r"])]
 ]);
-const SIMPLE_WRAPPERS = new Set(["sudo", "nohup", "time", "nice", "ionice", "command"]);
+const SIMPLE_WRAPPERS = new Set(["sudo", "doas", "nohup", "time", "nice", "ionice", "command", "exec"]);
 
 function escapeRegex(value) {
   return value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
@@ -703,13 +703,13 @@ function isLeadingRedirection(word) {
   return /^[0-9]*(?:>>?\|?|<>?|>&|<&)/.test(word);
 }
 
-function stripWrapper(words) {
+export function stripWrapper(words) {
   let current = [...words];
   let changed = true;
 
   while (changed && current.length > 0) {
     changed = false;
-    while (current.length > 0 && isAssignment(current[0])) {
+    while (current.length > 0 && (isAssignment(current[0]) || CONTROL_PREFIXES.has(current[0]))) {
       current = current.slice(1);
       changed = true;
     }
@@ -1186,7 +1186,7 @@ export function evaluateExecPolicyCore(command, options) {
 
     for (const rule of execPolicy.rules) {
       if (!commandRuleMatches(rule, text, words)) continue;
-      matches.push(`${rule.action}:${rule.id}`);
+      matches.push(`${rule.action}:${rule.id}`, ...(rule.action === "forbid" && rule.terminate ? [`terminate:${rule.id}`] : []));
       if (rule.action === "forbid") reasons.push(`Forbidden by exec policy ${rule.id}: ${rule.reason}`);
       if (rule.action === "prompt") reasons.push(`Prompt required by exec policy ${rule.id}: ${rule.reason}`);
     }
@@ -1229,7 +1229,7 @@ export function evaluateExecPolicyCore(command, options) {
   const confirmationPatternMatches = (pattern, words) => {
     const expected = shellWords(String(pattern ?? ""));
     if (expected.length === 0) return false;
-    const executableWords = stripWrapper(words);
+    const executableWords = gitSubcommandWords(stripWrapper(words));
     if (arrayStartsWith(executableWords, expected)) return true;
     if (expected.length !== 1) return false;
     const action = expected[0];

package/packages/piagent-core/extensions/shell-ast.js

@@ -0,0 +1,85 @@
+// The simple commands a shell line runs, read from a real shell syntax tree.
+//
+// policy-core.js splits a line into segments with its own scanner; this reads
+// the same line through a POSIX/Bash parser and walks every place a command
+// can sit: pipelines, && and ||, if/while/for/case bodies, functions, ( … ),
+// { … }, $( … ), backticks and <( … ). `bash -c '…'`, `sh -c` and `eval` are
+// parsed again, so the text they run is read as commands too. A check that
+// reads both lists sees a command whichever reader finds it.
+//
+// Words come back as text. A word built from an expansion the shell decides
+// at run time ($VAR, $(…), `…`) keeps it as written and is flagged dynamic;
+// nothing is evaluated here. A line the parser rejects gives null: callers
+// keep the scanner's answer, which is never weakened by this module.
+import { parse } from "@aliou/sh";
+
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "mksh"]);
+const MAX_DEPTH = 8;
+
+function wordText(word) {
+  let text = "", dynamic = false;
+  const visit = (parts) => {
+    for (const part of parts ?? []) {
+      if (part.type === "Literal" || part.type === "SglQuoted") text += part.value;
+      else if (part.type === "DblQuoted") visit(part.parts);
+      else if (part.type === "ParamExp") { text += `$${part.param?.value ?? ""}`; dynamic = true; }
+      else { text += "$(…)"; dynamic = true; }
+    }
+  };
+  visit(word?.parts);
+  return { text, dynamic };
+}
+
+// The $( … ) and ` … ` an unquoted heredoc body runs: the parser keeps the
+// body as text, and the shell expands it.
+function substitutions(text) {
+  const found = [];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "`") {
+      const close = text.indexOf("`", index + 1);
+      if (close < 0) break;
+      found.push(text.slice(index + 1, close)); index = close;
+    } else if (text.startsWith("$(", index) && text[index + 2] !== "(") {
+      let depth = 0, close = -1;
+      for (let at = index + 1; at < text.length; at += 1) {
+        if (text[at] === "(") depth += 1;
+        else if (text[at] === ")" && --depth === 0) { close = at; break; }
+      }
+      if (close < 0) break;
+      found.push(text.slice(index + 2, close)); index = close;
+    }
+  }
+  return found;
+}
+
+function collect(node, found, depth) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) { for (const item of node) collect(item, found, depth); return; }
+  if (node.type === "Redirect" && node.heredoc && node.target?.parts?.every((part) => part.type === "Literal") && depth < MAX_DEPTH) {
+    for (const source of substitutions(wordText(node.heredoc).text)) collectSource(source, found, depth + 1);
+  }
+  if (node.type === "SimpleCommand" && node.words?.length) {
+    const words = node.words.map(wordText);
+    found.push({ words: words.map((word) => word.text), dynamic: words.some((word) => word.dynamic) });
+    const name = String(words[0]?.text ?? "").split("/").pop();
+    const inline = SHELLS.has(name) ? words.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/.test(word.text)) + 1 : name === "eval" ? 1 : 0;
+    if (inline > 0 && depth < MAX_DEPTH) {
+      const source = name === "eval" ? words.slice(1).map((word) => word.text).join(" ") : words[inline]?.text;
+      if (source) collectSource(source, found, depth + 1);
+    }
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key !== "pos" && key !== "end" && value && typeof value === "object") collect(value, found, depth);
+  }
+}
+
+function collectSource(source, found, depth) {
+  try { collect(parse(String(source), { dialect: "bash" }).ast, found, depth); } catch { /* the scanner still reads it */ }
+}
+
+// [{ words, dynamic }] for every simple command, or null when the line does not parse.
+export function astCommands(command) {
+  const found = [];
+  try { collect(parse(String(command), { dialect: "bash" }).ast, found, 0); } catch { return null; }
+  return found;
+}

package/packages/piagent-core/extensions/shell-command-words.js

@@ -0,0 +1,19 @@
+// How a simple command's words name what runs, shared by policy-core.js and
+// the handoff policy (runtime/policy/handoff-policy.mjs).
+
+// Shell words that open a compound statement: the command follows them.
+// `if true; then rm -rf /; fi` splits into `then rm -rf /`, which runs rm.
+export const CONTROL_PREFIXES = new Set(["!", "{", "(", "if", "then", "do", "elif", "else", "while", "until"]);
+
+// Git's global options come before the subcommand: `git -C api push` and
+// `git -c core.hooksPath=x --no-pager push` push as `git push` does. Without
+// this a rule written as "git push" matched only the plain spelling.
+const GIT_OPTIONS_WITH_VALUE = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--config-env", "--exec-path", "--list-cmds"]);
+export function gitSubcommandWords(words) {
+  if (String(words[0] ?? "").split("/").pop() !== "git") return words;
+  let index = 1;
+  while (index < words.length && words[index].startsWith("-")) {
+    index += GIT_OPTIONS_WITH_VALUE.has(words[index]) ? 2 : 1;
+  }
+  return ["git", ...words.slice(index)];
+}

package/packages/piagent-core/managed/command-tools.mjs

@@ -1,44 +1,61 @@
 import { spawn } from 'node:child_process';
-import { asksNothing, broadAccess, networkConfirmation } from './permission.mjs';
+import { asksOnlyHandoff, broadAccess, effectivePermission, networkConfirmation } from './permission.mjs';
+import { handoffReason } from '../runtime/policy/handoff-policy.mjs';
 import { engineAlive, engineLauncher } from './container-engine.mjs';
 import { MEMBER_ONLY, memberOnlyReason, credentialReason, runHostCommand } from './host-command.mjs';
 import { processTools } from './background-process.mjs';
 import { checkpointsOf } from './checkpoints.mjs';
+import { detachedEmulator, simulatorCommandReason } from './simulator-commands.mjs';
 
-// Commands that leave the plain sandbox, each after the member approves that
-// exact command: run_with_network (internet, a local server or browser),
-// run_with_docker when this machine has Docker (the same plus the engine's
-// socket) and run_on_host (on the member's machine, outside the sandbox).
-// Bypass runs the first two without asking (owner, 2026-10-09), except what
-// must be confirmed for any command (bypass-policy.mjs: pushes, deploys,
-// registry logins, deletes known only at run time). run_on_host asks in every
-// mode but Bypass; Bypass still asks when the command reaches credentials.
+// Commands that leave the plain sandbox: run_with_network (internet, a local
+// server or browser), run_with_docker when this machine has Docker (the same
+// plus the engine's socket), run_on_host (on the member's machine, outside the
+// sandbox) and run_on_simulator. What each mode asks (permission.mjs):
+// - Ask first: every command.
+// - Full access: run_with_network, run_with_docker and run_on_simulator run,
+//   except the handoff and destructive steps (mustConfirm); run_on_host asks
+//   every command.
+// - Bypass: all four run, except the handoff (handoffReason: push, PR,
+//   publish, deploy, remote and cloud tools, uploads) and, on the host, a
+//   command that reaches credentials.
 const PARAMETERS = { type: 'object', properties: { command: { type: 'string', minLength: 1, maxLength: 4000 }, reason: { type: 'string', minLength: 1, maxLength: 300 }, timeout: { type: 'number', minimum: 1, maximum: 1800 } }, required: ['command', 'reason'], additionalProperties: false };
 
 const KINDS = {
   network: {
     name: 'run_with_network', label: 'Run with network', scope: 'network-command-once', provider: 'network', riskClass: 'medium',
-    description: 'Run one shell command that needs the internet beyond the package registries bash already reaches (a download site or registry the package proxy refuses), or that starts a local server or a browser (end-to-end tests with Playwright\'s Chromium against a server on 127.0.0.1), after the user approves that exact command. Normal bash has no internet; on macOS it reaches servers on this Mac and runs Playwright\'s Chromium against them, except while a local proxy listens. Credentials (.npmrc, SSH keys, Keychain) stay unavailable, so private registries and git push are not possible here.',
+    description: 'Run one shell command that needs the internet beyond the package registries bash already reaches (a download site or registry the package proxy refuses), or that starts a local server or a browser (end-to-end tests with Playwright\'s Chromium against a server on 127.0.0.1), after the user approves that exact command (Full access and Bypass run it without asking, but a push, publish, deploy or upload is always asked). Normal bash has no internet; on macOS it reaches servers on this Mac and runs Playwright\'s Chromium against them, except while a local proxy listens. Credentials (.npmrc, SSH keys, Keychain) stay unavailable, so private registries and git push are not possible here.',
     allow: 'Run this exact command once, with internet access; a server it starts accepts connections while it runs.',
     title: 'Chạy lệnh có internet', allowText: 'chạy đúng lệnh này một lần, có internet; server nó mở nhận kết nối trong lúc chạy.',
     confirm: (self, command) => networkConfirmation(self, command),
   },
   docker: {
     name: 'run_with_docker', label: 'Run with Docker', scope: 'docker-command-once', provider: 'docker', riskClass: 'high',
-    description: 'Run one shell command that needs the Docker engine of this machine: docker, docker compose (a database or service for tests), docker build, or tests that start containers themselves (Testcontainers), after the user approves that exact command. It has internet access too. Normal bash and run_with_network cannot reach Docker. Mount only folders inside the project. Registry credentials are unavailable: public images pull, private registries and docker push do not. Containers started in the background (-d, compose up -d) keep running after the command: stop them (docker compose down) when the work is done unless the member wants them kept.',
+    description: 'Run one shell command that needs the Docker engine of this machine: docker, docker compose (a database or service for tests), docker build, or tests that start containers themselves (Testcontainers), after the user approves that exact command (Full access and Bypass run it without asking, but docker push or login and any other handoff is always asked). It has internet access too. Normal bash and run_with_network cannot reach Docker. Mount only folders inside the project. Registry credentials are unavailable: public images pull, private registries and docker push do not. Containers started in the background (-d, compose up -d) keep running after the command: stop them (docker compose down) when the work is done unless the member wants them kept.',
     allow: 'Run this exact command once, with internet access and the Docker engine; a container it starts can read folders Docker shares from this machine and may keep running.',
     title: 'Chạy lệnh dùng Docker', allowText: 'chạy đúng lệnh này một lần, có internet và Docker; container nó tạo có thể đọc thư mục Docker được chia sẻ trên máy và có thể tiếp tục chạy.',
     confirm: (self, command) => networkConfirmation(self, command),
   },
   host: {
     name: 'run_on_host', label: 'Run on this machine', scope: 'host-command-once', provider: 'host', riskClass: 'high',
-    description: 'Run one shell command on the member\'s machine, outside the sandbox, as the member, after they approve that exact command. Use it when the sandbox blocks what the task needs and no other tool covers it: install a runtime or tool the project needs (brew install openjdk@21, brew install node@22, sdk install java…), git pull or git push with the member\'s sign-in, a private registry, a file outside the project. It has the member\'s files, Keychain and sign-ins, so ask only for what the task needs and say why in reason. No input can be typed: commands that need the member\'s password (sudo, a .pkg installer) or an interactive sign-in are refused; ask the member with ask_user for those.',
+    description: 'Run one shell command on the member\'s machine, outside the sandbox, as the member, after they approve that exact command (only Bypass runs it without asking, and even there a push, PR, publish, deploy or a command that reaches credentials is asked). Use it when the sandbox blocks what the task needs and no other tool covers it: install a runtime or tool the project needs (brew install openjdk@21, brew install node@22, sdk install java…), git pull with the member\'s sign-in, git push only when the member asked for it, a private registry, a file outside the project. It has the member\'s files, Keychain and sign-ins, so ask only for what the task needs and say why in reason. No input can be typed: commands that need the member\'s password (sudo, a .pkg installer) or an interactive sign-in are refused; ask the member with ask_user for those.',
     allow: 'Run this exact command once on this machine, outside the sandbox, as you: it can read and change your files and use your sign-ins.',
     title: 'Chạy lệnh trên máy (ngoài sandbox)', allowText: 'chạy đúng lệnh này một lần trên máy bạn, ngoài sandbox, bằng quyền của bạn: lệnh đọc/sửa được file và dùng được tài khoản đã đăng nhập trên máy.',
     // Full access does not cover it: the member approves each command (with
-    // what Full access would still have asked about). Bypass asks only about
-    // credentials: a prompt injection's "cat ~/.ssh/id_rsa" is never silent.
-    confirm: async (self, command) => asksNothing(self) ? credentialReason(command) : await networkConfirmation(self, command) ?? 'ask',
+    // what Full access would still have asked about). Bypass asks about the
+    // handoff and about credentials: a prompt injection's "cat ~/.ssh/id_rsa"
+    // or "git push --force" is never silent.
+    confirm: async (self, command) => asksOnlyHandoff(self) ? credentialReason(command) ?? await handoffReason(command) : await networkConfirmation(self, command) ?? 'ask',
+  },
+  // The sandbox reaches neither CoreSimulator nor adb. Simulator and app build
+  // commands only (simulator-commands.mjs), asked about as network commands:
+  // Full access and Bypass run them, except what reaches credentials and what
+  // either mode asks about any command.
+  simulator: {
+    name: 'run_on_simulator', label: 'Run on simulator', scope: 'simulator-command-once', provider: 'host', riskClass: 'medium',
+    description: 'Run one iOS Simulator or Android emulator command on the member\'s machine, outside the sandbox. iOS: xcrun simctl (list, boot, bootstatus -b, install, launch, terminate, openurl, io <device> screenshot <file>, ui appearance, status_bar, spawn <device> log show --info --last 5m --predicate \'process == "<App>"\'), xcodebuild with a simulator destination (build, test: XCUITest is the reliable way to tap, type and answer system dialogs), xcodegen generate, axe (describe-ui reads the screen\'s elements; tap, type, swipe where this Xcode accepts them), open -a Simulator (some Xcode versions run simulators without that window; the device works without it). Android: adb (devices, install, shell am start, shell input tap/text/swipe, exec-out screencap -p > <file>, logcat -d), emulator -avd <name> (started in the background), avdmanager, ./gradlew installDebug. Also flutter, pod install, npx expo/react-native/cap, mkdir -p and cd inside the project. Parts may be joined by && or || and piped into grep, head, tail, xcbeautify or jq; files may be written only inside the project or to /dev/null. Read a screenshot you saved with read to see the screen. Other commands: run_on_host.',
+    allow: 'Run this exact simulator or app build command once on this machine, outside the sandbox: a build can run the project\'s build scripts as you.',
+    title: 'Chạy lệnh simulator', allowText: 'chạy đúng lệnh simulator/build app này một lần trên máy bạn, ngoài sandbox: build có thể chạy script build của project bằng quyền của bạn.',
+    confirm: async (self, command) => credentialReason(command) ?? await networkConfirmation(self, command),
   },
 };
 
@@ -49,14 +66,34 @@ async function engineReady(boundary) {
 }
 const DOCKER_STOPPED = 'managed-docker-unreachable: Docker engine trên máy không chạy. Gọi start_docker để xin member duyệt mở Docker, rồi chạy lại đúng lệnh này bằng run_with_docker.';
 
-// One approval of the member (the dashboard card, else the Terminal).
+// Why a mode that runs commands without asking asks about this one, as the
+// card says it: the mode named as it is.
+export function stillAsks(self, reason) {
+  return effectivePermission(self) === 'bypass' ? { en: `Bypass still asks: ${reason}`, vi: `Bypass vẫn hỏi: ${reason}` }
+    : { en: `Full access still asks: ${reason}`, vi: `Full access vẫn hỏi: ${reason}` };
+}
+
+// One approval of the member (the dashboard card, else the Terminal). The
+// member may allow it once, allow the same exact action for the rest of the
+// conversation (never a handoff: its scope names it), deny it, or deny it and
+// stop the turn so the agent does not try again.
+const CHOICES = { once: 'Đồng ý một lần', session: 'Đồng ý cho cả cuộc trò chuyện (đúng lệnh này)', deny: 'Từ chối', stop: 'Từ chối và dừng lượt này' };
 export async function approve(self, id, signal, ctx, action, { title, body }) {
+  const grantable = !/handoff/.test(String(action.requestedScope ?? '')), key = `${action.toolName}\u0000${action.commandPreview ?? JSON.stringify(action.rawAction ?? {})}`;
+  if (grantable && self.sessionApprovals?.has(key)) return;
   const { piApprovalBroker } = await import('../runtime/inspection/approval-broker.ts');
+  const choices = ['once', ...(grantable ? ['session'] : []), 'deny', 'stop'];
   const decision = await piApprovalBroker.request({ cwd: self.cwd, rawSessionId: self.session.sessionManager.getSessionId(), toolCallId: id,
     action: { kind: 'external-provider-action', preconditionClass: 'runtime-only', targetPaths: [self.cwd], urlOrigin: null, ...action },
     terminalConfirm: () => ctx?.ui?.confirm?.(title, body) ?? Promise.resolve(false),
+    ...(ctx?.mode === 'tui' && ctx?.hasUI && typeof ctx.ui?.select === 'function' ? { terminalChoose: async () => {
+      const picked = await ctx.ui.select(`${title}\n\n${body}`, choices.map(choice => CHOICES[choice]));
+      return choices.find(choice => CHOICES[choice] === picked) ?? 'deny';
+    } } : {}),
     unavailableFallback: 'terminal-confirm', recheck: () => !signal?.aborted && Boolean(self.grant) });
+  if (!decision.allowed && decision.choice === 'stop') { try { ctx?.abort?.(); } catch { /* the denial below still stands */ } throw Error('managed-operation-denied-stop: bạn đã từ chối và dừng lượt này; không thử lại, chờ member.'); }
   if (!decision.allowed || !decision.consume() || signal?.aborted) throw Error('managed-operation-denied');
+  if (decision.choice === 'session' && grantable) (self.sessionApprovals ??= new Set()).add(key);
 }
 
 function commandTool(self, kind) {
@@ -66,16 +103,22 @@ function commandTool(self, kind) {
       if (kind === 'docker' && !await engineReady(self.boundary)) throw Error(DOCKER_STOPPED);
       const memberOnly = kind === 'host' ? memberOnlyReason(args.command) : null;
       if (memberOnly) throw Error(MEMBER_ONLY(memberOnly));
+      const notSimulator = kind === 'simulator' ? simulatorCommandReason(args.command, self.cwd) : null;
+      if (notSimulator) throw Error(`managed-simulator-command: ${notSimulator}.`);
       const confirm = await spec.confirm(self, args.command);
-      if (confirm !== null) await approve(self, id, signal, ctx, { toolName: spec.name, rawAction: { command: args.command }, commandPreview: String(args.command),
-        provider: spec.provider, requestedScope: spec.scope, reason: (confirm === 'ask' ? String(args.reason) : `Full access still asks: ${confirm}. ${args.reason}`).slice(0, 300), riskClass: spec.riskClass,
-        allowConsequence: spec.allow, denyConsequence: 'The command does not run; the agent is told you declined.' },
-      { title: spec.title, body: `${args.command}\n\nLý do: ${args.reason}${confirm === 'ask' ? '' : `\nBypass vẫn hỏi: ${confirm}`}\n\nĐồng ý: ${spec.allowText}\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.` });
+      if (confirm !== null) {
+        const why = confirm === 'ask' ? null : stillAsks(self, confirm), handoff = await handoffReason(args.command);
+        await approve(self, id, signal, ctx, { toolName: spec.name, rawAction: { command: args.command }, commandPreview: String(args.command),
+          provider: spec.provider, requestedScope: handoff ? 'handoff-once' : spec.scope, reason: (why ? `${why.en}. ${args.reason}` : String(args.reason)).slice(0, 300), riskClass: spec.riskClass,
+          allowConsequence: spec.allow, denyConsequence: 'The command does not run; the agent is told you declined.' },
+        { title: spec.title, body: `${args.command}\n\nLý do: ${args.reason}${why ? `\n${why.vi}` : ''}\n\nĐồng ý: ${spec.allowText}\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.` });
+      }
       let ok = false;
       if (self.run) await checkpointsOf(self).take();
       const before = await self.changedFiles();
       try {
-        const result = kind === 'host' ? await runHostCommand({ command: args.command, cwd: self.cwd, userHome: self.boundary.userHome, timeout: args.timeout, signal, onUpdate })
+        const result = kind === 'simulator' && detachedEmulator(args.command) ? await runHostCommand({ command: `nohup ${args.command} >/dev/null 2>&1 & sleep 3; echo "Emulator started in the background; wait for it with: adb wait-for-device"`, cwd: self.cwd, userHome: self.boundary.userHome, timeout: 60, signal, onUpdate })
+          : kind === 'host' || kind === 'simulator' ? await runHostCommand({ command: args.command, cwd: self.cwd, userHome: self.boundary.userHome, timeout: args.timeout, signal, onUpdate })
           : await self.boundary.invoke('bash', { command: args.command, ...(args.timeout ? { timeout: args.timeout } : {}) }, signal, onUpdate, ctx?.model, kind === 'docker' ? { docker: true } : { network: true });
         ok = !result?.isError; return result;
       } finally {
@@ -87,7 +130,8 @@ function commandTool(self, kind) {
 }
 
 // start_docker: the engine the member installed, started after they approve
-// (Bypass starts it without asking: local and reversible), then waited for.
+// (Full access and Bypass start it without asking: local and reversible),
+// then waited for.
 const textResult = text => ({ content: [{ type: 'text', text }], details: {} });
 function startDockerTool(self, { wait = 180_000, every = 2000, launcher: found = engineLauncher, spawnImpl = spawn } = {}) {
   return { name: 'start_docker', label: 'Start Docker',
@@ -115,15 +159,15 @@ function startDockerTool(self, { wait = 180_000, every = 2000, launcher: found =
 
 export function commandTools(self, options) {
   const docker = self.boundary.engine || self.boundary.dockerCli;
-  return [commandTool(self, 'network'), ...(docker ? [commandTool(self, 'docker')] : []), startDockerTool(self, options), commandTool(self, 'host'), ...processTools(self)];
+  return [commandTool(self, 'network'), ...(docker ? [commandTool(self, 'docker')] : []), startDockerTool(self, options), commandTool(self, 'host'), commandTool(self, 'simulator'), ...processTools(self)];
 }
 
 // What the system prompt says about services and what the sandbox blocks: it
 // is read for every request, so a Docker started since shows up.
-const HOST_PROMPT = ' When the sandbox blocks something the task needs (a missing runtime such as a JDK or a Node version, the member\'s sign-in for git pull or git push or a private registry, a file outside the project), do not stop and do not tell the member to run it: request run_on_host with the exact command; it runs on the member\'s machine once they approve. Only what needs the member themselves (their password for sudo or an installer, an interactive sign-in, a window to click) goes to ask_user, with the exact steps and the options to continue or skip; after their answer, check and carry on.';
+const HOST_PROMPT = ' When the sandbox blocks something the task needs (a missing runtime such as a JDK or a Node version, the member\'s sign-in for git pull or a private registry, a file outside the project), do not stop and do not tell the member to run it: request run_on_host with the exact command; it runs on the member\'s machine once they approve. The work ends at the handoff: commit locally, then report what is ready; push, open or merge a pull request, publish or deploy only when the member asked for it in this conversation, and each of those steps is asked about in every access mode. Only what needs the member themselves (their password for sudo or an installer, an interactive sign-in, a window to click) goes to ask_user, with the exact steps and the options to continue or skip; after their answer, check and carry on.';
 export function servicesPrompt(boundary) {
-  const simulator = ' The iOS Simulator is not available in the sandbox: ask the member with ask_user to run those tests.';
-  if (boundary.engine) return ' Docker is available through run_with_docker (the member approves each command): a database or service for tests (docker compose up -d, then the tests through bash or run_with_network), docker build, or Testcontainers tests. If the engine stops answering, start_docker asks the member to start it. Stop what you started when done unless the member wants it kept.' + simulator + HOST_PROMPT;
+  const simulator = ' The iOS Simulator and Android emulator are not reachable from bash: boot them, build and install the app, launch it, tap and type, and take screenshots with run_on_simulator (save the screenshot in the project, then read it to see the screen). Do not ask the member to run simulator steps you can run.';
+  if (boundary.engine) return ' Docker is available through run_with_docker (in Ask first the member approves each command): a database or service for tests (docker compose up -d, then the tests through bash or run_with_network), docker build, or Testcontainers tests. If the engine stops answering, start_docker asks the member to start it. Stop what you started when done unless the member wants it kept.' + simulator + HOST_PROMPT;
   if (boundary.dockerCli) return ' Docker is installed but not running: when the task needs it, call start_docker (the member approves), then run_with_docker.' + simulator + HOST_PROMPT;
   return ' Docker is not installed on this machine: when the task needs it, ask the member with ask_user (install it, or check another way).' + simulator + HOST_PROMPT;
 }

package/packages/piagent-core/managed/fetch-guard.mjs

@@ -1,4 +1,4 @@
-import { asksNothing } from './permission.mjs';
+import { asksOnlyHandoff } from './permission.mjs';
 import { approve } from './command-tools.mjs';
 
 // web_fetch is a request to any public https address: a page that tells the
@@ -6,7 +6,7 @@ import { approve } from './command-tools.mjs';
 // Documentation and package registries are read freely. Another host is asked
 // about once per conversation; an address there that carries a query or a
 // fragment (where data rides along) is asked about every time. Bypass asks
-// only about the latter. A helper cannot ask the member: it is told to hand
+// only about the latter: data sent out is a handoff. A helper cannot ask the member: it is told to hand
 // the address to the main agent.
 const TRUSTED = ['github.com', 'raw.githubusercontent.com', 'docs.github.com', 'npmjs.com', 'www.npmjs.com', 'registry.npmjs.org', 'pypi.org', 'docs.python.org',
   'developer.mozilla.org', 'nodejs.org', 'go.dev', 'pkg.go.dev', 'crates.io', 'docs.rs', 'doc.rust-lang.org', 'learn.microsoft.com', 'developer.apple.com',
@@ -21,7 +21,7 @@ export function fetchDecision(owner, role, raw) {
   if (trustedHost(host)) return null;
   const carries = Boolean(url.search || url.hash), known = owner.fetchHosts?.has(host);
   if (role !== 'main') return carries || !known ? 'refuse' : null;
-  if (asksNothing(owner)) return carries ? 'ask' : null;
+  if (asksOnlyHandoff(owner)) return carries ? 'ask' : null;
   return carries || !known ? 'ask' : null;
 }
 export async function guardFetch(owner, role, raw, id, signal, ctx) {

package/packages/piagent-core/managed/host-command.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { redactedText } from '../runtime/managed-failure.mjs';
+import { commandSegments, stripWrapper } from '../runtime/policy/handoff-policy.mjs';
 
 // Commands the member approved to run on their machine, outside the sandbox
 // (run_on_host, start_docker): installing a runtime the project needs, git
@@ -13,12 +14,14 @@ import { redactedText } from '../runtime/managed-failure.mjs';
 const PASSWORD = new Set(['sudo', 'doas', 'su', 'pkexec', 'passwd']);
 const SIGN_IN = [/^gh auth (login|refresh)\b/, /^(npm|pnpm) (login|adduser)\b/, /^yarn npm login\b/, /^docker login\b(?!.*--password-stdin)/, /^az login\b/,
   /^gcloud auth (login|application-default login)\b/, /^aws (configure\s*$|sso login\b)/, /^(firebase|vercel|wrangler|heroku|netlify) login\b/];
-const WRAPPERS = new Set(['env', 'command', 'exec', 'time', 'nohup']);
+// Read through the shared shell parser (policy-core.js): `(sudo ls)`,
+// `echo x & sudo ls` and `if …; then sudo …` are each a sudo.
 export function memberOnlyReason(command) {
-  for (const part of String(command).split(/&&|\|\||;|\||\n/)) {
-    const words = part.trim().split(/\s+/).filter(Boolean);
-    while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || WRAPPERS.has(words[0]))) words.shift();
-    const name = words[0]?.split('/').pop(), rest = words.join(' ');
+  for (const { words } of commandSegments(command)) {
+    const run = stripWrapper(words), prefix = words.slice(0, words.length - run.length).map(word => word.split('/').pop());
+    const elevated = prefix.find(word => PASSWORD.has(word));
+    if (elevated) return `${elevated} needs the member's password`;
+    const name = run[0], rest = run.join(' ');
     if (PASSWORD.has(name)) return `${name} needs the member's password`;
     if (name === 'installer' || name === 'softwareupdate') return `${name} needs the member's password`;
     if (SIGN_IN.some(rule => rule.test(rest))) return 'an interactive sign-in needs the member';
@@ -26,8 +29,13 @@ export function memberOnlyReason(command) {
   return null;
 }
 // Where credentials live on the member's machine. A command that names one
-// reads or moves secrets, so it is asked about even in Bypass.
-const CREDENTIALS = [/~\/\.(ssh|aws|gnupg|kube|docker|pi|codex|claude|piagent|config\/gh|config\/gcloud|azure|npmrc|netrc|pypirc|git-credentials)\b/, /\$HOME\/\.(ssh|aws|gnupg|kube|docker|pi|codex|claude|piagent)\b/,
+// reads or moves secrets, so it is asked about even in Bypass. A text check,
+// not a boundary: it catches the usual spellings (~/.ssh, $HOME/.ssh,
+// /Users/me/.ssh, `tar -C ~ .ssh`); the sandbox is what keeps secrets out of
+// plain bash. Folders whose names projects also use (.docker, .pi) count only
+// under a home directory.
+const HOME = String.raw`(?:~|\$HOME|\$\{HOME\}|/Users/[^/\s'"]+|/home/[^/\s'"]+|/root)/`;
+const CREDENTIALS = [/(^|[\s'"=:/])\.(ssh|aws|gnupg|kube|azure|npmrc|netrc|pypirc|git-credentials)(\b|\/|$)/, new RegExp(String.raw`${HOME}\.(docker|pi|codex|claude|piagent|config/gh|config/gcloud)\b`),
   /(^|[\s'"/])\.env(\.[\w-]+)?\b/, /\bauth\.json\b/, /\bcredentials(\.json)?\b/, /\bid_(rsa|ed25519|ecdsa|dsa)\b/, /\.(pem|p12|pfx|key)\b/,
   /\bsecurity\s+(find-(generic|internet)-password|dump-keychain|export)\b/, /Library\/Keychains\b/, /\bprintenv\b|(^|[;&|]\s*)env\s*($|[|;&>])/];
 export function credentialReason(command) {

package/packages/piagent-core/managed/member-mcp.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { evaluateMcpApproval } from '../runtime/mcp-repository-gate.mjs';
+import { mcpWriteAction } from '../runtime/policy/handoff-policy.mjs';
+import { userToolchains } from './toolchain.mjs';
+import { fenced } from './untrusted.mjs';
+
+// The member's MCP servers in company sessions. Company sessions load no Pi
+// extension of the member's, with one exception: the MCP adapter Piagent
+// installs (pi-mcp-adapter in Piagent's own Pi home). It reads the same
+// configuration as personal Piagent (piagent-mcp add, ~/.config/mcp/mcp.json,
+// a project's .mcp.json, /mcp) and the same logins (/mcp-auth), so a server the
+// member added once works in both. The member decides which servers exist;
+// company sessions keep the protections personal Piagent has: a server a
+// repository defines runs only once someone on this machine approved it, a
+// tool that writes to the server's system (create, update, push, merge,
+// publish, send… in its name) is asked about in every access mode, Bypass
+// included, since it hands work to the outside, and what a server returns
+// reaches the agent as data, not instructions.
+
+const ADAPTER = 'pi-mcp-adapter';
+const readJson = file => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+const inside = (file, dir) => { const relative = path.relative(dir, file); return !!relative && !relative.startsWith('..') && !path.isAbsolute(relative); };
+
+// The adapter the member installed in Piagent's Pi home and still lists among
+// its packages, or null. `piagent studio` starts from a cleared environment, so
+// the home is the default one (~/.piagent/agent) unless a caller names another.
+export function memberMcpAdapter(home = os.homedir(), agentDir = path.join(home, '.piagent', 'agent')) {
+  const packages = readJson(path.join(agentDir, 'settings.json'))?.packages;
+  const listed = Array.isArray(packages) && packages.some(entry => new RegExp(`(^|[:/])${ADAPTER}(@|$)`).test(String(typeof entry === 'string' ? entry : entry?.source ?? '')));
+  const dir = path.join(agentDir, 'npm', 'node_modules', ADAPTER);
+  if (!listed || !fs.existsSync(path.join(dir, 'package.json'))) return null;
+  return { agentDir, dir: fs.realpathSync(dir) };
+}
+
+// What the adapter and the servers it starts need from a cleared environment:
+// Piagent's Pi home (its mcp.json, logins and caches, shared with personal
+// Piagent) and a PATH that finds npx, uvx, docker… as in the member's
+// Terminal. Nothing else of the member's shell is passed, as for host commands.
+export function memberMcpEnvironment(adapter, home = os.homedir(), env = process.env) {
+  env.PI_CODING_AGENT_DIR ||= adapter.agentDir;
+  const toolchains = userToolchains(home);
+  const dirs = [...toolchains.bins, path.dirname(process.execPath), '/opt/homebrew/bin', '/usr/local/bin', ...(env.PATH ?? '/usr/bin:/bin').split(':')];
+  env.PATH = [...new Set(dirs.filter(Boolean))].join(':');
+  for (const [name, value] of Object.entries(toolchains.env)) env[name] ||= value;
+  return env;
+}
+
+// The MCP tool a call runs: the proxy's `tool` (`mcp` with tool and server),
+// or a direct tool the adapter registered. null for anything else.
+export function mcpToolCalled(toolName, input, fromAdapter) {
+  if (toolName === 'mcp') return typeof input?.tool === 'string' && input.tool.trim() ? { tool: input.tool.trim(), server: String(input.server ?? '').trim() } : null;
+  return fromAdapter(toolName) ? { tool: toolName, server: '' } : null;
+}
+
+// The repository approval gate on every tool call (as personal Piagent's
+// guard), the member's approval of an MCP write, and the adapter's results
+// fenced as data. Without an owner (no conversation to ask in) a write is refused.
+export function memberMcpGuard(cwd, adapterDir, owner = null) {
+  return pi => {
+    const fromAdapter = name => { const source = pi.getAllTools().find(tool => tool.name === name)?.sourceInfo?.path; return !!source && (source === adapterDir || inside(source, adapterDir)); };
+    pi.on('tool_call', async (event, ctx) => {
+      const decision = evaluateMcpApproval(cwd, event.toolName, event.input ?? {});
+      if (decision.block) return { block: true, reason: decision.reason };
+      const called = mcpToolCalled(event.toolName, event.input, fromAdapter);
+      const action = called && await mcpWriteAction(called.tool);
+      if (!action) return undefined;
+      if (!owner) return { block: true, reason: `MCP tool ${called.tool} writes outside (${action}) and no member can approve it here.` };
+      const { approve } = await import('./command-tools.mjs');
+      const name = called.server ? `${called.server} → ${called.tool}` : called.tool, args = JSON.stringify(event.input?.args ?? event.input ?? {}).slice(0, 600);
+      try {
+        await approve(owner, event.toolCallId, ctx?.signal, ctx, { toolName: event.toolName, rawAction: { tool: called.tool, server: called.server, input: event.input ?? {} }, commandPreview: name,
+          provider: called.server || 'mcp', requestedScope: 'mcp-handoff-once', reason: `The MCP tool ${name} writes outside this machine (${action}); every access mode asks before a handoff.`, riskClass: 'high',
+          allowConsequence: 'Run this exact MCP call once; it changes the system behind that server.', denyConsequence: 'The call does not run; the agent is told you declined.' },
+        { title: 'Công cụ MCP ghi ra ngoài', body: `${name}\n${args}\n\nCông cụ này ${action} trên hệ thống của server MCP. Mọi chế độ truy cập, kể cả Bypass, đều hỏi trước việc bàn giao ra ngoài.\n\nĐồng ý: chạy đúng lệnh gọi này một lần.\nTừ chối: không chạy, agent được báo bạn đã từ chối.` });
+      } catch { return { block: true, reason: `User denied MCP tool ${name}.` }; }
+      return undefined;
+    });
+    pi.on('tool_result', event => {
+      if (!fromAdapter(event.toolName)) return undefined;
+      const text = (event.content ?? []).filter(part => part?.type === 'text').map(part => part.text).join('\n');
+      const images = (event.content ?? []).filter(part => part?.type === 'image');
+      return { content: [{ type: 'text', text: fenced(`Result of MCP tool ${event.toolName}`, text) }, ...images] };
+    });
+  };
+}
+
+// The company session's own extension factories, with the member's MCP added
+// when the adapter is installed: [factories, extension paths] for inlineExtensions.
+export function withMemberMcp(cwd, factories, home = os.homedir(), owner = null) {
+  const adapter = memberMcpAdapter(home);
+  if (!adapter) return [factories, []];
+  memberMcpEnvironment(adapter, home);
+  return [[...factories, memberMcpGuard(cwd, adapter.dir, owner)], [adapter.dir]];
+}

package/packages/piagent-core/managed/memory-lessons.mjs

@@ -8,7 +8,7 @@ import { createHash } from 'node:crypto';
 import { redactedText } from '../runtime/managed-failure.mjs';
 import { isCheckCommand } from './workflow.mjs';
 
-const COMMAND_TOOLS = new Set(['bash','run_with_network','run_with_docker','run_on_host']);
+const COMMAND_TOOLS = new Set(['bash','run_with_network','run_with_docker','run_on_host','run_on_simulator']);
 const textOf = result => (result?.content ?? []).filter(p => p?.type === 'text').map(p => p.text ?? '').join('\n');
 const clean = (value, max) => redactedText(String(value ?? '')).replace(/\bas_(?:live|run)_[A-Za-z0-9_-]{8,}/g,'[REDACTED_SECRET]').split(os.homedir()).join('~').replace(/\s+/g,' ').trim().slice(0,max);
 const hash = s => createHash('sha256').update(s).digest('hex').slice(0,20);

package/packages/piagent-core/managed/permission.mjs

@@ -1,11 +1,13 @@
 // A company conversation's access, chosen by the member and kept with the
-// conversation: "workspace-write" asks before every command that needs the
-// internet; "trusted-full-access" (Full access) asks only for what must be
-// confirmed (runtime/policy/bypass-policy.mjs); "bypass" asks nothing, as
-// Codex's bypass mode, where the team's Harness allows it
+// conversation (runtime/policy/handoff-policy.mjs has both lists):
+// "workspace-write" (Ask first) asks before every command that leaves the
+// sandbox; "trusted-full-access" (Full access) asks only about the handoff and
+// what is destructive (mustConfirm); "bypass" runs the work and asks only about
+// the handoff (handoffReason: push, PR, publish, deploy, remote and cloud
+// tools, uploads), where the team's Harness allows it
 // (harness.configuration.bypass_mode, an administrator's switch in Studio).
-// The sandbox itself stays: bypass removes the questions, not the boundary.
-import { mustConfirm } from '../runtime/policy/bypass-policy.mjs';
+// The sandbox itself stays: bypass removes questions, not the boundary.
+import { handoffReason, mustConfirm } from '../runtime/policy/handoff-policy.mjs';
 
 export const PERMISSIONS = ['workspace-write', 'trusted-full-access', 'bypass'];
 const ENTRY = 'agent-watch-permission';
@@ -36,10 +38,15 @@ export function recordBypass(owner, manager) {
   const last = manager.getEntries().filter(e => e.type === 'custom' && e.customType === ALLOWANCE).at(-1)?.data;
   if ((last?.allowed === true) !== allowed) manager.appendCustomEntry(ALLOWANCE, { allowed, at: new Date().toISOString() });
 }
-// Whether this conversation may skip the questions Full access still asks.
-export const asksNothing = owner => effectivePermission(owner) === 'bypass';
+// Whether this conversation skips the questions Full access still asks
+// (everything but the handoff).
+export const asksOnlyHandoff = owner => effectivePermission(owner) === 'bypass';
 export const broadAccess = owner => ['trusted-full-access', 'bypass'].includes(effectivePermission(owner));
-// Why a network command must still be asked about: null runs it in Full
-// access or Bypass, 'ask' when the member asks first.
-export const networkConfirmation = async (owner, command) => asksNothing(owner) ? null
-  : effectivePermission(owner) === 'trusted-full-access' ? mustConfirm(command) : 'ask';
+// Why a command that leaves the sandbox must be asked about: the reason, or
+// 'ask' in Ask first, or null to run it. Every mode asks about the handoff.
+export const networkConfirmation = async (owner, command) => {
+  const mode = effectivePermission(owner);
+  if (mode === 'bypass') return handoffReason(command);
+  if (mode === 'trusted-full-access') return mustConfirm(command);
+  return 'ask';
+};

package/packages/piagent-core/managed/repository-operation.mjs

@@ -107,7 +107,7 @@ export async function executeRepositoryFetch(boundary,plan,signal,{transport=fet
 }
 
 // The fetch_origin tool of a company conversation: one approved fetch of the
-// GitHub origin (Bypass fetches without asking).
+// GitHub origin (Full access and Bypass fetch without asking: it only downloads).
 export function fetchOriginTool(self) {
   return {name:'fetch_origin',label:'Fetch origin',description:'Request one approved GitHub origin fetch. Refreshes origin branches without changing working files. Does not expose credentials or allow arbitrary network commands. When the conversation folder holds several repositories, pass path: the repository folder inside it. Use this instead of git fetch, which has no GitHub sign-in here.',
     parameters:{type:'object',properties:{path:{type:'string',maxLength:500,description:'Repository folder inside the conversation folder, such as "api"; omit when the conversation folder is the repository.'}},additionalProperties:false},