agent-bios 0.14.0 → 0.15.0

package/claude/guides/claude-prompting.md

@@ -15,6 +15,14 @@ core_rules:
   - make tool descriptions prescriptive about when to call, not only what the tool does
   - require progress claims to be audited against a tool result from the same session
   - name the boundary explicitly — what to do without asking, and what to stop and ask about
+derived_at: 2026-09-01
+source_pins:
+  - doc: prompting-claude-opus-5
+    sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
+    pinned_at: 2026-09-01
+  - doc: claude-prompting-best-practices
+    sha256: 476ddc2744812dced0b520c8f628aecb52df52babdaf82ee5a0b10f25f5bcbdb
+    pinned_at: 2026-09-01
 targets:
   - claude-fable-5
   - claude-opus-5
@@ -68,7 +76,12 @@ pick the path.
 - Delegation: say when *not* to delegate, and cap the spawn count. The helm
   binding reaches for subagents readily — the reverse of the binding it replaced
   — and every spawn rebuilds context, reports back, and is then re-read, so
-  unbounded delegation multiplies cost and latency. File-based memory and custom
+  unbounded delegation multiplies cost and latency. Where the harness offers
+  deterministic caps, prefer them to prose: under Claude Code and the Agent SDK
+  these are `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`,
+  `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and the SDK's `max_budget_usd` — a
+  limit the model cannot talk itself past. Confirm the harness version supports
+  them before relying on it. File-based memory and custom
   tools are the opposite case: they still need an explicit when-to-use trigger.
 - Autonomous runs with no human watching: say so. Otherwise it asks permission
   it does not need and blocks. Grant autonomy on minor choices (naming,
@@ -107,7 +120,9 @@ pick the path.
   treating a quiet call as a hang.
 - Do not add "summarize every N tool calls" scaffolding — this tier narrates on
   its own. If it narrates too much for a coding agent, set a silence default
-  instead: text only on a finding, a direction change, or a blocker.
+  instead: text only on a finding, a direction change, or a blocker. Describe the
+  cadence you want by example; a positive description of the style outperforms a
+  list of what not to do.
 - Length is a prompting lever, not an effort lever. This tier writes longer
   answers and longer files than its predecessors, and lowering `effort` does not
   reliably shorten visible output — only an explicit instruction does. Calibrate
@@ -121,6 +136,36 @@ pick the path.
   work they did not watch. Lead with the outcome; drop the working shorthand.
 - Do not show a remaining-context countdown. This tier can start conserving and
   suggest a fresh session instead of finishing.
+- Re-validate prompt-side vision workarounds carried from older bindings; this
+  tier is strong on charts, documents, diagrams, and UI replication, and the
+  workaround may now be the thing costing quality. Tools that let it crop and
+  visually verify beat thinking alone here.
+- Instruction following stays consistent across the full context window, so a
+  rule does not need restating near the end to survive a long session.
+
+## Running with thinking disabled
+
+Disabling thinking is accepted only at `high` effort or below, and it is usually
+the wrong lever: thinking on at `low` effort generally beats thinking off at
+comparable cost. Reach for lower effort before reaching for the switch.
+
+Two artifacts appear when it is off, and both are prompt-fixable:
+
+- A tool call written as **user-facing text** instead of a structured call. The
+  turn completes, the call never runs, and in an agentic loop the leaked text
+  stays in history and contaminates later turns. Most common on tool-heavy work.
+- Internal XML tags leaking into the visible response.
+
+One instruction mitigates both — permission to speak before a call, an out when
+no tool fits, and a general ban on internal tags:
+
+> When you use a tool, you may say a brief sentence first. If no tool can express
+> what the user asked for, say so instead of guessing. Do not include internal or
+> system XML tags in your response.
+
+Two traps. Naming the tags specifically is **less** effective than the general
+form. And if a prompt anywhere tells this tier not to think or not to reason,
+delete it: that instruction increases tag leakage rather than suppressing it.
 
 ## Prompt assembly checklist
 
@@ -134,8 +179,15 @@ pick the path.
 
 ## Sources
 
-Derived from the vendor's published guidance for the `targets` models above.
-When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound. `launch/check-prompting-targets.sh` fails when the launch config
-binds a model this guide does not list.
+Derived from the vendor's `prompting-claude-opus-5` and
+`claude-prompting-best-practices` documents, at the exact bytes whose hashes are
+recorded in `source_pins` above. The pin is what makes a later vendor edit
+detectable rather than remembered.
+
+Prompting guidance is version-bound — this generation inverted advice the last one
+gave — so when a `targets` model changes, re-derive from the current documents
+rather than editing around the old rules.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.

package/claude/guides/gpt-prompting.md

@@ -15,6 +15,14 @@ core_rules:
   - replace blanket ALWAYS/NEVER with decision rules naming the condition each choice applies under
   - fix the prompt before raising effort — weak output usually means a missing success criterion, dependency rule, tool-routing rule, or verification loop
   - prompting habits carried from older gpt models cost tokens and can cost accuracy
+derived_at: 2026-09-01
+source_pins:
+  - doc: prompt-guidance-gpt-5p6
+    sha256: 46181efec9fd1160ef537b0379282a14c1ba32380f2f8149a805128253c1115a
+    pinned_at: 2026-09-01
+  - doc: latest-model
+    sha256: 48f61f648eab971334f6076bc61478d0f2bcd7a50111064722eba267a0f98d61
+    pinned_at: 2026-09-01
 targets:
   - gpt-5.6-sol
   - gpt-5.6-terra
@@ -85,9 +93,50 @@ Compose in this order; omit any block that would not change the artifact.
 - Prefer a self-contained packet over resuming a long history: it is cheaper to
   reason about and cheaper to cache.
 
+## Programmatic tool calling
+
+A bounded stage where code processes several tool results and returns a much smaller
+structured result. The qualifier is **reduction**, not parallelism: multiple, parallel,
+or dependent calls alone do not justify it.
+
+- Use it for filtering, joining, sorting, ranking, deduplication and aggregation;
+  batching across many similar records; repeated deterministic validation; and large
+  structured results reducible to a compact schema.
+- Prefer direct calls when one call suffices, when intermediate outputs are already
+  small, when each result may change the next decision, when an action needs approval,
+  when the answer must preserve citations or native artifacts, or when semantic
+  judgment sits between calls.
+- A generic "use programmatic tool calling efficiently" does nothing. State the bounded
+  stage, the eligible tools, the output schema, the retry limit, the stop condition, and
+  the handoff back to direct judgment. If both routes are needed, define one handoff and
+  say not to switch routes or repeat completed work.
+- **Test both outputs.** The program's result and the final assistant message are
+  separate; a program can return the right records while the message drops a required
+  field, citation, or caveat.
+- Compare the two routes on the same tasks, and count lower token/latency/cost as an
+  improvement only when the response still passes the existing evals.
+
 ## Working rules
 
 - One clear task per run, with an explicit output contract.
+- **Read the assembled prompt for contradictions.** This tier follows a prompt contract
+  closely, so two rules that disagree destabilize it more than a missing rule does —
+  the opposite of the intuition that more instruction is safer.
+- State each authority rule once. Repeating "ask first", "do not mutate", or "wait for
+  approval" produces approval requests for safe, expected actions.
+- Name the current layer of work — research, design, implementation, review, external
+  coordination — on long-running tasks, so the model does not move between layers
+  silently.
+- Persisted reasoning is not a free optimization. It helps while the objective and
+  priorities hold; once they move, stale reasoning adds tokens and anchors the model to
+  a superseded approach. Compact at milestones, not every turn, and treat compacted
+  items as opaque.
+- Set the default detail level through the API (`text.verbosity`) and keep the prompt
+  for task-specific length and structure; a prompt-only length rule has to be restated
+  everywhere.
+- Preserve explicit user values. Where the right value is implicit, give decision
+  criteria and let the model reason from context or schema rather than installing
+  universal defaults or keyword maps.
 - Keep reusable prefixes stable and avoid churn in large system prompts. Add
   explicit cache breakpoints only where they measurably improve cache behavior —
   a cache write costs 1.25× the uncached input rate, so read the cached-token
@@ -110,9 +159,16 @@ Compose in this order; omit any block that would not change the artifact.
 
 ## Sources
 
-Derived from the vendor's published prompting guidance for the `targets` models
-above. When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound, and the previous generation's advice inverted on this one.
+Derived from the vendor's `prompt-guidance-gpt-5p6` and `latest-model`
+documents, at the exact bytes whose hashes are recorded in `source_pins` above.
+The pin is what makes a later vendor edit detectable rather than remembered.
+
+Prompting guidance is version-bound and the previous generation's advice inverted
+on this one, so when a `targets` model changes, re-derive from the current
+documents rather than editing around the old rules.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.
 `launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list.

