@craftsamo/git-tools 0.1.0 → 0.2.0

package/.antigravity-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "git-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Git tools for coding agents: state, commits, rewrites and stacked branches, worktrees and pushing.",
   "author": {
     "name": "craftsamo",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "git-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Git tools for coding agents: state, commits, rewrites and stacked branches, worktrees and pushing.",
   "author": {
     "name": "craftsamo",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "git-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Git tools for coding agents: state, commits, rewrites and stacked branches, worktrees and pushing.",
   "author": {
     "name": "craftsamo",
@@ -15,6 +15,7 @@
       "command": "node",
       "args": ["dist/mcp.js"],
       "cwd": ".",
+      "default_tools_approval_mode": "writes",
       "env_vars": [
         "GIT_TOOLS_TOOLSETS",
         "GIT_TOOLS_READ_ONLY",

package/README.md

@@ -96,7 +96,15 @@ codex plugin add git-tools@craft-agent
 
 Codex turns `-` into `_` in server names, so it shows the tools as
 `mcp__git_tools__git_*`. It starts the MCP server in the plugin's
-install directory, which is never the caller's working tree.
+install directory and passes no roots, so the server takes each call's directory
+from what Codex sends with the call: its sandbox state, which the server asks
+for, else the one workspace it names.
+
+The plugin declares `default_tools_approval_mode = "writes"`: Codex asks before
+every tool not marked read-only. A user's
+`[plugins."<plugin>".mcp_servers.<server>]` setting can only tighten it. Setting
+`auto` there yields `prompt` (reads asked too), since Codex treats `auto` and
+`writes` as incomparable.
 
 ### Grok Build
 
@@ -244,8 +252,10 @@ The toolset is opt-in. The `git-push` skill says how they fit together.
    the entry points do. A tool that runs a program is tested against a fake of
    that program on `PATH`; no test reaches a real service.
 3. List it in `src/tools.ts`. A new toolset goes into `toolsets` in
-   `src/project.ts` (and `defaultToolsets` when it is on by default), and a
-   variable the tool reads besides the settings into `toolVariables`.
+   `src/project.ts` (and `defaultToolsets` when it is on by default), a
+   setting of the package's own into `options` (and `OPTIONS` in `project.py`
+   with `config_schema` in `plugin.yaml`), and a variable the tool reads
+   besides the settings into `toolVariables`.
 4. Add or update the toolset's skill, `skills/<prefix>-<toolset>/SKILL.md`,
    whose frontmatter names the toolset under `metadata`.
 5. Run `pnpm run build && pnpm run manifests` to list the tool in
@@ -272,8 +282,11 @@ Where a write is asked about, and where it is not:
 
 - **OpenCode** grants any action no rule names, so a write runs unasked unless
   a rule asks for it: add the `git_*` rule shown under [OpenCode](#opencode).
-- **Codex** under `codex exec`, and **Grok Build** under `grok -p`, refuse a
-  write they cannot ask about, unless it is allowed beforehand.
+- **Codex** asks before every write because of the plugin's approval mode.
+  Under `codex exec` it refuses with "MCP tool call requires approval, but
+  approval policy is never".
+- **Grok Build** under `grok -p` refuses a write it cannot ask about, unless it
+  is allowed beforehand.
 - **Grok Build** calls the plugin's tools through its `use_tool` tool, and the
   agent often names a tool without its server first. Grok checks the rules
   against the name as given, so the server-qualified rule alone does not match
@@ -298,15 +311,17 @@ variable, and an option or setting wins over the variable too.
 | `exclude_tools`        | `--exclude-tools`        | `GIT_TOOLS_EXCLUDE_TOOLS`        | single tools to remove by ID; wins over `tools` and `toolsets`                                             |
 | `confirm`              | `--confirm`              | `GIT_TOOLS_CONFIRM`              | MCP server only: `harness` (default) or `elicitation`, as the conventions say                              |
 | `language`             | `--language`             | `GIT_TOOLS_LANGUAGE`             | native plugins only: the approval prompt's language, such as `ja`                                          |
+| `emoji`                | —                        | —                                | Hermes only: the emoji shown beside each toolset, by toolset name (`""` for none)                          |
 | `published_text_rules` | `--published-text-rules` | `GIT_TOOLS_PUBLISHED_TEXT_RULES` | the absolute path of a JSON file of published-text rules (see the push toolset); unset, nothing is checked |
 | `worktree_root`        | `--worktree-root`        | `GIT_TOOLS_WORKTREE_ROOT`        | the absolute path where task worktrees go (`~` allowed); unset, `~/worktrees`                              |
 
-Lists are comma-separated in a flag or a variable. `published_text_rules` and
-`worktree_root` hold text, trimmed and blank meaning unset, and are read by the
-tools themselves; the plugin options and Hermes settings name them the same
-way. The layout is `<root>/<repository>/<branch>`, with each `/` of the branch
-written `-`; the repository is the last part of `origin`'s URL without `.git`,
-else the folder name of the main checkout. Where each harness reads them:
+Lists are comma-separated in a flag or a variable. A package's own settings,
+listed in `options` in `src/project.ts`, take a row each here and are read the
+same way: `published_text_rules` and `worktree_root` hold text, trimmed and
+blank meaning unset, and the tools read them themselves. The layout is
+`<root>/<repository>/<branch>`, with each `/` of the branch written `-`; the
+repository is the last part of `origin`'s URL without `.git`, else the folder
+name of the main checkout. Where each harness reads them:
 
 - **OpenCode** takes the plugin `options` shown above, with lists as arrays and
   `read_only` as a boolean, and falls back to the variables. V2 runs plugins in
@@ -358,7 +373,7 @@ else the folder name of the main checkout. Where each harness reads them:
 ## Layout
 
 - `src/project.ts` — the package's name, tool ID prefix, setting prefix,
-  toolsets and the other variables its tools read.
+  toolsets, tool options and the other variables its tools read.
 - `src/core/` — the tool contract and the tools, free of any harness and of
   the project's names.
 - `src/tools.ts` — the list of every tool, which each entry point registers.

package/dist/cli.js

@@ -26,8 +26,8 @@ var PROJECT = {
   toolsets: ["repo", "commit", "rebase", "worktree", "push"],
   /** The toolsets on when a setting names none. */
   defaultToolsets: ["repo", "commit", "rebase"],
-  /** The settings the tools themselves read, beside the ones every entry point takes; each holds text and is named in snake_case. */
-  options: ["published_text_rules", "worktree_root"],
+  /** The package's own settings, which the tools themselves read: each snake_case name and its type, with bounds when it needs them. */
+  options: { published_text_rules: "text", worktree_root: "text" },
   /** The environment variables the tools read besides the settings, which Codex forwards to the server after them. */
   toolVariables: [
     "LANGUAGE",
@@ -22994,7 +22994,8 @@ function compileRules(path, entries) {
   });
 }
 async function loadPublishedTextRules(options, signal) {
-  const path = options?.[PUBLISHED_TEXT_RULES_OPTION]?.trim();
+  const option = options?.[PUBLISHED_TEXT_RULES_OPTION];
+  const path = typeof option === "string" ? option.trim() : void 0;
   if (!path) return [];
   if (!isAbsolute4(path)) throw invalidRules(path, "the value must be an absolute path");
   return compileRules(path, parseRulesJson(path, await readRulesFile(path, signal)));
@@ -25349,7 +25350,8 @@ function expandHome(value) {
   return value.startsWith(HOME_PREFIX) ? join8(homeDirectory(), value.slice(HOME_PREFIX.length)) : value;
 }
 function worktreeRoot(ctx) {
-  const value = ctx.options?.[WORKTREE_ROOT_OPTION]?.trim();
+  const option = ctx.options?.[WORKTREE_ROOT_OPTION];
+  const value = typeof option === "string" ? option.trim() : void 0;
   if (!value) return join8(homeDirectory(), DEFAULT_ROOT_FOLDER);
   const expanded = expandHome(value);
   if (!isAbsolute5(expanded)) {
@@ -26440,6 +26442,8 @@ var PROJECT_PROFILE = {
 };
 
 // src/entry/settings.ts
+import { homedir as homedir2 } from "node:os";
+import { isAbsolute as isAbsolute6, join as join11, resolve as resolvePath, sep as sep3 } from "node:path";
 var CONFIRM_MODES = ["harness", "elicitation"];
 var ALL_TOOLSETS = "all";
 var TRUE_VALUES = ["1", "true"];
@@ -26451,10 +26455,17 @@ var OPTIONS = {
   exclude_tools: { flag: "--exclude-tools", envSuffix: "EXCLUDE_TOOLS" },
   confirm: { flag: "--confirm", envSuffix: "CONFIRM" }
 };
+function profileOptions(profile) {
+  return profile.options ?? {};
+}
 function settingOptions(profile) {
-  const toolOptions = profile.options.map((name) => [
+  const toolOptions = Object.entries(profileOptions(profile)).map(([name, spec]) => [
     name,
-    { flag: `--${name.replace(/_/g, "-")}`, envSuffix: name.toUpperCase() }
+    {
+      flag: `--${name.replace(/_/g, "-")}`,
+      envSuffix: name.toUpperCase(),
+      ...optionType(spec) === "boolean" && { boolean: true }
+    }
   ]);
   return { ...OPTIONS, ...Object.fromEntries(toolOptions) };
 }
@@ -26462,8 +26473,9 @@ function envName(name, profile) {
   return `${profile.envPrefix}_${settingOptions(profile)[name].envSuffix}`;
 }
 function readFlags(argv, profile) {
-  const options = settingOptions(profile);
-  const byFlag = new Map(Object.entries(options).map(([name, option]) => [option.flag, { name, ...option }]));
+  const byFlag = new Map(
+    Object.entries(settingOptions(profile)).map(([name, option]) => [option.flag, { name, ...option }])
+  );
   const given = {};
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -26515,19 +26527,103 @@ function parseConfirm(value, source) {
   }
   return mode;
 }
+function parseNumber(value, source) {
+  const trimmed2 = value.trim();
+  const parsed = trimmed2 === "" ? Number.NaN : Number(trimmed2);
+  if (!Number.isFinite(parsed)) {
+    throw new ToolError("invalid_argument", `Unknown number "${value}" in ${source}; use a finite number.`);
+  }
+  return parsed;
+}
+function absolutePath(text, source, env) {
+  const home = env.HOME !== void 0 && isAbsolute6(env.HOME) ? env.HOME : homedir2();
+  const expanded = text === "~" || text.startsWith("~/") || text.startsWith(`~${sep3}`) ? join11(home, text.slice(1)) : text;
+  if (!isAbsolute6(expanded)) throw new ToolError("invalid_argument", `${source} must be an absolute path.`);
+  return resolvePath(expanded);
+}
+function absolutePaths(items, source, env) {
+  return items.length > 0 ? items.map((item) => absolutePath(item, source, env)) : void 0;
+}
 function envText(name, env, profile) {
   const variable = envName(name, profile);
   const text = env[variable];
   return text === void 0 || text.trim() === "" ? void 0 : { text, source: variable };
 }
+function optionType(spec) {
+  return typeof spec === "string" ? spec : spec.type;
+}
+function itemCount(count) {
+  return count === 1 ? "1 item" : `${count} items`;
+}
+function numberBoundsError({ integer: integer2, min, max }, source) {
+  const range = min !== void 0 && max !== void 0 ? ` from ${min} to ${max}` : min !== void 0 ? ` of at least ${min}` : max !== void 0 ? ` of at most ${max}` : "";
+  return new ToolError("invalid_argument", `${source} must be ${integer2 ? "a whole number" : "a number"}${range}.`);
+}
+function countBoundsError({ min, max }, source) {
+  const range = min !== void 0 && max !== void 0 ? `from ${min} to ${max} items` : min !== void 0 ? `at least ${itemCount(min)}` : `at most ${itemCount(max)}`;
+  return new ToolError("invalid_argument", `${source} must list ${range}.`);
+}
+function withinBounds(spec, value, source) {
+  if (value === void 0 || typeof spec === "string") return value;
+  const bounds = spec;
+  const { integer: integer2, min, max } = bounds;
+  if (typeof value === "number") {
+    if (integer2 && !Number.isInteger(value) || min !== void 0 && value < min || max !== void 0 && value > max) {
+      throw numberBoundsError(bounds, source);
+    }
+  } else if (typeof value === "object" && (min !== void 0 && value.length < min || max !== void 0 && value.length > max)) {
+    throw countBoundsError(bounds, source);
+  }
+  return value;
+}
+function parseOptionText(spec, given, env) {
+  return withinBounds(spec, parseTypedText(optionType(spec), given, env), given.source);
+}
+function parseTypedText(kind, given, env) {
+  switch (kind) {
+    case "text":
+      return nonBlank(given.text);
+    case "boolean":
+      return parseBoolean(given.text, given.source);
+    case "number":
+      return parseNumber(given.text, given.source);
+    case "list": {
+      const items = splitList(given.text);
+      return items.length > 0 ? items : void 0;
+    }
+    case "path": {
+      const text = nonBlank(given.text);
+      return text === void 0 ? void 0 : absolutePath(text, given.source, env);
+    }
+    case "paths":
+      return absolutePaths(splitList(given.text), given.source, env);
+  }
+}
 function optionsFrom(flags, env, profile) {
   const options = {};
-  for (const name of profile.options) {
-    const text = nonBlank(flags[name] ?? envText(name, env, profile)?.text);
-    if (text !== void 0) options[name] = text;
+  for (const [name, spec] of Object.entries(profileOptions(profile))) {
+    if (flags[name] !== void 0) {
+      const parsed = parseOptionText(spec, { text: flags[name], source: settingOptions(profile)[name].flag }, env);
+      if (parsed !== void 0) options[name] = parsed;
+      continue;
+    }
+    const fromEnv = envText(name, env, profile);
+    if (fromEnv !== void 0) {
+      const parsed = parseOptionText(spec, fromEnv, env);
+      if (parsed !== void 0) options[name] = parsed;
+    }
   }
   return options;
 }
+function parseToolOptions(argv, env, profile = PROJECT_PROFILE) {
+  const flags = readFlags(argv, profile);
+  const known = profileOptions(profile);
+  const other = Object.keys(flags).find((name) => !(name in known));
+  if (other !== void 0) {
+    throw new ToolError("invalid_argument", `Unknown option "${settingOptions(profile)[other].flag}".`);
+  }
+  return optionsFrom(flags, env, profile);
+}
 function parseSettings(argv, env, profile = PROJECT_PROFILE) {
   const flags = readFlags(argv, profile);
   const value = (name) => flags[name] !== void 0 ? { text: flags[name], source: OPTIONS[name].flag } : envText(name, env, profile);
@@ -26556,14 +26652,6 @@ function parseToolSettings(argv, env, profile = PROJECT_PROFILE) {
   );
   return settings;
 }
-function parseToolOptions(argv, env, profile = PROJECT_PROFILE) {
-  const flags = readFlags(argv, profile);
-  const other = Object.keys(flags).find((name) => !profile.options.includes(name));
-  if (other !== void 0) {
-    throw new ToolError("invalid_argument", `Unknown option "${settingOptions(profile)[other].flag}".`);
-  }
-  return optionsFrom(flags, env, profile);
-}
 function languageVariable(profile = PROJECT_PROFILE) {
   return `${profile.envPrefix}_LANGUAGE`;
 }

package/dist/mcp.js

@@ -29094,6 +29094,10 @@ function packageRoot(bundleUrl) {
   return dirname2(dirname2(fileURLToPath(bundleUrl)));
 }
 
+// src/entry/settings.ts
+import { homedir } from "node:os";
+import { isAbsolute as isAbsolute2, join as join2, resolve as resolvePath, sep as sep2 } from "node:path";
+
 // src/project.ts
 var PROJECT = {
   /** The plugin, MCP server and program name. */
@@ -29108,8 +29112,8 @@ var PROJECT = {
   toolsets: ["repo", "commit", "rebase", "worktree", "push"],
   /** The toolsets on when a setting names none. */
   defaultToolsets: ["repo", "commit", "rebase"],
-  /** The settings the tools themselves read, beside the ones every entry point takes; each holds text and is named in snake_case. */
-  options: ["published_text_rules", "worktree_root"],
+  /** The package's own settings, which the tools themselves read: each snake_case name and its type, with bounds when it needs them. */
+  options: { published_text_rules: "text", worktree_root: "text" },
   /** The environment variables the tools read besides the settings, which Codex forwards to the server after them. */
   toolVariables: [
     "LANGUAGE",
@@ -29169,10 +29173,17 @@ var OPTIONS = {
   exclude_tools: { flag: "--exclude-tools", envSuffix: "EXCLUDE_TOOLS" },
   confirm: { flag: "--confirm", envSuffix: "CONFIRM" }
 };
+function profileOptions(profile) {
+  return profile.options ?? {};
+}
 function settingOptions(profile) {
-  const toolOptions = profile.options.map((name) => [
+  const toolOptions = Object.entries(profileOptions(profile)).map(([name, spec]) => [
     name,
-    { flag: `--${name.replace(/_/g, "-")}`, envSuffix: name.toUpperCase() }
+    {
+      flag: `--${name.replace(/_/g, "-")}`,
+      envSuffix: name.toUpperCase(),
+      ...optionType(spec) === "boolean" && { boolean: true }
+    }
   ]);
   return { ...OPTIONS, ...Object.fromEntries(toolOptions) };
 }
@@ -29180,8 +29191,9 @@ function envName(name, profile) {
   return `${profile.envPrefix}_${settingOptions(profile)[name].envSuffix}`;
 }
 function readFlags(argv, profile) {
-  const options = settingOptions(profile);
-  const byFlag = new Map(Object.entries(options).map(([name, option]) => [option.flag, { name, ...option }]));
+  const byFlag = new Map(
+    Object.entries(settingOptions(profile)).map(([name, option]) => [option.flag, { name, ...option }])
+  );
   const given = {};
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -29233,16 +29245,91 @@ function parseConfirm(value, source) {
   }
   return mode;
 }
+function parseNumber(value, source) {
+  const trimmed2 = value.trim();
+  const parsed = trimmed2 === "" ? Number.NaN : Number(trimmed2);
+  if (!Number.isFinite(parsed)) {
+    throw new ToolError("invalid_argument", `Unknown number "${value}" in ${source}; use a finite number.`);
+  }
+  return parsed;
+}
+function absolutePath(text, source, env) {
+  const home = env.HOME !== void 0 && isAbsolute2(env.HOME) ? env.HOME : homedir();
+  const expanded = text === "~" || text.startsWith("~/") || text.startsWith(`~${sep2}`) ? join2(home, text.slice(1)) : text;
+  if (!isAbsolute2(expanded)) throw new ToolError("invalid_argument", `${source} must be an absolute path.`);
+  return resolvePath(expanded);
+}
+function absolutePaths(items, source, env) {
+  return items.length > 0 ? items.map((item) => absolutePath(item, source, env)) : void 0;
+}
 function envText(name, env, profile) {
   const variable = envName(name, profile);
   const text = env[variable];
   return text === void 0 || text.trim() === "" ? void 0 : { text, source: variable };
 }
+function optionType(spec) {
+  return typeof spec === "string" ? spec : spec.type;
+}
+function itemCount(count) {
+  return count === 1 ? "1 item" : `${count} items`;
+}
+function numberBoundsError({ integer: integer2, min, max }, source) {
+  const range = min !== void 0 && max !== void 0 ? ` from ${min} to ${max}` : min !== void 0 ? ` of at least ${min}` : max !== void 0 ? ` of at most ${max}` : "";
+  return new ToolError("invalid_argument", `${source} must be ${integer2 ? "a whole number" : "a number"}${range}.`);
+}
+function countBoundsError({ min, max }, source) {
+  const range = min !== void 0 && max !== void 0 ? `from ${min} to ${max} items` : min !== void 0 ? `at least ${itemCount(min)}` : `at most ${itemCount(max)}`;
+  return new ToolError("invalid_argument", `${source} must list ${range}.`);
+}
+function withinBounds(spec, value, source) {
+  if (value === void 0 || typeof spec === "string") return value;
+  const bounds = spec;
+  const { integer: integer2, min, max } = bounds;
+  if (typeof value === "number") {
+    if (integer2 && !Number.isInteger(value) || min !== void 0 && value < min || max !== void 0 && value > max) {
+      throw numberBoundsError(bounds, source);
+    }
+  } else if (typeof value === "object" && (min !== void 0 && value.length < min || max !== void 0 && value.length > max)) {
+    throw countBoundsError(bounds, source);
+  }
+  return value;
+}
+function parseOptionText(spec, given, env) {
+  return withinBounds(spec, parseTypedText(optionType(spec), given, env), given.source);
+}
+function parseTypedText(kind, given, env) {
+  switch (kind) {
+    case "text":
+      return nonBlank(given.text);
+    case "boolean":
+      return parseBoolean(given.text, given.source);
+    case "number":
+      return parseNumber(given.text, given.source);
+    case "list": {
+      const items = splitList(given.text);
+      return items.length > 0 ? items : void 0;
+    }
+    case "path": {
+      const text = nonBlank(given.text);
+      return text === void 0 ? void 0 : absolutePath(text, given.source, env);
+    }
+    case "paths":
+      return absolutePaths(splitList(given.text), given.source, env);
+  }
+}
 function optionsFrom(flags, env, profile) {
   const options = {};
-  for (const name of profile.options) {
-    const text = nonBlank(flags[name] ?? envText(name, env, profile)?.text);
-    if (text !== void 0) options[name] = text;
+  for (const [name, spec] of Object.entries(profileOptions(profile))) {
+    if (flags[name] !== void 0) {
+      const parsed = parseOptionText(spec, { text: flags[name], source: settingOptions(profile)[name].flag }, env);
+      if (parsed !== void 0) options[name] = parsed;
+      continue;
+    }
+    const fromEnv = envText(name, env, profile);
+    if (fromEnv !== void 0) {
+      const parsed = parseOptionText(spec, fromEnv, env);
+      if (parsed !== void 0) options[name] = parsed;
+    }
   }
   return options;
 }
@@ -30375,11 +30462,11 @@ import { stat as stat4 } from "node:fs/promises";
 
 // src/core/commit/lint.ts
 import { readFile, stat as stat3 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 
 // src/core/repo/conventions.ts
 import { stat as stat2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 var DEFAULT_SAMPLE = 30;
 var MAX_SAMPLE = 200;
 var SUBJECTS_MAX = 15;
@@ -30421,7 +30508,7 @@ var conventionsSchema = external_exports.object({
 });
 async function isFile(root, path) {
   try {
-    return (await stat2(join2(root, path))).isFile();
+    return (await stat2(join3(root, path))).isFile();
   } catch {
     return false;
   }
@@ -30603,7 +30690,7 @@ async function isFile2(path) {
   }
 }
 async function commitlintHook(root, signal) {
-  const candidates = [await gitPath(root, "hooks/commit-msg", signal), join3(root, HUSKY_HOOK)];
+  const candidates = [await gitPath(root, "hooks/commit-msg", signal), join4(root, HUSKY_HOOK)];
   for (const path of candidates) {
     let text;
     try {
@@ -30618,10 +30705,10 @@ async function commitlintHook(root, signal) {
 }
 async function commitlintConfigured(root) {
   for (const name of COMMITLINT_CONFIG_FILES) {
-    if (await isFile2(join3(root, name))) return true;
+    if (await isFile2(join4(root, name))) return true;
   }
   try {
-    const manifest = JSON.parse(await readFile(join3(root, "package.json"), "utf8"));
+    const manifest = JSON.parse(await readFile(join4(root, "package.json"), "utf8"));
     return typeof manifest === "object" && manifest !== null && "commitlint" in manifest;
   } catch {
     return false;
@@ -30629,7 +30716,7 @@ async function commitlintConfigured(root) {
 }
 async function commitlint(root, message, signal) {
   const hook = await commitlintHook(root, signal);
-  const binary = join3(root, COMMITLINT_BIN);
+  const binary = join4(root, COMMITLINT_BIN);
   if (await isFile2(binary)) {
     const result = await exec([binary], {
       cwd: root,
@@ -31192,7 +31279,7 @@ async function readAmendCheck(root, sha, signal) {
 
 // src/core/commit/hunks.ts
 import { createHash as createHash2 } from "node:crypto";
-import { isAbsolute as isAbsolute2, relative as relative2, resolve, sep as sep2 } from "node:path";
+import { isAbsolute as isAbsolute3, relative as relative2, resolve, sep as sep3 } from "node:path";
 var MAX_LISTED_HUNKS = 200;
 var PREVIEW_LINES = 8;
 var DIGEST_LENGTH = 16;
@@ -31324,7 +31411,7 @@ function diffDigest(diff) {
 function checkPaths(root, paths) {
   for (const path of paths) {
     const inside = relative2(root, resolve(root, path));
-    if (inside === ".." || inside.startsWith(`..${sep2}`) || isAbsolute2(inside)) {
+    if (inside === ".." || inside.startsWith(`..${sep3}`) || isAbsolute3(inside)) {
       throw new ToolError(
         "invalid_argument",
         `${path} is outside the working tree (${root}); name files or directories inside it.`
@@ -31548,7 +31635,7 @@ var commitStage = defineTool({
 // src/core/commit/verify.ts
 import { mkdtemp, realpath as realpath2, rm, stat as stat5 } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { isAbsolute as isAbsolute3, join as join4 } from "node:path";
+import { isAbsolute as isAbsolute4, join as join5 } from "node:path";
 var COMMITS_MAX = 30;
 var OUTPUT_TAIL_LINES = 40;
 var TIMEOUT_DEFAULT_SEC = 600;
@@ -31602,7 +31689,7 @@ ${result.stderr}`.trim().split("\n").slice(-OUTPUT_TAIL_LINES).join("\n");
 }
 function checkDir(dir) {
   const relative3 = dir?.trim() || ".";
-  if (isAbsolute3(relative3) || relative3.split(/[\\/]/).includes("..")) {
+  if (isAbsolute4(relative3) || relative3.split(/[\\/]/).includes("..")) {
     throw new ToolError("invalid_argument", "dir must be a relative path inside the repository.");
   }
   return relative3;
@@ -31684,14 +31771,14 @@ var commitVerify = defineTool({
       ctx,
       `Run \`${args.command}\` at each of ${commits.length} commits of ${branch} in a throwaway worktree.`
     );
-    const parent = await realpath2(await mkdtemp(join4(tmpdir(), TEMP_DIR_PREFIX)));
-    const tree = join4(parent, "tree");
+    const parent = await realpath2(await mkdtemp(join5(tmpdir(), TEMP_DIR_PREFIX)));
+    const tree = join5(parent, "tree");
     const results = [];
     let setup = null;
     try {
       await git(["worktree", "add", "--detach", "--quiet", tree, commits[0]], { cwd: root, signal, hooks: false });
       const run = async (command) => {
-        const cwd = join4(tree, dir);
+        const cwd = join5(tree, dir);
         const present = await stat5(cwd).then(
           (stats) => stats.isDirectory(),
           () => false
@@ -31770,7 +31857,7 @@ async function compareBranch(root, remote, selected, expect, signal) {
 
 // src/core/push/published-text.ts
 import { readFile as readFile2, stat as stat6 } from "node:fs/promises";
-import { isAbsolute as isAbsolute4 } from "node:path";
+import { isAbsolute as isAbsolute5 } from "node:path";
 var PUBLISHED_TEXT_RULES_OPTION = "published_text_rules";
 var MAX_FILE_BYTES = 64 * 1024;
 var MAX_RULES = 100;
@@ -31839,9 +31926,10 @@ function compileRules(path, entries) {
   });
 }
 async function loadPublishedTextRules(options, signal) {
-  const path = options?.[PUBLISHED_TEXT_RULES_OPTION]?.trim();
+  const option = options?.[PUBLISHED_TEXT_RULES_OPTION];
+  const path = typeof option === "string" ? option.trim() : void 0;
   if (!path) return [];
-  if (!isAbsolute4(path)) throw invalidRules(path, "the value must be an absolute path");
+  if (!isAbsolute5(path)) throw invalidRules(path, "the value must be an absolute path");
   return compileRules(path, parseRulesJson(path, await readRulesFile(path, signal)));
 }
 var publishedTextFindingSchema = external_exports.object({
@@ -32796,11 +32884,11 @@ var rebaseRead = defineTool({
 // src/core/rebase/resume.ts
 import { createHash as createHash3 } from "node:crypto";
 import { readFile as readFile5 } from "node:fs/promises";
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 
 // src/core/conflicts.ts
 import { readFile as readFile3 } from "node:fs/promises";
-import { basename as basename2, join as join5 } from "node:path";
+import { basename as basename2, join as join6 } from "node:path";
 var REGION_MAX = 20;
 var SIDE_LINES_MAX = 40;
 var LOCKFILES = {
@@ -32912,7 +33000,7 @@ async function readConflictFile(root, path, xy, operation) {
   }
   let text;
   try {
-    text = await readFile3(join5(root, path), "utf8");
+    text = await readFile3(join6(root, path), "utf8");
   } catch {
     return { ...file2, region_count: 0, regions: [] };
   }
@@ -32995,13 +33083,13 @@ var rebaseOutcomeSchema = external_exports.object({
 
 // src/core/rebase/rebase-state.ts
 import { readFile as readFile4 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 var HEADS_PREFIX = "refs/heads/";
 var STATE_DIRS = ["rebase-merge", "rebase-apply"];
 var UPDATE_REFS_LINES = 3;
 async function readStateFile(dir, name) {
   try {
-    return (await readFile4(join6(dir, name), "utf8")).trim();
+    return (await readFile4(join7(dir, name), "utf8")).trim();
   } catch {
     return void 0;
   }
@@ -33176,7 +33264,7 @@ async function conflictedFiles(root, signal) {
   for (const path of await unmergedPaths(root, signal)) {
     let content;
     try {
-      content = await readFile5(join7(root, path));
+      content = await readFile5(join8(root, path));
     } catch {
       content = null;
     }
@@ -34175,8 +34263,8 @@ var repoRead = defineTool({
 import { lstat } from "node:fs/promises";
 
 // src/core/worktree/layout.ts
-import { homedir } from "node:os";
-import { basename as basename3, dirname as dirname3, isAbsolute as isAbsolute5, join as join8, resolve as resolve2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { basename as basename3, dirname as dirname3, isAbsolute as isAbsolute6, join as join9, resolve as resolve2 } from "node:path";
 var WORKTREE_ROOT_OPTION = "worktree_root";
 var DEFAULT_ROOT_FOLDER = "worktrees";
 var HOME_MARK = "~";
@@ -34187,17 +34275,18 @@ var URL_SEPARATOR = /[/:]/;
 var TRAILING_SLASHES = /\/+$/;
 var NOT_A_NAME = [".", ".."];
 function homeDirectory() {
-  return process.env.HOME?.trim() || homedir();
+  return process.env.HOME?.trim() || homedir2();
 }
 function expandHome(value) {
   if (value === HOME_MARK) return homeDirectory();
-  return value.startsWith(HOME_PREFIX) ? join8(homeDirectory(), value.slice(HOME_PREFIX.length)) : value;
+  return value.startsWith(HOME_PREFIX) ? join9(homeDirectory(), value.slice(HOME_PREFIX.length)) : value;
 }
 function worktreeRoot(ctx) {
-  const value = ctx.options?.[WORKTREE_ROOT_OPTION]?.trim();
-  if (!value) return join8(homeDirectory(), DEFAULT_ROOT_FOLDER);
+  const option = ctx.options?.[WORKTREE_ROOT_OPTION];
+  const value = typeof option === "string" ? option.trim() : void 0;
+  if (!value) return join9(homeDirectory(), DEFAULT_ROOT_FOLDER);
   const expanded = expandHome(value);
-  if (!isAbsolute5(expanded)) {
+  if (!isAbsolute6(expanded)) {
     throw new ToolError(
       "invalid_argument",
       `The ${WORKTREE_ROOT_OPTION} setting (${value}): the value must be an absolute path, or start with ${HOME_PREFIX}.`
@@ -34219,7 +34308,7 @@ async function repositoryName(root, signal) {
   return fromUrl || basename3(await mainCheckout(root, signal)).replace(GIT_SUFFIX, "");
 }
 function worktreePath(root, repository, branch) {
-  return join8(root, repository, branch.replaceAll("/", "-"));
+  return join9(root, repository, branch.replaceAll("/", "-"));
 }
 
 // src/core/worktree/add-plan.ts
@@ -34482,7 +34571,7 @@ var worktreeAdd = defineTool({
 });
 
 // src/core/worktree/list.ts
-import { dirname as dirname5, join as join9 } from "node:path";
+import { dirname as dirname5, join as join10 } from "node:path";
 var worktreeSchema = external_exports.object({
   directory: external_exports.string().describe("The worktree's directory: its real path when it exists, else as git prints it."),
   branch: external_exports.string().nullable().describe("The checked-out branch's name; null when HEAD is detached or bare."),
@@ -34517,7 +34606,7 @@ async function readWorktreeList(callerRoot, root, signal) {
   const repository = await repositoryName(callerRoot, signal);
   const [caller, layoutFolder, entries] = await Promise.all([
     realpathOrSelf(callerRoot),
-    realpathOfExisting(join9(root, repository)),
+    realpathOfExisting(join10(root, repository)),
     listWorktrees(callerRoot, signal)
   ]);
   return {
@@ -34696,7 +34785,7 @@ async function planRemove(request) {
 
 // src/core/worktree/remove-run.ts
 import { rmdir } from "node:fs/promises";
-import { dirname as dirname6, join as join10 } from "node:path";
+import { dirname as dirname6, join as join11 } from "node:path";
 
 // src/core/worktree/landed.ts
 var LANDED_READ_TIMEOUT_MS = PROTECTION_READ_TIMEOUT_MS;
@@ -34778,7 +34867,7 @@ async function removeWorktreeRecord(request, plan) {
 }
 async function removeEmptyLayoutFolder(request, plan) {
   const { callerRoot, worktreeRoot: worktreeRoot2, signal } = request;
-  const folder = await realpathOfExisting(join10(worktreeRoot2, await repositoryName(callerRoot, signal)));
+  const folder = await realpathOfExisting(join11(worktreeRoot2, await repositoryName(callerRoot, signal)));
   const parent = dirname6(plan.directory);
   if (await realpathOfExisting(parent) !== folder) return;
   try {
@@ -36699,23 +36788,52 @@ function elicitationConfirm(server, signal) {
 
 // src/mcp/roots.ts
 import { statSync } from "node:fs";
+import { isAbsolute as isAbsolute7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var FILE_URI_PROTOCOL = "file:";
+var SANDBOX_STATE_META = "codex/sandbox-state-meta";
+var TURN_METADATA = "x-codex-turn-metadata";
+function existingDirectory(dir) {
+  try {
+    return statSync(dir, { throwIfNoEntry: false })?.isDirectory() ? dir : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function localDirectory(uri) {
   try {
     const url2 = new URL(uri);
-    if (url2.protocol !== FILE_URI_PROTOCOL) return void 0;
-    const dir = fileURLToPath2(url2);
-    return statSync(dir, { throwIfNoEntry: false })?.isDirectory() ? dir : void 0;
+    return url2.protocol === FILE_URI_PROTOCOL ? existingDirectory(fileURLToPath2(url2)) : void 0;
   } catch {
     return void 0;
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function usableDirectory(candidate, ownDir, allowPath = false) {
+  if (typeof candidate !== "string") return void 0;
+  const dir = allowPath && isAbsolute7(candidate) ? existingDirectory(candidate) : localDirectory(candidate);
+  if (dir === void 0 || ownDir !== void 0 && await isWithin(dir, ownDir)) return void 0;
+  return dir;
+}
+async function callDirectory(meta3, ownDir) {
+  if (!isRecord(meta3)) return void 0;
+  const sandbox = meta3[SANDBOX_STATE_META];
+  if (isRecord(sandbox)) {
+    const dir = await usableDirectory(sandbox.sandboxCwd, ownDir, true);
+    if (dir !== void 0) return dir;
+  }
+  const turn = meta3[TURN_METADATA];
+  if (!isRecord(turn) || !isRecord(turn.workspaces)) return void 0;
+  const workspaces = Object.keys(turn.workspaces);
+  return workspaces.length === 1 ? usableDirectory(workspaces[0], ownDir, true) : void 0;
+}
 async function firstUsableRoot(server, ownDir, signal) {
   const { roots } = await server.listRoots(void 0, { signal });
   for (const root of roots) {
-    const dir = localDirectory(root.uri);
-    if (dir !== void 0 && !(ownDir !== void 0 && await isWithin(dir, ownDir))) return dir;
+    const dir = await usableDirectory(root.uri, ownDir);
+    if (dir !== void 0) return dir;
   }
   return void 0;
 }
@@ -36726,7 +36844,9 @@ function createWorkingDirResolver(server, fallback, ownDir) {
     cached2 = void 0;
     generation++;
   });
-  return async (signal) => {
+  return async (signal, meta3) => {
+    const callDir = await callDirectory(meta3, ownDir);
+    if (callDir !== void 0) return callDir;
     if (!server.getClientCapabilities()?.roots) return fallback();
     if (cached2 !== void 0) return cached2;
     const started = generation;
@@ -36767,7 +36887,7 @@ function createServer(specs, settings, options = {}) {
 `));
   const server = new Server(
     { name: PROJECT.name, version: options.version ?? DEFAULT_VERSION },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: {}, experimental: { [SANDBOX_STATE_META]: {} } } }
   );
   const workingDir = createWorkingDirResolver(server, options.cwd ?? (() => process.cwd()), options.ownDir);
   const toolsets = options.toolsets ?? PROJECT_PROFILE.toolsets;
@@ -36780,7 +36900,7 @@ function createServer(specs, settings, options = {}) {
     try {
       const confirm = settings.confirm === "elicitation" ? elicitationConfirm(server, extra.signal) : void 0;
       const ctx = {
-        cwd: await workingDir(extra.signal),
+        cwd: await workingDir(extra.signal, request.params._meta),
         ownDir: options.ownDir,
         options: settings.options,
         signal: extra.signal,
@@ -36808,7 +36928,7 @@ async function main() {
     const settings = parseSettings(process.argv.slice(2), process.env);
     server = createServer(ALL_TOOLS, settings, {
       ownDir: packageRoot(import.meta.url),
-      version: true ? "0.1.0" : void 0
+      version: true ? "0.2.0" : void 0
     });
   } catch (error62) {
     if (!isToolError(error62)) throw error62;

package/dist/opencode.js

@@ -25,8 +25,8 @@ var PROJECT = {
   toolsets: ["repo", "commit", "rebase", "worktree", "push"],
   /** The toolsets on when a setting names none. */
   defaultToolsets: ["repo", "commit", "rebase"],
-  /** The settings the tools themselves read, beside the ones every entry point takes; each holds text and is named in snake_case. */
-  options: ["published_text_rules", "worktree_root"],
+  /** The package's own settings, which the tools themselves read: each snake_case name and its type, with bounds when it needs them. */
+  options: { published_text_rules: "text", worktree_root: "text" },
   /** The environment variables the tools read besides the settings, which Codex forwards to the server after them. */
   toolVariables: [
     "LANGUAGE",
@@ -22980,7 +22980,8 @@ function compileRules(path, entries) {
   });
 }
 async function loadPublishedTextRules(options, signal) {
-  const path = options?.[PUBLISHED_TEXT_RULES_OPTION]?.trim();
+  const option = options?.[PUBLISHED_TEXT_RULES_OPTION];
+  const path = typeof option === "string" ? option.trim() : void 0;
   if (!path) return [];
   if (!isAbsolute4(path)) throw invalidRules(path, "the value must be an absolute path");
   return compileRules(path, parseRulesJson(path, await readRulesFile(path, signal)));
@@ -25335,7 +25336,8 @@ function expandHome(value) {
   return value.startsWith(HOME_PREFIX) ? join8(homeDirectory(), value.slice(HOME_PREFIX.length)) : value;
 }
 function worktreeRoot(ctx) {
-  const value = ctx.options?.[WORKTREE_ROOT_OPTION]?.trim();
+  const option = ctx.options?.[WORKTREE_ROOT_OPTION];
+  const value = typeof option === "string" ? option.trim() : void 0;
   if (!value) return join8(homeDirectory(), DEFAULT_ROOT_FOLDER);
   const expanded = expandHome(value);
   if (!isAbsolute5(expanded)) {
@@ -26454,6 +26456,8 @@ var PROJECT_PROFILE = {
 };
 
 // src/entry/settings.ts
+import { homedir as homedir2 } from "node:os";
+import { isAbsolute as isAbsolute6, join as join11, resolve as resolvePath, sep as sep3 } from "node:path";
 var ALL_TOOLSETS = "all";
 var TRUE_VALUES = ["1", "true"];
 var FALSE_VALUES = ["0", "false"];
@@ -26464,10 +26468,17 @@ var OPTIONS = {
   exclude_tools: { flag: "--exclude-tools", envSuffix: "EXCLUDE_TOOLS" },
   confirm: { flag: "--confirm", envSuffix: "CONFIRM" }
 };
+function profileOptions(profile) {
+  return profile.options ?? {};
+}
 function settingOptions(profile) {
-  const toolOptions = profile.options.map((name) => [
+  const toolOptions = Object.entries(profileOptions(profile)).map(([name, spec]) => [
     name,
-    { flag: `--${name.replace(/_/g, "-")}`, envSuffix: name.toUpperCase() }
+    {
+      flag: `--${name.replace(/_/g, "-")}`,
+      envSuffix: name.toUpperCase(),
+      ...optionType(spec) === "boolean" && { boolean: true }
+    }
   ]);
   return { ...OPTIONS, ...Object.fromEntries(toolOptions) };
 }
@@ -26495,11 +26506,78 @@ function parseBoolean(value, source) {
     `Unknown value "${value}" in ${source}; use one of ${[...TRUE_VALUES, ...FALSE_VALUES].join(", ")}.`
   );
 }
+function parseNumber(value, source) {
+  const trimmed2 = value.trim();
+  const parsed = trimmed2 === "" ? Number.NaN : Number(trimmed2);
+  if (!Number.isFinite(parsed)) {
+    throw new ToolError("invalid_argument", `Unknown number "${value}" in ${source}; use a finite number.`);
+  }
+  return parsed;
+}
+function absolutePath(text, source, env) {
+  const home = env.HOME !== void 0 && isAbsolute6(env.HOME) ? env.HOME : homedir2();
+  const expanded = text === "~" || text.startsWith("~/") || text.startsWith(`~${sep3}`) ? join11(home, text.slice(1)) : text;
+  if (!isAbsolute6(expanded)) throw new ToolError("invalid_argument", `${source} must be an absolute path.`);
+  return resolvePath(expanded);
+}
+function absolutePaths(items, source, env) {
+  return items.length > 0 ? items.map((item) => absolutePath(item, source, env)) : void 0;
+}
 function envText(name, env, profile) {
   const variable = envName(name, profile);
   const text = env[variable];
   return text === void 0 || text.trim() === "" ? void 0 : { text, source: variable };
 }
+function optionType(spec) {
+  return typeof spec === "string" ? spec : spec.type;
+}
+function itemCount(count) {
+  return count === 1 ? "1 item" : `${count} items`;
+}
+function numberBoundsError({ integer: integer2, min, max }, source) {
+  const range = min !== void 0 && max !== void 0 ? ` from ${min} to ${max}` : min !== void 0 ? ` of at least ${min}` : max !== void 0 ? ` of at most ${max}` : "";
+  return new ToolError("invalid_argument", `${source} must be ${integer2 ? "a whole number" : "a number"}${range}.`);
+}
+function countBoundsError({ min, max }, source) {
+  const range = min !== void 0 && max !== void 0 ? `from ${min} to ${max} items` : min !== void 0 ? `at least ${itemCount(min)}` : `at most ${itemCount(max)}`;
+  return new ToolError("invalid_argument", `${source} must list ${range}.`);
+}
+function withinBounds(spec, value, source) {
+  if (value === void 0 || typeof spec === "string") return value;
+  const bounds = spec;
+  const { integer: integer2, min, max } = bounds;
+  if (typeof value === "number") {
+    if (integer2 && !Number.isInteger(value) || min !== void 0 && value < min || max !== void 0 && value > max) {
+      throw numberBoundsError(bounds, source);
+    }
+  } else if (typeof value === "object" && (min !== void 0 && value.length < min || max !== void 0 && value.length > max)) {
+    throw countBoundsError(bounds, source);
+  }
+  return value;
+}
+function parseOptionText(spec, given, env) {
+  return withinBounds(spec, parseTypedText(optionType(spec), given, env), given.source);
+}
+function parseTypedText(kind, given, env) {
+  switch (kind) {
+    case "text":
+      return nonBlank(given.text);
+    case "boolean":
+      return parseBoolean(given.text, given.source);
+    case "number":
+      return parseNumber(given.text, given.source);
+    case "list": {
+      const items = splitList(given.text);
+      return items.length > 0 ? items : void 0;
+    }
+    case "path": {
+      const text = nonBlank(given.text);
+      return text === void 0 ? void 0 : absolutePath(text, given.source, env);
+    }
+    case "paths":
+      return absolutePaths(splitList(given.text), given.source, env);
+  }
+}
 var TOOL_OPTION_NAMES = ["toolsets", "read_only", "tools", "exclude_tools"];
 function stringList(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
@@ -26526,7 +26604,7 @@ function listOption(name) {
 }
 var LANGUAGE_OPTION = "language";
 function pluginOptionNames(profile) {
-  return [...TOOL_OPTION_NAMES, LANGUAGE_OPTION, ...profile.options];
+  return [...TOOL_OPTION_NAMES, LANGUAGE_OPTION, ...Object.keys(profileOptions(profile))];
 }
 function languageVariable(profile = PROJECT_PROFILE) {
   return `${profile.envPrefix}_LANGUAGE`;
@@ -26542,9 +26620,41 @@ function languageOption(value) {
   if (typeof value !== "string") throw optionError(LANGUAGE_OPTION, 'a language tag such as "ja"');
   return nonBlank(value);
 }
-function textOption(name, value) {
-  if (typeof value !== "string") throw optionError(name, "text");
-  return nonBlank(value);
+function toolOption(name, spec, value, env) {
+  return withinBounds(spec, toolOptionOfType(name, optionType(spec), value, env), `Option "${name}"`);
+}
+function toolOptionOfType(name, kind, value, env) {
+  switch (kind) {
+    case "text":
+      if (typeof value !== "string") throw optionError(name, "text");
+      return nonBlank(value);
+    case "boolean":
+      if (typeof value !== "boolean") throw optionError(name, "true or false");
+      return value;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) throw optionError(name, "a finite number");
+      return value;
+    case "list": {
+      const list = stringList(value);
+      if (!list) throw optionError(name, "a list of strings");
+      const items = list.map((item) => item.trim()).filter((item) => item !== "");
+      return items.length > 0 ? items : void 0;
+    }
+    case "path": {
+      if (typeof value !== "string") throw optionError(name, "an absolute path");
+      const text = nonBlank(value);
+      return text === void 0 ? void 0 : absolutePath(text, `Option "${name}"`, env);
+    }
+    case "paths": {
+      const list = stringList(value);
+      if (!list) throw optionError(name, "a list of absolute paths");
+      return absolutePaths(
+        list.flatMap((item) => nonBlank(item) ?? []),
+        `Option "${name}"`,
+        env
+      );
+    }
+  }
 }
 function settingsFromOptions(options, env, profile = PROJECT_PROFILE) {
   const given = options ?? {};
@@ -26558,12 +26668,18 @@ function settingsFromOptions(options, env, profile = PROJECT_PROFILE) {
     const text = envText(name, env, profile);
     return text !== void 0 ? fromText(text) : void 0;
   };
-  const toolOptions = {};
-  for (const name of profile.options) {
-    const text = given[name] !== void 0 ? textOption(name, given[name]) : nonBlank(envText(name, env, profile)?.text);
-    if (text !== void 0) toolOptions[name] = text;
+  const parsedOptions = {};
+  for (const [name, spec] of Object.entries(profileOptions(profile))) {
+    let parsed;
+    if (given[name] !== void 0) {
+      parsed = toolOption(name, spec, given[name], env);
+    } else {
+      const fromEnv = envText(name, env, profile);
+      if (fromEnv !== void 0) parsed = parseOptionText(spec, fromEnv, env);
+    }
+    if (parsed !== void 0) parsedOptions[name] = parsed;
   }
-  const settings = { options: toolOptions };
+  const settings = { options: parsedOptions };
   const toolsets = resolve5(
     "toolsets",
     (value) => toolsetsOption(value, profile.toolsets),
@@ -26669,7 +26785,7 @@ function createV1Server(specs, deps = {}) {
 
 // src/opencode/skills.ts
 import { readFile as readFile6, readdir } from "node:fs/promises";
-import { join as join11, resolve as resolve4 } from "node:path";
+import { join as join12, resolve as resolve4 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var SKILL_FILE = "SKILL.md";
 var FRONTMATTER = /^---[ \t]*\r?\n([\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/;
@@ -26770,7 +26886,7 @@ async function readSkills(dir) {
   }
   const skills = /* @__PURE__ */ new Map();
   for (const directory of entries.sort()) {
-    const path = join11(root, directory, SKILL_FILE);
+    const path = join12(root, directory, SKILL_FILE);
     const text = await readSkillFile(path);
     if (text === void 0) continue;
     const found = parseSkill(directory, text, path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftsamo/git-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Git tools for coding agents: state, commits, rewrites and stacked branches, worktrees and pushing.",
   "author": "craftsamo",
   "license": "LicenseRef-AGPL-3.0-Commons-Clause",

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: git-tools
-version: 0.1.0
+version: 0.2.0
 description: "Git tools for coding agents: state, commits, rewrites and stacked branches, worktrees and pushing."
 manifest_version: 1
 requires_hermes: ">=0.22"
@@ -35,6 +35,9 @@ config_schema:
     description: Single tools to remove by id. Wins over tools and toolsets.
   language:
     description: The language of the approval card, such as ja. Defaults to Hermes's display language, else English.
+  emoji:
+    type: dict
+    description: 'The emoji shown beside each toolset, by toolset name; "" shows none. Merged over the package''s emoji.'
   published_text_rules:
     description: The absolute path of a JSON file of published-text rules for the push tools. Unset, nothing is checked.
   worktree_root:

package/skills/git-rebase/SKILL.md

@@ -55,8 +55,8 @@ below, and returns to the branch it started on.
   replays; a commit whose change the base already has is dropped. `onto`
   names another commit or ref.
 - **Folding fixups in place** (`keep_base`): replays on the current base with
-  no fetch, folding `fixup!`, `squash!` and `amend!` commits into their
-  targets.
+  no fetch, folding each commit marked `fixup!` or `squash!` or `amend!`
+  into its target.
 - **After a lower layer landed** (`after`): when a layer was merged by a
   squash, its commits are not on the default branch as they are. `after`
   names that layer: only the layers above it are replayed onto the new base,

package/src/hermes/git_tools_hermes/approval.py

@@ -162,18 +162,13 @@ def resolve_target(
     """What ``target`` prints: ``["*"]`` for resources that cannot be told, no description for one absent or bad.
 
     ``language`` is the plugin's ``language`` setting and ``harness_language`` reads Hermes' display language
-    per call; neither may fail the run, and ``target`` picks among them. ``option_flags`` are the flags of the
-    plugin's tool options, which the call's description may read as ``run`` does.
+    per call; neither may fail the run, and ``target`` picks among them.
     """
     try:
         result = runtime.run(
             [
-                "target",
-                tool_id,
-                "--cwd",
-                agent_cwd(),
-                *language_flags(language, _known(harness_language)),
-                *(option_flags or []),
+                "target", tool_id, "--cwd", agent_cwd(),
+                *language_flags(language, _known(harness_language)), *(option_flags or []),
             ],
             stdin=json.dumps(run_arguments(args)),
             timeout=TARGET_TIMEOUT_SECONDS,
@@ -232,8 +227,7 @@ def make_hook(
 
     Whether a person is there to ask, and what happens when none is, is
     Hermes' own gate to decide. ``language`` is the plugin's ``language``
-    setting; ``harness_language`` is read on every call; ``option_flags``
-    are the flags of the plugin's tool options, passed to ``target``. When ``pins`` is
+    setting; ``harness_language`` is read on every call. When ``pins`` is
     given, the pin ``target`` answered is kept in it under the call's
     ``pin_key`` for the pin hook; the decision is the same either way.
     """
@@ -309,7 +303,6 @@ def register_approval(
 ) -> None:
     """Hold every non-read call of ``tools`` for approval, with the card in ``language`` (the plugin's setting).
 
-    ``option_flags`` are the flags of the plugin's tool options, which ``target`` reads as ``run`` does.
     Two hooks, in this order, since Hermes runs them in registration order: the approval hook
     stashes the pin of what the card shows, then the pin hook gives it to the call.
     """
@@ -317,12 +310,7 @@ def register_approval(
     ctx.register_hook(
         HOOK_NAME,
         make_hook(
-            runtime,
-            tools,
-            surface=lambda: session_surface(ctx),
-            language=language,
-            pins=pins,
-            option_flags=option_flags,
+            runtime, tools, surface=lambda: session_surface(ctx), language=language, pins=pins, option_flags=option_flags
         ),
     )
     ctx.register_hook(HOOK_NAME, make_pin_hook(tools, pins))

package/src/hermes/git_tools_hermes/plugin.py

@@ -9,7 +9,7 @@ from .context import PluginContext
 from .listing import list_tools
 from . import project
 from .runtime import Unavailable, locate_runtime
-from .settings import SettingsError, language_setting, option_flags, settings_flags
+from .settings import SettingsError, emoji_setting, language_setting, option_flags, settings_flags
 from .skills import register_skills
 from .tools import register_tools
 
@@ -33,6 +33,6 @@ def register(ctx: PluginContext) -> None:
         logger.warning("%s is not available and registers nothing: %s", project.PLUGIN_NAME, error)
         return
 
-    register_tools(ctx, runtime, tools, flags)
+    register_tools(ctx, runtime, tools, flags, emoji_setting(ctx))
     register_approval(ctx, runtime, tools, language_setting(ctx), option_flags(ctx))
     register_skills(ctx, runtime.skills_dir, {tool.toolset for tool in tools})

package/src/hermes/git_tools_hermes/project.py

@@ -14,9 +14,10 @@ SKILL_PREFIX = "git-"
 #: The emoji each toolset is shown with; empty by default until a project adds its own.
 TOOLSET_EMOJI: dict[str, str] = {}
 
-#: The settings the tools themselves read, beside the ones every plugin takes: each holds text and is named in
-#: snake_case, as in ``src/project.ts``. A setting ``a_b`` becomes the flag ``--a-b`` of the command line.
-OPTIONS: tuple[str, ...] = ("published_text_rules", "worktree_root")
+#: The settings the tools themselves read: each snake_case name and a type (``text``, ``boolean``, ``number``,
+#: ``list``, ``path`` or ``paths``) or a dict with ``type`` and optional bounds (``integer``, ``min``, ``max``),
+#: as in ``src/project.ts``. Write OPTIONS on one line with double quotes. A setting ``a_b`` becomes ``--a-b``.
+OPTIONS: dict[str, str | dict[str, object]] = {"published_text_rules": "text", "worktree_root": "text"}
 
 __all__ = [
     "CLI_NAME",

package/src/hermes/git_tools_hermes/settings.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import math
+from collections.abc import Mapping
 from typing import Any
 
 from . import project
@@ -31,30 +33,60 @@ def language_setting(ctx: PluginContext) -> str | None:
     return (value.strip() or None) if isinstance(value, str) else None
 
 
-def option_flags(ctx: PluginContext) -> list[str]:
-    """Read the tool options (``project.OPTIONS``) and return the flags that say the same, each ``--a-b <text>``.
+def emoji_setting(ctx: PluginContext, defaults: Mapping[str, str] | None = None) -> dict[str, str]:
+    """The emoji per toolset: ``defaults`` (``project.TOOLSET_EMOJI``) with string entries of ``emoji`` merged over it.
 
-    An option that is absent or blank gives no flag, so the command line's own
-    variable (``GIT_TOOLS_<OPTION>``) applies. These are the only flags
-    ``target`` takes beside its language ones.
+    A setting that is not a ``dict``, and an entry whose key or value is not a
+    ``str``, are ignored so a typo never takes every tool away. It is no flag
+    of ``settings_flags``.
+    """
+    merged = dict(project.TOOLSET_EMOJI if defaults is None else defaults)
+    value = ctx.get_config("emoji")
+    if isinstance(value, dict):
+        merged.update({key: item for key, item in value.items() if isinstance(key, str) and isinstance(item, str)})
+    return merged
 
-    Raises:
-        SettingsError: an option is not text.
+
+def _option_flag(name: str, declaration: str | dict[str, object], value: Any) -> list[str]:
+    kind = declaration["type"] if isinstance(declaration, dict) else declaration
+    flag = f"--{name.replace('_', '-')}"
+    if kind in ("text", "path"):
+        if not isinstance(value, str):
+            expected = "a path" if kind == "path" else "text"
+            raise SettingsError(f'setting "{name}" must be {expected}')
+        return [flag, text] if (text := value.strip()) else []
+    if kind == "boolean":
+        if not isinstance(value, bool):
+            raise SettingsError(f'setting "{name}" must be true or false')
+        return [flag] if value else []
+    if kind == "number":
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+            raise SettingsError(f'setting "{name}" must be a finite number')
+        return [flag, str(value)]
+    if kind in ("list", "paths"):
+        if not isinstance(value, list) or not all(isinstance(item, str) and "," not in item for item in value):
+            expected = "paths" if kind == "paths" else "strings"
+            raise SettingsError(f'setting "{name}" must be a list of {expected} without commas')
+        items = [item.strip() for item in value if item.strip()]
+        return [flag, ",".join(items)] if items else []
+    raise SettingsError(f'unknown option type "{kind}" for "{name}"')
+
+
+def option_flags(ctx: PluginContext, options: Mapping[str, str | dict[str, object]] | None = None) -> list[str]:
+    """The package's tool options as flags, with absent settings left to the command line's environment.
+
+    Bounds and path absoluteness are checked by the command line, not here.
     """
     flags: list[str] = []
-    for name in project.OPTIONS:
+    for name, declaration in (project.OPTIONS if options is None else options).items():
         value = ctx.get_config(name)
-        if value is None:
-            continue
-        if not isinstance(value, str):
-            raise SettingsError(f'setting "{name}" must be text')
-        if text := value.strip():
-            flags += [f"--{name.replace('_', '-')}", text]
+        if value is not None:
+            flags += _option_flag(name, declaration, value)
     return flags
 
 
 def settings_flags(ctx: PluginContext) -> list[str]:
-    """Read ``toolsets``, ``read_only``, ``tools``, ``exclude_tools`` and the tool options and return the flags that say the same.
+    """Read ``toolsets``, ``read_only``, ``tools`` and ``exclude_tools`` and return the flags that say the same.
 
     A setting that is absent gives no flag, so the command line's own defaults
     (and ``GIT_TOOLS_*`` variables) apply. A wrong type is refused rather

package/src/hermes/git_tools_hermes/tools.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from typing import Any
 
 from .approval import PIN_ARGUMENT, parse_pin, run_arguments
@@ -76,14 +76,21 @@ def make_handler(runtime: Runtime, tool_id: str, flags: list[str]) -> Callable[.
     return handler
 
 
-def register_tools(ctx: PluginContext, runtime: Runtime, tools: list[ToolInfo], flags: list[str]) -> None:
+def register_tools(
+    ctx: PluginContext,
+    runtime: Runtime,
+    tools: list[ToolInfo],
+    flags: list[str],
+    emoji: Mapping[str, str] | None = None,
+) -> None:
     """Register each listed tool under its own ID, grouped in one Hermes toolset per package toolset."""
+    toolset_emoji = TOOLSET_EMOJI if emoji is None else emoji
     for tool in tools:
         ctx.register_tool(
             name=tool.id,
             toolset=TOOLSET_PREFIX + tool.toolset.replace("_", "-"),
             schema={"name": tool.id, "description": tool.description, "parameters": tool.input_schema},
             handler=make_handler(runtime, tool.id, flags),
-            emoji=TOOLSET_EMOJI.get(tool.toolset, ""),
+            emoji=toolset_emoji.get(tool.toolset, ""),
             description=tool.title,
         )