From 10dad6c87a988ad5ced0764bbf8650f2ce042104 Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Fri, 5 Jun 2026 15:48:56 +0200
Subject: [PATCH] docs(pi): document thinking level config

---
 .../docs/docs/targets/coding-agents.mdx       | 17 +++++++++
 .../test/evaluation/providers/targets.test.ts | 36 +++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/apps/web/src/content/docs/docs/targets/coding-agents.mdx b/apps/web/src/content/docs/docs/targets/coding-agents.mdx
index 19106a463..887040f28 100644
--- a/apps/web/src/content/docs/docs/targets/coding-agents.mdx
+++ b/apps/web/src/content/docs/docs/targets/coding-agents.mdx
@@ -148,14 +148,31 @@ targets:
 targets:
   - name: pi_target
     provider: pi-coding-agent
+    subprovider: openai-codex
+    model: gpt-5.5
+    thinking: medium
     grader_target: azure-base
 ```
 
 | Field | Required | Description |
 |-------|----------|-------------|
+| `subprovider` | No | Pi provider to use, such as `google`, `openai`, `openai-codex`, `azure`, `anthropic`, or `openrouter`. Defaults to Pi's default provider. |
+| `model` | No | Model to use. For OpenAI subscription auth through Pi, use `subprovider: openai-codex` with a subscription model such as `gpt-5.5`. |
+| `thinking` | No | Pi reasoning level: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Passed to the Pi SDK as `thinkingLevel`. |
+| `tools` | No | Comma-separated Pi tool allowlist, such as `read,bash,edit,write`. |
+| `api_key` | No | Provider API key. Prefer `${{ ENV_VAR }}` references. Omit for subscription auth handled by Pi. |
+| `base_url` | No | Provider base URL or Azure resource URL/name. |
 | `cwd` | No | Working directory |
+| `timeout_seconds` | No | Per-case timeout |
 | `grader_target` | Yes | LLM target for evaluation |
 
+Use `provider: pi-cli` instead when you want AgentV to spawn the `pi` binary directly. It accepts the same Pi fields above plus:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `executable` | No | Pi binary or shim to run. Defaults to `pi`. |
+| `args` | No | Extra arguments appended before the prompt. |
+
 ## VS Code
 
 ```yaml
diff --git a/packages/core/test/evaluation/providers/targets.test.ts b/packages/core/test/evaluation/providers/targets.test.ts
index 00de80ebd..6b53e5b9f 100644
--- a/packages/core/test/evaluation/providers/targets.test.ts
+++ b/packages/core/test/evaluation/providers/targets.test.ts
@@ -1243,6 +1243,24 @@ describe('createProvider', () => {
     expect(resolved.config.tools).toBe('read,bash,edit,write');
   });
 
+  it('resolves pi-coding-agent thinking level from target config', () => {
+    const resolved = resolveTargetDefinition(
+      {
+        name: 'pi-openai-codex',
+        provider: 'pi-coding-agent',
+        subprovider: 'openai-codex',
+        model: 'gpt-5.5',
+        thinking: 'medium',
+      },
+      {},
+    );
+
+    expect(resolved.kind).toBe('pi-coding-agent');
+    if (resolved.kind !== 'pi-coding-agent') throw new Error('expected pi-coding-agent');
+    expect(resolved.config.model).toBe('gpt-5.5');
+    expect(resolved.config.thinking).toBe('medium');
+  });
+
   it('resolves pi-cli with azure subprovider and base_url', () => {
     const env = {
       AZURE_OPENAI_ENDPOINT: 'https://my-resource.openai.azure.com',
@@ -1269,4 +1287,22 @@ describe('createProvider', () => {
     expect(resolved.config.model).toBe('gpt-4o');
     expect(resolved.config.apiKey).toBe('azure-secret');
   });
+
+  it('resolves pi-cli thinking level from env-backed config', () => {
+    const resolved = resolveTargetDefinition(
+      {
+        name: 'pi-cli-openai-codex',
+        provider: 'pi-cli',
+        subprovider: 'openai-codex',
+        model: 'gpt-5.5',
+        thinking: '${{ PI_THINKING }}',
+      },
+      { PI_THINKING: 'medium' },
+    );
+
+    expect(resolved.kind).toBe('pi-cli');
+    if (resolved.kind !== 'pi-cli') throw new Error('expected pi-cli');
+    expect(resolved.config.model).toBe('gpt-5.5');
+    expect(resolved.config.thinking).toBe('medium');
+  });
 });