package/codex/guides/claude-prompting.md

@@ -15,6 +15,14 @@ core_rules:
   - make tool descriptions prescriptive about when to call, not only what the tool does
   - require progress claims to be audited against a tool result from the same session
   - name the boundary explicitly — what to do without asking, and what to stop and ask about
+derived_at: 2026-09-01
+source_pins:
+  - doc: prompting-claude-opus-5
+    sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
+    pinned_at: 2026-09-01
+  - doc: claude-prompting-best-practices
+    sha256: 476ddc2744812dced0b520c8f628aecb52df52babdaf82ee5a0b10f25f5bcbdb
+    pinned_at: 2026-09-01
 targets:
   - claude-fable-5
   - claude-opus-5
@@ -68,7 +76,12 @@ pick the path.
 - Delegation: say when *not* to delegate, and cap the spawn count. The helm
   binding reaches for subagents readily — the reverse of the binding it replaced
   — and every spawn rebuilds context, reports back, and is then re-read, so
-  unbounded delegation multiplies cost and latency. File-based memory and custom
+  unbounded delegation multiplies cost and latency. Where the harness offers
+  deterministic caps, prefer them to prose: under Claude Code and the Agent SDK
+  these are `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`,
+  `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and the SDK's `max_budget_usd` — a
+  limit the model cannot talk itself past. Confirm the harness version supports
+  them before relying on it. File-based memory and custom
   tools are the opposite case: they still need an explicit when-to-use trigger.
 - Autonomous runs with no human watching: say so. Otherwise it asks permission
   it does not need and blocks. Grant autonomy on minor choices (naming,
@@ -107,7 +120,9 @@ pick the path.
   treating a quiet call as a hang.
 - Do not add "summarize every N tool calls" scaffolding — this tier narrates on
   its own. If it narrates too much for a coding agent, set a silence default
-  instead: text only on a finding, a direction change, or a blocker.
+  instead: text only on a finding, a direction change, or a blocker. Describe the
+  cadence you want by example; a positive description of the style outperforms a
+  list of what not to do.
 - Length is a prompting lever, not an effort lever. This tier writes longer
   answers and longer files than its predecessors, and lowering `effort` does not
   reliably shorten visible output — only an explicit instruction does. Calibrate
@@ -121,6 +136,36 @@ pick the path.
   work they did not watch. Lead with the outcome; drop the working shorthand.
 - Do not show a remaining-context countdown. This tier can start conserving and
   suggest a fresh session instead of finishing.
+- Re-validate prompt-side vision workarounds carried from older bindings; this
+  tier is strong on charts, documents, diagrams, and UI replication, and the
+  workaround may now be the thing costing quality. Tools that let it crop and
+  visually verify beat thinking alone here.
+- Instruction following stays consistent across the full context window, so a
+  rule does not need restating near the end to survive a long session.
+
+## Running with thinking disabled
+
+Disabling thinking is accepted only at `high` effort or below, and it is usually
+the wrong lever: thinking on at `low` effort generally beats thinking off at
+comparable cost. Reach for lower effort before reaching for the switch.
+
+Two artifacts appear when it is off, and both are prompt-fixable:
+
+- A tool call written as **user-facing text** instead of a structured call. The
+  turn completes, the call never runs, and in an agentic loop the leaked text
+  stays in history and contaminates later turns. Most common on tool-heavy work.
+- Internal XML tags leaking into the visible response.
+
+One instruction mitigates both — permission to speak before a call, an out when
+no tool fits, and a general ban on internal tags:
+
+> When you use a tool, you may say a brief sentence first. If no tool can express
+> what the user asked for, say so instead of guessing. Do not include internal or
+> system XML tags in your response.
+
+Two traps. Naming the tags specifically is **less** effective than the general
+form. And if a prompt anywhere tells this tier not to think or not to reason,
+delete it: that instruction increases tag leakage rather than suppressing it.
 
 ## Prompt assembly checklist
 
@@ -134,8 +179,15 @@ pick the path.
 
 ## Sources
 
-Derived from the vendor's published guidance for the `targets` models above.
-When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound. `launch/check-prompting-targets.sh` fails when the launch config
-binds a model this guide does not list.
+Derived from the vendor's `prompting-claude-opus-5` and
+`claude-prompting-best-practices` documents, at the exact bytes whose hashes are
+recorded in `source_pins` above. The pin is what makes a later vendor edit
+detectable rather than remembered.
+
+Prompting guidance is version-bound — this generation inverted advice the last one
+gave — so when a `targets` model changes, re-derive from the current documents
+rather than editing around the old rules.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.

package/codex/guides/gpt-prompting.md

@@ -15,6 +15,14 @@ core_rules:
   - replace blanket ALWAYS/NEVER with decision rules naming the condition each choice applies under
   - fix the prompt before raising effort — weak output usually means a missing success criterion, dependency rule, tool-routing rule, or verification loop
   - prompting habits carried from older gpt models cost tokens and can cost accuracy
+derived_at: 2026-09-01
+source_pins:
+  - doc: prompt-guidance-gpt-5p6
+    sha256: 46181efec9fd1160ef537b0379282a14c1ba32380f2f8149a805128253c1115a
+    pinned_at: 2026-09-01
+  - doc: latest-model
+    sha256: 48f61f648eab971334f6076bc61478d0f2bcd7a50111064722eba267a0f98d61
+    pinned_at: 2026-09-01
 targets:
   - gpt-5.6-sol
   - gpt-5.6-terra
@@ -85,9 +93,50 @@ Compose in this order; omit any block that would not change the artifact.
 - Prefer a self-contained packet over resuming a long history: it is cheaper to
   reason about and cheaper to cache.
 
+## Programmatic tool calling
+
+A bounded stage where code processes several tool results and returns a much smaller
+structured result. The qualifier is **reduction**, not parallelism: multiple, parallel,
+or dependent calls alone do not justify it.
+
+- Use it for filtering, joining, sorting, ranking, deduplication and aggregation;
+  batching across many similar records; repeated deterministic validation; and large
+  structured results reducible to a compact schema.
+- Prefer direct calls when one call suffices, when intermediate outputs are already
+  small, when each result may change the next decision, when an action needs approval,
+  when the answer must preserve citations or native artifacts, or when semantic
+  judgment sits between calls.
+- A generic "use programmatic tool calling efficiently" does nothing. State the bounded
+  stage, the eligible tools, the output schema, the retry limit, the stop condition, and
+  the handoff back to direct judgment. If both routes are needed, define one handoff and
+  say not to switch routes or repeat completed work.
+- **Test both outputs.** The program's result and the final assistant message are
+  separate; a program can return the right records while the message drops a required
+  field, citation, or caveat.
+- Compare the two routes on the same tasks, and count lower token/latency/cost as an
+  improvement only when the response still passes the existing evals.
+
 ## Working rules
 
 - One clear task per run, with an explicit output contract.
+- **Read the assembled prompt for contradictions.** This tier follows a prompt contract
+  closely, so two rules that disagree destabilize it more than a missing rule does —
+  the opposite of the intuition that more instruction is safer.
+- State each authority rule once. Repeating "ask first", "do not mutate", or "wait for
+  approval" produces approval requests for safe, expected actions.
+- Name the current layer of work — research, design, implementation, review, external
+  coordination — on long-running tasks, so the model does not move between layers
+  silently.
+- Persisted reasoning is not a free optimization. It helps while the objective and
+  priorities hold; once they move, stale reasoning adds tokens and anchors the model to
+  a superseded approach. Compact at milestones, not every turn, and treat compacted
+  items as opaque.
+- Set the default detail level through the API (`text.verbosity`) and keep the prompt
+  for task-specific length and structure; a prompt-only length rule has to be restated
+  everywhere.
+- Preserve explicit user values. Where the right value is implicit, give decision
+  criteria and let the model reason from context or schema rather than installing
+  universal defaults or keyword maps.
 - Keep reusable prefixes stable and avoid churn in large system prompts. Add
   explicit cache breakpoints only where they measurably improve cache behavior —
   a cache write costs 1.25× the uncached input rate, so read the cached-token
@@ -110,9 +159,16 @@ Compose in this order; omit any block that would not change the artifact.
 
 ## Sources
 
-Derived from the vendor's published prompting guidance for the `targets` models
-above. When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound, and the previous generation's advice inverted on this one.
+Derived from the vendor's `prompt-guidance-gpt-5p6` and `latest-model`
+documents, at the exact bytes whose hashes are recorded in `source_pins` above.
+The pin is what makes a later vendor edit detectable rather than remembered.
+
+Prompting guidance is version-bound and the previous generation's advice inverted
+on this one, so when a `targets` model changes, re-derive from the current
+documents rather than editing around the old rules.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.
 `launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list.