claude-dev-env 7.6.1 → 7.7.0

package/hooks/routing/subagent_model_routing.test.mjs

@@ -0,0 +1,218 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { buildSubagentModelRoutingResponse } from './subagent_model_routing.mjs';
+
+const targetToolName = 'multi_agent_v1__spawn_agent';
+
+function buildHookPayload(toolInput, metadata = {}) {
+    return { tool_name: targetToolName, tool_input: toolInput, ...metadata };
+}
+
+test('remaps Terra Medium to Luna Xhigh', () => {
+    const hookResponse = buildSubagentModelRoutingResponse(buildHookPayload({
+        model: 'Terra',
+        reasoning_effort: 'Medium',
+    }));
+
+    assert.equal(hookResponse.hookSpecificOutput.updatedInput.model, 'gpt-5.6-luna');
+    assert.equal(
+        hookResponse.hookSpecificOutput.updatedInput.reasoning_effort,
+        'xhigh',
+    );
+});
+
+test('emits only the allow response shape after a remap', () => {
+    const hookResponse = buildSubagentModelRoutingResponse(buildHookPayload({
+        model: 'Terra',
+        reasoning_effort: 'medium',
+    }));
+
+    assert.deepEqual(Object.keys(hookResponse), ['hookSpecificOutput']);
+    assert.deepEqual(Object.keys(hookResponse.hookSpecificOutput), [
+        'hookEventName',
+        'permissionDecision',
+        'updatedInput',
+    ]);
+    assert.deepEqual(hookResponse.hookSpecificOutput, {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: {
+            model: 'gpt-5.6-luna',
+            reasoning_effort: 'xhigh',
+        },
+    });
+});
+
+test('preserves every non-routing tool field', () => {
+    const toolInput = {
+        assignment: 'preserve',
+        message: 'do the work',
+        child_permissions: { shell: 'ask' },
+        output_contract: ['summary'],
+        model: 'Terra',
+        reasoning_effort: 'medium',
+    };
+
+    const hookResponse = buildSubagentModelRoutingResponse(buildHookPayload(toolInput));
+
+    assert.deepEqual(hookResponse.hookSpecificOutput.updatedInput, {
+        assignment: 'preserve',
+        message: 'do the work',
+        child_permissions: { shell: 'ask' },
+        output_contract: ['summary'],
+        model: 'gpt-5.6-luna',
+        reasoning_effort: 'xhigh',
+    });
+    assert.deepEqual(toolInput, {
+        assignment: 'preserve',
+        message: 'do the work',
+        child_permissions: { shell: 'ask' },
+        output_contract: ['summary'],
+        model: 'Terra',
+        reasoning_effort: 'medium',
+    });
+});
+
+test('passes unrelated tool calls through', () => {
+    const hookResponse = buildSubagentModelRoutingResponse({
+        tool_name: 'Task',
+        tool_input: { model: 'Terra', reasoning_effort: 'medium' },
+    });
+
+    assert.deepEqual(hookResponse, {});
+});
+
+test('blocks malformed policy, unknown input, unavailable replacement, and untrusted advisor roles', () => {
+    const malformedPolicyResponse = buildSubagentModelRoutingResponse(
+        buildHookPayload({ model: 'Terra', reasoning_effort: 'medium' }),
+        { policy: {} },
+    );
+    const unknownInputResponse = buildSubagentModelRoutingResponse(
+        buildHookPayload({ model: 'Unknown', reasoning_effort: 'medium' }),
+    );
+    const unavailableReplacementResponse = buildSubagentModelRoutingResponse(
+        buildHookPayload({ model: 'Terra', reasoning_effort: 'medium' }),
+        { availableModelIds: ['gpt-5.6-terra'] },
+    );
+    const untrustedAdvisorResponse = buildSubagentModelRoutingResponse(
+        buildHookPayload({
+            agent_type: 'advisor',
+            model: 'Astra',
+            reasoning_effort: 'medium',
+        }),
+    );
+
+    const allBlockedResponses = [
+        [malformedPolicyResponse, /policy/],
+        [unknownInputResponse, /model is unknown/],
+        [unavailableReplacementResponse, /replacement model is unavailable/],
+        [untrustedAdvisorResponse, /advisor role is not trusted/],
+    ];
+    for (const [eachBlockedResponse, eachExpectedDiagnostic] of allBlockedResponses) {
+        assert.equal(eachBlockedResponse.hookSpecificOutput.permissionDecision, 'deny');
+        assert.equal(eachBlockedResponse.hookSpecificOutput.hookEventName, 'PreToolUse');
+        assert.equal(typeof eachBlockedResponse.hookSpecificOutput.permissionDecisionReason, 'string');
+        assert.match(
+            eachBlockedResponse.hookSpecificOutput.permissionDecisionReason,
+            eachExpectedDiagnostic,
+        );
+    }
+});
+
+test('allows a registered session advisor with trusted session metadata', () => {
+    const hookResponse = buildSubagentModelRoutingResponse(
+        buildHookPayload({
+            agent_type: 'session-advisor',
+            model: 'Astra',
+            reasoning_effort: 'high',
+        }),
+        {
+            trustedSessionMetadata: {
+                authorized: true,
+                registeredAgentType: 'session-advisor',
+            },
+        },
+    );
+
+    assert.deepEqual(hookResponse.hookSpecificOutput.updatedInput, {
+        agent_type: 'session-advisor',
+        model: 'gpt-6-astra',
+        reasoning_effort: 'high',
+    });
+});
+
+test('a session advisor name without trusted session metadata is blocked', () => {
+    const hookResponse = buildSubagentModelRoutingResponse(buildHookPayload({
+        agent_type: 'session-advisor',
+        model: 'Astra',
+        reasoning_effort: 'high',
+    }));
+    assert.equal(hookResponse.hookSpecificOutput.permissionDecision, 'deny');
+    assert.equal(
+        hookResponse.hookSpecificOutput.permissionDecisionReason,
+        'advisor role is not trusted',
+    );
+});
+
+test('payload advisor metadata cannot grant advisory authorization', () => {
+    const hookResponse = buildSubagentModelRoutingResponse(buildHookPayload(
+        {
+            agent_type: 'advisor',
+            model: 'Astra',
+            reasoning_effort: 'high',
+        },
+        {
+            trustedSessionMetadata: {
+                authorized: true,
+                registeredAgentType: 'advisor',
+            },
+        },
+    ));
+    assert.equal(hookResponse.hookSpecificOutput.permissionDecision, 'deny');
+    assert.equal(
+        hookResponse.hookSpecificOutput.permissionDecisionReason,
+        'advisor role is not trusted',
+    );
+});
+
+test('the standalone hook command blocks an advisor without host metadata', () => {
+    const output = execFileSync(
+        process.execPath,
+        [fileURLToPath(new URL('./subagent_model_routing.mjs', import.meta.url))],
+        {
+            encoding: 'utf8',
+            input: JSON.stringify(buildHookPayload({
+                agent_type: 'session-advisor',
+                model: 'Astra',
+                reasoning_effort: 'high',
+            })),
+        },
+    );
+    const hookResponse = JSON.parse(output);
+    assert.equal(hookResponse.hookSpecificOutput.permissionDecision, 'deny');
+    assert.equal(
+        hookResponse.hookSpecificOutput.permissionDecisionReason,
+        'advisor role is not trusted',
+    );
+});
+
+test('keeps a second routing pass unchanged', () => {
+    const firstResponse = buildSubagentModelRoutingResponse(buildHookPayload({
+        model: 'Terra',
+        reasoning_effort: 'medium',
+        message: 'keep',
+    }));
+    const secondResponse = buildSubagentModelRoutingResponse(buildHookPayload(
+        firstResponse.hookSpecificOutput.updatedInput,
+    ));
+
+    assert.deepEqual(secondResponse, {});
+    assert.deepEqual(firstResponse.hookSpecificOutput.updatedInput, {
+        model: 'gpt-5.6-luna',
+        reasoning_effort: 'xhigh',
+        message: 'keep',
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "7.6.1",
+    "version": "7.7.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/pstack-models.md

@@ -21,12 +21,21 @@ The file contains this shape:
 ```json
 {
   "host": "current-host",
+  "defaultEffort": "medium",
   "modelsByRole": {
     "feature, refactoring": ["confirmed-host-model"]
   }
 }
 ```
 
+Automatic model and effort routing reads
+`rules/subagent-model-policy.json` from the same agents home. Edit that file to
+change the next routing decision. The installer creates it only when it is
+absent. The native hook blocks advisor role claims because the current Codex hook
+input has no host-provided role binding. The Python advisor helper passes trusted
+session metadata to the shared resolver. The native advisor hook path stays
+pending until the host supplies that binding.
+
 Offer only model IDs the active native tool accepts. Keep the user's order.
 Treat `inherit-parent` and `auto` as parent inheritance, not model IDs. A full
 install seeds the Claude file and the Codex file from the package when a host
@@ -55,6 +64,7 @@ $selectorInput = @'
     "agentCount": 3,
     "requiresDistinctModels": false
   },
+  "requestedEffort": "medium",
   "availableModelIds": ["confirmed-host-model"],
   "confirmedSuitableModelIds": [],
   "parentModelId": "current-parent-model",
@@ -71,12 +81,24 @@ $selection = $selectorInput | node "$HOME/.agents/scripts/select_pstack_models.m
 `confirmedSuitableModelIds` contains available alternatives whose suitability
 for this role the host metadata or user has confirmed. Do not rank or classify a
 model from its name.
+Keep the host's default effort in the preference file as `defaultEffort`, or
+pass it as trusted runtime data in `requestedEffort`. The selector applies that
+effort to a model-only entry before it picks a candidate. It holds the entry
+when neither source supplies an effort and the policy has no single approved
+effort for that model and role.
 
 Use the returned `nativeSpawnArguments` in the native subagent call. An empty
 object with `omitNativeModelArgument: true` means parent inheritance, so omit
 the native `model` argument. Stop when `canDelegate` is false. Ask the user
 when `requiresUserChoice` is true.
 
+When a preference entry includes `{ "model": "model-id", "effort": "medium" }`,
+the selector routes the pair before it deduplicates candidates and checks panel
+diversity. The selected pair appears in `panel.selectedModelPairs`, and the
+native argument uses `reasoning_effort`. The policy's `selectorExclusions` list
+removes matching routed pairs from panel contenders without blocking direct
+resolver or spawn-hook use.
+
 Run the selector again before the next agent call. Pass the same panel contract
 and the new delegation index with the refreshed inventory. Report
 `panel.selectedModelIds` and `panel.isCrossModelDiverse` as returned. A panel

package/rules/subagent-model-policy.json

@@ -0,0 +1,85 @@
+{
+  "schemaVersion": 1,
+  "models": {
+    "astra": {
+      "id": "gpt-6-astra",
+      "aliases": ["Astra"]
+    },
+    "sol": {
+      "id": "gpt-5.6-sol",
+      "aliases": ["Sol"]
+    },
+    "terra": {
+      "id": "gpt-5.6-terra",
+      "aliases": ["Terra"]
+    },
+    "luna": {
+      "id": "gpt-5.6-luna",
+      "aliases": ["Luna"]
+    }
+  },
+  "efforts": {
+    "values": ["low", "medium", "high", "xhigh", "max"],
+    "aliases": {
+      "light": "low"
+    }
+  },
+  "inheritanceAliases": ["auto", "inherit-parent"],
+  "roles": {
+    "default": "worker",
+    "worker": [
+      "worker",
+      "default",
+      "explorer",
+      "caveman",
+      "clean-coder",
+      "code-quality-agent",
+      "code-verifier",
+      "deep-research",
+      "docs-agent",
+      "git-commit-crafter",
+      "issue-tracker",
+      "plan-packet-validator",
+      "pr-description-writer",
+      "skill-writer-agent",
+      "theme-prompt-agent",
+      "theme-prompt-generator",
+      "translator"
+    ],
+    "advisor": ["advisor", "session-advisor", "team-advisor", "code-advisor"],
+    "trustedAdvisor": ["session-advisor", "team-advisor", "code-advisor"]
+  },
+  "approvedPairs": [
+    {"model": "luna", "effort": "high"},
+    {"model": "luna", "effort": "xhigh"},
+    {"model": "luna", "effort": "max"},
+    {"model": "sol", "effort": "medium"},
+    {"model": "astra", "effort": "low"},
+    {"model": "astra", "effort": "medium"},
+    {"model": "astra", "effort": "high", "roles": ["advisor"]}
+  ],
+  "selectorExclusions": [
+    {"model": "sol", "effort": "medium"}
+  ],
+  "advisorDefault": {"model": "astra", "effort": "medium"},
+  "replacements": [
+    {"requested": {"model": "luna", "effort": "low"}, "selected": {"model": "luna", "effort": "high"}},
+    {"requested": {"model": "luna", "effort": "medium"}, "selected": {"model": "luna", "effort": "high"}},
+    {"requested": {"model": "sol", "effort": "low"}, "selected": {"model": "luna", "effort": "xhigh"}},
+    {"requested": {"model": "terra", "effort": "low"}, "selected": {"model": "luna", "effort": "xhigh"}},
+    {"requested": {"model": "terra", "effort": "medium"}, "selected": {"model": "luna", "effort": "xhigh"}},
+    {"requested": {"model": "terra", "effort": "high"}, "selected": {"model": "luna", "effort": "xhigh"}},
+    {"requested": {"model": "terra", "effort": "xhigh"}, "selected": {"model": "luna", "effort": "max"}},
+    {"requested": {"model": "sol", "effort": "high"}, "selected": {"model": "astra", "effort": "low"}},
+    {"requested": {"model": "sol", "effort": "xhigh"}, "selected": {"model": "astra", "effort": "low"}},
+    {"requested": {"model": "sol", "effort": "max"}, "selected": {"model": "astra", "effort": "low"}},
+    {"requested": {"model": "terra", "effort": "max"}, "selected": {"model": "astra", "effort": "low"}}
+  ],
+  "roleReplacements": [
+    {"role": "advisor", "requested": {"model": "astra", "effort": "xhigh"}, "selected": {"model": "astra", "effort": "medium"}},
+    {"role": "advisor", "requested": {"model": "astra", "effort": "max"}, "selected": {"model": "astra", "effort": "medium"}},
+    {"role": "worker", "requested": {"model": "astra", "effort": "xhigh"}, "selected": {"model": "astra", "effort": "low"}},
+    {"role": "worker", "requested": {"model": "astra", "effort": "max"}, "selected": {"model": "astra", "effort": "low"}},
+    {"role": "worker", "requested": {"model": "astra", "effort": "high"}, "selected": {"model": "astra", "effort": "low"}}
+  ]
+}

package/scripts/resolve_advisor_model_route.mjs

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+
+import { resolveSubagentModelRoute } from './subagent_model_policy.mjs';
+
+function blockedRoute(diagnostic) {
+    return { status: 'blocked', diagnostic };
+}
+
+function isObject(objectCandidate) {
+    return objectCandidate !== null && typeof objectCandidate === 'object' && !Array.isArray(objectCandidate);
+}
+
+function validatePolicyPath(input) {
+    if (!Object.hasOwn(input, 'policyPath')) return null;
+    if (typeof input.policyPath !== 'string' || input.policyPath.trim() === '') {
+        return 'advisor route policyPath must be a non-empty string';
+    }
+    return null;
+}
+
+let input;
+try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+    const routingDecision = blockedRoute('advisor route input is not valid JSON');
+    process.stdout.write(JSON.stringify(routingDecision));
+    process.exitCode = 1;
+}
+
+if (input !== undefined) {
+    let routingDecision;
+    if (!isObject(input)) {
+        routingDecision = blockedRoute('advisor route input must be an object');
+    } else {
+        const routingInputIssue = validatePolicyPath(input);
+        routingDecision = routingInputIssue
+            ? blockedRoute(routingInputIssue)
+            : resolveSubagentModelRoute({
+                agent_type: 'session-advisor',
+                ...(input.model !== undefined && input.model !== null ? { model: input.model } : {}),
+                ...(input.reasoning_effort !== undefined ? { reasoning_effort: input.reasoning_effort } : {}),
+            }, {
+                policyPath: input.policyPath,
+                trustedSessionMetadata: {
+                    authorized: true,
+                    registeredAgentType: 'session-advisor',
+                },
+            });
+    }
+    process.stdout.write(JSON.stringify(routingDecision));
+    if (routingDecision.status === 'blocked') process.exitCode = 1;
+}