agent-policy-kit 0.4.0 → 0.5.1

package/src/explicit.mjs

@@ -11,7 +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.
+// Grok accepts 'role=model' (native default, as in 0.4.0), 'role=model:<effort>' and 'role=model:native'.
+// A model id may contain colons, so only a trailing effort name or 'native' is read as the effort.
 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();
@@ -32,8 +33,8 @@ export function parseExplicitOptions(options,roleIds){
    if(at<1||!roles.includes(role)||Object.hasOwn(choices,role))invalidExplicit();
    let model=value,effort=null;
    if(client==='gemini'){if(!['pro','flash','flash_lite','inherit'].includes(model))invalidExplicit();}
-   else if(client==='grok'){if(grokEffortSuffix(value))invalidExplicit();}
-   else{
+   // A Grok value without an effort suffix is the whole model id.
+   else if(client!=='grok'||grokEffortSuffix(value)){
     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;
@@ -68,9 +69,10 @@ 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(['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')}`;
+   if(client==='gemini'&&selected.effort!==null)invalidExplicit();
+   // A Grok native default keeps the 0.4.0 form unless the model id itself ends like an effort suffix.
+   const plain=client==='gemini'||(client==='grok'&&selected.effort===null&&!grokEffortSuffix(selected.model));
+   return `${role}=${selected.model}${plain?'':':'+(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();

package/src/inspect.mjs

@@ -2,7 +2,7 @@ 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 {CLIENTS,NATIVE_EFFORTS} from './policy.mjs';
 import {inspectConfiguration} from './install.mjs';
 
 const ROOTS={chatgpt:'.codex',claude:'.claude',kimi:'.kimi-code',gemini:'.gemini',grok:'.grok'};
@@ -43,7 +43,7 @@ async function readFile(file,budget){
  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 allowed=['UNSAFE_FILE','INSPECTION_LIMIT','CONFIG_CHANGED_DURING_READ','UNSUPPORTED_NATIVE_SETTING','UNSUPPORTED_ROLE_FORMAT','UNSUPPORTED_ROLE_EFFORT','UNSUPPORTED_ROLE_CAPABILITY','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';
@@ -56,7 +56,9 @@ function scalar(value){
  if(!match)throw failure('UNSUPPORTED_ROLE_FORMAT');
  return match[1];
 }
-function frontmatter(text){
+// Values that Grok Build 1.0.70 accepts for capabilityMode (serde kebab-case names and aliases of SubagentCapabilityMode).
+const GROK_CAPABILITY_MODES=['read-only','readonly','readOnly','read_only','ReadOnly','read-write','readwrite','readWrite','read_write','ReadWrite','execute','Execute','EXECUTE','all','All','ALL'];
+function frontmatter(text,id){
  const match=text.replace(/^\uFEFF/,'').match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
  if(!match)throw failure('UNSUPPORTED_ROLE_FORMAT');
  const fields={};
@@ -64,13 +66,17 @@ function frontmatter(text){
   // 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*(.*)$/);
+  const field=line.match(id==='grok'?/^(name|model|effort|subagent|capabilityMode)[ \t]*:\s*(.*)$/:/^(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 if(field[1]==='capabilityMode'){
+   // Keep a value Grok Build would reject without echoing it; it only selects a warning.
+   const raw=field[2].trim().replace(/\s+#.*$/,''),quoted=raw.match(/^(["'])(.*)\1$/),value=quoted?quoted[2]:raw;
+   fields.capabilityMode=GROK_CAPABILITY_MODES.includes(value)?value:null;
   }else fields[field[1]]=scalar(field[2]);
  }
  if(!fields.name)throw failure('UNSUPPORTED_ROLE_FORMAT');
@@ -139,7 +145,7 @@ async function rolesIn(directory,client,id,budget,models,depth=0){
    }
    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 fields=id==='chatgpt'?parseToml(body):frontmatter(body,id);
    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
@@ -151,9 +157,12 @@ async function rolesIn(directory,client,id,budget,models,depth=0){
     }
    }
    if(id==='grok'){
-    // The native per-subagent model override lives in config.toml, not in the agent file.
+    // The native per-subagent model override lives in config.toml, not in the agent file; the effort lives in the agent frontmatter.
     role.model=models.get(role.name)??role.model;
-    if(fields.effort!==undefined){role.effort=null;warning(client,failure('UNSUPPORTED_ROLE_EFFORT'));}
+    // Grok Build drops an agent whose frontmatter effort is not a level it accepts.
+    if(role.effort!==null&&!NATIVE_EFFORTS.grok.includes(role.effort))warning(client,failure('UNSUPPORTED_ROLE_EFFORT'));
+    // It also drops an agent whose capabilityMode is not a mode it accepts. The snake_case key is not a Grok field.
+    if(fields.capabilityMode===null)warning(client,failure('UNSUPPORTED_ROLE_CAPABILITY'));
    }
    if(id==='gemini'){
     if(role.model!==null&&!['pro','flash','flash_lite','inherit'].includes(role.model))throw failure('UNSUPPORTED_NATIVE_SETTING');

package/src/native.mjs

@@ -24,9 +24,13 @@ export function nativeRoles(client,config,selectedRoles=ROLE_IDS) {
     const {description,prompt}=ROLE_DEFINITIONS.find(value=>value.id===role);
     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)}`];
-    // Grok selects the model from config.toml [subagents.models]; read-only roles use the bundled plan permission mode.
+    // Grok selects the model from config.toml [subagents.models] and reads a role effort from the agent frontmatter;
+    // a null effort writes nothing, so the role keeps its model's native default. Grok Build reads camelCase agent fields:
+    // capabilityMode read-only removes the edit, write, delete and shell tools when a subagent of this type starts.
+    // Releases 0.4.0 and 0.5.0 wrote `permission_mode: plan`, which Grok Build ignores; `permissionMode: plan` has no effect at spawn.
     if(client==='grok') {
-      if(['reviewer','explorer'].includes(role))fields.push('permission_mode: plan');
+      if(selected.effort!==null)fields.push(`effort: ${selected.effort}`);
+      if(['reviewer','explorer'].includes(role))fields.push('capabilityMode: read-only');
     } else if(client==='kimi') {
       if(['reviewer','explorer'].includes(role))fields.push('tools: [Read, Grep, Glob]');
     } else {
@@ -51,7 +55,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==='grok')text.push("Use the named role definitions for model and effort selection. A role effort applies only when its model supports effort; a role without an effort uses its model's native default 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==='chatgpt'||client==='claude')text.push('An omitted role effort uses the native client default; it does not pin a level.');
@@ -60,5 +64,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==='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'];
+  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-effort-model-dependent','grok-native-precedence-limits']:client==='claude'?['claude-native-precedence-limits']:['chatgpt-native-precedence-limits'];
 }

package/src/output.mjs

@@ -11,7 +11,9 @@ const NOTES={
  'kimi-model-pool-routing-guidance':'Kimi: the parent selects the model alias for each role.',
  'gemini-concurrency-guidance-only':'Gemini: the concurrency limit is guidance.',
  'gemini-per-role-effort-unsupported':'Gemini: native tiers do not support per-role effort.',
- 'grok-per-role-effort-unsupported':'Grok: native agent settings do not support per-role effort.',
+ 'grok-effort-model-dependent':'Grok: a role effort applies only when its model supports effort; a role without one uses its model default.',
+ // Receipts written by 0.4.0 still carry this code; it is shown with the corrected text.
+ 'grok-per-role-effort-unsupported':'Grok: a role effort applies only when its model supports effort; a role without one uses its model default.',
  '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.',
 };

package/src/share.mjs

@@ -55,7 +55,7 @@ function shareRelease(release){
 }
 function shareChoice(choice,id,metadata){
  shareRecord(choice,['model','effort']);
- if(typeof choice.model!=='string'||choice.model.length>128||(choice.effort!==null&&(['gemini','grok'].includes(id)||!metadata.catalog[id].efforts.includes(choice.effort))))invalidShare();
+ if(typeof choice.model!=='string'||choice.model.length>128||(choice.effort!==null&&(id==='gemini'||!metadata.catalog[id].efforts.includes(choice.effort))))invalidShare();
  return {model:choice.model,effort:choice.effort};
 }
 function sharePayload(payload,release,metadata){