tunestra 0.3.0 → 0.5.0

package/README.md

@@ -13,8 +13,8 @@
 > before v1.0.
 
 tunestra gives Claude Code, Codex and other AI coding agents **one shared source** of rules,
-skills, commands, MCP servers and environment variables, and generates each agent's native
-configuration from it.
+skills, commands, MCP servers, environment variables and permissions, and generates each
+agent's native configuration from it.
 
 The source is a chain of **presets**, from general to specific:
 
@@ -45,8 +45,8 @@ extends:
 agents: [claude]            # add codex: [claude, codex]
 ```
 
-Commit `tunestra.yaml`, `.tunestra/`, `AGENTS.md`, `CLAUDE.md` and, when presets set `env`,
-`.claude/settings.json`. Everything else that tunestra generates is listed in `.gitignore`
+Commit `tunestra.yaml`, `.tunestra/`, `AGENTS.md`, `CLAUDE.md` and, when presets set `env` or
+`permissions`, `.claude/settings.json`. Everything else that tunestra generates is listed in `.gitignore`
 automatically.
 
 ## Principles
@@ -70,9 +70,26 @@ the manifest only holds metadata and overrides.
   rules/<key>.md            # rules, one topic per file
   skills/<key>/SKILL.md     # skills (Agent Skills format)
   commands/<key>.md         # slash commands
+  agents/<key>.md           # subagents
   mcp/<key>.yaml            # MCP servers
 ```
 
+A subagent is a markdown file with frontmatter; the text after it is the instructions:
+
+```md
+---
+description: Reviews a diff for bugs and missing tests   # required: when to use it
+model:                      # optional: the model for each agent
+  claude: sonnet            #   otherwise the agent uses the model of the main session
+  codex: gpt-5.5
+effort: medium              # optional: low | medium | high | xhigh
+readOnly: true              # optional: the subagent must not change files
+---
+Review the diff. Report each finding with a file and a line.
+```
+
+The file name is the name of the subagent: lowercase letters, digits and single hyphens.
+
 ### Manifest: `tunestra.preset.yaml`
 
 ```yaml
@@ -90,6 +107,10 @@ overrides:                  # optional: patch inherited MCP servers
         QUEUE: TEAM
 env:                        # optional: environment variables of the agents
   MCP_TIMEOUT: 120000
+permissions:                # optional: rules in the syntax of Claude Code
+  allow: [Bash(npm test *)]
+  ask: [Bash(git push *)]
+  deny: [Read(./.env), Bash(rm -rf *)]
 ```
 
 ### Project: `tunestra.yaml`
@@ -139,8 +160,13 @@ chain once, before both of them.
 | Level instructions (`AGENTS.md`) | `instructions@<preset name>` | never collides: every level keeps its own | `exclude.rules` |
 | Skill | `name` from `SKILL.md`, otherwise the folder name | replaces it | `exclude.skills` |
 | Command | file name without `.md` | replaces it | `exclude.commands` |
+| Subagent | file name without `.md` | replaces it | `exclude.subagents` |
 | MCP server | file name without `.yaml` | replaces it | `exclude.mcp` |
 | Environment variable | name in `env` | replaces it | `exclude.env` |
+| Permission rule | the rule, like `Bash(npm test *)` | lists are joined: every level adds its rules | `exclude.permissions`, only for `allow` and `ask` |
+
+A `deny` rule cannot be removed: the organization keeps a floor of what agents may never do.
+Agents check `deny` first, so a `deny` rule on any level wins over an `allow` rule.
 
 `overrides.mcp.<key>` patches an inherited server instead of replacing it: `env` and `headers`
 are merged by key (the specific value wins); `command`, `args` and `url` are replaced.
@@ -157,7 +183,10 @@ are merged by key (the specific value wins); `command`, `args` and `url` are rep
 - after a patch, an MCP server has both `command` and `url`, or neither;
 - an `env` value refers to another variable, like `${TOKEN}`: agents do not expand it in
   their settings, so write the value itself and keep secrets out of presets;
-- `env` sets a variable that Claude Code ignores in project settings (see below).
+- `env` sets a variable that Claude Code ignores in project settings (see below);
+- `exclude.permissions` tries to remove a `deny` rule;
+- a subagent has no `description` or no instructions, an unknown field, or a file name that
+  cannot be a subagent name.
 
 All problems are reported at once, in the order of the files, so you can fix them in one pass.
 
@@ -167,7 +196,7 @@ For every agent:
 
 | Path | Content | Committed |
 |---|---|---|
-| `AGENTS.md` | Index: hierarchy, rules, skills, commands, MCP servers | yes |
+| `AGENTS.md` | Index: hierarchy, rules, skills, commands, MCP servers, subagents | yes |
 | `.agents/rules/<NN>-<level>-<key>.md` | Rule texts, ordered from specific to general | no |
 | `.agents/skills/<key>/` | Skills | no |
 | `.tunestra/state/` | What tunestra generated last time | no |
@@ -181,22 +210,27 @@ For every agent:
 | `.claude/rules/tunestra/<NN>-<level>-<key>.md` | Copies of the rules; Claude Code loads them in every session | no |
 | `.claude/skills/<key>` | Symlinks to `.agents/skills/<key>` | no |
 | `.claude/commands/<key>.md` | Commands | no |
+| `.claude/agents/<key>.md` | Subagents | no |
 | `.mcp.json` | MCP servers | no |
-| `.claude/settings.json` | `env`, when presets set it | yes |
+| `.claude/settings.json` | `env` and `permissions`, when presets set them | yes |
 
 `.claude/settings.json` is shared by the team, so tunestra writes it and you commit it. Keep
 your personal settings in `.claude/settings.local.json` or `~/.claude/settings.json`. A
 `.claude/settings.json` with other keys, like `hooks` or `model`, stops setup and asks you to
