agent-policy-kit 0.1.0 → 0.2.0

package/src/detect.mjs

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 
-const CLIENTS = ['codex','claude','kimi','agy'];
+const CLIENTS = ['codex','claude','kimi','agy','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}); }
@@ -82,6 +82,7 @@ function identity(client,output) {
     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')],
+    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;

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({codex:'codex',claude:'claude',kimi:'kimi',antigravity:'agy',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={};
@@ -30,6 +32,7 @@ export function parseExplicitOptions(options,roleIds){
    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();}
+   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(['agy','grok'].includes(client)&&selected.effort!==null)invalidExplicit();
+   if(client==='grok'&&grokEffortSuffix(selected.model))invalidExplicit();
+   return `${role}=${selected.model}${['agy','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={codex:'.codex',claude:'.claude',kimi:'.kimi-code',agy:'.gemini',grok:'.grok'};
+const ENV_ROOTS={codex:'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==='codex'){
+  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==='codex')continue;
+    if(depth>=4)throw failure('INSPECTION_LIMIT');
+    await rolesIn(file,client,id,budget,models,depth+1);continue;
+   }
+   if(!entry.name.endsWith(id==='codex'?'.toml':'.md'))continue;
+   const body=await readFile(file,budget);if(body===null)throw failure('CONFIG_CHANGED_DURING_READ');
+   const fields=id==='codex'?parseToml(body):frontmatter(body);
+   const role={name:safeString(fields.name,namePattern),model:optionalString(fields.model),effort:optionalString(id==='codex'?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==='agy'){
+    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:['codex','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!=='agy'){
+    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==='agy'?'config/agents':'agents'),c,id,budget,models);
+   if(id==='kimi'||id==='agy'){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 = ['codex', 'claude', 'kimi', 'agy', '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';
@@ -156,6 +156,7 @@ 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==='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,7 +183,7 @@ 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(!(schemaVersion===2?[3]:[2,3]).includes(file.ops.length))fail('INVALID_RECEIPT');
@@ -191,6 +192,14 @@ function validateTomlSnapshot(file,client,schemaVersion) {
     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,6 +382,13 @@ 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==='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==='codex') {
       if(native.agents&&own(native.agents,'max_threads'))fail('CODEX_CAP_ALIAS_CONFLICT');
       const cap=native.agents?.max_concurrent_threads_per_session;

package/src/native.mjs

@@ -4,9 +4,9 @@ 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 = {codex:'.codex',claude:'.claude',kimi:'.kimi-code',agy:'.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={codex:'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]);
 }
@@ -24,7 +24,10 @@ export function nativeRoles(client,config,selectedRoles=ROLE_IDS) {
     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('');
     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)}`);
@@ -48,6 +51,7 @@ export function instructionBlock(client,config,maxConcurrent,selectedRoles=ROLE_
     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.');
@@ -56,5 +60,5 @@ export function instructionBlock(client,config,maxConcurrent,selectedRoles=ROLE_
   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==='agy'?['agy-concurrency-guidance-only','agy-per-role-effort-unsupported']:client==='grok'?['grok-per-role-effort-unsupported','grok-native-precedence-limits']:client==='claude'?['claude-native-precedence-limits']:['codex-native-precedence-limits'];
 }

package/src/output.mjs

@@ -0,0 +1,108 @@
+import {PRESETS} from './release.mjs';
+const LABELS={codex:'Codex',claude:'Claude Code',kimi:'Kimi',agy:'Antigravity',grok:'Grok Build'};
+const label=client=>LABELS[client]??'Tool';
+const code=value=>typeof value==='string'&&/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(value)?value:'OPERATION_FAILED';
+const PRESET_LABELS=Object.fromEntries(PRESETS.map(entry=>[entry.id,entry.label]));
+const preset=value=>Object.hasOwn(PRESET_LABELS,value)?' · '+PRESET_LABELS[value]:'';
+const NOTES={
+ 'codex-native-precedence-limits':'Project and explicit client settings can override these defaults.',
+ 'claude-native-precedence-limits':'Project and explicit client settings can override these defaults.',
+ 'kimi-concurrency-guidance-only':'Kimi: the concurrency limit is guidance.',
+ 'kimi-model-pool-routing-guidance':'Kimi: the parent selects the model alias for each role.',
+ 'agy-concurrency-guidance-only':'Antigravity: the concurrency limit is guidance.',
+ 'agy-per-role-effort-unsupported':'Antigravity: native tiers do not support per-role effort.',
+ 'grok-per-role-effort-unsupported':'Grok Build: native agent settings do not support per-role effort.',
+ 'grok-native-precedence-limits':'Project and explicit client settings can override these defaults.',
+ 'kimi-catalog-alias-resolved':'Kimi: an existing matching model alias was selected.',
+};
+const REASONS={
+ OWNED_DRIFT:'Local edits prevent an update',
+ 'kimi-provisioned-models-required':'Required model aliases are missing',
+ 'native-home-override-unsupported':'The active client profile uses a nonstandard location',
+ 'client-not-selected':'This tool is not selected in the configuration',
+ 'claude-force-model-conflict':'A forced model conflicts with the selected roles',
+ 'kimi-supported-effort-required':'A selected alias does not declare the required effort support',
+ 'kimi-main-effort-conflict':'The requested effort would change the main model defaults',
+ 'kimi-thinking-disabled':'Thinking is disabled for a model that requires it',
+ 'kimi-mixed-native-default-effort':'A shared effort override conflicts with native-default roles',
+ 'kimi-catalog-alias-ambiguous':'More than one existing model alias matches',
+ 'kimi-resolved-model-avoided':'The matching alias is on the avoid list',
+ 'kimi-resolved-effort-conflict':'Roles sharing an alias request conflicting effort levels',
+ INSTALLATION_CONFLICT:'Installed preferences differ from this request',
+ POLICY_CONFLICT:'Saved preferences differ from this request',
+ RECOVERY_REQUIRED:'An interrupted transaction requires recovery',
+ INSTALL_LOCKED:'Another configuration operation holds the lock',
+};
+export const useJsonOutput=({isTTY,json=false}={})=>json||!isTTY;
+function reason(value){const id=code(value);return (REASONS[id]??'Configuration could not be completed')+` (${id})`;}
+function row(client,text,mark='✓'){return `${mark} ${label(client).padEnd(14)} ${text}`;}
+function setup(result,{apply}){
+ const results=result.results??[],failed=results.some(r=>['error','prerequisite','invalid','timeout'].includes(r.status));
+ const changed=results.filter(r=>r.status==='configured');
+ const heading=failed?'Setup incomplete':result.status==='no_clients'?'No supported selected tools found':!apply?'Preview · no files changed':changed.length?'Configuration applied':'Already up to date';
+ const lines=[heading,''],missing=[],notes=new Set();
+ for(const r of results){
+  if(r.status==='not_selected')continue;
+  if(r.status==='not_found'){missing.push(label(r.client));continue;}
+  const warnings=r.warnings??r.plan?.warnings??[];
+  let text,mark='✓';
+  if(r.status==='configured')text='Configuration applied'+preset(r.appliedPreset);
+  else if(r.status==='unchanged'||r.status==='planned'&&r.plan?.files?.length===0)text='Already up to date'+preset(r.appliedPreset);
+  else if(r.status==='planned'){text='Would configure'+preset(r.targetPreset);mark='·';}
+  else if(r.status==='invalid'){text='Client executable identity could not be verified';mark='!';}
+  else if(r.status==='timeout'){text='Client detection timed out';mark='!';}
+  else {text=reason(r.error??warnings[0]);mark='!';}
+  lines.push(row(r.client,text,mark));
+  if(r.status==='prerequisite'&&r.appliedReleaseVersion&&/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(r.appliedReleaseVersion))lines.push(`  Existing configuration retained · ${r.appliedReleaseVersion}${preset(r.appliedPreset)}`);
+  if(['configured','unchanged','planned'].includes(r.status))for(const warning of warnings)notes.add(NOTES[warning]??`Client note: ${code(warning)}`);
+ }
+ if(missing.length)lines.push(`Skipped: ${missing.join(', ')} — not installed.`);
+ if(changed.length)lines.push('',`Open a new session in ${changed.map(r=>label(r.client)).join(', ')} to load the changes.`);
+ if(results.some(r=>r.error==='OWNED_DRIFT'))lines.push('Review local edits before retrying; APK will not overwrite them.');
+ if(results.some(r=>(r.warnings??r.plan?.warnings??[]).includes('kimi-provisioned-models-required')))lines.push('Configure the selected model aliases in Kimi, then run the same command again.');
+ if(notes.size)lines.push('',...notes);
+ lines.push('Native configuration only; model execution was not checked.');
+ return lines;
+}
+function uninstall(result,{apply}){
+ const results=result.results??(result.client?[result]:[]);
+ const lines=[!apply?'Preview · no files changed':result.status==='partial'?'Removal incomplete':result.status==='not_installed'?'Nothing to remove':'Configuration removal',''];
+ for(const r of results){const bad=r.status==='error';lines.push(row(r.client,bad?reason(r.error):r.status==='unchanged'||r.files?.length===0?'Nothing to remove':apply?'Configuration removed':'Would remove',bad?'!':apply?'✓':'·'));}
+ return lines;
+}
+const setting=value=>typeof value==='string'&&/^[A-Za-z0-9][A-Za-z0-9 _.:@/\[\]-]{0,127}$/.test(value)?value:'native default';
+function show(result){
+ const lines=['User configuration · subagents',''];
+ for(const[id,c]of Object.entries(result.clients??{})){
+  lines.push(`${label(id)}${c.status==='attention'?' · incomplete read':c.status==='not_configured'?' · no explicit subagent settings':''}`);
+  if(c.status!=='not_configured'){
+   if(c.defaults.enabled===false)lines.push('  Subagents explicitly disabled.');
+   lines.push(`  Default model: ${setting(c.defaults.model)} · effort: ${setting(c.defaults.effort)}`);
+   lines.push(`  Max concurrent: ${Number.isSafeInteger(c.concurrency.value)?c.concurrency.value:'not explicitly set'}${c.concurrency.kind==='guidance'?' (guidance)':' (native setting)'}`);
+   for(const role of c.roles)lines.push(`  ${setting(role.name).padEnd(22)} ${setting(role.model)} · ${setting(role.effort)}${role.modelSelection==='guidance'?' (routing guidance)':role.modelSelection==='parent'?' (parent selects model)':''}${role.enabled===false?' (delegation disabled)':''}`);
+   for(const entry of c.pool)lines.push(`  Pool: ${setting(entry.alias)} · ${setting(entry.effort)}${entry.configured?'':' · alias not provisioned'}`);
+   for(const[field,value]of Object.entries(c.overrides??{}))lines.push(`  Override ${field}: ${typeof value==='boolean'?String(value):typeof value==='number'?value:setting(value)}`);
+  }
+  if(c.apk.status==='modified')lines.push('  APK-managed files have local edits; the values above come from current files.');
+  for(const warning of c.warnings)lines.push(`  ! ${code(warning)}`);
+  lines.push('');
+ }
+ lines.push('User-level files only; project, managed and session settings may override them.','Native configuration only; model execution was not checked.');
+ return lines;
+}
+export function formatResult(command,result,{version='',apply=false}={}){
+ let lines;
+ if(result.error)lines=[`Operation failed (${code(result.error)})`];
+ else if(command==='setup'||command==='install')lines=setup(result,{apply});
+ else if(command==='uninstall')lines=uninstall(result,{apply});
+ else if(command==='show')lines=show(result);
+ else if(command==='init')lines=['Preferences created.'];
+ else if(command==='detect')lines=result.map(r=>row(r.client,r.status==='detected'?`Detected${typeof r.version==='string'&&/^[0-9A-Za-z.+-]{1,128}$/.test(r.version)?' · '+r.version:''}`:r.status==='not_found'?'Not installed':r.status==='timeout'?'Detection timed out':'Identity unverified',r.status==='detected'?'✓':r.status==='not_found'?'·':'!'));
+ else if(command==='doctor'){
+  lines=['Configuration check',''];
+  for(const[client,r]of Object.entries(result.clients??{})){const c=r.configuration;lines.push(row(client,c.status==='verified'?`Verified${preset(c.preset)}`:c.status==='not_configured'?'Not configured':reason(c.reason),c.status==='attention'?'!':c.status==='verified'?'✓':'·'));}
+  lines.push('Native configuration only; model execution was not checked.');
+ }else if(command==='release')lines=[`Configuration release ${/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(result.version)?result.version:''}${preset(result.preset)}`,'','Use setup --release to preview; add --apply to configure.'];
+ else lines=['Operation completed.'];
+ return [`Agent Policy Kit${/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version)?' · '+version:''}`,'',...lines].join('\n')+'\n';
+}

package/src/policy.mjs

@@ -1,7 +1,7 @@
 import catalog from '../models/catalog.json' with {type:'json'};
 import {ROLES,ROLE_IDS,selectedRoleIds} from './roles.mjs';
 export {ROLES} from './roles.mjs';
-export const CLIENTS = Object.freeze(['codex', 'claude', 'kimi', 'agy']);
+export const CLIENTS = Object.freeze(['codex', 'claude', 'kimi', 'agy', 'grok']);
 export const rolePreference=(config,role)=>config.roles?.[role]??config[ROLES[role]];
 export const NATIVE_EFFORTS=Object.freeze(Object.fromEntries(CLIENTS.map(client=>[client,Object.freeze([...catalog.clients[client].efforts])])));
 const identifier = /^[A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,127}$/;
@@ -21,7 +21,8 @@ export function validatePolicy(value) {
   object(value.clients,CLIENTS);
   if (!Object.keys(value.clients).length) invalid();
   for (const [client,config] of Object.entries(value.clients)) {
-    object(config,['code','light','roles','avoidModels']);
+    object(config,['code','light','roles','avoidModels','maxConcurrent']);
+    if(config.maxConcurrent!==undefined&&(!Number.isInteger(config.maxConcurrent)||config.maxConcurrent<1||config.maxConcurrent>32))invalid();
     if(config.roles!==undefined)object(config.roles,Object.keys(ROLES));
     for (const selected of [config.code,config.light,...Object.values(config.roles??{})]) {
       object(selected,['model','effort']); model(selected.model);

package/src/release.mjs

@@ -4,7 +4,7 @@ import {validatePolicy} from './policy.mjs';
 
 export const PACKAGE_VERSION=JSON.parse(fs.readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
 const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])])):value;
-export const PRESETS=Object.freeze([{id:'fast',label:'Fast & economical',description:'For small, well-defined tasks. Lighter models, with extra reasoning for review and tests.'},{id:'balanced',label:'Balanced',description:'Stronger coding and verification, lighter exploration and mechanical work.'},{id:'quality',label:'Quality first',description:'For demanding implementation and verification. Prioritizes capability over response time and usage.'}].map(Object.freeze));
+export const PRESETS=Object.freeze([{id:'fast',label:'Light',description:'Light models for every role. Limits last longest.'},{id:'balanced',label:'Standard',description:'Stronger models for code, review, tests and docs. Fits most plans.'},{id:'quality',label:'Top-tier',description:'High-end models for most roles. Uses limits fastest.',topModels:Object.freeze({codex:'gpt-6-astra',claude:'claude-fable-5-1',kimi:'kimi-code/k3.1-pro'})}].map(Object.freeze));
 export function presetPreferences(id='balanced'){
   if(!PRESETS.some(preset=>preset.id===id))throw Object.assign(new Error('Unknown preset.'),{code:'UNKNOWN_PRESET'});
   return validatePolicy(JSON.parse(fs.readFileSync(new URL(`../policies/${id}.json`,import.meta.url),'utf8')));