agent-policy-kit 0.1.0 → 0.3.0

package/src/detect.mjs

@@ -4,17 +4,65 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 
-const CLIENTS = ['codex','claude','kimi','agy'];
+const CLIENTS = ['chatgpt','claude','kimi','gemini','grok'];
+// Each tool's own executable keeps its native name: ChatGPT runs Codex, and Gemini runs Antigravity (agy).
+const EXECUTABLES = {chatgpt:'codex',claude:'claude',kimi:'kimi',gemini:'agy',grok:'grok'};
 const OUTPUT_LIMIT = 65536;
 const VERSION = String.raw`(\d{1,4}\.\d{1,4}\.\d{1,4}(?:-[A-Za-z0-9][A-Za-z0-9.-]{0,63})?(?:\+[A-Za-z0-9][A-Za-z0-9.-]{0,63})?)`;
 function failure(code) { return Object.assign(new Error(code),{code}); }
-function options({env=process.env,hostHome=os.homedir(),timeoutMs=5000} = {}) {
-  if (!env || typeof env !== 'object' || typeof hostHome !== 'string' || !path.isAbsolute(hostHome) || hostHome.includes('\0') || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw failure('INVALID_DETECTION_OPTIONS');
-  return {env,hostHome:path.resolve(hostHome),timeoutMs};
+const absolute = value => typeof value === 'string' && path.isAbsolute(value) && !value.includes('\0');
+function options({env=process.env,hostHome=os.homedir(),timeoutMs=5000,platform=process.platform,systemApplications} = {}) {
+  // AGENT_POLICY_APPLICATIONS_DIR replaces /Applications, so hermetic runs never see the host's installed apps.
+  systemApplications ??= (typeof env?.AGENT_POLICY_APPLICATIONS_DIR === 'string' && env.AGENT_POLICY_APPLICATIONS_DIR) || '/Applications';
+  if (!env || typeof env !== 'object' || !absolute(hostHome) || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || typeof platform !== 'string' || !absolute(systemApplications)) throw failure('INVALID_DETECTION_OPTIONS');
+  return {env,hostHome:path.resolve(hostHome),timeoutMs,platform,systemApplications:path.resolve(systemApplications)};
 }
-function candidates(client,{env,hostHome}) {
+// Desktop apps ship their own copy of a CLI and keep it off PATH. ChatGPT Desktop runs Codex from a
+// fixed bundle path; Claude Desktop keeps one Claude Code per <version>/<build> directory.
+const CHATGPT_CODEX = 'ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex';
+const CLAUDE_DESKTOP = 'Library/Application Support/Claude/claude-code';
+const DESKTOP_VERSION = /^(\d{1,4})\.(\d{1,4})\.(\d{1,4})$/;
+const DESKTOP_BUILD = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const DESKTOP_LIMIT = 8;
+async function directories(dir) {
+  try { return (await fs.readdir(dir,{withFileTypes:true})).filter(entry=>entry.isDirectory()).map(entry=>entry.name); }
+  catch { return []; }
+}
+function newerFirst(a,b) {
+  const [x,y] = [a,b].map(name=>name.match(DESKTOP_VERSION).slice(1).map(Number));
+  return y[0]-x[0] || y[1]-x[1] || y[2]-x[2];
+}
+async function desktopCandidates(client,{hostHome,platform,systemApplications}) {
+  if (platform !== 'darwin') return [];
+  if (client === 'chatgpt') return [systemApplications,path.join(hostHome,'Applications')].map(dir=>path.join(dir,CHATGPT_CODEX));
+  if (client !== 'claude') return [];
+  const base = path.join(hostHome,CLAUDE_DESKTOP), files = [];
+  for (const version of (await directories(base)).filter(name=>DESKTOP_VERSION.test(name)).sort(newerFirst)) {
+    // Only builds that contain the CLI count toward the limit, so empty or partial folders cannot hide a working one.
+    // Within one version the most recently written CLI comes first; the name breaks ties.
+    const builds = [];
+    for (const build of (await directories(path.join(base,version))).filter(name=>DESKTOP_BUILD.test(name))) {
+      const file = path.join(base,version,build,'claude.app/Contents/MacOS/claude');
+      try { const stat = await fs.stat(file); if (stat.isFile()) builds.push({file,build,mtime:stat.mtimeMs}); } catch {}
+    }
+    builds.sort((a,b)=>b.mtime-a.mtime || (a.build < b.build ? -1 : a.build > b.build ? 1 : 0));
+    for (const {file} of builds) {
+      files.push(file);
+      // The limit bounds detection time: each candidate that exists is started once with --version.
+      if (files.length === DESKTOP_LIMIT) return files;
+    }
+  }
+  return files;
+}
+async function candidates(client,settings) {
+  const result = cliCandidates(client,settings);
+  for (const file of await desktopCandidates(client,settings)) result.push({file,origin:'desktop_app'});
+  return result.filter((candidate,index) => result.findIndex(c=>c.file === candidate.file) === index);
+}
+function cliCandidates(client,{env,hostHome}) {
   const dirs = typeof env.PATH === 'string' ? env.PATH.split(path.delimiter) : [];
-  const names = process.platform === 'win32' ? [client + '.exe',client] : [client];
+  const executable = EXECUTABLES[client];
+  const names = process.platform === 'win32' ? [executable + '.exe',executable] : [executable];
   const result = [];
   for (const dir of dirs) {
     // Never search the working directory through empty/relative PATH segments.
@@ -23,9 +71,9 @@ function candidates(client,{env,hostHome}) {
   }
   const conventional = client === 'kimi' ? ['.kimi-code/bin/kimi']
     : client === 'claude' ? ['.local/bin/claude','.claude/local/claude']
-    : [`.local/bin/${client}`];
+    : [`.local/bin/${executable}`];
   for (const relative of conventional) result.push({file:path.join(hostHome,relative),origin:'known_location'});
-  return result.filter((candidate,index) => result.findIndex(c=>c.file === candidate.file) === index);
+  return result;
 }
 async function inspect(file) {
   try {
@@ -78,10 +126,11 @@ function probe(executable,arg,{env,timeoutMs}) {
 }
 function identity(client,output) {
   const patterns = {
-    codex:[new RegExp(String.raw`^\s*codex(?:-cli)?\s+v?${VERSION}(?:\s|$)`,'im')],
+    chatgpt:[new RegExp(String.raw`^\s*codex(?:-cli)?\s+v?${VERSION}(?:\s|$)`,'im')],
     claude:[new RegExp(String.raw`^\s*v?${VERSION}\s+\(Claude Code\)(?:\s|$)`,'im'),new RegExp(String.raw`^\s*Claude Code\s+v?${VERSION}(?:\s|$)`,'im')],
     kimi:[new RegExp(String.raw`^\s*kimi(?:\s+code(?:\s+cli)?)?(?:,?\s+version)?\s+v?${VERSION}(?:\s|$)`,'im')],
-    agy:[new RegExp(String.raw`^\s*(?:Antigravity|agy)\s+v?${VERSION}(?:\s|$)`,'im')],
+    gemini:[new RegExp(String.raw`^\s*(?:Antigravity|agy)\s+v?${VERSION}(?:\s|$)`,'im')],
+    grok:[new RegExp(String.raw`^\s*grok\s+v?${VERSION}(?:\s|$)`,'im')],
   };
   for (const pattern of patterns[client]) { const match = output.match(pattern); if (match && match[1].length <= 128) return match[1]; }
   return null;
@@ -91,7 +140,7 @@ async function verify(client,executable,opts) {
   if (version.status !== 'ok') return {status:version.status};
   const branded = identity(client,version.output);
   if (branded) return {status:'detected',version:branded};
-  if (client !== 'kimi' && client !== 'agy') return {status:'invalid'};
+  if (client !== 'kimi' && client !== 'gemini') return {status:'invalid'};
   const number = version.output.match(new RegExp(String.raw`^\s*v?${VERSION}(?:\s|$)`));
   if (!number || number[1].length > 128) return {status:'invalid'};
   const help = await probe(executable,'--help',opts);
@@ -109,7 +158,7 @@ export async function resolveClient(client,opts = {}) {
   const settings = options(opts);
   let best = {client,status:'not_found',version:null,origin:null,executable:null};
   const checked = new Set();
-  for (const candidate of candidates(client,settings)) {
+  for (const candidate of await candidates(client,settings)) {
     const inspected = await inspect(candidate.file);
     if (inspected.status === 'not_found') continue;
     if (inspected.status === 'invalid') {
@@ -131,6 +180,6 @@ export function summarizeDetection(records) {
   return records.filter(r=>CLIENTS.includes(r?.client)).map(({client,status,version,origin})=>{
     status = ['detected','not_found','invalid','timeout'].includes(status) ? status : 'invalid';
     if (status === 'detected' && (typeof version !== 'string' || version.length > 128 || !new RegExp(`^${VERSION}$`).test(version))) status = 'invalid';
-    return {client,status,version:status === 'detected' ? version : null,origin:['path','known_location'].includes(origin) ? origin : null};
+    return {client,status,version:status === 'detected' ? version : null,origin:['path','known_location','desktop_app'].includes(origin) ? origin : null};
   });
 }

package/src/explicit.mjs

@@ -1,6 +1,6 @@
 // Pure command codec, also embedded in the offline configuration page.
-export const TOOL_FLAGS=Object.freeze({codex:'codex',claude:'claude',kimi:'kimi',antigravity:'agy'});
-export const EXPLICIT_FIELDS=Object.freeze(['roles','max-concurrent',...Object.keys(TOOL_FLAGS),...Object.keys(TOOL_FLAGS).map(flag=>'avoid-'+flag)]);
+export const TOOL_FLAGS=Object.freeze({chatgpt:'chatgpt',claude:'claude',kimi:'kimi',gemini:'gemini',grok:'grok'});
+export const EXPLICIT_FIELDS=Object.freeze(['roles','max-concurrent',...Object.keys(TOOL_FLAGS),...Object.keys(TOOL_FLAGS).map(flag=>'avoid-'+flag),...Object.keys(TOOL_FLAGS).map(flag=>flag+'-max-concurrent')]);
 const EXPLICIT_MODEL=/^[A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,127}$/;
 const EXPLICIT_EFFORTS=['none','minimal','low','medium','high','xhigh','max'];
 function invalidExplicit(){throw Object.assign(new Error('Invalid explicit configuration.'),{code:'INVALID_EXPLICIT_CONFIG'});}
@@ -11,6 +11,8 @@ function explicitList(value,limit){
  return list;
 }
 
+// Grok has no per-role effort, so its value is the whole model id; a trailing ':<effort>' would be ambiguous and is refused.
+const grokEffortSuffix=model=>{const colon=model.lastIndexOf(':');return colon>=0&&['native',...EXPLICIT_EFFORTS].includes(model.slice(colon+1));};
 export function parseExplicitOptions(options,roleIds){
  if(!options||typeof options!=='object'||Array.isArray(options))invalidExplicit();
  const fields=Object.getOwnPropertyDescriptors(options);
@@ -21,7 +23,7 @@ export function parseExplicitOptions(options,roleIds){
  if(requested.some(role=>!roleIds.includes(role)))invalidExplicit();
  const roles=roleIds.filter(role=>requested.includes(role)),maxConcurrent=Number(options['max-concurrent']);
  if(!/^[1-9]\d*$/.test(options['max-concurrent'])||!Number.isInteger(maxConcurrent)||maxConcurrent>32)invalidExplicit();
- for(const flag of Object.keys(TOOL_FLAGS))if(options['avoid-'+flag]!==undefined&&options[flag]===undefined)invalidExplicit();
+ for(const flag of Object.keys(TOOL_FLAGS))if((options['avoid-'+flag]!==undefined||options[flag+'-max-concurrent']!==undefined)&&options[flag]===undefined)invalidExplicit();
  const clients={};
  for(const flag of Object.keys(options).filter(flag=>Object.hasOwn(TOOL_FLAGS,flag))){
   const client=TOOL_FLAGS[flag],choices={};
@@ -29,7 +31,8 @@ export function parseExplicitOptions(options,roleIds){
    const at=entry.indexOf('='),role=entry.slice(0,at).trim(),value=entry.slice(at+1).trim();
    if(at<1||!roles.includes(role)||Object.hasOwn(choices,role))invalidExplicit();
    let model=value,effort=null;
-   if(client==='agy'){if(!['pro','flash','flash_lite','inherit'].includes(model))invalidExplicit();}
+   if(client==='gemini'){if(!['pro','flash','flash_lite','inherit'].includes(model))invalidExplicit();}
+   else if(client==='grok'){if(grokEffortSuffix(value))invalidExplicit();}
    else{
     const colon=value.lastIndexOf(':');if(colon<1)invalidExplicit();
     model=value.slice(0,colon);const level=value.slice(colon+1);
@@ -41,7 +44,9 @@ export function parseExplicitOptions(options,roleIds){
   const avoidModels=options['avoid-'+flag]===undefined?[]:explicitList(options['avoid-'+flag],32);
   if(avoidModels.some(model=>!EXPLICIT_MODEL.test(model)))invalidExplicit();
   const first=choices[roles[0]];
-  clients[client]={code:{...first},light:{...first},roles:Object.fromEntries(roles.map(role=>[role,choices[role]])),avoidModels};
+  const limit=options[flag+'-max-concurrent'];
+  if(limit!==undefined&&(!/^[1-9]\d*$/.test(limit)||Number(limit)>32))invalidExplicit();
+  clients[client]={...(limit===undefined?{}:{maxConcurrent:Number(limit)}),code:{...first},light:{...first},roles:Object.fromEntries(roles.map(role=>[role,choices[role]])),avoidModels};
  }
  if(!Object.keys(clients).length)invalidExplicit();
  return {schemaVersion:1,maxConcurrent,...(roles.length===roleIds.length?{}:{selectedRoles:roles}),clients};
@@ -63,9 +68,11 @@ export function explicitOptions(config,roleCatalog){
   options[flag]=roles.map(role=>{
    const selected=preferences.roles?.[role]??preferences[kinds.get(role)];
    if(!selected||typeof selected.model!=='string'||!EXPLICIT_MODEL.test(selected.model)||(selected.effort!==null&&!EXPLICIT_EFFORTS.includes(selected.effort)))invalidExplicit();
-   if(client==='agy'&&selected.effort!==null)invalidExplicit();
-   return `${role}=${selected.model}${client==='agy'?'':':'+(selected.effort??'native')}`;
+   if(['gemini','grok'].includes(client)&&selected.effort!==null)invalidExplicit();
+   if(client==='grok'&&grokEffortSuffix(selected.model))invalidExplicit();
+   return `${role}=${selected.model}${['gemini','grok'].includes(client)?'':':'+(selected.effort??'native')}`;
   }).join(',');
+  if(preferences.maxConcurrent!==undefined)options[flag+'-max-concurrent']=String(preferences.maxConcurrent);
   if(!Array.isArray(preferences.avoidModels)||preferences.avoidModels.some(model=>typeof model!=='string'||!EXPLICIT_MODEL.test(model)))invalidExplicit();
   if(preferences.avoidModels.length)options['avoid-'+flag]=preferences.avoidModels.join(',');
  }
@@ -77,6 +84,6 @@ export function formatExplicitCommand(config,version,roleCatalog){
  if(typeof version!=='string'||!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))throw new Error('Invalid release version.');
  const options=explicitOptions(config,roleCatalog),quote=value=>"'"+value.replaceAll("'","'\"'\"'")+"'";
  const lines=[`npx --yes --ignore-scripts --package agent-policy-kit@${version} agent-policy setup`];
- for(const [name,value]of Object.entries(options))lines.push(`--${name} ${name==='max-concurrent'?value:quote(value)}`);
+ for(const [name,value]of Object.entries(options))lines.push(`--${name} ${name==='max-concurrent'||name.endsWith('-max-concurrent')?value:quote(value)}`);
  lines.push('--apply');return lines.join(' \\\n  ');
 }

package/src/inspect.mjs

@@ -0,0 +1,203 @@
+import fs from 'node:fs/promises';
+import {constants} from 'node:fs';
+import path from 'node:path';
+import {parseToml} from './toml.mjs';
+import {CLIENTS} from './policy.mjs';
+import {inspectConfiguration} from './install.mjs';
+
+const ROOTS={chatgpt:'.codex',claude:'.claude',kimi:'.kimi-code',gemini:'.gemini',grok:'.grok'};
+const ENV_ROOTS={chatgpt:'CODEX_HOME',claude:'CLAUDE_CONFIG_DIR',kimi:'KIMI_CODE_HOME',grok:'GROK_HOME'};
+const MAX_FILE=1024*1024,MAX_TOTAL=4*MAX_FILE,MAX_ENTRIES=256;
+const identifier=/^[A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,127}$/;
+const namePattern=/^[A-Za-z0-9][A-Za-z0-9 _.-]{0,79}$/;
+const record=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const failure=code=>Object.assign(new Error(code),{code});
+function safeString(value,pattern=identifier){
+ if(typeof value!=='string'||!pattern.test(value)||/^(?:sk-|ghp_|github_pat_)/.test(value)||/\/(?:Users|home)\//.test(value))throw failure('UNSUPPORTED_NATIVE_SETTING');
+ return value;
+}
+async function safePath(target){
+ let current=path.parse(target).root;
+ for(const part of path.relative(current,target).split(path.sep).filter(Boolean)){
+  current=path.join(current,part);
+  try{if((await fs.lstat(current)).isSymbolicLink())throw failure('UNSAFE_FILE');}
+  catch(error){if(error.code==='ENOENT')return;throw error;}
+ }
+}
+async function readFile(file,budget){
+ await safePath(file);
+ let handle;
+ try{
+  handle=await fs.open(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  const before=await handle.stat();
+  if(!before.isFile())throw failure('UNSAFE_FILE');
+  if(before.size>MAX_FILE||budget.bytes+before.size>MAX_TOTAL)throw failure('INSPECTION_LIMIT');
+  const buffer=Buffer.alloc(MAX_FILE+1);let size=0;
+  while(size<buffer.length){const chunk=await handle.read(buffer,size,buffer.length-size,null);if(!chunk.bytesRead)break;size+=chunk.bytesRead;}
+  const after=await handle.stat();
+  budget.bytes+=size;
+  if(size>MAX_FILE||budget.bytes>MAX_TOTAL)throw failure('INSPECTION_LIMIT');
+  if(before.size!==after.size||before.mtimeMs!==after.mtimeMs||size!==after.size)throw failure('CONFIG_CHANGED_DURING_READ');
+  return buffer.subarray(0,size).toString('utf8');
+ }catch(error){if(error.code==='ENOENT')return null;throw error;}
+ finally{await handle?.close();}
+}
+function warning(client,error){
+ const allowed=['UNSAFE_FILE','INSPECTION_LIMIT','CONFIG_CHANGED_DURING_READ','UNSUPPORTED_NATIVE_SETTING','UNSUPPORTED_ROLE_FORMAT','UNSUPPORTED_ROLE_EFFORT','INVALID_TOML','INVALID_JSON','EACCES','EPERM','NATIVE_CAP_CONFLICT','EXTERNAL_ROLE_REFERENCES_NOT_READ'];
+ const code=allowed.includes(error?.code)?error.code:'NATIVE_READ_FAILED';
+ if(!client.warnings.includes(code))client.warnings.push(code);
+ client.status='attention';
+}
+function scalar(value){
+ const text=value.trim();
+ if(text.startsWith('"')){const match=text.match(/^("(?:[^"\\]|\\.)*")\s*(?:#.*)?$/);if(!match)throw failure('UNSUPPORTED_ROLE_FORMAT');try{return JSON.parse(match[1]);}catch{throw failure('UNSUPPORTED_ROLE_FORMAT');}}
+ if(text.startsWith("'")){const match=text.match(/^'((?:[^']|'')*)'\s*(?:#.*)?$/);if(!match)throw failure('UNSUPPORTED_ROLE_FORMAT');return match[1].replaceAll("''", "'");}
+ const match=text.match(/^([A-Za-z0-9][A-Za-z0-9._:@/\[\]-]*)(?:\s+#.*)?$/);
+ if(!match)throw failure('UNSUPPORTED_ROLE_FORMAT');
+ return match[1];
+}
+function frontmatter(text){
+ const match=text.replace(/^\uFEFF/,'').match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+ if(!match)throw failure('UNSUPPORTED_ROLE_FORMAT');
+ const fields={};
+ for(const line of match[1].split(/\r?\n/)){
+  // YAML merges, quoted keys and flow mappings can supply model fields that
+  // this deliberately small scalar reader cannot resolve safely.
+  if(/^(?:<<\s*:|["'{\[])/.test(line))throw failure('UNSUPPORTED_ROLE_FORMAT');
+  const field=line.match(/^(name|model|effort|subagent)[ \t]*:\s*(.*)$/);
+  if(!field)continue;
+  if(Object.hasOwn(fields,field[1]))throw failure('UNSUPPORTED_ROLE_FORMAT');
+  if(field[1]==='subagent'){
+   const boolean=field[2].trim().match(/^(true|false)(?:\s+#.*)?$/);
+   if(!boolean)throw failure('UNSUPPORTED_ROLE_FORMAT');
+   fields.subagent=boolean[1]==='true';
+  }else fields[field[1]]=scalar(field[2]);
+ }
+ if(!fields.name)throw failure('UNSUPPORTED_ROLE_FORMAT');
+ return fields;
+}
+function cap(value){if(!Number.isSafeInteger(value)||value<1)throw failure('UNSUPPORTED_NATIVE_SETTING');return value;}
+function optionalString(value,pattern){return value===undefined?null:safeString(value,pattern);}
+function extractSettings(client,id,native,env,models){
+ if(!record(native))throw failure('UNSUPPORTED_NATIVE_SETTING');
+ if(id==='grok'){
+  const subagents=native.subagents??{};if(!record(subagents))throw failure('UNSUPPORTED_NATIVE_SETTING');
+  const configured=subagents.models??{};if(!record(configured)||Object.keys(configured).length>MAX_ENTRIES)throw failure(record(configured)?'INSPECTION_LIMIT':'UNSUPPORTED_NATIVE_SETTING');
+  for(const[name,model]of Object.entries(configured))models.set(safeString(name,namePattern),safeString(model));
+  client.defaults.model=models.get('general-purpose')??null;
+  if(subagents.max_concurrent!==undefined)client.concurrency.value=cap(subagents.max_concurrent);
+  return;
+ }
+ if(id==='chatgpt'){
+  const agents=native.agents??{};if(!record(agents))throw failure('UNSUPPORTED_NATIVE_SETTING');
+  client.defaults.model=optionalString(agents.default_subagent_model);
+  client.defaults.effort=optionalString(agents.default_subagent_reasoning_effort);
+  if(agents.enabled!==undefined){if(typeof agents.enabled!=='boolean')throw failure('UNSUPPORTED_NATIVE_SETTING');client.defaults.enabled=agents.enabled;}
+  const current=agents.max_concurrent_threads_per_session,legacy=agents.max_threads;
+  if(current!==undefined&&legacy!==undefined&&current!==legacy)throw failure('NATIVE_CAP_CONFLICT');
+  if(current!==undefined||legacy!==undefined)client.concurrency.value=cap(current??legacy);
+  if(Object.values(agents).some(value=>record(value)&&value.config_file!==undefined))warning(client,failure('EXTERNAL_ROLE_REFERENCES_NOT_READ'));
+ }else if(id==='claude'){
+  const stored=native.env??{};if(!record(stored))throw failure('UNSUPPORTED_NATIVE_SETTING');
+  client.defaults.model=optionalString(stored.CLAUDE_CODE_SUBAGENT_MODEL);
+  const count=stored.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS;
+  if(count!==undefined){if(typeof count!=='string'||!/^\d{1,9}$/.test(count))throw failure('UNSUPPORTED_NATIVE_SETTING');client.concurrency.value=cap(Number(count));}
+  client.overrides={};
+  for(const[key,field]of [['CLAUDE_CODE_SUBAGENT_MODEL','model'],['CLAUDE_CODE_EFFORT_LEVEL','effort']]){
+   const value=env[key]??(field==='effort'?stored[key]:undefined);
+   if(value!==undefined)client.overrides[field]=safeString(value);
+  }
+  if((env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE??stored.CLAUDE_CODE_SUBAGENT_MODEL_FORCE)==='1')client.overrides.forceModel=true;
+  if(env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS!==undefined){if(!/^\d{1,9}$/.test(env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS))throw failure('UNSUPPORTED_NATIVE_SETTING');client.overrides.maxConcurrent=cap(Number(env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS));}
+ }else if(id==='kimi'){
+  const secondary=native.secondary_model??{};if(!record(secondary))throw failure('UNSUPPORTED_NATIVE_SETTING');
+  client.defaults.model=optionalString(secondary.default_model);
+  client.defaults.effort=optionalString(secondary.default_effort);
+  const pool=secondary.models??{};if(!record(pool)||Object.keys(pool).length>MAX_ENTRIES)throw failure('INSPECTION_LIMIT');
+  const aliases=new Set([...Object.keys(pool),...(client.defaults.model?[client.defaults.model]:[])]);
+  for(const alias of aliases){
+   const entry=native.models?.[alias];
+   client.pool.push({alias:safeString(alias),effort:optionalString(secondary.default_effort??entry?.overrides?.default_effort??entry?.default_effort),configured:record(entry)});
+  }
+ }
+}
+async function rolesIn(directory,client,id,budget,models,depth=0){
+ await safePath(directory);
+ let directoryHandle;
+ try{directoryHandle=await fs.opendir(directory);}catch(error){if(error.code==='ENOENT')return;throw error;}
+ const entries=[];
+ for await(const entry of directoryHandle){if(++budget.entries>MAX_ENTRIES)throw failure('INSPECTION_LIMIT');entries.push(entry);}
+ for(const entry of entries.sort((a,b)=>a.name.localeCompare(b.name,'en'))){
+  const file=path.join(directory,entry.name);
+  try{
+   if(entry.isSymbolicLink())throw failure('UNSAFE_FILE');
+   if(entry.isDirectory()){
+    if(id==='chatgpt')continue;
+    if(depth>=4)throw failure('INSPECTION_LIMIT');
+    await rolesIn(file,client,id,budget,models,depth+1);continue;
+   }
+   if(!entry.name.endsWith(id==='chatgpt'?'.toml':'.md'))continue;
+   const body=await readFile(file,budget);if(body===null)throw failure('CONFIG_CHANGED_DURING_READ');
+   const fields=id==='chatgpt'?parseToml(body):frontmatter(body);
+   const role={name:safeString(fields.name,namePattern),model:optionalString(fields.model),effort:optionalString(id==='chatgpt'?fields.model_reasoning_effort:fields.effort)};
+   if(id==='kimi'){
+    // APK's Markdown role files contain explicit routing guidance, not a
+    // native model binding. Other prose is never interpreted as configuration.
+    role.model=null;role.effort=null;role.modelSelection='parent';
+    if(role.name.startsWith('apk-')){
+     const routing=body.match(/^The parent must select configured pool alias ([A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,127}) for this role; Markdown frontmatter does not select a model\. Requested effort: (native default|[A-Za-z0-9_-]+)\.$/m);
+     if(routing){role.model=safeString(routing[1]);role.effort=routing[2]==='native default'?null:safeString(routing[2]);role.modelSelection='guidance';}
+    }
+   }
+   if(id==='grok'){
+    // The native per-subagent model override lives in config.toml, not in the agent file.
+    role.model=models.get(role.name)??role.model;
+    if(fields.effort!==undefined){role.effort=null;warning(client,failure('UNSUPPORTED_ROLE_EFFORT'));}
+   }
+   if(id==='gemini'){
+    if(role.model!==null&&!['pro','flash','flash_lite','inherit'].includes(role.model))throw failure('UNSUPPORTED_NATIVE_SETTING');
+    role.enabled=fields.subagent??null;
+    if(fields.effort!==undefined){role.effort=null;warning(client,failure('UNSUPPORTED_ROLE_EFFORT'));}
+   }
+   if(client.roles.some(r=>r.name===role.name))throw failure('UNSUPPORTED_ROLE_FORMAT');
+   client.roles.push(role);
+  }catch(error){warning(client,error);}
+ }
+}
+async function readGuidance(root,client,budget){
+ const text=await readFile(path.join(root,'AGENTS.md'),budget);
+ if(text===null)return;
+ const blocks=[...text.matchAll(/<!-- BEGIN agent-policy-kit -->\r?\n([\s\S]*?)<!-- END agent-policy-kit -->/g)];
+ if(!blocks.length)return;
+ if(blocks.length!==1)throw failure('UNSUPPORTED_NATIVE_SETTING');
+ const counts=[...blocks[0][1].matchAll(/^When delegating, run at most (\d+) subagents concurrently in this session\./gm)];
+ if(counts.length!==1)throw failure('UNSUPPORTED_NATIVE_SETTING');
+ client.concurrency.value=cap(Number(counts[0][1]));
+}
+export async function readConfiguration({client=null,home,env=process.env,explicitHome=false,stateDir=path.join(home,'.agent-policy-kit')}={}){
+ if(!path.isAbsolute(home)||client!==null&&!CLIENTS.includes(client))throw failure('INVALID_CLIENT');
+ const report={schemaVersion:1,scope:'user',modelExecution:'not_checked',clients:{}};
+ for(const id of client?[client]:CLIENTS){
+  const root=path.resolve(!explicitHome&&env[ENV_ROOTS[id]]?env[ENV_ROOTS[id]]:path.join(home,ROOTS[id]));
+  const c={status:'not_configured',defaults:{model:null,effort:null,enabled:null},concurrency:{value:null,kind:['chatgpt','claude','grok'].includes(id)?'native_setting':'guidance'},roles:[],pool:[],warnings:[],apk:{status:'not_checked'}};
+  report.clients[id]=c;const budget={bytes:0,entries:0},models=new Map();
+  try{
+   await safePath(root);
+   if(id!=='gemini'){
+    try{
+     const text=await readFile(path.join(root,id==='claude'?'settings.json':'config.toml'),budget);
+     if(text!==null){let native;if(id==='claude'){try{native=JSON.parse(text);}catch{throw failure('INVALID_JSON');}}else native=parseToml(text);extractSettings(c,id,native,env,models);}
+     else if(id==='claude')extractSettings(c,id,{},env,models);
+    }catch(error){warning(c,error);}
+   }
+   await rolesIn(path.join(root,id==='gemini'?'config/agents':'agents'),c,id,budget,models);
+   if(id==='kimi'||id==='gemini'){try{await readGuidance(root,c,budget);}catch(error){warning(c,error);}}
+   if(c.status!=='attention'&&(c.roles.length||c.pool.length||c.defaults.model!==null||c.defaults.effort!==null||c.defaults.enabled!==null||c.concurrency.value!==null||Object.keys(c.overrides??{}).length))c.status='configured';
+   if(root===path.resolve(home,ROOTS[id])){
+    try{const installed=await inspectConfiguration({client:id,home,stateDir});c.apk.status=installed.status;if(installed.status==='verified'){c.apk.releaseVersion=installed.releaseVersion;c.apk.preset=installed.preset;}}
+    catch(error){c.apk.status=error.code==='OWNED_DRIFT'?'modified':'attention';warning(c,error);}
+   }
+  }catch(error){warning(c,error);}
+ }
+ return report;
+}

package/src/install.mjs

@@ -10,7 +10,7 @@ import catalog from '../models/catalog.json' with {type:'json'};
 import { parseToml, setTomlValue, restoreTomlValue, removeTomlValue } from './toml.mjs';
 import { nativeLocations, nativeRoles, instructionBlock, nativeWarnings, BEGIN, END } from './native.mjs';
 
-const CLIENTS = ['codex', 'claude', 'kimi', 'agy'];
+const CLIENTS = ['chatgpt', 'claude', 'kimi', 'gemini', 'grok'];
 const LIMIT = 1024 * 1024;
 const digest = value => value === null ? null : createHash('sha256').update(value).digest('hex');
 const json = value => JSON.stringify(value, null, 2) + '\n';
@@ -155,7 +155,8 @@ function selectedAliases(preferences,selectedRoles=ROLE_IDS) {
 }
 function tomlSettings(client,preferences,maxConcurrent,selectedRoles=ROLE_IDS) {
   const worker=rolePreference(preferences,selectedRoles[0]);
-  if(client==='codex')return [[['agents','max_concurrent_threads_per_session'],maxConcurrent],[['agents','default_subagent_model'],worker.model],...(worker.effort===null?[]:[[['agents','default_subagent_reasoning_effort'],worker.effort]])];
+  if(client==='chatgpt')return [[['agents','max_concurrent_threads_per_session'],maxConcurrent],[['agents','default_subagent_model'],worker.model],...(worker.effort===null?[]:[[['agents','default_subagent_reasoning_effort'],worker.effort]])];
+  if(client==='grok')return [[['subagents','max_concurrent'],maxConcurrent],...selectedRoles.map(role=>[['subagents','models','apk-'+role],rolePreference(preferences,role).model]),[['subagents','models','general-purpose'],worker.model]];
   if(client!=='kimi')return [];
   const selected=selectedAliases(preferences,selectedRoles),roles=effectiveRoles(preferences,selectedRoles);
   return [[['secondary_model','default_model'],worker.model],...selected.map(value=>[['secondary_model','models',value.model],'Use for '+roles.filter(role=>role.model===value.model).map(role=>'apk-'+role.role).join(', ')+'.']),...selected.filter(value=>value.effort!==null).map(value=>[['models',value.model,'overrides','default_effort'],value.effort])];
@@ -182,15 +183,23 @@ function scalar(op,target,type) {
   literalValue(op.before,type,true);
   return literalValue(op.after,type);
 }
-function validateTomlSnapshot(file,client,schemaVersion) {
+function validateTomlSnapshot(file,client,schemaVersion,selectedRoles=ROLE_IDS) {
   if(!Array.isArray(file.ops)||!file.ops.every(op=>object(op)&&Array.isArray(op.path)&&op.path.every(key=>typeof key==='string')&&op.path.length<=4))fail('INVALID_RECEIPT');
-  if(client==='codex') {
+  if(client==='chatgpt') {
     if(!(schemaVersion===2?[3]:[2,3]).includes(file.ops.length))fail('INVALID_RECEIPT');
     const cap=scalar(file.ops[0],['agents','max_concurrent_threads_per_session'],'number');
     if(cap<1||cap>32)fail('INVALID_RECEIPT');
     scalar(file.ops[1],['agents','default_subagent_model'],'string');if(file.ops.length===3)scalar(file.ops[2],['agents','default_subagent_reasoning_effort'],'string');
     return;
   }
+  if(client==='grok') {
+    if(schemaVersion!==4||file.ops.length!==selectedRoles.length+2)fail('INVALID_RECEIPT');
+    const cap=scalar(file.ops[0],['subagents','max_concurrent'],'number');
+    if(cap<1||cap>32)fail('INVALID_RECEIPT');
+    for(const[i,role]of selectedRoles.entries())scalar(file.ops[1+i],['subagents','models','apk-'+role],'string');
+    scalar(file.ops.at(-1),['subagents','models','general-purpose'],'string');
+    return;
+  }
   if(client!=='kimi')fail('INVALID_RECEIPT');
   if(schemaVersion===2) {
     if(![4,6].includes(file.ops.length))fail('INVALID_RECEIPT');
@@ -253,7 +262,7 @@ function validateReceipt(r,plan) {
     } else if(plan.client==='claude') {
       fields(file,['path','type','existed','ops','created']);if(file.type!=='json')fail('INVALID_RECEIPT');validateJsonSnapshot(file);
     } else {
-      fields(file,['path','type','existed','ops']);if(file.type!=='toml')fail('INVALID_RECEIPT');validateTomlSnapshot(file,plan.client,r.schemaVersion);
+      fields(file,['path','type','existed','ops']);if(file.type!=='toml')fail('INVALID_RECEIPT');validateTomlSnapshot(file,plan.client,r.schemaVersion,r.schemaVersion===4?r.selectedRoles:LEGACY_ROLE_IDS);
     }
   }
   return r;
@@ -348,7 +357,7 @@ export async function planInstall(options) {
   if(!own(policy.clients,plan.client))fail('INVALID_POLICY');
   let selected=policy.clients[plan.client],resolvedAliases=false;
   const roleIds=selectedRoleIds(policy);
-  const maxConcurrent=policy.maxConcurrent,policyHash=digest(json(canonical(policy)));
+  const maxConcurrent=selected.maxConcurrent??policy.maxConcurrent,policyHash=digest(json(canonical(policy)));
   const policyBefore=await readDependency(plan,l.policy,plan.stateDir);
   const baselines=record?await undoFiles(plan,record,false):new Map();
   if(record&&!replace) {
@@ -373,8 +382,15 @@ export async function planInstall(options) {
       const required=kimiPrerequisite(native,selected,roleIds);if(required)return prerequisite(plan,required);
       if(selectedAliases(selected,roleIds).some(value=>value.effort!==null)&&native.secondary_model?.default_effort!==undefined&&typeof native.secondary_model.default_effort!=='string')fail('UNSUPPORTED_CONFIG');
     }
-    if(plan.client==='codex') {
-      if(native.agents&&own(native.agents,'max_threads'))fail('CODEX_CAP_ALIAS_CONFLICT');
+    if(plan.client==='grok') {
+      const subagents=native.subagents;
+      if(subagents!==undefined&&!object(subagents))fail('UNSUPPORTED_CONFIG');
+      if(subagents?.models!==undefined&&!object(subagents.models))fail('UNSUPPORTED_CONFIG');
+      const cap=subagents?.max_concurrent;
+      if(cap!==undefined&&(!Number.isSafeInteger(cap)||cap<1))fail('UNSUPPORTED_CONFIG');
+    }
+    if(plan.client==='chatgpt') {
+      if(native.agents&&own(native.agents,'max_threads'))fail('CHATGPT_CAP_ALIAS_CONFLICT');
       const cap=native.agents?.max_concurrent_threads_per_session;
       if(cap!==undefined&&(!Number.isSafeInteger(cap)||cap<1))fail('UNSUPPORTED_CONFIG');
     }

package/src/native.mjs

@@ -4,27 +4,30 @@ import {ROLE_DEFINITIONS,ROLE_IDS} from './roles.mjs';
 
 export const BEGIN = '<!-- BEGIN agent-policy-kit -->';
 export const END = '<!-- END agent-policy-kit -->';
-const directory = {codex:'.codex',claude:'.claude',kimi:'.kimi-code',agy:'.gemini'};
+const directory = {chatgpt:'.codex',claude:'.claude',kimi:'.kimi-code',gemini:'.gemini',grok:'.grok'};
 export function nativeHomeConflict(client,home,env) {
-  const variable={codex:'CODEX_HOME',claude:'CLAUDE_CONFIG_DIR',kimi:'KIMI_CODE_HOME'}[client];
+  const variable={chatgpt:'CODEX_HOME',claude:'CLAUDE_CONFIG_DIR',kimi:'KIMI_CODE_HOME',grok:'GROK_HOME'}[client];
   const active=variable&&env[variable];
   return typeof active==='string'&&active.length>0&&path.resolve(active)!==path.resolve(home,directory[client]);
 }
 export function nativeLocations(client,home) {
   const root=path.join(home,directory[client]);
   return {
-    config:client==='agy'?null:path.join(root,client==='claude'?'settings.json':'config.toml'),
+    config:client==='gemini'?null:path.join(root,client==='claude'?'settings.json':'config.toml'),
     instructions:path.join(root,client==='claude'?'CLAUDE.md':'AGENTS.md'),
-    roles:Object.keys(ROLES).map(role=>path.join(root,client==='agy'?'config/agents':'agents',`apk-${role}.${client==='codex'?'toml':'md'}`))
+    roles:Object.keys(ROLES).map(role=>path.join(root,client==='gemini'?'config/agents':'agents',`apk-${role}.${client==='chatgpt'?'toml':'md'}`))
   };
 }
 export function nativeRoles(client,config,selectedRoles=ROLE_IDS) {
   return selectedRoles.map(role=>{
     const selected=rolePreference(config,role),name='apk-'+role;
     const {description,prompt}=ROLE_DEFINITIONS.find(value=>value.id===role);
-    if(client==='codex') return Object.entries({name,description,model:selected.model,...(selected.effort===null?{}:{model_reasoning_effort:selected.effort}),developer_instructions:prompt}).map(([k,v])=>`${k} = ${JSON.stringify(v)}\n`).join('');
+    if(client==='chatgpt') return Object.entries({name,description,model:selected.model,...(selected.effort===null?{}:{model_reasoning_effort:selected.effort}),developer_instructions:prompt}).map(([k,v])=>`${k} = ${JSON.stringify(v)}\n`).join('');
     const fields=[`name: ${name}`,`description: ${JSON.stringify(description)}`];
-    if(client==='kimi') {
+    // Grok selects the model from config.toml [subagents.models]; read-only roles use the bundled plan permission mode.
+    if(client==='grok') {
+      if(['reviewer','explorer'].includes(role))fields.push('permission_mode: plan');
+    } else if(client==='kimi') {
       if(['reviewer','explorer'].includes(role))fields.push('tools: [Read, Grep, Glob]');
     } else {
       fields.push(`model: ${JSON.stringify(selected.model)}`);
@@ -44,17 +47,18 @@ export function instructionBlock(client,config,maxConcurrent,selectedRoles=ROLE_
     for(const role of selectedRoles) {const selected=rolePreference(config,role);text.push(`For apk-${role}, select pool alias ${selected.model} (effort ${selected.effort??'native default'}).`);}
     text.push('Roles sharing an alias share its native effort default; an explicit effort pin for that alias also affects its native-default roles.');
     text.push("Use the Agent tool's model selection when spawning; the role file alone does not select a model. The concurrency limit is guidance; no native Agent cap is configured.");
-  } else if(client==='agy') {
+  } else if(client==='gemini') {
     for(const role of selectedRoles)text.push(`When delegating to apk-${role}, use model tier ${rolePreference(config,role).model}.`);
     text.push('Per-role effort and a hard concurrency cap are not supported by the documented native agent settings.');
   }
+  else if(client==='grok')text.push('Use the named role definitions for model selection. Per-role effort is not supported by the documented native agent settings; subagents use the main session effort. Explicit spawn settings and higher-priority instructions can supersede user defaults.');
   else if(client==='claude')text.push('Use the named role definitions for model and effort selection. Session, project, managed settings, environment overrides and some spawn paths can supersede these user defaults; the native cap applies to ordinary Agent-tool spawns with documented exceptions.');
   else text.push('Use the named role definitions for model and effort selection. Explicit spawn settings and higher-priority instructions can supersede user defaults.');
-  if(client==='codex'||client==='claude')text.push('An omitted role effort uses the native client default; it does not pin a level.');
+  if(client==='chatgpt'||client==='claude')text.push('An omitted role effort uses the native client default; it does not pin a level.');
   if(config.avoidModels.length)text.push(`Avoid these models when delegating: ${config.avoidModels.join(', ')}. This is routing guidance.`);
   text.push(END);
   return text.join('\n')+'\n';
 }
 export function nativeWarnings(client) {
-  return client==='kimi'?['kimi-concurrency-guidance-only','kimi-model-pool-routing-guidance']:client==='agy'?['agy-concurrency-guidance-only','agy-per-role-effort-unsupported']:client==='claude'?['claude-native-precedence-limits']:['codex-native-precedence-limits'];
+  return client==='kimi'?['kimi-concurrency-guidance-only','kimi-model-pool-routing-guidance']:client==='gemini'?['gemini-concurrency-guidance-only','gemini-per-role-effort-unsupported']:client==='grok'?['grok-per-role-effort-unsupported','grok-native-precedence-limits']:client==='claude'?['claude-native-precedence-limits']:['chatgpt-native-precedence-limits'];
 }