-move them; a file with only `$schema` and `env` is replaced with a warning, for example in a
+move them; a file with only `$schema`, `env` and `permissions` is replaced with a warning, for example in a
 fresh clone where `.tunestra/state/` does not exist yet.
 
-Claude Code applies project `env` after you trust the folder. It ignores some variables in
+Claude Code applies project `env` and `allow` rules after you trust the folder; `deny` and
+`ask` rules apply right away. It ignores some variables in
 project settings: the ones that turn telemetry on or choose where it goes
 (`CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_*_EXPORTER`, `OTEL_EXPORTER_OTLP_*` and others), and
 the ones that choose its own directories (`HOME`, `XDG_*`, `CLAUDE_CONFIG_DIR`). setup stops
 on them, because they would not work; set them in managed settings, `~/.claude/settings.json`
 or your shell. Values that turn telemetry off, like `OTEL_LOGS_EXPORTER: none`, are allowed.
 
+A read-only subagent of Claude Code loses the tools that change files: `Write`, `Edit`,
+`NotebookEdit` and `Bash`. It keeps the tools that read and search, and MCP tools.
+
 ### Codex
 
 Codex reads `AGENTS.md` and `.agents/skills/` by itself. It does not follow the links in
@@ -205,15 +239,29 @@ Codex reads `AGENTS.md` and `.agents/skills/` by itself. It does not follow the
 | Path | Content | Committed |
 |---|---|---|
 | `.codex/config.toml` | `developer_instructions` with every rule, from specific to general, `[shell_environment_policy] set` with `env`, and `[mcp_servers]` | no |
+| `.codex/rules/tunestra.rules` | `deny` and `ask` rules for shell commands as `prefix_rule`: `forbidden` and `prompt` | no |
 | `.agents/skills/<command>/` | Each command as a skill that runs only when you call it: `$release-notes` | no |
+| `.codex/agents/<key>.toml` | Subagents | no |
 
 Codex reads `.codex/config.toml` only in a trusted project: trust the project when Codex asks.
 Codex gets `env` as the environment of the commands it runs; it does not change how Codex
 itself works, and Codex ignores telemetry settings in a project.
+
+Codex rules match only the start of a shell command, so tunestra converts only `Bash` rules
+like `Bash(git push *)` or `Bash(rm -rf)`. A rule without a wildcard also becomes a prefix,
+which is stricter for `deny` and `ask`. Other rules (`Read`, `Edit`, `WebFetch`, MCP tools, and
+`Bash` rules with wildcards in the middle or shell syntax) are skipped with a note. `allow`
+rules are skipped too: in Codex, an allowed command runs outside the sandbox without asking,
+which is more than an `allow` rule of Claude Code means.
 Codex has no `type` for MCP servers and does not support SSE: an SSE server is skipped with a
 note, and `headers` become `http_headers`. tunestra owns the whole `.codex/config.toml`; keep
 your personal Codex settings in `~/.codex/config.toml`.
 
+A Codex subagent gets the sandbox, the permissions and the MCP servers of the main session; its
+file can change only the model and the instructions. So Codex cannot make a subagent
+read-only: tunestra turns off its shell (`features.shell_tool = false`) and asks it not to
+edit files in the instructions, and setup says so in a note.
+
 `<NN>` orders rules from specific to general: `10` project, `20` team, `30` domain, `40` base.
 Level instructions get the key `instructions`, and the preset name when it differs from the
 level: `20-team-instructions.md`, but `20-team-instructions-frontend.md` for a `team` preset
@@ -264,7 +312,7 @@ and tells you where to move their text.
 |---|---|
 | v0.1 | Inheritance for Claude Code |
 | v0.2 | Codex (this document) |
-| v0.3 | `env`, then permissions, subagents and a personal `local` level |
+| v0.3 | `env` and permissions, then subagents and a personal `local` level |
 | v0.4 | Spaces, npm sources, lockfile |
 | v0.5 | `required` / `locked` policies, CI check |
 | v0.6 | Hooks |

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as VERSION } from "./src-BNeh64fK.mjs";
+import { t as VERSION } from "./src-CZK2Ixbt.mjs";
 import { Command } from "@commander-js/extra-typings";
 import pc from "picocolors";
 import { copyFile, lstat, mkdir, readFile, readdir, readlink, rename, rm, rmdir, stat, symlink, unlink, writeFile } from "node:fs/promises";
@@ -338,13 +338,22 @@ const envSchema = z.record(z.string(), envValue).superRefine((env, context) => {
 		path: [name]
 	});
 });
