agent-policy-kit 0.0.0-stage → 0.2.0

package/src/detect.mjs

@@ -0,0 +1,137 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+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}); }
+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};
+}
+function candidates(client,{env,hostHome}) {
+  const dirs = typeof env.PATH === 'string' ? env.PATH.split(path.delimiter) : [];
+  const names = process.platform === 'win32' ? [client + '.exe',client] : [client];
+  const result = [];
+  for (const dir of dirs) {
+    // Never search the working directory through empty/relative PATH segments.
+    if (!path.isAbsolute(dir) || dir.includes('\0')) continue;
+    for (const name of names) result.push({file:path.join(dir,name),origin:'path'});
+  }
+  const conventional = client === 'kimi' ? ['.kimi-code/bin/kimi']
+    : client === 'claude' ? ['.local/bin/claude','.claude/local/claude']
+    : [`.local/bin/${client}`];
+  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);
+}
+async function inspect(file) {
+  try {
+    const executable = await fs.realpath(file);
+    const stat = await fs.stat(executable);
+    if (!stat.isFile()) return {status:'invalid'};
+    await fs.access(executable,constants.X_OK);
+    return {status:'executable',executable};
+  } catch (error) {
+    return {status:error.code === 'ENOENT' || error.code === 'ENOTDIR' ? 'not_found' : 'invalid'};
+  }
+}
+function probe(executable,arg,{env,timeoutMs}) {
+  return new Promise(resolve => {
+    let child, timer, settled = false, size = 0;
+    const ownGroup = process.platform !== 'win32';
+    const buffers = [];
+    const killOwned = () => {
+      if (!child?.pid) return;
+      try { if (ownGroup) process.kill(-child.pid,'SIGKILL'); else child.kill('SIGKILL'); } catch {}
+    };
+    const alive = () => {
+      if (!child?.pid) return false;
+      if (!ownGroup) return child.exitCode === null && child.signalCode === null;
+      try { process.kill(-child.pid,0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+    };
+    const finish = async (status) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      killOwned();
+      child?.stdout?.destroy(); child?.stderr?.destroy();
+      for (let elapsed = 0; alive() && elapsed < 500; elapsed += 20) await new Promise(done=>setTimeout(done,20));
+      if (status === 'ok' && alive()) status = 'invalid';
+      resolve({status,output:status === 'ok' ? Buffer.concat(buffers).toString('utf8') : ''});
+    };
+    try { child = spawn(executable,[arg],{env,stdio:['ignore','pipe','pipe'],shell:false,windowsHide:true,detached:ownGroup}); }
+    catch { finish('invalid'); return; }
+    timer = setTimeout(()=>finish('timeout'),timeoutMs);
+    for (const stream of [child.stdout,child.stderr]) stream.on('data',chunk=>{
+      size += chunk.length;
+      if (size > OUTPUT_LIMIT) finish('invalid'); else buffers.push(chunk);
+    });
+    // A wrapper can exit successfully while descendants retain inherited pipes.
+    // Its dedicated POSIX group remains ours; stop it before waiting for close.
+    child.on('exit',killOwned);
+    child.on('error',()=>finish('invalid'));
+    child.on('close',code=>finish(code === 0 ? 'ok' : 'invalid'));
+  });
+}
+function identity(client,output) {
+  const patterns = {
+    codex:[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')],
+    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;
+}
+async function verify(client,executable,opts) {
+  const version = await probe(executable,'--version',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'};
+  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);
+  if (help.status !== 'ok') return {status:help.status};
+  const known = client === 'kimi' ? /\bKimi (?:Code(?: CLI)?|CLI)\b/i.test(help.output)
+      && (/\busage:\s*kimi\b/i.test(help.output) || /moonshotai\.github\.io\/kimi-code\//i.test(help.output))
+    : /\bAntigravity\b/i.test(help.output) && /\busage:\s*agy\b/i.test(help.output)
+      || /Usage of agy:/i.test(help.output) && /Available subcommands:/i.test(help.output)
+        && ['--agent','--model','--effort'].every(flag=>help.output.includes(flag));
+  return known ? {status:'detected',version:number[1]} : {status:'invalid'};
+}
+
+export async function resolveClient(client,opts = {}) {
+  if (!CLIENTS.includes(client)) throw failure('INVALID_CLIENT');
+  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)) {
+    const inspected = await inspect(candidate.file);
+    if (inspected.status === 'not_found') continue;
+    if (inspected.status === 'invalid') {
+      if (best.status === 'not_found') best = {...best,status:'invalid',origin:candidate.origin};
+      continue;
+    }
+    if (checked.has(inspected.executable)) continue;
+    checked.add(inspected.executable);
+    const result = await verify(client,inspected.executable,settings);
+    if (result.status === 'detected') return {client,status:'detected',version:result.version,origin:candidate.origin,executable:inspected.executable};
+    if (result.status === 'timeout' || best.status === 'not_found') best = {...best,status:result.status,origin:candidate.origin};
+  }
+  return best;
+}
+export async function detectClients(opts = {}) {
+  return Promise.all(CLIENTS.map(client=>resolveClient(client,opts)));
+}
+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};
+  });
+}

