@technomoron/agent-run 0.99.12 → 0.99.14

package/CHANGES

@@ -1,8 +1,13 @@
 CHANGES
 =======
 
-Unreleased (2026-04-24)
------------------------
+Version 0.99.14 (2026-04-30)
+----------------------------
+* Add `--show` for Codex and Claude runs to print the tool-specific source templates/includes and generated files without launching the underlying tool.
+
+Version 0.99.13 (2026-04-27)
+----------------------------
+* Render each profile's generated files and runtime state under `live/`, leaving the profile root for source config and templates.
 
 Version 0.99.12 (2026-04-27)
 ----------------------------

package/dist/agent-run.js

@@ -22,28 +22,13 @@ const CONFIG_DIR_ENV = 'AGENT_CONFIG_DIR';
 const VERBOSE_ENV = 'AGENT_RUN_VERBOSE';
 const MANIFEST_FILE_NAME = 'agent-run.jsonc';
 const LOCAL_TEMPLATE_FILE_NAME = 'local.md.njk';
+const LIVE_DIR_NAME = 'live';
 const PACKAGE_VERSION = '0.99.10';
 const UNEXPANDED_TEMPLATE_RE = /\{\{[^}]+\}\}|\{%[^%]+%\}/;
 const agentRunEnvCache = new Map();
 const GENERATED_GITIGNORE_ENTRIES = [
-    '# Generated agent-run files',
-    '**/AGENTS.md',
-    '**/CLAUDE.md',
-    '**/GEMINI.md',
-    '**/config.toml',
-    '',
-    '# Generated native agent homes',
-    '**/.agents/',
-    '**/.claude/',
-    '**/.codex/',
-    '',
-    '# Generated runtime files',
-    '**/bin/',
-    '**/reviews/',
-    '**/memories/',
-    '',
-    '# Generated review reports',
-    '**/REVIEW-*.md',
+    '# Generated agent-run live profiles',
+    '**/live/',
     '',
     '# Optional generated caches',
     '**/.agent-run-cache/'
@@ -217,6 +202,7 @@ function parseRunCommand(command, inputArgs) {
         none: false,
         create: false,
         local: false,
+        show: false,
         codexSandboxMode: null,
         codexNetwork: false
     };
@@ -243,6 +229,10 @@ function parseRunCommand(command, inputArgs) {
             wrapperArgs.local = true;
             continue;
         }
+        if (arg === '--show') {
+            wrapperArgs.show = true;
+            continue;
+        }
         if (arg === '--danger') {
             if (command !== 'codex') {
                 fail('--danger is only supported for agent-run codex');
@@ -417,9 +407,9 @@ function renderHelp(topic) {
                 '  agent-run --init [config-root]',
                 '',
                 'Commands:',
-                '  codex [--none] [--create] [--local] [--danger|--sandboxed] [--network] [args...]',
+                '  codex [--none] [--create] [--local] [--show] [--danger|--sandboxed] [--network] [args...]',
                 '                                           Run codex with generated private config',
-                '  claude [--none] [--create] [--local] [args...]',
+                '  claude [--none] [--create] [--local] [--show] [args...]',
                 '                                           Run claude with generated private config',
                 '  check [--all] [path]                  Validate generated profile output',
                 '  init [path]                           Create profile source files and render output',
@@ -434,8 +424,11 @@ function renderHelp(topic) {
                 '  --config-root DIR  Override the agent-config root',
                 '  --init [DIR]       Copy the packaged starter config root to DIR (default ~/.agent-config)',
                 '',
-                'Codex wrapper options:',
+                'Run wrapper options:',
                 '  --local            Warn about local AI files instead of failing',
+                '  --show             Show read/include and generated files without running the tool',
+                '',
+                'Codex wrapper options:',
                 '  --danger           Run Codex with no sandbox: -a never -s danger-full-access (default)',
                 '  --sandboxed        Run Codex with workspace-write sandbox',
                 '  --network          Enable network for --sandboxed via config override',
@@ -489,30 +482,41 @@ function normalizeCommandName(value) {
 }
 function runTool(parsed) {
     const { args, command, wrapperArgs } = parsed;
-    const realBinary = findRealBinary(command);
-    const permissionArgs = getPermissionArgs(command);
     const projectRoot = findProjectRoot(process.cwd());
     verbose(`run ${command}: cwd=${process.cwd()} projectRoot=${projectRoot}`);
+    if (wrapperArgs.show && wrapperArgs.none) {
+        fail('--show cannot be combined with --none');
+    }
+    if (wrapperArgs.show && isIgnoredDir(projectRoot)) {
+        fail(`cannot show generated ${command} files for ignored project: ${projectRoot}`);
+    }
     if (wrapperArgs.none || isIgnoredDir(projectRoot)) {
+        const realBinary = findRealBinary(command);
+        const permissionArgs = getPermissionArgs(command);
         verbose(`wrapper bypassed for ${command}${wrapperArgs.none ? ' via --none' : ' because project is ignored'}`);
         execTool(realBinary, [...permissionArgs, ...args]);
         return;
     }
     const profileResult = resolveProfileResult(projectRoot);
-    const excludedDir = profileResult.profile === null ? null : resolveAgentDir(projectRoot);
-    const localAiFiles = findLocalAiFiles(projectRoot, excludedDir);
-    if (localAiFiles.length > 0) {
-        if (!wrapperArgs.local) {
-            failForLocalAiFiles(command, projectRoot, localAiFiles);
-        }
-        warnForLocalAiFiles(command, projectRoot, localAiFiles);
-    }
     if (profileResult.profile === null) {
         fail(profileResult.reason);
     }
     const profile = profileResult.profile;
     const configRoot = defaultConfigRoot(projectRoot);
     const agentDir = resolveAgentDir(projectRoot);
+    if (wrapperArgs.show) {
+        showToolProfile(command, projectRoot, agentDir);
+        return;
+    }
+    const localAiFiles = findLocalAiFiles(projectRoot, agentDir);
+    if (localAiFiles.length > 0) {
+        if (!wrapperArgs.local) {
+            failForLocalAiFiles(command, projectRoot, localAiFiles);
+        }
+        warnForLocalAiFiles(command, projectRoot, localAiFiles);
+    }
+    const realBinary = findRealBinary(command);
+    const permissionArgs = getPermissionArgs(command);
     if (wrapperArgs.create) {
         runInit({ command: 'init', targetPath: projectRoot });
     }
@@ -524,6 +528,31 @@ function runTool(parsed) {
     }
     runClaude(realBinary, permissionArgs, agentDir, configRoot, args, projectRoot, wrapperArgs);
 }
+function showToolProfile(command, projectRoot, agentDir) {
+    const trace = { sourceFiles: new Set() };
+    const rendered = renderProfile(projectRoot, agentDir, true, command, trace);
+    const generatedFiles = uniqueSorted(rendered.files.map((file) => file.path));
+    const sourceFiles = uniqueSorted([...trace.sourceFiles]);
+    process.stdout.write([
+        `Agent: ${command}`,
+        `Profile: ${rendered.profile}`,
+        `Project root: ${projectRoot}`,
+        `Profile dir: ${agentDir}`,
+        '',
+        'Reads/includes:',
+        ...formatPathList(sourceFiles),
+        '',
+        'Generates:',
+        ...formatPathList(generatedFiles),
+        ''
+    ].join('\n'));
+}
+function uniqueSorted(values) {
+    return [...new Set(values.map((value) => path.resolve(value)))].sort((a, b) => a.localeCompare(b));
+}
+function formatPathList(paths) {
+    return paths.length === 0 ? ['  (none)'] : paths.map((entry) => `  ${entry}`);
+}
 function runInit(parsed) {
     const projectRoot = findProjectRoot(parsed.targetPath);
     verbose(`init target=${parsed.targetPath} projectRoot=${projectRoot}`);
@@ -670,7 +699,8 @@ function runCheck(parsed) {
 }
 function printUpdateSummary(rendered) {
     process.stdout.write(`OK profile ${rendered.profile}\n`);
-    process.stdout.write(`Agent dir: ${rendered.agentDir}\n`);
+    process.stdout.write(`Profile dir: ${rendered.agentDir}\n`);
+    process.stdout.write(`Live dir: ${rendered.context.paths.liveDir}\n`);
     process.stdout.write(`Generated files: ${rendered.files.length}\n`);
     process.stdout.write(`Installed skills: ${rendered.skills.map((skill) => skill.name).join(', ') || '(none)'}\n`);
 }
@@ -873,7 +903,7 @@ function createDefaultLocalFile(agentDir, profile) {
 function ensureProfileOverridesDir(agentDir) {
     fs.mkdirSync(path.join(agentDir, 'overrides'), { recursive: true });
 }
-function loadManifest(_configRoot, agentDir, profile) {
+function loadManifest(_configRoot, agentDir, profile, trace) {
     const manifestPath = path.join(agentDir, MANIFEST_FILE_NAME);
     if (!fs.existsSync(manifestPath)) {
         const manifest = defaultManifest(profile);
@@ -893,6 +923,7 @@ function loadManifest(_configRoot, agentDir, profile) {
         }
         return manifest;
     }
+    trace?.sourceFiles.add(manifestPath);
     const text = fs.readFileSync(manifestPath, 'utf8');
     const errors = [];
     const parsed = (0, jsonc_parser_1.parse)(text, errors, { allowTrailingComma: true });
@@ -992,29 +1023,33 @@ function createNunjucksEnv(configRoot) {
         throwOnUndefined: true
     });
 }
-function buildRenderContext(projectRoot, agentDir, configRoot, manifest, env) {
+function buildRenderContext(projectRoot, profileDir, configRoot, manifest, env) {
     const date = localDateString();
+    const liveDir = path.join(profileDir, LIVE_DIR_NAME);
     const baseContext = {
         profile: manifest.profile,
         kind: manifest.kind,
         projectRoot,
-        agentDir,
+        agentDir: liveDir,
+        profileDir,
         configRoot,
         date,
         checks: manifest.checks,
         guardrails: manifest.guardrails
     };
     const paths = {
+        profileDir,
+        liveDir,
         changesFile: resolveRuntimePath(configRoot, manifest.paths.changesFile, env, baseContext),
         reviewDir: resolveRuntimePath(configRoot, manifest.paths.reviewDir, env, baseContext),
         reviewFile: resolveRuntimePath(configRoot, manifest.paths.reviewFile, env, baseContext),
         memoriesDir: resolveRuntimePath(configRoot, manifest.paths.memoriesDir, env, baseContext),
         globalMemoryDir: globalMemoryDir(configRoot),
         codexHomeDir: path.join(resolveRuntimePath(configRoot, manifest.paths.memoriesDir, env, baseContext), 'codex-home'),
-        overridesDir: path.join(agentDir, 'overrides'),
-        codexSkillsDir: path.join(agentDir, '.agents', 'skills'),
-        claudeSkillsDir: path.join(agentDir, '.claude', 'skills'),
-        binDir: path.join(agentDir, 'bin')
+        overridesDir: path.join(profileDir, 'overrides'),
+        codexSkillsDir: path.join(liveDir, '.agents', 'skills'),
+        claudeSkillsDir: path.join(liveDir, '.claude', 'skills'),
+        binDir: path.join(liveDir, 'bin')
     };
     return {
         ...baseContext,
@@ -1047,19 +1082,48 @@ function resolveRuntimePath(configRoot, pathTemplate, env, context) {
     const rendered = renderInlineTemplate(env, pathTemplate, context);
     return path.isAbsolute(rendered) ? path.resolve(rendered) : path.resolve(configRoot, rendered);
 }
-function renderTemplateFile(env, configRoot, templatePath, context) {
+function renderTemplateFile(env, configRoot, templatePath, context, trace) {
     const resolvedPath = resolveConfigPath(configRoot, templatePath, context);
     if (!fs.existsSync(resolvedPath)) {
         throw new Error(`missing template: ${resolvedPath}`);
     }
     const relativePath = path.relative(configRoot, resolvedPath).replace(/\\/g, '/');
     let content = fs.readFileSync(resolvedPath, 'utf8');
+    traceTemplateSource(configRoot, resolvedPath, content, context, trace);
     if (path.basename(resolvedPath) === 'AGENTS-MODS.md') {
-        content = renderLegacyAgentsMods(resolvedPath);
+        content = renderLegacyAgentsMods(resolvedPath, [], trace);
         return renderInlineTemplate(env, content, context);
     }
     return env.render(relativePath, context);
 }
+function traceTemplateSource(configRoot, sourcePath, content, context, trace, stack = []) {
+    if (trace === undefined) {
+        return;
+    }
+    const resolvedSource = path.resolve(sourcePath);
+    trace.sourceFiles.add(resolvedSource);
+    if (stack.includes(resolvedSource)) {
+        return;
+    }
+    const nextStack = [...stack, resolvedSource];
+    const includeRe = /{%\s*(?:include|extends|import)\s+["']([^"']+)["']|{%\s*from\s+["']([^"']+)["']/g;
+    for (;;) {
+        const match = includeRe.exec(content);
+        if (match === null) {
+            break;
+        }
+        const includePath = match[1] ?? match[2];
+        if (!includePath) {
+            continue;
+        }
+        const includedPath = resolveConfigPath(configRoot, includePath, context);
+        if (!fs.existsSync(includedPath)) {
+            continue;
+        }
+        const includedContent = fs.readFileSync(includedPath, 'utf8');
+        traceTemplateSource(configRoot, includedPath, includedContent, context, trace, nextStack);
+    }
+}
 function renderInlineTemplate(env, source, context) {
     return env.renderString(source, context);
 }
@@ -1100,11 +1164,11 @@ function copySkeletonTree(sourceDir, targetDir) {
         fs.copyFileSync(sourcePath, targetPath);
     }
 }
-function renderProfile(projectRoot, agentDir, checkOnly = false) {
+function renderProfile(projectRoot, agentDir, checkOnly = false, targetTool = null, trace) {
     const configRoot = defaultConfigRoot(projectRoot);
     const profile = resolveProfile(projectRoot);
     const env = createNunjucksEnv(configRoot);
-    const manifest = normalizeManifest(loadManifest(configRoot, agentDir, profile), profile);
+    const manifest = normalizeManifest(loadManifest(configRoot, agentDir, profile, trace), profile);
     if (manifest.profile !== profile) {
         const parsed = parseProfile(manifest.profile, `${path.join(agentDir, MANIFEST_FILE_NAME)} profile`);
         if (parsed.profile === null) {
@@ -1115,7 +1179,7 @@ function renderProfile(projectRoot, agentDir, checkOnly = false) {
         ensureConfigRootGitignore(configRoot);
     }
     const context = buildRenderContext(projectRoot, agentDir, configRoot, manifest, env);
-    const sections = [renderTemplateFile(env, configRoot, manifest.agent.base, context)];
+    const sections = [renderTemplateFile(env, configRoot, manifest.agent.base, context, trace)];
     for (const include of manifest.agent.includes) {
         const includePath = resolveConfigPath(configRoot, include, context);
         if (!fs.existsSync(includePath)) {
@@ -1124,23 +1188,31 @@ function renderProfile(projectRoot, agentDir, checkOnly = false) {
             }
             throw new Error(`missing template: ${includePath}`);
         }
-        sections.push(renderTemplateFile(env, configRoot, include, context));
+        sections.push(renderTemplateFile(env, configRoot, include, context, trace));
     }
     context.renderedAgentSections = sections.map((section, index) => {
         const label = index === 0 ? manifest.agent.base : manifest.agent.includes[index - 1] ?? `section ${index}`;
         assertNoUnexpandedTemplateVars(label, section);
         return section.trimEnd();
     });
-    context.skills = renderSkills(env, configRoot, manifest, context);
+    context.skills = renderSkills(env, configRoot, manifest, context, trace);
     const files = [];
-    const agentsContent = renderToolInstructions('AGENTS.md', env, configRoot, context, false);
-    const claudeContent = renderToolInstructions('CLAUDE.md', env, configRoot, context, true);
-    files.push({ path: path.join(agentDir, 'AGENTS.md'), content: agentsContent });
-    files.push({ path: path.join(agentDir, 'CLAUDE.md'), content: claudeContent });
-    files.push({ path: path.join(agentDir, '.claude', 'CLAUDE.md'), content: claudeContent });
-    files.push({ path: path.join(agentDir, 'config.toml'), content: renderCodexConfig(env, configRoot, context) });
-    files.push({ path: path.join(agentDir, '.claude', 'agent-run-settings.json'), content: renderClaudeSettings(env, configRoot, context) });
-    files.push(...renderNativeSkillFiles(context));
+    if (targetTool === null || targetTool === 'codex') {
+        const agentsContent = renderToolInstructions('AGENTS.md', env, configRoot, context, false, trace);
+        files.push({ path: path.join(context.paths.liveDir, 'AGENTS.md'), content: agentsContent });
+        files.push({ path: path.join(context.paths.liveDir, 'config.toml'), content: renderCodexConfig(env, configRoot, context, trace) });
+        files.push(...renderNativeSkillFiles(context, 'codex'));
+    }
+    if (targetTool === null || targetTool === 'claude') {
+        const claudeContent = renderToolInstructions('CLAUDE.md', env, configRoot, context, true, trace);
+        files.push({ path: path.join(context.paths.liveDir, 'CLAUDE.md'), content: claudeContent });
+        files.push({ path: path.join(context.paths.liveDir, '.claude', 'CLAUDE.md'), content: claudeContent });
+        files.push({
+            path: path.join(context.paths.liveDir, '.claude', 'agent-run-settings.json'),
+            content: renderClaudeSettings(env, configRoot, context, trace)
+        });
+        files.push(...renderNativeSkillFiles(context, 'claude'));
+    }
     files.push(...renderGuardShims(context));
     return {
         agentDir,
@@ -1161,15 +1233,22 @@ function syncAgentProfile(projectRoot, agentDir) {
     return rendered;
 }
 function removeLegacyGeneratedClaudeSettings(context) {
-    const legacyPath = path.join(context.agentDir, '.claude', 'settings.json');
-    if (!fs.existsSync(legacyPath)) {
-        return;
-    }
-    const actual = fs.readFileSync(legacyPath, 'utf8').replace(/\r\n/g, '\n');
-    const legacyGeneratedContent = legacyDefaultClaudeSettingsContent(context);
-    if (actual === legacyGeneratedContent) {
-        fs.rmSync(legacyPath);
-        verbose(`removed legacy generated Claude settings ${legacyPath}`);
+    for (const legacyPath of [
+        path.join(context.paths.liveDir, '.claude', 'settings.json'),
+        path.join(context.profileDir, '.claude', 'settings.json')
+    ]) {
+        if (!fs.existsSync(legacyPath)) {
+            continue;
+        }
+        const actual = fs.readFileSync(legacyPath, 'utf8').replace(/\r\n/g, '\n');
+        const legacyGeneratedContents = [
+            legacyDefaultClaudeSettingsContent(context, context.agentDir),
+            legacyDefaultClaudeSettingsContent(context, context.profileDir)
+        ];
+        if (legacyGeneratedContents.includes(actual)) {
+            fs.rmSync(legacyPath);
+            verbose(`removed legacy generated Claude settings ${legacyPath}`);
+        }
     }
 }
 function checkRenderedProfile(projectRoot, agentDir) {
@@ -1191,6 +1270,7 @@ function checkRenderedProfile(projectRoot, agentDir) {
             rendered.context.paths.reviewDir,
             rendered.context.paths.memoriesDir,
             rendered.context.paths.codexHomeDir,
+            rendered.context.paths.liveDir,
             rendered.context.paths.overridesDir,
             rendered.context.paths.codexSkillsDir,
             rendered.context.paths.claudeSkillsDir,
@@ -1224,7 +1304,7 @@ function checkRenderedProfile(projectRoot, agentDir) {
     }
     return findings;
 }
-function renderSkills(env, configRoot, manifest, context) {
+function renderSkills(env, configRoot, manifest, context, trace) {
     const skills = [];
     for (const name of manifest.skills.install) {
         const sourceTemplate = manifest.skills.overrides[name] ?? `global/skills/${name}/SKILL.md.njk`;
@@ -1232,7 +1312,7 @@ function renderSkills(env, configRoot, manifest, context) {
         if (!fs.existsSync(sourcePath)) {
             throw new Error(`missing skill template for ${name}: ${sourcePath}`);
         }
-        const renderedContent = renderTemplateFile(env, configRoot, sourceTemplate, context);
+        const renderedContent = renderTemplateFile(env, configRoot, sourceTemplate, context, trace);
         assertNoUnexpandedTemplateVars(`skill ${name}`, renderedContent);
         validateRenderedSkill(renderedContent, sourcePath);
         const description = extractSkillDescription(renderedContent);
@@ -1240,41 +1320,45 @@ function renderSkills(env, configRoot, manifest, context) {
     }
     return skills;
 }
-function renderNativeSkillFiles(context) {
+function renderNativeSkillFiles(context, targetTool = null) {
     const files = [];
     for (const skill of context.skills) {
-        files.push({
-            path: path.join(context.paths.codexSkillsDir, skill.name, 'SKILL.md'),
-            content: skill.renderedContent
-        });
-        files.push({
-            path: path.join(context.paths.claudeSkillsDir, skill.name, 'SKILL.md'),
-            content: skill.renderedContent
-        });
+        if (targetTool === null || targetTool === 'codex') {
+            files.push({
+                path: path.join(context.paths.codexSkillsDir, skill.name, 'SKILL.md'),
+                content: skill.renderedContent
+            });
+        }
+        if (targetTool === null || targetTool === 'claude') {
+            files.push({
+                path: path.join(context.paths.claudeSkillsDir, skill.name, 'SKILL.md'),
+                content: skill.renderedContent
+            });
+        }
     }
     return files;
 }
-function renderToolInstructions(templateName, env, configRoot, context, isClaude) {
+function renderToolInstructions(templateName, env, configRoot, context, isClaude, trace) {
     const templatePath = `global/tool-templates/${templateName}.njk`;
     const absoluteTemplate = path.join(configRoot, templatePath);
     const content = fs.existsSync(absoluteTemplate)
-        ? renderTemplateFile(env, configRoot, templatePath, context)
+        ? renderTemplateFile(env, configRoot, templatePath, context, trace)
         : renderInlineTemplate(env, defaultToolInstructionsTemplate(isClaude), context);
     assertNoUnexpandedTemplateVars(templateName, content);
     return content.replace(/\n*$/, '\n');
 }
-function renderCodexConfig(env, configRoot, context) {
+function renderCodexConfig(env, configRoot, context, trace) {
     const templatePath = resolveProfileOverrideTemplate(configRoot, context, 'codex-config.toml.njk', 'global/tool-templates/codex-config.toml.njk');
     const content = templatePath !== null
-        ? renderTemplateFile(env, configRoot, templatePath, context)
+        ? renderTemplateFile(env, configRoot, templatePath, context, trace)
         : defaultCodexConfigContent(context);
     assertNoUnexpandedTemplateVars('config.toml', content);
     return content.replace(/\n*$/, '\n');
 }
-function renderClaudeSettings(env, configRoot, context) {
+function renderClaudeSettings(env, configRoot, context, trace) {
     const templatePath = resolveProfileOverrideTemplate(configRoot, context, 'claude-settings.json.njk', 'global/tool-templates/claude-settings.json.njk');
     const content = templatePath !== null
-        ? renderTemplateFile(env, configRoot, templatePath, context)
+        ? renderTemplateFile(env, configRoot, templatePath, context, trace)
         : defaultClaudeSettingsContent(context);
     assertNoUnexpandedTemplateVars('claude settings.json', content);
     return content.replace(/\n*$/, '\n');
@@ -1312,7 +1396,7 @@ function syncRuntimeDirs(context) {
         context.paths.codexSkillsDir,
         context.paths.claudeSkillsDir,
         context.paths.binDir,
-        path.join(context.agentDir, '.claude')
+        path.join(context.paths.liveDir, '.claude')
     ]) {
         fs.mkdirSync(dir, { recursive: true });
     }
@@ -1346,8 +1430,9 @@ function extractSkillDescription(content) {
     }
     return '';
 }
-function renderLegacyAgentsMods(sourceFile, stack = []) {
+function renderLegacyAgentsMods(sourceFile, stack = [], trace) {
     const resolvedSource = path.resolve(sourceFile);
+    trace?.sourceFiles.add(resolvedSource);
     if (stack.includes(resolvedSource)) {
         throw new Error(`Include cycle detected: ${[...stack, resolvedSource].join(' -> ')}`);
     }
@@ -1367,7 +1452,9 @@ function renderLegacyAgentsMods(sourceFile, stack = []) {
             if (!includePath) {
                 continue;
             }
-            output.push(renderLegacyAgentsMods(resolveIncludePath(resolvedSource, includePath), nextStack));
+            const resolvedInclude = resolveIncludePath(resolvedSource, includePath);
+            trace?.sourceFiles.add(resolvedInclude);
+            output.push(renderLegacyAgentsMods(resolvedInclude, nextStack, trace));
             if (!contentStarted) {
                 sawLeadingInclude = true;
             }
@@ -1522,17 +1609,19 @@ function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function runCodex(realBinary, permissionArgs, agentDir, configRoot, args, projectRoot, wrapperArgs) {
-    const agentsPath = path.join(agentDir, 'AGENTS.md');
+    const liveDir = profileLiveDir(agentDir);
+    const agentsPath = path.join(liveDir, 'AGENTS.md');
     if (!fs.existsSync(agentsPath)) {
         failMissingConfig('codex', agentDir);
     }
-    const guardBin = path.join(agentDir, 'bin');
-    const codexHomeDir = path.join(agentDir, 'memories', 'codex-home');
+    const guardBin = path.join(liveDir, 'bin');
+    const codexHomeDir = path.join(liveDir, 'memories', 'codex-home');
     fs.mkdirSync(codexHomeDir, { recursive: true });
     const env = {
         ...process.env,
         CODEX_HOME: codexHomeDir,
-        AGENT_DIR: agentDir,
+        AGENT_DIR: liveDir,
+        AGENT_PROFILE_DIR: agentDir,
         AGENT_RUN_PROJECT_ROOT: projectRoot,
         PATH: `${guardBin}${path.delimiter}${process.env.PATH ?? ''}`
     };
@@ -1561,16 +1650,18 @@ function buildCodexRuntimeArgs(wrapperArgs) {
     return ['-a', 'never', '-s', 'danger-full-access'];
 }
 function runClaude(realBinary, permissionArgs, agentDir, configRoot, args, projectRoot, wrapperArgs) {
-    const claudePath = path.join(agentDir, 'CLAUDE.md');
+    const liveDir = profileLiveDir(agentDir);
+    const claudePath = path.join(liveDir, 'CLAUDE.md');
     if (!fs.existsSync(claudePath)) {
         failMissingConfig('claude', agentDir);
     }
-    const guardBin = path.join(agentDir, 'bin');
-    const claudeConfigDir = path.join(agentDir, '.claude');
+    const guardBin = path.join(liveDir, 'bin');
+    const claudeConfigDir = path.join(liveDir, '.claude');
     const env = {
         ...process.env,
         CLAUDE_CONFIG_DIR: claudeConfigDir,
-        AGENT_DIR: agentDir,
+        AGENT_DIR: liveDir,
+        AGENT_PROFILE_DIR: agentDir,
         AGENT_RUN_PROJECT_ROOT: projectRoot,
         PATH: `${guardBin}${path.delimiter}${process.env.PATH ?? ''}`
     };
@@ -1581,11 +1672,14 @@ function runClaude(realBinary, permissionArgs, agentDir, configRoot, args, proje
         '--add-dir',
         projectRoot,
         '--add-dir',
-        agentDir,
+        liveDir,
         ...globalMemoryArgs(configRoot),
         ...args
     ], shouldUseShell(realBinary), env, projectRoot, (code) => postflightProjectCheck(projectRoot, agentDir, wrapperArgs.local, code));
 }
+function profileLiveDir(agentDir) {
+    return path.join(agentDir, LIVE_DIR_NAME);
+}
 function globalMemoryArgs(configRoot) {
     const memoryDir = globalMemoryDir(configRoot);
     return fs.existsSync(memoryDir) ? ['--add-dir', memoryDir] : [];
@@ -2135,6 +2229,12 @@ function defaultLocalTemplate(_profile) {
         '{{ agentDir }}',
         '```',
         '',
+        'Profile source directory:',
+        '',
+        '```text',
+        '{{ profileDir }}',
+        '```',
+        '',
         'Add project-specific rules here.',
         ''
     ].join('\n');
@@ -2177,7 +2277,8 @@ function defaultNoAiFilesSnippet() {
         '## Agent File Storage',
         '',
         'Do not create AGENTS.md, CLAUDE.md, .agents, .claude, .codex, or other agent runtime files inside the project repository.',
-        'Agent-only files belong under {{ agentDir }}.',
+        'Generated agent-only files belong under {{ paths.liveDir }}.',
+        'Source config files belong under {{ profileDir }}.',
         ''
     ].join('\n');
 }
@@ -2249,8 +2350,8 @@ function defaultToolInstructionsTemplate(isClaude) {
         'Do not edit this file directly. Edit:',
         '',
         '```text',
-        '{{ agentDir }}/agent-run.jsonc',
-        '{{ agentDir }}/local.md.njk',
+        '{{ profileDir }}/agent-run.jsonc',
+        '{{ profileDir }}/local.md.njk',
         '```',
         '',
         '{% for section in renderedAgentSections %}',
@@ -2271,6 +2372,12 @@ function defaultToolInstructionsTemplate(isClaude) {
         '{{ agentDir }}',
         '```',
         '',
+        'Profile source directory:',
+        '',
+        '```text',
+        '{{ profileDir }}',
+        '```',
+        '',
         'Review directory:',
         '',
         '```text',
@@ -2310,13 +2417,14 @@ function defaultToolInstructionsTemplate(isClaude) {
         '## Tool Note',
         '',
         isClaude
-            ? 'Claude uses the generated config directory under {{ agentDir }}/.claude and may read {{ agentDir }} via `--add-dir`.'
+            ? 'Claude uses the generated config directory under {{ paths.liveDir }}/.claude and may read {{ paths.liveDir }} via `--add-dir`.'
             : 'Codex uses {{ agentDir }}/AGENTS.md as `system_prompt_file` and {{ paths.codexHomeDir }} as CODEX_HOME.',
         '',
         '## Mandatory Path Rule',
         '',
         'Do not create AGENTS.md, CLAUDE.md, .agents, .claude, .codex, or AI-related files inside the project repository.',
-        'Agent-only files must be stored under the agent directory shown above.',
+        'Generated agent-only files must be stored under the agent directory shown above.',
+        'Source config files must be stored under the profile source directory shown above.',
         ''
     ].join('\n');
 }
@@ -2331,6 +2439,7 @@ function defaultCodexConfigTemplate() {
         'writable_roots = [',
         '  "{{ projectRoot }}",',
         '  "{{ agentDir }}",',
+        '  "{{ profileDir }}",',
         '  "{{ paths.globalMemoryDir }}"',
         ']',
         'network_access = false',
@@ -2341,6 +2450,7 @@ function defaultClaudeSettingsTemplate() {
     const envBlock = [
         '  "env": {',
         '    "AGENT_DIR": "{{ agentDir }}",',
+        '    "AGENT_PROFILE_DIR": "{{ profileDir }}",',
         '    "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",',
         '    "AGENT_GLOBAL_MEMORY_DIR": "{{ paths.globalMemoryDir }}"',
         '  }'
@@ -2371,6 +2481,7 @@ function defaultCodexConfigContent(context) {
         'writable_roots = [',
         `  ${jsonString(context.projectRoot)},`,
         `  ${jsonString(context.agentDir)},`,
+        `  ${jsonString(context.profileDir)},`,
         `  ${jsonString(context.paths.globalMemoryDir)}`,
         ']',
         'network_access = false',
@@ -2381,6 +2492,7 @@ function defaultClaudeSettingsContent(context) {
     const settings = {
         env: {
             AGENT_DIR: context.agentDir,
+            AGENT_PROFILE_DIR: context.profileDir,
             AGENT_RUN_PROJECT_ROOT: context.projectRoot,
             AGENT_GLOBAL_MEMORY_DIR: context.paths.globalMemoryDir
         }
@@ -2390,10 +2502,10 @@ function defaultClaudeSettingsContent(context) {
     }
     return `${JSON.stringify(settings, null, 2)}\n`;
 }
-function legacyDefaultClaudeSettingsContent(context) {
+function legacyDefaultClaudeSettingsContent(context, agentDir) {
     return `${JSON.stringify({
         env: {
-            AGENT_DIR: context.agentDir,
+            AGENT_DIR: agentDir,
             AGENT_RUN_PROJECT_ROOT: context.projectRoot,
             AGENT_GLOBAL_MEMORY_DIR: context.paths.globalMemoryDir
         }

package/examples/basic-config/agent-config/gitignore

@@ -1,21 +1,5 @@
-# Generated agent-run files
-**/AGENTS.md
-**/CLAUDE.md
-**/GEMINI.md
-**/config.toml
-
-# Generated native agent homes
-**/.agents/
-**/.claude/
-**/.codex/
-
-# Generated runtime files
-**/bin/
-**/reviews/
-**/memories/
-
-# Generated review reports
-**/REVIEW-*.md
+# Generated agent-run live profiles
+**/live/
 
 # Optional generated caches
 **/.agent-run-cache/

package/examples/basic-config/agent-config/global/snippets/no-ai-files.md.njk

@@ -7,3 +7,9 @@ Agent directory:
 ```text
 {{ agentDir }}
 ```
+
+Profile source directory:
+
+```text
+{{ profileDir }}
+```

package/examples/basic-config/agent-config/global/tool-templates/AGENTS.md.njk

@@ -10,6 +10,7 @@ Do not edit this generated file. Edit `agent-run.jsonc` and `local.md.njk`.
 
 - projectRoot: `{{ projectRoot }}`
 - agentDir: `{{ agentDir }}`
+- profileDir: `{{ profileDir }}`
 - reviewFile: `{{ paths.reviewFile }}`
 - memoriesDir: `{{ paths.memoriesDir }}`
 - globalMemoryDir: `{{ paths.globalMemoryDir }}`

package/examples/basic-config/agent-config/global/tool-templates/claude-settings.json.njk

@@ -1,6 +1,7 @@
 {% if permissionsAllow.length %}{
   "env": {
     "AGENT_DIR": "{{ agentDir }}",
+    "AGENT_PROFILE_DIR": "{{ profileDir }}",
     "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",
     "AGENT_GLOBAL_MEMORY_DIR": "{{ paths.globalMemoryDir }}",
     "STARTER_PROFILE": "{{ profile }}"
@@ -14,6 +15,7 @@
 {% else %}{
   "env": {
     "AGENT_DIR": "{{ agentDir }}",
+    "AGENT_PROFILE_DIR": "{{ profileDir }}",
     "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",
     "AGENT_GLOBAL_MEMORY_DIR": "{{ paths.globalMemoryDir }}",
     "STARTER_PROFILE": "{{ profile }}"

package/examples/basic-config/agent-config/global/tool-templates/codex-config.toml.njk

@@ -6,6 +6,7 @@ sandbox_mode = "workspace-write"
 writable_roots = [
   "{{ projectRoot }}",
   "{{ agentDir }}",
+  "{{ profileDir }}",
   "{{ paths.memoriesDir }}",
   "{{ paths.globalMemoryDir }}"
 ]

package/examples/basic-config/agent-config/starter/basic-project/local.md.njk

@@ -3,3 +3,4 @@
 This starter profile belongs to `{{ profile }}`.
 
 Use the project root at `{{ projectRoot }}` and keep generated files in `{{ agentDir }}`.
+Keep source profile edits in `{{ profileDir }}`.

package/examples/basic-config/agent-config/starter/basic-project/overrides/claude-settings.json.njk

@@ -1,6 +1,7 @@
 {% if permissionsAllow.length %}{
   "env": {
     "AGENT_DIR": "{{ agentDir }}",
+    "AGENT_PROFILE_DIR": "{{ profileDir }}",
     "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",
     "AGENT_GLOBAL_MEMORY_DIR": "{{ paths.globalMemoryDir }}",
     "STARTER_PROFILE": "{{ profile }}",
@@ -15,6 +16,7 @@
 {% else %}{
   "env": {
     "AGENT_DIR": "{{ agentDir }}",
+    "AGENT_PROFILE_DIR": "{{ profileDir }}",
     "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",
     "AGENT_GLOBAL_MEMORY_DIR": "{{ paths.globalMemoryDir }}",
     "STARTER_PROFILE": "{{ profile }}",

package/examples/basic-config/agent-config/starter/basic-project/overrides/codex-config.toml.njk

@@ -6,6 +6,7 @@ sandbox_mode = "workspace-write"
 writable_roots = [
   "{{ projectRoot }}",
   "{{ agentDir }}",
+  "{{ profileDir }}",
   "{{ paths.memoriesDir }}",
   "{{ paths.globalMemoryDir }}"
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technomoron/agent-run",
-  "version": "0.99.12",
+  "version": "0.99.14",
   "packageManager": "pnpm@10.28.1",
   "bin": {
     "agent-run": "dist/agent-run.js"