+const permissionRules = z.array(z.string().regex(/^[A-Za-z][\w*-]*(\(.+\))?$/, "Write a rule as Tool or Tool(specifier), like Bash(npm test *)")).readonly();
+const permissionsSchema = z.strictObject({
+	allow: permissionRules.optional(),
+	ask: permissionRules.optional(),
+	deny: permissionRules.optional()
+});
 const skillName = z.string().regex(SKILL_NAME_PATTERN, "Use lowercase letters, digits and single hyphens").max(64);
 const excludeSchema = z.strictObject({
 	rules: keys.optional(),
 	skills: keys.optional(),
 	commands: keys.optional(),
 	mcp: keys.optional(),
-	env: keys.optional()
+	subagents: keys.optional(),
+	env: keys.optional(),
+	/** Inherited `allow` and `ask` rules; a `deny` rule cannot be removed. */
+	permissions: keys.optional()
 });
 const mcpPatchSchema = z.strictObject({
 	command: z.string().optional(),
@@ -361,7 +370,8 @@ const presetManifestSchema = z.strictObject({
 	extends: z.array(z.string().min(1)).readonly().default([]),
 	exclude: excludeSchema.default({}),
 	overrides: overridesSchema.default({}),
-	env: envSchema.default({})
+	env: envSchema.default({}),
+	permissions: permissionsSchema.default({})
 });
 const projectConfigSchema = z.strictObject({
 	name: z.string().min(1).optional(),
@@ -369,7 +379,8 @@ const projectConfigSchema = z.strictObject({
 	agents: z.array(z.enum(Agent)).min(1).readonly().default([Agent.Claude]),
 	exclude: excludeSchema.default({}),
 	overrides: overridesSchema.default({}),
-	env: envSchema.default({})
+	env: envSchema.default({}),
+	permissions: permissionsSchema.default({})
 });
 const mcpServerSchema = z.strictObject({
 	description: z.string().optional(),
@@ -453,6 +464,15 @@ async function mapSettled(items, map) {
 	throw buildResultsError(results);
 }
 //#endregion
+//#region src/shared/constants/subagents.ts
+/** Reasoning effort of a subagent: the levels that both Claude Code and Codex accept. */
+const SubagentEffort = {
+	Low: "low",
+	Medium: "medium",
+	High: "high",
+	ExtraHigh: "xhigh"
+};
+//#endregion
 //#region src/shared/schemas/frontmatter.ts
 const ruleFrontmatterSchema = z.looseObject({ description: z.string().optional() });
 const skillFrontmatterSchema = z.looseObject({
@@ -460,6 +480,15 @@ const skillFrontmatterSchema = z.looseObject({
 	description: z.string().min(1)
 });
 const commandFrontmatterSchema = z.looseObject({ description: z.string().optional() });
+/** The model names differ between agents, so a subagent sets one for each agent. */
+const subagentModelSchema = z.partialRecord(z.enum(Agent), z.string().min(1));
+/** tunestra writes the files of the agents itself, so it knows every field here. */
+const subagentFrontmatterSchema = z.strictObject({
+	description: z.string().min(1),
+	model: subagentModelSchema.default({}),
+	effort: z.enum(SubagentEffort).optional(),
+	readOnly: z.boolean().default(false)
+});
 //#endregion
 //#region src/presets/frontmatter.ts
 /**
@@ -592,6 +621,28 @@ function findDuplicateSkills(skills, dir) {
 	return problems;
 }
 //#endregion
+//#region src/presets/artifacts/subagents.ts
+/** Subagents live in `agents/`, like in Claude Code and Codex. */
+async function loadSubagents(dir) {
+	return mapSettled(await listFiles(dir, "agents/*.md"), (source) => loadSubagent(dir, source));
+}
+async function loadSubagent(dir, source) {
+	const file = join(dir, source);
+	const { data, body } = parseFrontmatter(await readFile(file, "utf8"), file);
+	const frontmatter = validate(data, subagentFrontmatterSchema, `frontmatter in ${file}`);
+	const key = validate(basename(source, ".md"), skillName, `subagent file ${source}`);
+	if (body.trim().length > 0 === false) throw new TunestraError(`${file} has no instructions: write them after the frontmatter`);
+	return {
+		key,
+		source,
+		description: frontmatter.description,
+		model: frontmatter.model,
+		effort: frontmatter.effort,
+		readOnly: frontmatter.readOnly,
+		body
+	};
+}
+//#endregion
 //#region src/presets/artifacts/load-artifacts.ts
 /** Loads every kind of artifact at the same time and reports the problems of all of them. */
 async function loadArtifacts(dir, presetName) {
@@ -599,19 +650,22 @@ async function loadArtifacts(dir, presetName) {
 	const skillsLoading = loadSkills(dir);
 	const commandsLoading = loadCommands(dir);
 	const mcpLoading = loadMcpServers(dir);
+	const subagentsLoading = loadSubagents(dir);
 	const results = await Promise.allSettled([
 		rulesLoading,
 		skillsLoading,
 		commandsLoading,
-		mcpLoading
+		mcpLoading,
+		subagentsLoading
 	]);
 	if (isEveryFulfilled(results) === false) throw buildResultsError(results);
-	const [rulesResult, skillsResult, commandsResult, mcpResult] = results;
+	const [rulesResult, skillsResult, commandsResult, mcpResult, subagentsResult] = results;
 	return {
 		rules: rulesResult.value,
 		skills: skillsResult.value,
 		commands: commandsResult.value,
-		mcp: mcpResult.value
+		mcp: mcpResult.value,
+		subagents: subagentsResult.value
 	};
 }
 //#endregion
@@ -635,6 +689,34 @@ function createEnvVariables(env, manifestPath, artifactsDir) {
 	}));
 }
 //#endregion
+//#region src/shared/constants/permissions.ts
+/** What an agent does with a tool call that matches a permission rule. */
+const PermissionDecision = {
+	/** Run without asking. */
+	Allow: "allow",
+	/** Ask every time. */
+	Ask: "ask",
+	/** Never run. Agents check deny first, so a deny rule always wins. */
+	Deny: "deny"
+};
+//#endregion
+//#region src/presets/permissions.ts
+const DECISIONS$1 = Object.values(PermissionDecision);
+/** The `permissions` lists of a manifest as one list of rules, in the order of the file. */
+function createPermissionRules(permissions, manifestPath, artifactsDir) {
+	const source = relativePosix(artifactsDir, manifestPath);
+	const rules = [];
+	for (const decision of DECISIONS$1) {
+		const keys = permissions[decision] ?? [];
+		for (const key of keys) rules.push({
+			key,
+			decision,
+			source
+		});
+	}
+	return rules;
+}
+//#endregion
 //#region src/presets/load-project.ts
 async function loadProject(dir) {
 	const root = resolve(dir);
@@ -646,6 +728,7 @@ async function loadProject(dir) {
 	const artifactsDir = join(root, PROJECT_DIR);
 	const artifacts = await loadArtifacts(artifactsDir, name);
 	const env = createEnvVariables(config.env, configPath, artifactsDir);
+	const permissions = createPermissionRules(config.permissions, configPath, artifactsDir);
 	return {
 		...config,
 		name,
@@ -655,7 +738,8 @@ async function loadProject(dir) {
 		artifactsDir,
 		remote: void 0,
 		...artifacts,
-		env
+		env,
+		permissions
 	};
 }
 //#endregion
@@ -861,6 +945,7 @@ async function loadPreset(dir) {
 	const manifest = await readYaml(manifestPath, presetManifestSchema, "preset manifest");
 	const artifacts = await loadArtifacts(root, manifest.name);
 	const env = createEnvVariables(manifest.env, manifestPath, root);
+	const permissions = createPermissionRules(manifest.permissions, manifestPath, root);
 	return {
 		...manifest,
 		description: manifest.description,
@@ -868,7 +953,8 @@ async function loadPreset(dir) {
 		artifactsDir: root,
 		remote: void 0,
 		...artifacts,
-		env
+		env,
+		permissions
 	};
 }
 //#endregion
@@ -1054,14 +1140,52 @@ function compareByName([a], [b]) {
 //#endregion
 //#region src/agents/claude/settings-json.ts
 const SETTINGS_SCHEMA = "https://json.schemastore.org/claude-code-settings.json";
+const DECISIONS = Object.values(PermissionDecision);
 /** The keys that tunestra writes; a file with only these keys is a generated one. */
-const SETTINGS_KEYS = ["$schema", "env"];
-function renderSettingsJson(env) {
-	const variables = buildEnvMap(env);
-	return `${JSON.stringify({
-		$schema: SETTINGS_SCHEMA,
-		env: variables
-	}, null, 2)}\n`;
+const SETTINGS_KEYS = [
+	"$schema",
+	"env",
+	"permissions"
+];
+/** `.claude/settings.json` with sorted keys and lists, so that its diff stays small. */
+function renderSettingsJson(settings) {
+	const content = { $schema: SETTINGS_SCHEMA };
+	const hasEnv = settings.env.length > 0;
+	const hasPermissions = settings.permissions.length > 0;
+	if (hasEnv) content.env = buildEnvMap(settings.env);
+	if (hasPermissions) content.permissions = buildPermissionLists(settings.permissions);
+	return `${JSON.stringify(content, null, 2)}\n`;
+}
+/** Only the lists that have rules; a rule repeated on several levels is written once. */
+function buildPermissionLists(permissions) {
+	const lists = {};
+	for (const decision of DECISIONS) {
+		const keys = permissions.filter((resolved) => resolved.artifact.decision === decision).map((resolved) => resolved.artifact.key);
+		const sortedKeys = [...new Set(keys)].toSorted();
+		if (sortedKeys.length > 0) lists[decision] = sortedKeys;
+	}
+	return lists;
+}
+//#endregion
+//#region src/agents/claude/subagent-md.ts
+/** Tools that change files; a read-only subagent keeps the tools that read and search. */
+const WRITING_TOOLS = [
+	"Write",
+	"Edit",
+	"NotebookEdit",
+	"Bash"
+];
+/** `.claude/agents/<name>.md`: the frontmatter of Claude Code and the instructions. */
+function renderSubagentMd(subagent) {
+	const { key, description, model, effort, readOnly, body } = subagent;
+	const frontmatter = {
+		name: key,
+		description
+	};
+	if (typeof model.claude === "string") frontmatter.model = model.claude;
+	if (typeof effort === "string") frontmatter.effort = effort;
+	if (readOnly) frontmatter.disallowedTools = WRITING_TOOLS;
+	return `---\n${stringify(frontmatter)}---\n${body}`;
 }
 //#endregion
 //#region src/agents/claude/claude-adapter.ts
@@ -1069,17 +1193,18 @@ const CLAUDE_FILE = "CLAUDE.md";
 const RULES_DIR = ".claude/rules/tunestra";
 const SKILLS_DIR = ".claude/skills";
 const COMMANDS_DIR = ".claude/commands";
+const SUBAGENTS_DIR$1 = ".claude/agents";
 const MCP_FILE = ".mcp.json";
 const MCP_SOURCE = "the mcp/ folders of tunestra.yaml and its presets";
 const SETTINGS_FILE = ".claude/settings.json";
-const SETTINGS_SOURCE = "env in tunestra.yaml and its presets";
+const SETTINGS_SOURCE = "env and permissions in tunestra.yaml and its presets";
 const LOCAL_SETTINGS_FILE = ".claude/settings.local.json";
 /**
 * Claude Code reads CLAUDE.md, so it imports AGENTS.md. Rules are copied to `.claude/rules`,
 * which Claude Code loads in every session; a symlink to a directory outside `.claude`
 * would need an approval. Skills are symlinks to the shared `.agents/skills`. Environment
-* variables go to `.claude/settings.json`, which the team commits; `settings.local.json`
-* stays for personal settings.
+* variables and permissions go to `.claude/settings.json`, which the team commits;
+* `settings.local.json` stays for personal settings.
 */
 const claudeAdapter = {
 	agent: Agent.Claude,
@@ -1097,11 +1222,15 @@ function planClaude(context) {
 		const source = describeArtifactSource(projectDir, command.origin, command.artifact.source);
 		return createFileOutput(path, command.artifact.content, source);
 	});
+	const subagentFiles = resolution.subagents.map((subagent) => {
+		return createFileOutput(`${SUBAGENTS_DIR$1}/${subagent.artifact.key}.md`, renderSubagentMd(subagent.artifact), describeArtifactSource(projectDir, subagent.origin, subagent.artifact.source));
+	});
 	const outputs = [
 		claudeFile,
 		...ruleCopies,
 		...skillLinks,
-		...commandFiles
+		...commandFiles,
+		...subagentFiles
 	];
 	if (resolution.mcp.length > 0) {
 		const mcpJson = renderMcpJson(resolution.mcp);
@@ -1109,8 +1238,8 @@ function planClaude(context) {
 		outputs.push(mcpFile);
 	}
 	const protectedPaths = [CLAUDE_FILE];
-	if (resolution.env.length > 0) {
-		const settingsFile = planSettingsFile(resolution.env);
+	if (resolution.env.length > 0 || resolution.permissions.length > 0) {
+		const settingsFile = planSettingsFile(resolution.env, resolution.permissions);
 		outputs.push(settingsFile);
 		protectedPaths.push(SETTINGS_FILE);
 	}
@@ -1120,6 +1249,7 @@ function planClaude(context) {
 			`${RULES_DIR}/`,
 			`${SKILLS_DIR}/`,
 			`${COMMANDS_DIR}/`,
+			`${SUBAGENTS_DIR$1}/`,
 			MCP_FILE
 		],
 		protectedPaths,
@@ -1127,10 +1257,13 @@ function planClaude(context) {
 	};
 }
 /** Claude Code drops some variables from project settings; setup says so instead. */
-function planSettingsFile(env) {
+function planSettingsFile(env, permissions) {
 	const problems = env.filter((variable) => isIgnoredByClaude(variable.artifact.key, variable.artifact.value)).map((variable) => `${variable.origin.name}: env sets ${variable.artifact.key}, but Claude Code ignores it in project settings. Set it in managed settings, ~/.claude/settings.json or your shell`);
 	if (problems.length > 0) throw createProblemsError(problems);
-	const content = renderSettingsJson(env);
+	const content = renderSettingsJson({
+		env,
+		permissions
+	});
 	const file = createFileOutput(SETTINGS_FILE, content, SETTINGS_SOURCE);
 	const ownership = {
 		keys: SETTINGS_KEYS,
@@ -1185,7 +1318,7 @@ function planCommandSkill(projectDir, command) {
 	return [createFileOutput(skillPath, skill, source), createFileOutput(policyPath, OPENAI_YAML, source)];
 }
 //#endregion
-//#region src/agents/codex/config-toml.ts
+//#region src/agents/codex/toml-text.ts
 /** Starts and ends a multi-line literal string, where TOML escapes nothing. */
 const LITERAL_DELIMITER = "'''";
 /**
@@ -1197,6 +1330,18 @@ const LITERAL_DELIMITER = "'''";
 */
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B-\u001F\u007F]/;
 /**
+* A key with a long text, like `developer_instructions`. The text is a literal string, so
+* that people can read it; a text that a literal string cannot hold is escaped.
+*/
+function renderTomlText(key, text) {
+	const hasDelimiter = text.includes(LITERAL_DELIMITER);
+	const hasControlCharacter = CONTROL_CHARACTER_PATTERN.test(text);
+	if (hasDelimiter || hasControlCharacter) return stringify$1({ [key]: text });
+	return `${key} = ${LITERAL_DELIMITER}\n${text}${LITERAL_DELIMITER}`;
+}
+//#endregion
+//#region src/agents/codex/config-toml.ts
+/**
 * `.codex/config.toml`: the rules as `developer_instructions`, which Codex adds to every
 * session, the environment of the commands that Codex runs, and the MCP servers. The rules
 * are a literal string, so that people can read them.
@@ -1204,7 +1349,7 @@ const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B-\u001F\u007F]/;
 function renderConfigToml(config) {
 	const parts = [GENERATED_HASH_NOTICE];
 	if (typeof config.instructions === "string") {
-		const line = renderInstructions$1(config.instructions);
+		const line = renderTomlText("developer_instructions", config.instructions);
 		parts.push(line);
 	}
 	const tables = {};
@@ -1224,12 +1369,6 @@ function renderConfigToml(config) {
 	}
 	return `${parts.join("\n\n")}\n`;
 }
-function renderInstructions$1(text) {
-	const hasDelimiter = text.includes(LITERAL_DELIMITER);
-	const hasControlCharacter = CONTROL_CHARACTER_PATTERN.test(text);
-	if (hasDelimiter || hasControlCharacter) return stringify$1({ developer_instructions: text });
-	return `developer_instructions = ${LITERAL_DELIMITER}\n${text}${LITERAL_DELIMITER}`;
-}
 /** Codex picks the transport by `command` or `url` and has no `type`. */
 function convertMcpConfig(config) {
 	const { type: _type, headers, ...server } = config;
@@ -1240,15 +1379,112 @@ function convertMcpConfig(config) {
 	};
 }
 //#endregion
+//#region src/agents/codex/exec-rules.ts
+/** A Bash rule of Claude Code with a specifier: `Bash(npm test *)`. */
+const BASH_RULE_START = "Bash(";
+const BASH_RULE_END = ")";
+/**
+* Shell syntax and wildcards that a Codex prefix rule cannot express.
+*
+* Matches:        "npm test && rm", "echo $HOME", "git * --force", "ls > out", "say 'hi'"
+* Does not match: "npm test", "git push --force", "rm -rf"
+*/
+const SHELL_SYNTAX_PATTERN = /["'`$\\|&;<>(){}*?[\]~]/;
+const WHITESPACE_PATTERN = /\s+/;
+/** A trailing ` *` or the older `:*` means "this command with any arguments". */
+const ANY_ARGUMENTS_SUFFIXES = [" *", ":*"];
+/**
+* Codex names for the decisions it gets. `allow` stays out: in Codex it runs a command
+* outside the sandbox without asking, which is more than an `allow` rule of Claude Code means.
+*/
+const CODEX_DECISIONS = {
+	[PermissionDecision.Deny]: "forbidden",
+	[PermissionDecision.Ask]: "prompt"
+};
+/**
+* The words of a Bash rule that Codex can match by prefix, or `undefined` when it cannot.
+* A rule without a wildcard becomes a prefix too: for `deny` and `ask` this is stricter.
+*/
+function convertBashRule(rule) {
+	if ((rule.startsWith(BASH_RULE_START) && rule.endsWith(BASH_RULE_END)) === false) return;
+	const specifier = rule.slice(5, -1);
+	const suffix = ANY_ARGUMENTS_SUFFIXES.find((ending) => specifier.endsWith(ending));
+	const command = typeof suffix === "string" ? specifier.slice(0, -suffix.length) : specifier;
+	if (SHELL_SYNTAX_PATTERN.test(command)) return;
+	const words = command.trim().split(WHITESPACE_PATTERN);
+	if (words.every((word) => word.length > 0)) return words;
+}
+function hasCodexDecision(decision) {
+	return decision in CODEX_DECISIONS;
+}
+function createExecRule(resolved, decision, pattern) {
+	return {
+		pattern,
+		decision: CODEX_DECISIONS[decision],
+		justification: `${resolved.artifact.key}: ${decision} from ${resolved.origin.name}`
+	};
+}
+/** `.codex/rules/tunestra.rules` in the Starlark format of Codex. */
+function renderExecRules(rules) {
+	const blocks = rules.map(renderExecRule);
+	return `${[GENERATED_HASH_NOTICE, ...blocks].join("\n\n")}\n`;
+}
+/** JSON strings are valid Starlark strings. */
+function renderExecRule(rule) {
+	const pattern = rule.pattern.map((word) => JSON.stringify(word)).join(", ");
+	const decision = JSON.stringify(rule.decision);
+	const justification = JSON.stringify(rule.justification);
+	return [
+		"prefix_rule(",
+		`    pattern = [${pattern}],`,
+		`    decision = ${decision},`,
+		`    justification = ${justification},`,
+		")"
+	].join("\n");
+}
+//#endregion
+//#region src/agents/codex/subagent-toml.ts
+/**
+* Codex has no read-only mode for a subagent: it can turn off the shell, but the subagent
+* still edits files with patches. So the instructions ask it not to.
+*/
+const READ_ONLY_INSTRUCTION = "Do not create, edit or delete files.";
+/**
+* `.codex/agents/<name>.toml`. Codex gives a subagent the sandbox, the permissions and the
+* MCP servers of the main session, so the file has only the model and the instructions.
+*/
+function renderSubagentToml(subagent) {
+	const { key, description, model, effort, readOnly, body } = subagent;
+	const fields = {
+		name: key,
+		description
+	};
+	if (typeof model.codex === "string") fields.model = model.codex;
+	if (typeof effort === "string") fields.model_reasoning_effort = effort;
+	const instructions = readOnly ? `${READ_ONLY_INSTRUCTION}\n\n${body}` : body;
+	const parts = [
+		GENERATED_HASH_NOTICE,
+		stringify$1(fields).trimEnd(),
+		renderTomlText("developer_instructions", instructions)
+	];
+	if (readOnly) parts.push(stringify$1({ features: { shell_tool: false } }).trimEnd());
+	return `${parts.join("\n\n")}\n`;
+}
+//#endregion
 //#region src/agents/codex/codex-adapter.ts
 const CONFIG_FILE = ".codex/config.toml";
 const CONFIG_SOURCE = "the rules/ and mcp/ folders and env of tunestra.yaml and its presets";
+const EXEC_RULES_FILE = ".codex/rules/tunestra.rules";
+const EXEC_RULES_SOURCE = "permissions in tunestra.yaml and its presets";
+const SUBAGENTS_DIR = ".codex/agents";
 const INSTRUCTIONS_INTRO = "Rules of this project, ordered from specific to general. When two rules conflict, follow the one that comes first.";
-const TRUST_NOTE = "Codex reads .codex/config.toml only in a trusted project: trust the project when Codex asks.";
+const TRUST_NOTE = "Codex reads .codex/ only in a trusted project: trust the project when Codex asks.";
 /**
 * Codex reads AGENTS.md and the skills in `.agents/skills` by itself. Rules go to
 * `developer_instructions` in `.codex/config.toml`, because Codex does not follow the links
-* in AGENTS.md; MCP servers go to the same file. Commands become skills.
+* in AGENTS.md; MCP servers and env go to the same file. Commands become skills, and
+* permission rules for shell commands become `.codex/rules/tunestra.rules`. Subagents go
+* to `.codex/agents`.
 */
 const codexAdapter = {
 	agent: Agent.Codex,
@@ -1265,25 +1501,86 @@ function planCodex(context) {
 		return false;
 	}).flatMap((command) => planCommandSkill(projectDir, command));
 	outputs.push(...commandSkills);
-	const configFile = planConfigFile(ruleFiles, resolution.mcp.filter((server) => {
+	const servers = resolution.mcp.filter((server) => {
 		if (server.artifact.config.type === "sse") {
 			notes.push(`Codex skips the MCP server "${server.artifact.key}": Codex does not support SSE.`);
 			return false;
 		}
 		return true;
-	}), resolution.env);
-	if (configFile === void 0) return {
+	});
+	const subagentFiles = resolution.subagents.map((subagent) => {
+		return createFileOutput(`${SUBAGENTS_DIR}/${subagent.artifact.key}.toml`, renderSubagentToml(subagent.artifact), describeArtifactSource(projectDir, subagent.origin, subagent.artifact.source));
+	});
+	const readOnlySubagents = resolution.subagents.filter((subagent) => subagent.artifact.readOnly).map((subagent) => subagent.artifact.key);
+	const hasReadOnlySubagents = readOnlySubagents.length > 0;
+	outputs.push(...subagentFiles);
+	if (hasReadOnlySubagents) {
+		const names = readOnlySubagents.join(", ");
+		notes.push(`Codex cannot make subagents read-only: ${names}. It turns off their shell and asks them not to edit files.`);
+	}
+	const configFile = planConfigFile(ruleFiles, servers, resolution.env);
+	const execRules = planExecRules(resolution.permissions);
+	const ignoredPaths = [];
+	notes.push(...execRules.notes);
+	if (typeof configFile === "object") {
+		outputs.push(configFile);
+		ignoredPaths.push(CONFIG_FILE);
+	}
+	if (typeof execRules.file === "object") {
+		outputs.push(execRules.file);
+		ignoredPaths.push(EXEC_RULES_FILE);
+	}
+	if (subagentFiles.length > 0) ignoredPaths.push(`${SUBAGENTS_DIR}/`);
+	if (ignoredPaths.length > 0) notes.push(TRUST_NOTE);
+	return {
 		outputs,
-		ignoredPaths: [],
+		ignoredPaths,
 		protectedPaths: [],
 		notes
 	};
-	outputs.push(configFile);
-	notes.push(TRUST_NOTE);
+}
+/**
+* `deny` and `ask` rules for Bash commands become prefix rules of Codex. Codex has no rules
+* for files, the web or MCP tools, and `allow` would mean more in Codex, so those are skipped.
+*/
+function planExecRules(permissions) {
+	const execRules = [];
+	const skippedRules = [];
+	const allowRules = [];
+	for (const resolved of permissions) {
+		const { key, decision } = resolved.artifact;
+		if (hasCodexDecision(decision) === false) {
+			allowRules.push(key);
+			continue;
+		}
+		const pattern = convertBashRule(key);
+		if (pattern === void 0) {
+			skippedRules.push(key);
+			continue;
+		}
+		const execRule = createExecRule(resolved, decision, pattern);
+		execRules.push(execRule);
+	}
+	const notes = [];
+	const hasSkippedRules = skippedRules.length > 0;
+	const hasAllowRules = allowRules.length > 0;
+	if (hasSkippedRules) {
+		const rules = skippedRules.join(", ");
+		notes.push(`Codex skips permission rules that it cannot enforce: ${rules}. Codex rules match only the start of a shell command.`);
+	}
+	if (hasAllowRules) {
+		const rules = allowRules.join(", ");
+		notes.push(`Codex skips allow rules: ${rules}. In Codex, an allowed command runs outside the sandbox without asking.`);
+	}
+	if (execRules.length > 0) {
+		const content = renderExecRules(execRules);
+		return {
+			file: createFileOutput(EXEC_RULES_FILE, content, EXEC_RULES_SOURCE),
+			notes
+		};
+	}
 	return {
-		outputs,
-		ignoredPaths: [CONFIG_FILE],
-		protectedPaths: [],
+		file: void 0,
 		notes
 	};
 }
@@ -1398,6 +1695,7 @@ function renderLevelLine(rule) {
 const HIERARCHY_INTRO = "Instructions are ordered from specific to general. When two instructions conflict, follow the one from the higher level in this list.";
 const RULES_INTRO = "Always follow these rules. Claude Code and Codex load them automatically; other agents should read them before starting work.";
 const SKILLS_INTRO = "Use a skill when the task matches its description.";
+const SUBAGENTS_INTRO = "Hand a task to a subagent when the task matches its description.";
 const ENV_INTRO = "Agents set these variables in every session, also for the commands they run. The values are in the presets.";
 const CHANGING_SECTION = [
 	"## Changing this setup",
@@ -1500,6 +1798,21 @@ function renderMcpServers(servers) {
 		];
 	})));
 }
+function renderSubagents(subagents) {
+	const table = renderTable([
+		"Subagent",
+		"Level",
+		"When to use"
+	], subagents.map((subagent) => {
+		const origin = describeOrigin(subagent);
+		return [
+			subagent.artifact.key,
+			origin,
+			subagent.artifact.description
+		];
+	}));
+	return renderSection("Subagents", SUBAGENTS_INTRO, table);
+}
 function renderEnv(env) {
 	const table = renderTable(["Variable", "Level"], env.map((variable) => {
 		const origin = describeOrigin(variable);
@@ -1532,7 +1845,7 @@ function renderSection(title, intro, table) {
 //#region src/generate/agents-index.ts
 /**
 * AGENTS.md: an index of the setup, not the rules themselves. It lists the levels, every
-* rule, skill, command and MCP server, where each comes from and where its file is.
+* rule, skill, command, MCP server and subagent, where each comes from and where its file is.
 */
 function renderAgentsIndex(resolution) {
 	const title = `# AI agent context: ${resolution.chain.project.name}`;
@@ -1546,6 +1859,7 @@ function renderAgentsIndex(resolution) {
 	const hasSkills = resolution.skills.length > 0;
 	const hasCommands = resolution.commands.length > 0;
 	const hasMcpServers = resolution.mcp.length > 0;
+	const hasSubagents = resolution.subagents.length > 0;
 	const hasEnv = resolution.env.length > 0;
 	if (hasRules) {
 		const rules = renderRules(resolution.rules);
@@ -1563,6 +1877,10 @@ function renderAgentsIndex(resolution) {
 		const servers = renderMcpServers(resolution.mcp);
 		sections.push(servers);
 	}
+	if (hasSubagents) {
+		const subagents = renderSubagents(resolution.subagents);
+		sections.push(subagents);
+	}
 	if (hasEnv) {
 		const env = renderEnv(resolution.env);
 		sections.push(env);
@@ -1652,6 +1970,7 @@ const ArtifactKind = {
 	Skills: "skills",
 	Commands: "commands",
 	Mcp: "mcp",
+	Subagents: "subagents",
 	Env: "env"
 };
 //#endregion
@@ -1722,6 +2041,62 @@ function orderFromSpecific(levels, inherited, selectArtifacts) {
 	return ordered;
 }
 //#endregion
+//#region src/inheritance/inherit-permissions.ts
+/**
+* Permission lists are joined along the chain: every level adds its rules. A more specific
+* level can remove inherited `allow` and `ask` rules with `exclude.permissions`, but not
+* `deny` rules, so that a general level keeps a floor of what is never allowed.
+*/
+function inheritPermissions(levels) {
+	const inherited = /* @__PURE__ */ new Map();
+	const problems = [];
+	for (const level of levels) {
+		const excludeProblems = excludeRules(inherited, level);
+		const origin = createOrigin(level);
+		problems.push(...excludeProblems);
+		for (const rule of level.permissions) {
+			const id = buildRuleId(rule);
+			const previous = inherited.get(id);
+			const overrides = previous === void 0 ? [] : [...previous.overrides, previous.origin];
+			inherited.set(id, {
+				artifact: rule,
+				origin,
+				overrides,
+				patchedBy: []
+			});
+		}
+	}
+	return {
+		artifacts: [...inherited.values()],
+		problems
+	};
+}
+/** The same rule can be in two lists, for example in `allow` on one level and `deny` on another. */
+function buildRuleId(rule) {
+	return `${rule.decision} ${rule.key}`;
+}
+function excludeRules(inherited, level) {
+	const keys = level.exclude.permissions ?? [];
+	const problems = [];
+	for (const key of keys) {
+		const matches = [...inherited.values()].filter((resolved) => resolved.artifact.key === key);
+		const deny = matches.find((resolved) => resolved.artifact.decision === PermissionDecision.Deny);
+		if (typeof deny === "object") {
+			problems.push(`${level.name}: exclude.permissions lists "${key}", but it is a deny rule of ${deny.origin.name}, and a deny rule cannot be removed`);
+			continue;
+		}
+		if (matches.length === 0) {
+			problems.push(`${level.name}: exclude.permissions lists "${key}", but no more general level has it`);
+			continue;
+		}
+		for (const match of matches) {
+			const id = buildRuleId(match.artifact);
+			inherited.delete(id);
+		}
+	}
+	return problems;
+}
+//#endregion
 //#region src/shared/utils/records.ts
 /** Merges two string maps; keys of `patch` win. Missing on both sides stays missing. */
 function mergeRecords(base, patch) {
@@ -1790,13 +2165,17 @@ function applyInheritance(chain) {
 	const skills = inheritArtifacts(chain.levels, ArtifactKind.Skills, (level) => level.skills);
 	const commands = inheritArtifacts(chain.levels, ArtifactKind.Commands, (level) => level.commands);
 	const mcp = inheritArtifacts(chain.levels, ArtifactKind.Mcp, (level) => level.mcp, patchMcpServers);
+	const subagents = inheritArtifacts(chain.levels, ArtifactKind.Subagents, (level) => level.subagents);
 	const env = inheritArtifacts(chain.levels, ArtifactKind.Env, (level) => level.env);
+	const permissions = inheritPermissions(chain.levels);
 	const problems = [
 		...rules.problems,
 		...skills.problems,
 		...commands.problems,
 		...mcp.problems,
-		...env.problems
+		...subagents.problems,
+		...env.problems,
+		...permissions.problems
 	];
 	if (problems.length > 0) throw createProblemsError(problems);
 	return {
@@ -1805,7 +2184,9 @@ function applyInheritance(chain) {
 		skills: skills.artifacts,
 		commands: commands.artifacts,
 		mcp: mcp.artifacts,
-		env: env.artifacts
+		subagents: subagents.artifacts,
+		env: env.artifacts,
+		permissions: permissions.artifacts
 	};
 }
 //#endregion
@@ -2157,14 +2538,29 @@ async function runSetup(projectDir, options) {
 /** For --verbose: every artifact, the level it comes from and the file to edit. */
 function describeResolution(resolution) {
 	const projectDir = resolution.chain.project.dir;
+	const permissions = resolution.permissions.map(labelPermission);
 	return [
 		describeSection("Rules", resolution.rules, projectDir),
 		describeSection("Skills", resolution.skills, projectDir),
 		describeSection("Commands", resolution.commands, projectDir),
 		describeSection("MCP servers", resolution.mcp, projectDir),
-		describeSection("Environment", resolution.env, projectDir)
+		describeSection("Subagents", resolution.subagents, projectDir),
+		describeSection("Environment", resolution.env, projectDir),
+		describeSection("Permissions", permissions, projectDir)
 	].filter((section) => section.length > 0).join("\n\n");
 }
+/** For example `deny Read(./.env)`: the same rule can be in two lists. */
+function labelPermission(resolved) {
+	const { decision, key } = resolved.artifact;
+	const artifact = {
+		...resolved.artifact,
+		key: `${decision} ${key}`
+	};
+	return {
+		...resolved,
+		artifact
+	};
+}
 function describeSection(title, artifacts, projectDir) {
 	if (artifacts.length === 0) return "";
 	const rows = artifacts.map((resolved) => {

package/dist/index.mjs

@@ -1 +1 @@
-export { t as VERSION } from "./src-BNeh64fK.mjs";
+export { t as VERSION } from "./src-CZK2Ixbt.mjs";

package/dist/{src-BNeh64fK.mjs → src-CZK2Ixbt.mjs}

@@ -1,5 +1,5 @@
 //#endregion
 //#region src/index.ts
-const VERSION = "0.3.0";
+const VERSION = "0.5.0";
 //#endregion
 export { VERSION as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunestra",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Tune your AI agents to play as one orchestra: one source of rules, skills, commands and MCP servers for Claude Code, Codex and more.",
   "keywords": [
     "ai",