package/src/explicit.mjs

@@ -0,0 +1,89 @@
+// Pure command codec, also embedded in the offline configuration page.
+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'});}
+function explicitList(value,limit){
+ if(typeof value!=='string'||!value.length)invalidExplicit();
+ const list=value.split(',').map(value=>value.trim());
+ if(!list.length||list.length>limit||list.some(value=>!value)||new Set(list).size!==list.length)invalidExplicit();
+ 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);
+ if(Object.entries(fields).some(([key,value])=>!EXPLICIT_FIELDS.includes(key)||value.get||value.set||typeof value.value!=='string'))invalidExplicit();
+ options=Object.fromEntries(Object.entries(fields).map(([key,value])=>[key,value.value]));
+ if(Object.values(fields).reduce((size,value)=>size+value.value.length,0)>65536)invalidExplicit();
+ const requested=explicitList(options.roles,roleIds.length);
+ 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+'-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={};
+  for(const entry of explicitList(options[flag],roles.length)){
+   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();}
+   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);
+    if(level!=='native'&&!EXPLICIT_EFFORTS.includes(level))invalidExplicit();effort=level==='native'?null:level;
+   }
+   if(!EXPLICIT_MODEL.test(model))invalidExplicit();choices[role]={model,effort};
+  }
+  if(Object.keys(choices).length!==roles.length)invalidExplicit();
+  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]];
+  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};
+}
+
+export function explicitOptions(config,roleCatalog){
+ const legacy={worker:'code',reviewer:'code',explorer:'light',routine:'light'};
+ if(!Array.isArray(roleCatalog)||!roleCatalog.length)invalidExplicit();
+ const definitions=roleCatalog.map(role=>typeof role==='string'?{id:role,kind:legacy[role]}:role);
+ if(definitions.some(role=>!role||typeof role.id!=='string'||!['code','light'].includes(role.kind))||new Set(definitions.map(role=>role.id)).size!==definitions.length)invalidExplicit();
+ const roleIds=definitions.map(role=>role.id),kinds=new Map(definitions.map(role=>[role.id,role.kind]));
+ if(!config||config.schemaVersion!==1||!config.clients||typeof config.clients!=='object'||Array.isArray(config.clients))invalidExplicit();
+ const selected=config.selectedRoles??roleIds;
+ if(!Array.isArray(selected)||!selected.length||new Set(selected).size!==selected.length||selected.some(role=>!roleIds.includes(role)))invalidExplicit();
+ const roles=roleIds.filter(role=>selected.includes(role));
+ const options={roles:roles.join(','),'max-concurrent':String(config.maxConcurrent)};
+ for(const [client,preferences]of Object.entries(config.clients)){
+  const flag=Object.keys(TOOL_FLAGS).find(flag=>TOOL_FLAGS[flag]===client);if(!flag||!preferences)invalidExplicit();
+  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(['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(',');
+ }
+ parseExplicitOptions(options,roleIds);
+ return options;
+}
+
+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'||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;
+}